blob: 0b44e58e24db9792defa73f7f9db367cfa8b6076 [file] [log] [blame]
Bram Moolenaar773a97c2019-06-06 20:39:55 +02001*eval.txt* For Vim version 8.1. Last change: 2019 Jun 06
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|
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02003010. Vim script version |vimscript-version|
3111. No +eval feature |no-eval-feature|
3212. The sandbox |eval-sandbox|
3313. Textlock |textlock|
3414. Testing |testing|
Bram Moolenaar071d4272004-06-13 20:20:40 +000035
Bram Moolenaar071d4272004-06-13 20:20:40 +000036==============================================================================
371. Variables *variables*
38
Bram Moolenaar13065c42005-01-08 16:08:21 +0000391.1 Variable types ~
Bram Moolenaarbf821bc2019-01-23 21:15:02 +010040 *E712* *E896* *E897* *E899*
Bram Moolenaar38a55632016-02-15 22:07:32 +010041There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000042
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020043Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020044 64-bit Numbers are available only when compiled with the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020045 |+num64| feature.
Bram Moolenaar7571d552016-08-18 22:54:46 +020046 Examples: -123 0x10 0177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000047
Bram Moolenaar446cb832008-06-24 21:56:24 +000048Float A floating point number. |floating-point-format| *Float*
49 {only when compiled with the |+float| feature}
50 Examples: 123.456 1.15e-6 -1.1e3
51
Bram Moolenaar06481422016-04-30 15:13:38 +020052 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000053String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000054 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000055
Bram Moolenaard8968242019-01-15 22:51:57 +010056List An ordered sequence of items, see |List| for details.
Bram Moolenaard8b02732005-01-14 21:48:43 +000057 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000058
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000059Dictionary An associative, unordered array: Each entry has a key and a
60 value. |Dictionary|
61 Example: {'blue': "#0000ff", 'red': "#ff0000"}
62
Bram Moolenaar835dc632016-02-07 14:27:38 +010063Funcref A reference to a function |Funcref|.
64 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020065 It can be bound to a dictionary and arguments, it then works
66 like a Partial.
67 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010068
Bram Moolenaar02e83b42016-02-21 20:10:26 +010069Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010070
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020071Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010072
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020073Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010074
Bram Moolenaard8968242019-01-15 22:51:57 +010075Blob Binary Large Object. Stores any sequence of bytes. See |Blob|
76 for details
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010077 Example: 0zFF00ED015DAF
78 0z is an empty Blob.
79
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000080The Number and String types are converted automatically, depending on how they
81are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000082
83Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020084the Number. Examples:
85 Number 123 --> String "123" ~
86 Number 0 --> String "0" ~
87 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020088 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010089Conversion from a String to a Number is done by converting the first digits to
90a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
91recognized. If the String doesn't start with digits, the result is zero.
92Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020093 String "456" --> Number 456 ~
94 String "6bar" --> Number 6 ~
95 String "foo" --> Number 0 ~
96 String "0xf1" --> Number 241 ~
97 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +010098 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020099 String "-8" --> Number -8 ~
100 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000101
102To force conversion from String to Number, add zero to it: >
103 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000104< 64 ~
105
106To avoid a leading zero to cause octal conversion, or for using a different
107base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000108
Bram Moolenaard09091d2019-01-17 16:07:22 +0100109 *TRUE* *FALSE* *Boolean*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000110For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200111You can also use |v:false| and |v:true|. When TRUE is returned from a
112function it is the Number one, FALSE is the number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000113
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200114Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000115 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200116 :" NOT executed
117"foo" is converted to 0, which means FALSE. If the string starts with a
118non-zero number it means TRUE: >
119 :if "8foo"
120 :" executed
121To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200122 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100123<
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200124 *non-zero-arg*
125Function arguments often behave slightly different from |TRUE|: If the
126argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200127non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100128Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
129A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200130
Bram Moolenaar38a55632016-02-15 22:07:32 +0100131 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +0100132 *E974* *E975* *E976*
Bram Moolenaard09091d2019-01-17 16:07:22 +0100133|List|, |Dictionary|, |Funcref|, |Job|, |Channel| and |Blob| types are not
134automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000135
Bram Moolenaar446cb832008-06-24 21:56:24 +0000136 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200137When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000138there is no automatic conversion of Float. You can use str2float() for String
139to Float, printf() for Float to String and float2nr() for Float to Number.
140
Bram Moolenaar38a55632016-02-15 22:07:32 +0100141 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100142When expecting a Float a Number can also be used, but nothing else.
143
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100144 *no-type-checking*
145You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000146
Bram Moolenaar13065c42005-01-08 16:08:21 +0000147
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001481.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000149 *Funcref* *E695* *E718*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200150A Funcref variable is obtained with the |function()| function, the |funcref()|
151function or created with the lambda expression |expr-lambda|. It can be used
152in an expression in the place of a function name, before the parenthesis
153around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000154
155 :let Fn = function("MyFunc")
156 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000157< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000158A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200159can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000160cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000161
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000162A special case is defining a function and directly assigning its Funcref to a
163Dictionary entry. Example: >
164 :function dict.init() dict
165 : let self.val = 0
166 :endfunction
167
168The key of the Dictionary can start with a lower case letter. The actual
169function name is not used here. Also see |numbered-function|.
170
171A Funcref can also be used with the |:call| command: >
172 :call Fn()
173 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000174
175The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000176 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000177
178You can use |call()| to invoke a Funcref and use a list variable for the
179arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000180 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200181<
182 *Partial*
183A Funcref optionally binds a Dictionary and/or arguments. This is also called
184a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200185function() or funcref(). When calling the function the Dictionary and/or
186arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200187
188 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100189 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200190
191This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100192 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200193
194This is very useful when passing a function around, e.g. in the arguments of
195|ch_open()|.
196
197Note that binding a function to a Dictionary also happens when the function is
198a member of the Dictionary: >
199
200 let myDict.myFunction = MyFunction
201 call myDict.myFunction()
202
203Here MyFunction() will get myDict passed as "self". This happens when the
204"myFunction" member is accessed. When making assigning "myFunction" to
205otherDict and calling it, it will be bound to otherDict: >
206
207 let otherDict.myFunction = myDict.myFunction
208 call otherDict.myFunction()
209
210Now "self" will be "otherDict". But when the dictionary was bound explicitly
211this won't happen: >
212
213 let myDict.myFunction = function(MyFunction, myDict)
214 let otherDict.myFunction = myDict.myFunction
215 call otherDict.myFunction()
216
Bram Moolenaard823fa92016-08-12 16:29:27 +0200217Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000218
219
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002201.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200221 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000222A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200223can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000224position in the sequence.
225
Bram Moolenaar13065c42005-01-08 16:08:21 +0000226
227List creation ~
228 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000229A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000230Examples: >
231 :let mylist = [1, two, 3, "four"]
232 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000233
Bram Moolenaar58b85342016-08-14 19:54:54 +0200234An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000235List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000236 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000237
238An extra comma after the last item is ignored.
239
Bram Moolenaar13065c42005-01-08 16:08:21 +0000240
241List index ~
242 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000243An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000244after the List. Indexes are zero-based, thus the first item has index zero. >
245 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000246 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000247
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000248When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000249 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000250<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000251A negative index is counted from the end. Index -1 refers to the last item in
252the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000253 :let last = mylist[-1] " get the last item: "four"
254
Bram Moolenaar13065c42005-01-08 16:08:21 +0000255To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000256is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000257 :echo get(mylist, idx)
258 :echo get(mylist, idx, "NONE")
259
260
261List concatenation ~
262
263Two lists can be concatenated with the "+" operator: >
264 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000265 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000266
267To prepend or append an item turn the item into a list by putting [] around
268it. To change a list in-place see |list-modification| below.
269
270
271Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200272 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000273A part of the List can be obtained by specifying the first and last index,
274separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000275 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000276
277Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000278similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000279 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
280 :let shortlist = mylist[2:2] " List with one item: [3]
281 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000282
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000283If the first index is beyond the last item of the List or the second item is
284before the first item, the result is an empty list. There is no error
285message.
286
287If the second index is equal to or greater than the length of the list the
288length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000289 :let mylist = [0, 1, 2, 3]
290 :echo mylist[2:8] " result: [2, 3]
291
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000292NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200293using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000294mylist[s : e].
295
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000296
Bram Moolenaar13065c42005-01-08 16:08:21 +0000297List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000298 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000299When variable "aa" is a list and you assign it to another variable "bb", both
300variables refer to the same list. Thus changing the list "aa" will also
301change "bb": >
302 :let aa = [1, 2, 3]
303 :let bb = aa
304 :call add(aa, 4)
305 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000306< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000307
308Making a copy of a list is done with the |copy()| function. Using [:] also
309works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000310a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000311 :let aa = [[1, 'a'], 2, 3]
312 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000313 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000314 :let aa[0][1] = 'aaa'
315 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000316< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000317 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000318< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000319
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000320To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000321copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000322
323The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000324List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000325the same value. >
326 :let alist = [1, 2, 3]
327 :let blist = [1, 2, 3]
328 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000329< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000330 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000331< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000332
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000333Note about comparing lists: Two lists are considered equal if they have the
334same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000335exception: When comparing a number with a string they are considered
336different. There is no automatic type conversion, as with using "==" on
337variables. Example: >
338 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000339< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000340 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000341< 0
342
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000343Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000344can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000345
346 :let a = 5
347 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000348 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000349< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000350 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000351< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000352
Bram Moolenaar13065c42005-01-08 16:08:21 +0000353
354List unpack ~
355
356To unpack the items in a list to individual variables, put the variables in
357square brackets, like list items: >
358 :let [var1, var2] = mylist
359
360When the number of variables does not match the number of items in the list
361this produces an error. To handle any extra items from the list append ";"
362and a variable name: >
363 :let [var1, var2; rest] = mylist
364
365This works like: >
366 :let var1 = mylist[0]
367 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000368 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000369
370Except that there is no error if there are only two items. "rest" will be an
371empty list then.
372
373
374List modification ~
375 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000376To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000377 :let list[4] = "four"
378 :let listlist[0][3] = item
379
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000380To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000381modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000382 :let list[3:5] = [3, 4, 5]
383
Bram Moolenaar13065c42005-01-08 16:08:21 +0000384Adding and removing items from a list is done with functions. Here are a few
385examples: >
386 :call insert(list, 'a') " prepend item 'a'
387 :call insert(list, 'a', 3) " insert item 'a' before list[3]
388 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000389 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000390 :call extend(list, [1, 2]) " extend the list with two more items
391 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000392 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000393 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000394 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000395 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000396
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000397Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000398 :call sort(list) " sort a list alphabetically
399 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100400 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000401
Bram Moolenaar13065c42005-01-08 16:08:21 +0000402
403For loop ~
404
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000405The |:for| loop executes commands for each item in a list. A variable is set
406to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000407 :for item in mylist
408 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000409 :endfor
410
411This works like: >
412 :let index = 0
413 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000414 : let item = mylist[index]
415 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000416 : let index = index + 1
417 :endwhile
418
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000419If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000420function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000421
Bram Moolenaar58b85342016-08-14 19:54:54 +0200422Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000423requires the argument to be a list of lists. >
424 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
425 : call Doit(lnum, col)
426 :endfor
427
428This works like a |:let| command is done for each list item. Again, the types
429must remain the same to avoid an error.
430
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000431It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000432 :for [i, j; rest] in listlist
433 : call Doit(i, j)
434 : if !empty(rest)
435 : echo "remainder: " . string(rest)
436 : endif
437 :endfor
438
439
440List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000441 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000442Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000443 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000444 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000445 :let l = len(list) " number of items in list
446 :let big = max(list) " maximum value in list
447 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000448 :let xs = count(list, 'x') " count nr of times 'x' appears in list
449 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000450 :let lines = getline(1, 10) " get ten text lines from buffer
451 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000452 :let list = split("a b c") " create list from items in a string
453 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000454 :let s = string(list) " String representation of list
455 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000456
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000457Don't forget that a combination of features can make things simple. For
458example, to add up all the numbers in a list: >
459 :exe 'let sum = ' . join(nrlist, '+')
460
Bram Moolenaar13065c42005-01-08 16:08:21 +0000461
Bram Moolenaard8b02732005-01-14 21:48:43 +00004621.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100463 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000464A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000465entry can be located with the key. The entries are stored without a specific
466ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000467
468
469Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000470 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000471A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000472braces. Each entry has a key and a value, separated by a colon. Each key can
473only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000474 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
475 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000476< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000477A key is always a String. You can use a Number, it will be converted to a
478String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200479entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar03413f42016-04-12 21:07:15 +0200480Number will be converted to the String '4'. The empty string can be used as a
481key.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000482
Bram Moolenaar58b85342016-08-14 19:54:54 +0200483A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000484nested Dictionary: >
485 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
486
487An extra comma after the last entry is ignored.
488
489
490Accessing entries ~
491
492The normal way to access an entry is by putting the key in square brackets: >
493 :let val = mydict["one"]
494 :let mydict["four"] = 4
495
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000496You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000497
498For keys that consist entirely of letters, digits and underscore the following
499form can be used |expr-entry|: >
500 :let val = mydict.one
501 :let mydict.four = 4
502
503Since an entry can be any type, also a List and a Dictionary, the indexing and
504key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000505 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000506
507
508Dictionary to List conversion ~
509
Bram Moolenaar58b85342016-08-14 19:54:54 +0200510You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000511turn the Dictionary into a List and pass it to |:for|.
512
513Most often you want to loop over the keys, using the |keys()| function: >
514 :for key in keys(mydict)
515 : echo key . ': ' . mydict[key]
516 :endfor
517
518The List of keys is unsorted. You may want to sort them first: >
519 :for key in sort(keys(mydict))
520
521To loop over the values use the |values()| function: >
522 :for v in values(mydict)
523 : echo "value: " . v
524 :endfor
525
526If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100527a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000528 :for [key, value] in items(mydict)
529 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000530 :endfor
531
532
533Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000534 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000535Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
536Dictionary. Otherwise, assignment results in referring to the same
537Dictionary: >
538 :let onedict = {'a': 1, 'b': 2}
539 :let adict = onedict
540 :let adict['a'] = 11
541 :echo onedict['a']
542 11
543
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000544Two Dictionaries compare equal if all the key-value pairs compare equal. For
545more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000546
547
548Dictionary modification ~
549 *dict-modification*
550To change an already existing entry of a Dictionary, or to add a new entry,
551use |:let| this way: >
552 :let dict[4] = "four"
553 :let dict['one'] = item
554
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000555Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
556Three ways to remove the entry with key "aaa" from dict: >
557 :let i = remove(dict, 'aaa')
558 :unlet dict.aaa
559 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000560
561Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000562 :call extend(adict, bdict)
563This extends adict with all entries from bdict. Duplicate keys cause entries
564in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000565Note that the order of entries in a Dictionary is irrelevant, thus don't
566expect ":echo adict" to show the items from bdict after the older entries in
567adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000568
569Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000570 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000571This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000572
573
574Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100575 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000576When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200577special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000578 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000579 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000580 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000581 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
582 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000583
584This is like a method in object oriented programming. The entry in the
585Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
586the function was invoked from.
587
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000588It is also possible to add a function without the "dict" attribute as a
589Funcref to a Dictionary, but the "self" variable is not available then.
590
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000591 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000592To avoid the extra name for the function it can be defined and directly
593assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000594 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200595 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000596 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000597 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000598 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000599
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000600The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200601that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000602|Funcref|. It will automatically be deleted when there is no |Funcref|
603remaining that refers to it.
604
605It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000606
Bram Moolenaar1affd722010-08-04 17:49:30 +0200607If you get an error for a numbered function, you can find out what it is with
608a trick. Assuming the function is 42, the command is: >
609 :function {42}
610
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000611
612Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000613 *E715*
614Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000615 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
616 :if empty(dict) " TRUE if dict is empty
617 :let l = len(dict) " number of items in dict
618 :let big = max(dict) " maximum value in dict
619 :let small = min(dict) " minimum value in dict
620 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
621 :let s = string(dict) " String representation of dict
622 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000623
624
Bram Moolenaard8968242019-01-15 22:51:57 +01006251.5 Blobs ~
626 *blob* *Blob* *Blobs* *E978*
Bram Moolenaaraff74912019-03-30 18:11:49 +0100627A Blob is a binary object. It can be used to read an image from a file and
628send it over a channel, for example.
629
630A Blob mostly behaves like a |List| of numbers, where each number has the
631value of an 8-bit byte, from 0 to 255.
Bram Moolenaard8968242019-01-15 22:51:57 +0100632
633
634Blob creation ~
635
636A Blob can be created with a |blob-literal|: >
637 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100638Dots can be inserted between bytes (pair of hex characters) for readability,
639they don't change the value: >
640 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100641
642A blob can be read from a file with |readfile()| passing the {type} argument
643set to "B", for example: >
644 :let b = readfile('image.png', 'B')
645
646A blob can be read from a channel with the |ch_readblob()| function.
647
648
649Blob index ~
650 *blob-index* *E979*
651A byte in the Blob can be accessed by putting the index in square brackets
652after the Blob. Indexes are zero-based, thus the first byte has index zero. >
653 :let myblob = 0z00112233
654 :let byte = myblob[0] " get the first byte: 0x00
655 :let byte = myblob[2] " get the third byte: 0x22
656
657A negative index is counted from the end. Index -1 refers to the last byte in
658the Blob, -2 to the last but one byte, etc. >
659 :let last = myblob[-1] " get the last byte: 0x33
660
661To avoid an error for an invalid index use the |get()| function. When an item
662is not available it returns -1 or the default value you specify: >
663 :echo get(myblob, idx)
664 :echo get(myblob, idx, 999)
665
666
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100667Blob iteration ~
668
669The |:for| loop executes commands for each byte of a Blob. The loop variable is
670set to each byte in the Blob. Example: >
671 :for byte in 0z112233
672 : call Doit(byte)
673 :endfor
674This calls Doit() with 0x11, 0x22 and 0x33.
675
676
Bram Moolenaard8968242019-01-15 22:51:57 +0100677Blob concatenation ~
678
679Two blobs can be concatenated with the "+" operator: >
680 :let longblob = myblob + 0z4455
681 :let myblob += 0z6677
682
683To change a blob in-place see |blob-modification| below.
684
685
686Part of a blob ~
687
688A part of the Blob can be obtained by specifying the first and last index,
689separated by a colon in square brackets: >
690 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100691 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100692 :let shortblob = myblob[2:-1] " get 0z2233
693
694Omitting the first index is similar to zero. Omitting the last index is
695similar to -1. >
696 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
697 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
698 :let otherblob = myblob[:] " make a copy of the Blob
699
Bram Moolenaard09091d2019-01-17 16:07:22 +0100700If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100701before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100702message.
703
704If the second index is equal to or greater than the length of the list the
705length minus one is used: >
706 :echo myblob[2:8] " result: 0z2233
707
708
709Blob modification ~
710 *blob-modification*
711To change a specific byte of a blob use |:let| this way: >
712 :let blob[4] = 0x44
713
714When the index is just one beyond the end of the Blob, it is appended. Any
715higher index is an error.
716
717To change a sequence of bytes the [:] notation can be used: >
718 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100719The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100720provided. *E972*
721
722To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100723modified. The value must have the same number of bytes in the range: >
724 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100725
726You can also use the functions |add()|, |remove()| and |insert()|.
727
728
729Blob identity ~
730
731Blobs can be compared for equality: >
732 if blob == 0z001122
733And for equal identity: >
734 if blob is otherblob
735< *blob-identity* *E977*
736When variable "aa" is a Blob and you assign it to another variable "bb", both
737variables refer to the same Blob. Then the "is" operator returns true.
738
739When making a copy using [:] or |copy()| the values are the same, but the
740identity is different: >
741 :let blob = 0z112233
742 :let blob2 = blob
743 :echo blob == blob2
744< 1 >
745 :echo blob is blob2
746< 1 >
747 :let blob3 = blob[:]
748 :echo blob == blob3
749< 1 >
750 :echo blob is blob3
751< 0
752
Bram Moolenaard09091d2019-01-17 16:07:22 +0100753Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100754works, as explained above.
755
756
7571.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000758 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000759If you need to know the type of a variable or expression, use the |type()|
760function.
761
762When the '!' flag is included in the 'viminfo' option, global variables that
763start with an uppercase letter, and don't contain a lowercase letter, are
764stored in the viminfo file |viminfo-file|.
765
766When the 'sessionoptions' option contains "global", global variables that
767start with an uppercase letter and contain at least one lowercase letter are
768stored in the session file |session-file|.
769
770variable name can be stored where ~
771my_var_6 not
772My_Var_6 session file
773MY_VAR_6 viminfo file
774
775
776It's possible to form a variable name with curly braces, see
777|curly-braces-names|.
778
779==============================================================================
7802. Expression syntax *expression-syntax*
781
782Expression syntax summary, from least to most significant:
783
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200784|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200785 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000786
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200787|expr2| expr3
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200788 expr3 || expr3 ... logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000789
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200790|expr3| expr4
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200791 expr4 && expr4 ... logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000792
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200793|expr4| expr5
794 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000795 expr5 != expr5 not equal
796 expr5 > expr5 greater than
797 expr5 >= expr5 greater than or equal
798 expr5 < expr5 smaller than
799 expr5 <= expr5 smaller than or equal
800 expr5 =~ expr5 regexp matches
801 expr5 !~ expr5 regexp doesn't match
802
803 expr5 ==? expr5 equal, ignoring case
804 expr5 ==# expr5 equal, match case
805 etc. As above, append ? for ignoring case, # for
806 matching case
807
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100808 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
809 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
810 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000811
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200812|expr5| expr6
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200813 expr6 + expr6 ... number addition, list or blob concatenation
814 expr6 - expr6 ... number subtraction
815 expr6 . expr6 ... string concatenation
816 expr6 .. expr6 ... string concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000817
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200818|expr6| expr7
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200819 expr7 * expr7 ... number multiplication
820 expr7 / expr7 ... number division
821 expr7 % expr7 ... number modulo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200823|expr7| expr8
824 ! expr7 logical NOT
Bram Moolenaar071d4272004-06-13 20:20:40 +0000825 - expr7 unary minus
826 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000827
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200828|expr8| expr9
829 expr8[expr1] byte of a String or item of a |List|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000830 expr8[expr1 : expr1] substring of a String or sublist of a |List|
831 expr8.name entry in a |Dictionary|
832 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000833
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200834|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000835 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000836 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000837 [expr1, ...] |List|
838 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000839 &option option value
840 (expr1) nested expression
841 variable internal variable
842 va{ria}ble internal variable with curly braces
843 $VAR environment variable
844 @r contents of register 'r'
845 function(expr1, ...) function call
846 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar069c1e72016-07-15 21:25:08 +0200847 {args -> expr1} lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000848
849
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200850"..." indicates that the operations in this level can be concatenated.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000851Example: >
852 &nu || &list && &shell == "csh"
853
854All expressions within one level are parsed from left to right.
855
856
857expr1 *expr1* *E109*
858-----
859
860expr2 ? expr1 : expr1
861
862The expression before the '?' is evaluated to a number. If it evaluates to
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200863|TRUE|, the result is the value of the expression between the '?' and ':',
Bram Moolenaar071d4272004-06-13 20:20:40 +0000864otherwise the result is the value of the expression after the ':'.
865Example: >
866 :echo lnum == 1 ? "top" : lnum
867
868Since the first expression is an "expr2", it cannot contain another ?:. The
869other two expressions can, thus allow for recursive use of ?:.
870Example: >
871 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
872
873To keep this readable, using |line-continuation| is suggested: >
874 :echo lnum == 1
875 :\ ? "top"
876 :\ : lnum == 1000
877 :\ ? "last"
878 :\ : lnum
879
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000880You should always put a space before the ':', otherwise it can be mistaken for
881use in a variable such as "a:1".
882
Bram Moolenaar071d4272004-06-13 20:20:40 +0000883
884expr2 and expr3 *expr2* *expr3*
885---------------
886
Bram Moolenaar04186092016-08-29 21:55:35 +0200887expr3 || expr3 .. logical OR *expr-barbar*
888expr4 && expr4 .. logical AND *expr-&&*
889
Bram Moolenaar071d4272004-06-13 20:20:40 +0000890The "||" and "&&" operators take one argument on each side. The arguments
891are (converted to) Numbers. The result is:
892
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200893 input output ~
894n1 n2 n1 || n2 n1 && n2 ~
895|FALSE| |FALSE| |FALSE| |FALSE|
896|FALSE| |TRUE| |TRUE| |FALSE|
897|TRUE| |FALSE| |TRUE| |FALSE|
898|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000899
900The operators can be concatenated, for example: >
901
902 &nu || &list && &shell == "csh"
903
904Note that "&&" takes precedence over "||", so this has the meaning of: >
905
906 &nu || (&list && &shell == "csh")
907
908Once the result is known, the expression "short-circuits", that is, further
909arguments are not evaluated. This is like what happens in C. For example: >
910
911 let a = 1
912 echo a || b
913
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200914This is valid even if there is no variable called "b" because "a" is |TRUE|,
915so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000916
917 echo exists("b") && b == "yes"
918
919This is valid whether "b" has been defined or not. The second clause will
920only be evaluated if "b" has been defined.
921
922
923expr4 *expr4*
924-----
925
926expr5 {cmp} expr5
927
928Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
929if it evaluates to true.
930
Bram Moolenaar446cb832008-06-24 21:56:24 +0000931 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000932 *expr-<* *expr-<=* *expr-=~* *expr-!~*
933 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
934 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
935 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
936 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200937 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
938 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000939 use 'ignorecase' match case ignore case ~
940equal == ==# ==?
941not equal != !=# !=?
942greater than > ># >?
943greater than or equal >= >=# >=?
944smaller than < <# <?
945smaller than or equal <= <=# <=?
946regexp matches =~ =~# =~?
947regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200948same instance is is# is?
949different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000950
951Examples:
952"abc" ==# "Abc" evaluates to 0
953"abc" ==? "Abc" evaluates to 1
954"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
955
Bram Moolenaar13065c42005-01-08 16:08:21 +0000956 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +0100957A |List| can only be compared with a |List| and only "equal", "not equal",
958"is" and "isnot" can be used. This compares the values of the list,
959recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000960
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000961 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000962A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +0100963equal", "is" and "isnot" can be used. This compares the key/values of the
964|Dictionary| recursively. Ignoring case means case is ignored when comparing
965item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000966
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200967 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +0200968A |Funcref| can only be compared with a |Funcref| and only "equal", "not
969equal", "is" and "isnot" can be used. Case is never ignored. Whether
970arguments or a Dictionary are bound (with a partial) matters. The
971Dictionaries must also be equal (or the same, in case of "is") and the
972arguments must be equal (or the same).
973
974To compare Funcrefs to see if they refer to the same function, ignoring bound
975Dictionary and arguments, use |get()| to get the function name: >
976 if get(Part1, 'name') == get(Part2, 'name')
977 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000978
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100979Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
980the expressions are referring to the same |List|, |Dictionary| or |Blob|
981instance. A copy of a |List| is different from the original |List|. When
982using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
983using "equal", using "isnot" equivalent to using "not equal". Except that
984a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100985 echo 4 == '4'
986 1
987 echo 4 is '4'
988 0
989 echo 0 is []
990 0
991"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000992
Bram Moolenaar071d4272004-06-13 20:20:40 +0000993When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar58b85342016-08-14 19:54:54 +0200994and the comparison is done on Numbers. This means that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100995 echo 0 == 'x'
996 1
997because 'x' converted to a Number is zero. However: >
998 echo [0] == ['x']
999 0
1000Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001001
1002When comparing two Strings, this is done with strcmp() or stricmp(). This
1003results in the mathematical difference (comparing byte values), not
1004necessarily the alphabetical difference in the local language.
1005
Bram Moolenaar446cb832008-06-24 21:56:24 +00001006When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001007'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001008
1009When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001010'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1011
1012'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001013
1014The "=~" and "!~" operators match the lefthand argument with the righthand
1015argument, which is used as a pattern. See |pattern| for what a pattern is.
1016This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1017matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1018portable. To avoid backslashes in the regexp pattern to be doubled, use a
1019single-quote string, see |literal-string|.
1020Since a string is considered to be a single line, a multi-line pattern
1021(containing \n, backslash-n) will not match. However, a literal NL character
1022can be matched like an ordinary character. Examples:
1023 "foo\nbar" =~ "\n" evaluates to 1
1024 "foo\nbar" =~ "\\n" evaluates to 0
1025
1026
1027expr5 and expr6 *expr5* *expr6*
1028---------------
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001029expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+*
1030expr6 - expr6 Number subtraction *expr--*
1031expr6 . expr6 String concatenation *expr-.*
1032expr6 .. expr6 String concatenation *expr-..*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001033
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001034For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001035result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001036
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001037For String concatenation ".." is preferred, since "." is ambiguous, it is also
1038used for |Dict| member access and floating point numbers.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001039When |vimscript-version| is 2 or higher, using "." is not allowed.
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001040
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001041expr7 * expr7 Number multiplication *expr-star*
1042expr7 / expr7 Number division *expr-/*
1043expr7 % expr7 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001044
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02001045For all, except "." and "..", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001046For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001047
1048Note the difference between "+" and ".":
1049 "123" + "456" = 579
1050 "123" . "456" = "123456"
1051
Bram Moolenaar446cb832008-06-24 21:56:24 +00001052Since '.' has the same precedence as '+' and '-', you need to read: >
1053 1 . 90 + 90.0
1054As: >
1055 (1 . 90) + 90.0
1056That works, since the String "190" is automatically converted to the Number
1057190, which can be added to the Float 90.0. However: >
1058 1 . 90 * 90.0
1059Should be read as: >
1060 1 . (90 * 90.0)
1061Since '.' has lower precedence than '*'. This does NOT work, since this
1062attempts to concatenate a Float and a String.
1063
1064When dividing a Number by zero the result depends on the value:
1065 0 / 0 = -0x80000000 (like NaN for Float)
1066 >0 / 0 = 0x7fffffff (like positive infinity)
1067 <0 / 0 = -0x7fffffff (like negative infinity)
1068 (before Vim 7.2 it was always 0x7fffffff)
1069
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001070When 64-bit Number support is enabled:
1071 0 / 0 = -0x8000000000000000 (like NaN for Float)
1072 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1073 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1074
Bram Moolenaar071d4272004-06-13 20:20:40 +00001075When the righthand side of '%' is zero, the result is 0.
1076
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001077None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001078
Bram Moolenaar446cb832008-06-24 21:56:24 +00001079. and % do not work for Float. *E804*
1080
Bram Moolenaar071d4272004-06-13 20:20:40 +00001081
1082expr7 *expr7*
1083-----
1084! expr7 logical NOT *expr-!*
1085- expr7 unary minus *expr-unary--*
1086+ expr7 unary plus *expr-unary-+*
1087
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001088For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001089For '-' the sign of the number is changed.
1090For '+' the number is unchanged.
1091
1092A String will be converted to a Number first.
1093
Bram Moolenaar58b85342016-08-14 19:54:54 +02001094These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001095 !-1 == 0
1096 !!8 == 1
1097 --9 == 9
1098
1099
1100expr8 *expr8*
1101-----
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001102This expression is either |expr9| or a sequence of the alternatives below,
1103in any order. E.g., these are all possible:
1104 expr9[expr1].name
1105 expr9.name[expr1]
1106 expr9(expr1, ...)[expr1].name
1107
1108
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001109expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +02001110 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001111If expr8 is a Number or String this results in a String that contains the
1112expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001113Number. This doesn't recognize multi-byte encodings, see `byteidx()` for
Bram Moolenaar03413f42016-04-12 21:07:15 +02001114an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001115
Bram Moolenaar256972a2015-12-29 19:10:25 +01001116Index zero gives the first byte. This is like it works in C. Careful:
1117text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001118cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001119 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001120
1121If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001122String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001123compatibility). Use [-1:] to get the last byte.
1124
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001125If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001126for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001127error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001128 :let item = mylist[-1] " get last item
1129
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001130Generally, if a |List| index is equal to or higher than the length of the
1131|List|, or more negative than the length of the |List|, this results in an
1132error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001133
Bram Moolenaard8b02732005-01-14 21:48:43 +00001134
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001135expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001136
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001137If expr8 is a Number or String this results in the substring with the bytes
1138from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001139expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
1140|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001141
1142If expr1a is omitted zero is used. If expr1b is omitted the length of the
1143string minus one is used.
1144
1145A negative number can be used to measure from the end of the string. -1 is
1146the last character, -2 the last but one, etc.
1147
1148If an index goes out of range for the string characters are omitted. If
1149expr1b is smaller than expr1a the result is an empty string.
1150
1151Examples: >
1152 :let c = name[-1:] " last byte of a string
1153 :let c = name[-2:-2] " last but one byte of a string
1154 :let s = line(".")[4:] " from the fifth byte to the end
1155 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001156<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001157 *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001158If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001159the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001160just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001161 :let l = mylist[:3] " first four items
1162 :let l = mylist[4:4] " List with one item
1163 :let l = mylist[:] " shallow copy of a List
1164
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001165If expr8 is a |Blob| this results in a new |Blob| with the bytes in the
1166indexes expr1a and expr1b, inclusive. Examples: >
1167 :let b = 0zDEADBEEF
1168 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001169 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001170
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001171Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
1172error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001173
Bram Moolenaarda440d22016-01-16 21:27:23 +01001174Watch out for confusion between a namespace and a variable followed by a colon
1175for a sublist: >
1176 mylist[n:] " uses variable n
1177 mylist[s:] " uses namespace s:, error!
1178
Bram Moolenaard8b02732005-01-14 21:48:43 +00001179
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001180expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +00001181
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001182If expr8 is a |Dictionary| and it is followed by a dot, then the following
1183name will be used as a key in the |Dictionary|. This is just like:
1184expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001185
1186The name must consist of alphanumeric characters, just like a variable name,
1187but it may start with a number. Curly braces cannot be used.
1188
1189There must not be white space before or after the dot.
1190
1191Examples: >
1192 :let dict = {"one": 1, 2: "two"}
Bram Moolenaar68e65602019-05-26 21:33:31 +02001193 :echo dict.one " shows "1"
1194 :echo dict.2 " shows "two"
1195 :echo dict .2 " error because of space before the dot
Bram Moolenaard8b02732005-01-14 21:48:43 +00001196
1197Note that the dot is also used for String concatenation. To avoid confusion
1198always put spaces around the dot for String concatenation.
1199
1200
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001201expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001202
1203When expr8 is a |Funcref| type variable, invoke the function it refers to.
1204
1205
1206
1207 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001208number
1209------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001210number number constant *expr-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001211 *hex-number* *octal-number* *binary-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001212
Bram Moolenaar7571d552016-08-18 22:54:46 +02001213Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
1214and Octal (starting with 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001215
Bram Moolenaar446cb832008-06-24 21:56:24 +00001216 *floating-point-format*
1217Floating point numbers can be written in two forms:
1218
1219 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001220 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001221
1222{N} and {M} are numbers. Both {N} and {M} must be present and can only
1223contain digits.
1224[-+] means there is an optional plus or minus sign.
1225{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001226Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001227locale is.
1228{only when compiled with the |+float| feature}
1229
1230Examples:
1231 123.456
1232 +0.0001
1233 55.0
1234 -0.123
1235 1.234e03
1236 1.0E-6
1237 -3.1416e+88
1238
1239These are INVALID:
1240 3. empty {M}
1241 1e40 missing .{M}
1242
1243Rationale:
1244Before floating point was introduced, the text "123.456" was interpreted as
1245the two numbers "123" and "456", both converted to a string and concatenated,
1246resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001247could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001248incompatibility was accepted in favor of being able to use the normal notation
1249for floating point numbers.
1250
Bram Moolenaard47d5222018-12-09 20:43:55 +01001251 *float-pi* *float-e*
1252A few useful values to copy&paste: >
1253 :let pi = 3.14159265359
1254 :let e = 2.71828182846
1255Or, if you don't want to write them in as floating-point literals, you can
1256also use functions, like the following: >
1257 :let pi = acos(-1.0)
1258 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001259<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001260 *floating-point-precision*
1261The precision and range of floating points numbers depends on what "double"
1262means in the library Vim was compiled with. There is no way to change this at
1263runtime.
1264
1265The default for displaying a |Float| is to use 6 decimal places, like using
1266printf("%g", f). You can select something else when using the |printf()|
1267function. Example: >
1268 :echo printf('%.15e', atan(1))
1269< 7.853981633974483e-01
1270
1271
Bram Moolenaar071d4272004-06-13 20:20:40 +00001272
Bram Moolenaar979243b2015-06-26 19:35:49 +02001273string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274------
1275"string" string constant *expr-quote*
1276
1277Note that double quotes are used.
1278
1279A string constant accepts these special characters:
1280\... three-digit octal number (e.g., "\316")
1281\.. two-digit octal number (must be followed by non-digit)
1282\. one-digit octal number (must be followed by non-digit)
1283\x.. byte specified with two hex numbers (e.g., "\x1f")
1284\x. byte specified with one hex number (must be followed by non-hex char)
1285\X.. same as \x..
1286\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001287\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001288 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001289\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001290\b backspace <BS>
1291\e escape <Esc>
1292\f formfeed <FF>
1293\n newline <NL>
1294\r return <CR>
1295\t tab <Tab>
1296\\ backslash
1297\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001298\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001299 in mappings, the 0x80 byte is escaped.
1300 To use the double quote character it must be escaped: "<M-\">".
1301 Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as
1302 mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001303
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001304Note that "\xff" is stored as the byte 255, which may be invalid in some
1305encodings. Use "\u00ff" to store character 255 according to the current value
1306of 'encoding'.
1307
Bram Moolenaar071d4272004-06-13 20:20:40 +00001308Note that "\000" and "\x00" force the end of the string.
1309
1310
Bram Moolenaard8968242019-01-15 22:51:57 +01001311blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001312------------
1313
1314Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1315The sequence must be an even number of hex characters. Example: >
1316 :let b = 0zFF00ED015DAF
1317
1318
Bram Moolenaar071d4272004-06-13 20:20:40 +00001319literal-string *literal-string* *E115*
1320---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001321'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001322
1323Note that single quotes are used.
1324
Bram Moolenaar58b85342016-08-14 19:54:54 +02001325This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001326meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001327
1328Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001329to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001330 if a =~ "\\s*"
1331 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001332
1333
1334option *expr-option* *E112* *E113*
1335------
1336&option option value, local value if possible
1337&g:option global option value
1338&l:option local option value
1339
1340Examples: >
1341 echo "tabstop is " . &tabstop
1342 if &insertmode
1343
1344Any option name can be used here. See |options|. When using the local value
1345and there is no buffer-local or window-local value, the global value is used
1346anyway.
1347
1348
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001349register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001350--------
1351@r contents of register 'r'
1352
1353The result is the contents of the named register, as a single string.
1354Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001355register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001356registers.
1357
1358When using the '=' register you get the expression itself, not what it
1359evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001360
1361
1362nesting *expr-nesting* *E110*
1363-------
1364(expr1) nested expression
1365
1366
1367environment variable *expr-env*
1368--------------------
1369$VAR environment variable
1370
1371The String value of any environment variable. When it is not defined, the
1372result is an empty string.
Bram Moolenaar691ddee2019-05-09 14:52:41 +02001373
1374The functions `getenv()` and `setenv()` can also be used and work for
1375environment variables with non-alphanumeric names.
1376The function `environ()` can be used to get a Dict with all environment
1377variables.
1378
1379
Bram Moolenaar071d4272004-06-13 20:20:40 +00001380 *expr-env-expand*
1381Note that there is a difference between using $VAR directly and using
1382expand("$VAR"). Using it directly will only expand environment variables that
1383are known inside the current Vim session. Using expand() will first try using
1384the environment variables known inside the current Vim session. If that
1385fails, a shell will be used to expand the variable. This can be slow, but it
1386does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001387 :echo $shell
1388 :echo expand("$shell")
1389The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001390variable (if your shell supports it).
1391
1392
1393internal variable *expr-variable*
1394-----------------
1395variable internal variable
1396See below |internal-variables|.
1397
1398
Bram Moolenaar05159a02005-02-26 23:04:13 +00001399function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001400-------------
1401function(expr1, ...) function call
1402See below |functions|.
1403
1404
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001405lambda expression *expr-lambda* *lambda*
1406-----------------
1407{args -> expr1} lambda expression
1408
1409A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001410evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001411the following ways:
1412
14131. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1414 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020014152. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001416 :let F = {arg1, arg2 -> arg1 - arg2}
1417 :echo F(5, 2)
1418< 3
1419
1420The arguments are optional. Example: >
1421 :let F = {-> 'error function'}
1422 :echo F()
1423< error function
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001424 *closure*
1425Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001426often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001427while they already exist in the function scope. They remain valid even after
1428the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001429 :function Foo(arg)
1430 : let i = 3
1431 : return {x -> x + i - a:arg}
1432 :endfunction
1433 :let Bar = Foo(4)
1434 :echo Bar(6)
1435< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001436
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001437Note that the variables must exist in the outer scope before the lamba is
1438defined for this to work. See also |:func-closure|.
1439
1440Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001441 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001442
1443Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1444 :echo map([1, 2, 3], {idx, val -> val + 1})
1445< [2, 3, 4] >
1446 :echo sort([3,7,2,1,4], {a, b -> a - b})
1447< [1, 2, 3, 4, 7]
1448
1449The lambda expression is also useful for Channel, Job and timer: >
1450 :let timer = timer_start(500,
1451 \ {-> execute("echo 'Handler called'", "")},
1452 \ {'repeat': 3})
1453< Handler called
1454 Handler called
1455 Handler called
1456
1457Note how execute() is used to execute an Ex command. That's ugly though.
1458
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001459
1460Lambda expressions have internal names like '<lambda>42'. If you get an error
1461for a lambda expression, you can find what it is with the following command: >
1462 :function {'<lambda>42'}
1463See also: |numbered-function|
1464
Bram Moolenaar071d4272004-06-13 20:20:40 +00001465==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020014663. Internal variable *internal-variables* *E461*
1467
Bram Moolenaar071d4272004-06-13 20:20:40 +00001468An internal variable name can be made up of letters, digits and '_'. But it
1469cannot start with a digit. It's also possible to use curly braces, see
1470|curly-braces-names|.
1471
1472An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001473An internal variable is explicitly destroyed with the ":unlet" command
1474|:unlet|.
1475Using a name that is not an internal variable or refers to a variable that has
1476been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001477
1478There are several name spaces for variables. Which one is to be used is
1479specified by what is prepended:
1480
1481 (nothing) In a function: local to a function; otherwise: global
1482|buffer-variable| b: Local to the current buffer.
1483|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001484|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001485|global-variable| g: Global.
1486|local-variable| l: Local to a function.
1487|script-variable| s: Local to a |:source|'ed Vim script.
1488|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001489|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001490
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001491The scope name by itself can be used as a |Dictionary|. For example, to
1492delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001493 :for k in keys(s:)
1494 : unlet s:[k]
1495 :endfor
1496<
Bram Moolenaar531da592013-05-06 05:58:55 +02001497 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001498A variable name that is preceded with "b:" is local to the current buffer.
1499Thus you can have several "b:foo" variables, one for each buffer.
1500This kind of variable is deleted when the buffer is wiped out or deleted with
1501|:bdelete|.
1502
1503One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001504 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001505b:changedtick The total number of changes to the current buffer. It is
1506 incremented for each change. An undo command is also a change
1507 in this case. This can be used to perform an action only when
1508 the buffer has changed. Example: >
1509 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001510 : let my_changedtick = b:changedtick
1511 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001512 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001513< You cannot change or delete the b:changedtick variable.
1514
Bram Moolenaar531da592013-05-06 05:58:55 +02001515 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001516A variable name that is preceded with "w:" is local to the current window. It
1517is deleted when the window is closed.
1518
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001519 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001520A variable name that is preceded with "t:" is local to the current tab page,
1521It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001522without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001523
Bram Moolenaar531da592013-05-06 05:58:55 +02001524 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001525Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar58b85342016-08-14 19:54:54 +02001526access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001527place if you like.
1528
Bram Moolenaar531da592013-05-06 05:58:55 +02001529 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001530Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001531But you can also prepend "l:" if you like. However, without prepending "l:"
1532you may run into reserved variable names. For example "count". By itself it
1533refers to "v:count". Using "l:count" you can have a local variable with the
1534same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001535
1536 *script-variable* *s:var*
1537In a Vim script variables starting with "s:" can be used. They cannot be
1538accessed from outside of the scripts, thus are local to the script.
1539
1540They can be used in:
1541- commands executed while the script is sourced
1542- functions defined in the script
1543- autocommands defined in the script
1544- functions and autocommands defined in functions and autocommands which were
1545 defined in the script (recursively)
1546- user defined commands defined in the script
1547Thus not in:
1548- other scripts sourced from this one
1549- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001550- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001551- etc.
1552
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001553Script variables can be used to avoid conflicts with global variable names.
1554Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001555
1556 let s:counter = 0
1557 function MyCounter()
1558 let s:counter = s:counter + 1
1559 echo s:counter
1560 endfunction
1561 command Tick call MyCounter()
1562
1563You can now invoke "Tick" from any script, and the "s:counter" variable in
1564that script will not be changed, only the "s:counter" in the script where
1565"Tick" was defined is used.
1566
1567Another example that does the same: >
1568
1569 let s:counter = 0
1570 command Tick let s:counter = s:counter + 1 | echo s:counter
1571
1572When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001573script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001574defined.
1575
1576The script variables are also available when a function is defined inside a
1577function that is defined in a script. Example: >
1578
1579 let s:counter = 0
1580 function StartCounting(incr)
1581 if a:incr
1582 function MyCounter()
1583 let s:counter = s:counter + 1
1584 endfunction
1585 else
1586 function MyCounter()
1587 let s:counter = s:counter - 1
1588 endfunction
1589 endif
1590 endfunction
1591
1592This defines the MyCounter() function either for counting up or counting down
1593when calling StartCounting(). It doesn't matter from where StartCounting() is
1594called, the s:counter variable will be accessible in MyCounter().
1595
1596When the same script is sourced again it will use the same script variables.
1597They will remain valid as long as Vim is running. This can be used to
1598maintain a counter: >
1599
1600 if !exists("s:counter")
1601 let s:counter = 1
1602 echo "script executed for the first time"
1603 else
1604 let s:counter = s:counter + 1
1605 echo "script executed " . s:counter . " times now"
1606 endif
1607
1608Note that this means that filetype plugins don't get a different set of script
1609variables for each buffer. Use local buffer variables instead |b:var|.
1610
1611
Bram Moolenaard47d5222018-12-09 20:43:55 +01001612PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
1613 *E963*
1614Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001615
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001616 *v:beval_col* *beval_col-variable*
1617v:beval_col The number of the column, over which the mouse pointer is.
1618 This is the byte index in the |v:beval_lnum| line.
1619 Only valid while evaluating the 'balloonexpr' option.
1620
1621 *v:beval_bufnr* *beval_bufnr-variable*
1622v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1623 valid while evaluating the 'balloonexpr' option.
1624
1625 *v:beval_lnum* *beval_lnum-variable*
1626v:beval_lnum The number of the line, over which the mouse pointer is. Only
1627 valid while evaluating the 'balloonexpr' option.
1628
1629 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001630v:beval_text The text under or after the mouse pointer. Usually a word as
1631 it is useful for debugging a C program. 'iskeyword' applies,
1632 but a dot and "->" before the position is included. When on a
1633 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001634 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001635 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001636 Only valid while evaluating the 'balloonexpr' option.
1637
1638 *v:beval_winnr* *beval_winnr-variable*
1639v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001640 valid while evaluating the 'balloonexpr' option. The first
1641 window has number zero (unlike most other places where a
1642 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001643
Bram Moolenaar511972d2016-06-04 18:09:59 +02001644 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001645v:beval_winid The |window-ID| of the window, over which the mouse pointer
1646 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001647
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001648 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001649v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001650 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001651 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001652
Bram Moolenaar071d4272004-06-13 20:20:40 +00001653 *v:charconvert_from* *charconvert_from-variable*
1654v:charconvert_from
1655 The name of the character encoding of a file to be converted.
1656 Only valid while evaluating the 'charconvert' option.
1657
1658 *v:charconvert_to* *charconvert_to-variable*
1659v:charconvert_to
1660 The name of the character encoding of a file after conversion.
1661 Only valid while evaluating the 'charconvert' option.
1662
1663 *v:cmdarg* *cmdarg-variable*
1664v:cmdarg This variable is used for two purposes:
1665 1. The extra arguments given to a file read/write command.
1666 Currently these are "++enc=" and "++ff=". This variable is
1667 set before an autocommand event for a file read/write
1668 command is triggered. There is a leading space to make it
1669 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001670 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001671 included here, because it will be executed anyway.
1672 2. When printing a PostScript file with ":hardcopy" this is
1673 the argument for the ":hardcopy" command. This can be used
1674 in 'printexpr'.
1675
1676 *v:cmdbang* *cmdbang-variable*
1677v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1678 was used the value is 1, otherwise it is 0. Note that this
1679 can only be used in autocommands. For user commands |<bang>|
1680 can be used.
1681
Bram Moolenaar42a45122015-07-10 17:56:23 +02001682 *v:completed_item* *completed_item-variable*
1683v:completed_item
1684 |Dictionary| containing the |complete-items| for the most
1685 recently completed word after |CompleteDone|. The
1686 |Dictionary| is empty if the completion failed.
1687
Bram Moolenaar071d4272004-06-13 20:20:40 +00001688 *v:count* *count-variable*
1689v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001690 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001691 :map _x :<C-U>echo "the count is " . v:count<CR>
1692< Note: The <C-U> is required to remove the line range that you
1693 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001694 When there are two counts, as in "3d2w", they are multiplied,
1695 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001696 Also used for evaluating the 'formatexpr' option.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001697 "count" also works, for backwards compatibility, unless
1698 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001699
1700 *v:count1* *count1-variable*
1701v:count1 Just like "v:count", but defaults to one when no count is
1702 used.
1703
1704 *v:ctype* *ctype-variable*
1705v:ctype The current locale setting for characters of the runtime
1706 environment. This allows Vim scripts to be aware of the
1707 current locale encoding. Technical: it's the value of
1708 LC_CTYPE. When not using a locale the value is "C".
1709 This variable can not be set directly, use the |:language|
1710 command.
1711 See |multi-lang|.
1712
1713 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001714v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001715 one. When multiple signals are caught the number increases.
1716 Can be used in an autocommand to check if Vim didn't
1717 terminate normally. {only works on Unix}
1718 Example: >
1719 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001720< Note: if another deadly signal is caught when v:dying is one,
1721 VimLeave autocommands will not be executed.
1722
Bram Moolenaar071d4272004-06-13 20:20:40 +00001723 *v:errmsg* *errmsg-variable*
1724v:errmsg Last given error message. It's allowed to set this variable.
1725 Example: >
1726 :let v:errmsg = ""
1727 :silent! next
1728 :if v:errmsg != ""
1729 : ... handle error
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001730< "errmsg" also works, for backwards compatibility, unless
1731 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732
Bram Moolenaar65a54642018-04-28 16:56:53 +02001733 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001734v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001735 This is a list of strings.
1736 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02001737 The return value indicates this: a one is returned if an item
1738 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01001739 To remove old results make it empty: >
1740 :let v:errors = []
1741< If v:errors is set to anything but a list it is made an empty
1742 list by the assert function.
1743
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001744 *v:event* *event-variable*
1745v:event Dictionary containing information about the current
1746 |autocommand|. The dictionary is emptied when the |autocommand|
1747 finishes, please refer to |dict-identity| for how to get an
1748 independent copy of it.
1749
Bram Moolenaar071d4272004-06-13 20:20:40 +00001750 *v:exception* *exception-variable*
1751v:exception The value of the exception most recently caught and not
1752 finished. See also |v:throwpoint| and |throw-variables|.
1753 Example: >
1754 :try
1755 : throw "oops"
1756 :catch /.*/
1757 : echo "caught" v:exception
1758 :endtry
1759< Output: "caught oops".
1760
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001761 *v:false* *false-variable*
1762v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001763 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001764 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001765 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001766< v:false ~
1767 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001768 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001769
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001770 *v:fcs_reason* *fcs_reason-variable*
1771v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1772 Can be used in an autocommand to decide what to do and/or what
1773 to set v:fcs_choice to. Possible values:
1774 deleted file no longer exists
1775 conflict file contents, mode or timestamp was
1776 changed and buffer is modified
1777 changed file contents has changed
1778 mode mode of file changed
1779 time only file timestamp changed
1780
1781 *v:fcs_choice* *fcs_choice-variable*
1782v:fcs_choice What should happen after a |FileChangedShell| event was
1783 triggered. Can be used in an autocommand to tell Vim what to
1784 do with the affected buffer:
1785 reload Reload the buffer (does not work if
1786 the file was deleted).
1787 ask Ask the user what to do, as if there
1788 was no autocommand. Except that when
1789 only the timestamp changed nothing
1790 will happen.
1791 <empty> Nothing, the autocommand should do
1792 everything that needs to be done.
1793 The default is empty. If another (invalid) value is used then
1794 Vim behaves like it is empty, there is no warning message.
1795
Bram Moolenaar071d4272004-06-13 20:20:40 +00001796 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001797v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001798 option used for ~
1799 'charconvert' file to be converted
1800 'diffexpr' original file
1801 'patchexpr' original file
1802 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001803 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001804
1805 *v:fname_out* *fname_out-variable*
1806v:fname_out The name of the output file. Only valid while
1807 evaluating:
1808 option used for ~
1809 'charconvert' resulting converted file (*)
1810 'diffexpr' output of diff
1811 'patchexpr' resulting patched file
1812 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02001813 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001814 for a read command (e.g., ":e file") it will be a temporary
1815 file and different from v:fname_in.
1816
1817 *v:fname_new* *fname_new-variable*
1818v:fname_new The name of the new version of the file. Only valid while
1819 evaluating 'diffexpr'.
1820
1821 *v:fname_diff* *fname_diff-variable*
1822v:fname_diff The name of the diff (patch) file. Only valid while
1823 evaluating 'patchexpr'.
1824
1825 *v:folddashes* *folddashes-variable*
1826v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1827 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001828 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001829
1830 *v:foldlevel* *foldlevel-variable*
1831v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001832 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001833
1834 *v:foldend* *foldend-variable*
1835v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001836 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001837
1838 *v:foldstart* *foldstart-variable*
1839v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001840 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001841
Bram Moolenaar817a8802013-11-09 01:44:43 +01001842 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001843v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01001844 Setting it makes sense only if 'hlsearch' is enabled which
1845 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001846 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001847 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001848< Note that the value is restored when returning from a
1849 function. |function-search-undo|.
1850
Bram Moolenaar843ee412004-06-30 16:16:41 +00001851 *v:insertmode* *insertmode-variable*
1852v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1853 events. Values:
1854 i Insert mode
1855 r Replace mode
1856 v Virtual Replace mode
1857
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001858 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001859v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001860 evaluating the expression used with |map()| and |filter()|.
1861 Read-only.
1862
Bram Moolenaar071d4272004-06-13 20:20:40 +00001863 *v:lang* *lang-variable*
1864v:lang The current locale setting for messages of the runtime
1865 environment. This allows Vim scripts to be aware of the
1866 current language. Technical: it's the value of LC_MESSAGES.
1867 The value is system dependent.
1868 This variable can not be set directly, use the |:language|
1869 command.
1870 It can be different from |v:ctype| when messages are desired
1871 in a different language than what is used for character
1872 encoding. See |multi-lang|.
1873
1874 *v:lc_time* *lc_time-variable*
1875v:lc_time The current locale setting for time messages of the runtime
1876 environment. This allows Vim scripts to be aware of the
1877 current language. Technical: it's the value of LC_TIME.
1878 This variable can not be set directly, use the |:language|
1879 command. See |multi-lang|.
1880
1881 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001882v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1883 'indentexpr' expressions, tab page number for 'guitablabel'
1884 and 'guitabtooltip'. Only valid while one of these
1885 expressions is being evaluated. Read-only when in the
1886 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001887
Bram Moolenaar219b8702006-11-01 14:32:36 +00001888 *v:mouse_win* *mouse_win-variable*
1889v:mouse_win Window number for a mouse click obtained with |getchar()|.
1890 First window has number 1, like with |winnr()|. The value is
1891 zero when there was no mouse button click.
1892
Bram Moolenaar511972d2016-06-04 18:09:59 +02001893 *v:mouse_winid* *mouse_winid-variable*
1894v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
1895 The value is zero when there was no mouse button click.
1896
Bram Moolenaar219b8702006-11-01 14:32:36 +00001897 *v:mouse_lnum* *mouse_lnum-variable*
1898v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1899 This is the text line number, not the screen line number. The
1900 value is zero when there was no mouse button click.
1901
1902 *v:mouse_col* *mouse_col-variable*
1903v:mouse_col Column number for a mouse click obtained with |getchar()|.
1904 This is the screen column number, like with |virtcol()|. The
1905 value is zero when there was no mouse button click.
1906
Bram Moolenaard09091d2019-01-17 16:07:22 +01001907 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001908v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001909 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001910 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001911 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001912 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001913< v:none ~
1914 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001915 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001916
1917 *v:null* *null-variable*
1918v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001919 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001920 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001921 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001922 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001923< v:null ~
1924 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001925 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001926
Bram Moolenaard812df62008-11-09 12:46:09 +00001927 *v:oldfiles* *oldfiles-variable*
1928v:oldfiles List of file names that is loaded from the |viminfo| file on
1929 startup. These are the files that Vim remembers marks for.
1930 The length of the List is limited by the ' argument of the
1931 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001932 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001933 Also see |:oldfiles| and |c_#<|.
1934 The List can be modified, but this has no effect on what is
1935 stored in the |viminfo| file later. If you use values other
1936 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001937 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001938
Bram Moolenaar53744302015-07-17 17:38:22 +02001939 *v:option_new*
1940v:option_new New value of the option. Valid while executing an |OptionSet|
1941 autocommand.
1942 *v:option_old*
1943v:option_old Old value of the option. Valid while executing an |OptionSet|
1944 autocommand.
1945 *v:option_type*
1946v:option_type Scope of the set command. Valid while executing an
1947 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001948 *v:operator* *operator-variable*
1949v:operator The last operator given in Normal mode. This is a single
1950 character except for commands starting with <g> or <z>,
1951 in which case it is two characters. Best used alongside
1952 |v:prevcount| and |v:register|. Useful if you want to cancel
1953 Operator-pending mode and then use the operator, e.g.: >
1954 :omap O <Esc>:call MyMotion(v:operator)<CR>
1955< The value remains set until another operator is entered, thus
1956 don't expect it to be empty.
1957 v:operator is not set for |:delete|, |:yank| or other Ex
1958 commands.
1959 Read-only.
1960
Bram Moolenaar071d4272004-06-13 20:20:40 +00001961 *v:prevcount* *prevcount-variable*
1962v:prevcount The count given for the last but one Normal mode command.
1963 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001964 you want to cancel Visual or Operator-pending mode and then
1965 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001966 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1967< Read-only.
1968
Bram Moolenaar05159a02005-02-26 23:04:13 +00001969 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001970v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001971 See |profiling|.
1972
Bram Moolenaar071d4272004-06-13 20:20:40 +00001973 *v:progname* *progname-variable*
1974v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001975 invoked. Allows you to do special initialisations for |view|,
1976 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001977 Read-only.
1978
Bram Moolenaara1706c92014-04-01 19:55:49 +02001979 *v:progpath* *progpath-variable*
1980v:progpath Contains the command with which Vim was invoked, including the
1981 path. Useful if you want to message a Vim server using a
1982 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001983 To get the full path use: >
1984 echo exepath(v:progpath)
Bram Moolenaar08cab962017-03-04 14:37:18 +01001985< If the path is relative it will be expanded to the full path,
1986 so that it still works after `:cd`. Thus starting "./vim"
1987 results in "/home/user/path/to/vim/src/vim".
1988 On MS-Windows the executable may be called "vim.exe", but the
1989 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001990 Read-only.
1991
Bram Moolenaar071d4272004-06-13 20:20:40 +00001992 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001993v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001994 command (regardless of whether that command actually used a
1995 register). Or for the currently executing normal mode mapping
1996 (use this in custom commands that take a register).
1997 If none is supplied it is the default register '"', unless
1998 'clipboard' contains "unnamed" or "unnamedplus", then it is
1999 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01002000 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002001
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002002 *v:scrollstart* *scrollstart-variable*
2003v:scrollstart String describing the script or function that caused the
2004 screen to scroll up. It's only set when it is empty, thus the
2005 first reason is remembered. It is set to "Unknown" for a
2006 typed command.
2007 This can be used to find out why your script causes the
2008 hit-enter prompt.
2009
Bram Moolenaar071d4272004-06-13 20:20:40 +00002010 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002011v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002012 Read-only.
2013
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002014
Bram Moolenaar446cb832008-06-24 21:56:24 +00002015v:searchforward *v:searchforward* *searchforward-variable*
2016 Search direction: 1 after a forward search, 0 after a
2017 backward search. It is reset to forward when directly setting
2018 the last search pattern, see |quote/|.
2019 Note that the value is restored when returning from a
2020 function. |function-search-undo|.
2021 Read-write.
2022
Bram Moolenaar071d4272004-06-13 20:20:40 +00002023 *v:shell_error* *shell_error-variable*
2024v:shell_error Result of the last shell command. When non-zero, the last
2025 shell command had an error. When zero, there was no problem.
2026 This only works when the shell returns the error code to Vim.
2027 The value -1 is often used when the command could not be
2028 executed. Read-only.
2029 Example: >
2030 :!mv foo bar
2031 :if v:shell_error
2032 : echo 'could not rename "foo" to "bar"!'
2033 :endif
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002034< "shell_error" also works, for backwards compatibility, unless
2035 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002036
2037 *v:statusmsg* *statusmsg-variable*
2038v:statusmsg Last given status message. It's allowed to set this variable.
2039
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002040 *v:swapname* *swapname-variable*
2041v:swapname Only valid when executing |SwapExists| autocommands: Name of
2042 the swap file found. Read-only.
2043
2044 *v:swapchoice* *swapchoice-variable*
2045v:swapchoice |SwapExists| autocommands can set this to the selected choice
2046 for handling an existing swap file:
2047 'o' Open read-only
2048 'e' Edit anyway
2049 'r' Recover
2050 'd' Delete swapfile
2051 'q' Quit
2052 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002053 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002054 results in the user being asked, as would happen when there is
2055 no SwapExists autocommand. The default is empty.
2056
Bram Moolenaarb3480382005-12-11 21:33:32 +00002057 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002058v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002059 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002060 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002061 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002062 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002063
Bram Moolenaard823fa92016-08-12 16:29:27 +02002064 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002065v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002066 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002067v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002068 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002069v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002070 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002071v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002072 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002073v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002074 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002075v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002076 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002077v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002078 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002079v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002080 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002081v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002082 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002083v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002084 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002085v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002086
Bram Moolenaar071d4272004-06-13 20:20:40 +00002087 *v:termresponse* *termresponse-variable*
2088v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002089 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaarb4230122019-05-30 18:40:53 +02002090 that starts with ESC [ or CSI, then '>' or '?' and ends in a
2091 'c', with only digits and ';' in between.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002092 When this option is set, the TermResponse autocommand event is
2093 fired, so that you can react to the response from the
2094 terminal.
Bram Moolenaarb4230122019-05-30 18:40:53 +02002095 The response from a new xterm is: "<Esc>[> Pp ; Pv ; Pc c". Pp
Bram Moolenaar071d4272004-06-13 20:20:40 +00002096 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2097 patch level (since this was introduced in patch 95, it's
2098 always 95 or bigger). Pc is always zero.
2099 {only when compiled with |+termresponse| feature}
2100
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002101 *v:termblinkresp*
2102v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2103 termcap entry. This is used to find out whether the terminal
2104 cursor is blinking. This is used by |term_getcursor()|.
2105
2106 *v:termstyleresp*
2107v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2108 termcap entry. This is used to find out what the shape of the
2109 cursor is. This is used by |term_getcursor()|.
2110
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002111 *v:termrbgresp*
2112v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002113 termcap entry. This is used to find out what the terminal
2114 background color is, see 'background'.
2115
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002116 *v:termrfgresp*
2117v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2118 termcap entry. This is used to find out what the terminal
2119 foreground color is.
2120
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002121 *v:termu7resp*
2122v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2123 termcap entry. This is used to find out what the terminal
2124 does with ambiguous width characters, see 'ambiwidth'.
2125
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002126 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002127v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002128 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002129 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002130
Bram Moolenaar071d4272004-06-13 20:20:40 +00002131 *v:this_session* *this_session-variable*
2132v:this_session Full filename of the last loaded or saved session file. See
2133 |:mksession|. It is allowed to set this variable. When no
2134 session file has been saved, this variable is empty.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002135 "this_session" also works, for backwards compatibility, unless
2136 |scriptversion| is 3 or higher
Bram Moolenaar071d4272004-06-13 20:20:40 +00002137
2138 *v:throwpoint* *throwpoint-variable*
2139v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002140 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002141 also |v:exception| and |throw-variables|.
2142 Example: >
2143 :try
2144 : throw "oops"
2145 :catch /.*/
2146 : echo "Exception from" v:throwpoint
2147 :endtry
2148< Output: "Exception from test.vim, line 2"
2149
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002150 *v:true* *true-variable*
2151v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002152 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002153 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002154 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002155< v:true ~
2156 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002157 value. Read-only.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002158 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002159v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002160 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002161 |filter()|. Read-only.
2162
Bram Moolenaar071d4272004-06-13 20:20:40 +00002163 *v:version* *version-variable*
2164v:version Version number of Vim: Major version number times 100 plus
2165 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
2166 is 501. Read-only. "version" also works, for backwards
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002167 compatibility, unless |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002168 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002169 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002170< Note that patch numbers are specific to the version, thus both
2171 version 5.0 and 5.1 may have a patch 123, but these are
2172 completely different.
2173
Bram Moolenaar14735512016-03-26 21:00:08 +01002174 *v:vim_did_enter* *vim_did_enter-variable*
2175v:vim_did_enter Zero until most of startup is done. It is set to one just
2176 before |VimEnter| autocommands are triggered.
2177
Bram Moolenaar071d4272004-06-13 20:20:40 +00002178 *v:warningmsg* *warningmsg-variable*
2179v:warningmsg Last given warning message. It's allowed to set this variable.
2180
Bram Moolenaar727c8762010-10-20 19:17:48 +02002181 *v:windowid* *windowid-variable*
2182v:windowid When any X11 based GUI is running or when running in a
2183 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002184 set to the window ID.
2185 When an MS-Windows GUI is running this will be set to the
2186 window handle.
2187 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002188 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2189 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002190
Bram Moolenaar071d4272004-06-13 20:20:40 +00002191==============================================================================
21924. Builtin Functions *functions*
2193
2194See |function-list| for a list grouped by what the function is used for.
2195
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002196(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002197
2198USAGE RESULT DESCRIPTION ~
2199
Bram Moolenaar81edd172016-04-14 13:51:37 +02002200abs({expr}) Float or Number absolute value of {expr}
2201acos({expr}) Float arc cosine of {expr}
Bram Moolenaard8968242019-01-15 22:51:57 +01002202add({object}, {item}) List/Blob append {item} to {object}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002203and({expr}, {expr}) Number bitwise AND
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002204append({lnum}, {text}) Number append {text} below line {lnum}
2205appendbufline({expr}, {lnum}, {text})
2206 Number append {text} below line {lnum}
2207 in buffer {expr}
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002208argc([{winid}]) Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002209argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002210arglistid([{winnr} [, {tabnr}]]) Number argument list id
Bram Moolenaare6e39892018-10-25 12:32:11 +02002211argv({nr} [, {winid}]) String {nr} entry of the argument list
2212argv([-1, {winid}]) List the argument list
Bram Moolenaar65a54642018-04-28 16:56:53 +02002213assert_beeps({cmd}) Number assert {cmd} causes a beep
Bram Moolenaar42205552017-03-18 19:42:22 +01002214assert_equal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002215 Number assert {exp} is equal to {act}
Bram Moolenaard96ff162018-02-18 22:13:29 +01002216assert_equalfile({fname-one}, {fname-two})
Bram Moolenaar65a54642018-04-28 16:56:53 +02002217 Number assert file contents is equal
Bram Moolenaar42205552017-03-18 19:42:22 +01002218assert_exception({error} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002219 Number assert {error} is in v:exception
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002220assert_fails({cmd} [, {error} [, {msg}]])
2221 Number assert {cmd} fails
Bram Moolenaar42205552017-03-18 19:42:22 +01002222assert_false({actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002223 Number assert {actual} is false
Bram Moolenaar61c04492016-07-23 15:35:35 +02002224assert_inrange({lower}, {upper}, {actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002225 Number assert {actual} is inside the range
Bram Moolenaar42205552017-03-18 19:42:22 +01002226assert_match({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002227 Number assert {pat} matches {text}
Bram Moolenaar42205552017-03-18 19:42:22 +01002228assert_notequal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002229 Number assert {exp} is not equal {act}
Bram Moolenaar42205552017-03-18 19:42:22 +01002230assert_notmatch({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002231 Number assert {pat} not matches {text}
2232assert_report({msg}) Number report a test failure
2233assert_true({actual} [, {msg}]) Number assert {actual} is true
Bram Moolenaar81edd172016-04-14 13:51:37 +02002234asin({expr}) Float arc sine of {expr}
2235atan({expr}) Float arc tangent of {expr}
Bram Moolenaar04186092016-08-29 21:55:35 +02002236atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02002237balloon_gettext() String current text in the balloon
Bram Moolenaar74240d32017-12-10 15:26:15 +01002238balloon_show({expr}) none show {expr} inside the balloon
Bram Moolenaar246fe032017-11-19 19:56:27 +01002239balloon_split({msg}) List split {msg} as used for a balloon
Bram Moolenaar81edd172016-04-14 13:51:37 +02002240browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002241 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02002242browsedir({title}, {initdir}) String put up a directory requester
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002243bufexists({expr}) Number |TRUE| if buffer {expr} exists
2244buflisted({expr}) Number |TRUE| if buffer {expr} is listed
2245bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded
Bram Moolenaar81edd172016-04-14 13:51:37 +02002246bufname({expr}) String Name of the buffer {expr}
2247bufnr({expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002248bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002249bufwinnr({expr}) Number window number of buffer {expr}
2250byte2line({byte}) Number line number at byte count {byte}
2251byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2252byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2253call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002254 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002255ceil({expr}) Float round {expr} up
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002256ch_canread({handle}) Number check if there is something to read
Bram Moolenaar81edd172016-04-14 13:51:37 +02002257ch_close({handle}) none close {handle}
Bram Moolenaar0874a832016-09-01 15:11:51 +02002258ch_close_in({handle}) none close in part of {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002259ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002260 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002261ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002262 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002263ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2264ch_getjob({channel}) Job get the Job of {channel}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002265ch_info({handle}) String info about channel {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002266ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2267ch_logfile({fname} [, {mode}]) none start logging channel activity
2268ch_open({address} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002269 Channel open a channel to {address}
2270ch_read({handle} [, {options}]) String read from {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002271ch_readblob({handle} [, {options}])
2272 Blob read Blob from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002273ch_readraw({handle} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002274 String read raw from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002275ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002276 any send {expr} over JSON {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002277ch_sendraw({handle}, {expr} [, {options}])
2278 any send {expr} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002279ch_setoptions({handle}, {options})
2280 none set options for {handle}
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002281ch_status({handle} [, {options}])
2282 String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002283changenr() Number current change number
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002284char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02002285chdir({dir}) String change current working directory
Bram Moolenaar81edd172016-04-14 13:51:37 +02002286cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002287clearmatches([{win}]) none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002288col({expr}) Number column nr of cursor or mark
2289complete({startcol}, {matches}) none set Insert mode completion
2290complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002291complete_check() Number check for key typed during completion
Bram Moolenaarfd133322019-03-29 12:20:27 +01002292complete_info([{what}]) Dict get current completion information
Bram Moolenaar81edd172016-04-14 13:51:37 +02002293confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002294 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002295copy({expr}) any make a shallow copy of {expr}
2296cos({expr}) Float cosine of {expr}
2297cosh({expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002298count({comp}, {expr} [, {ic} [, {start}]])
2299 Number count how many {expr} are in {comp}
Bram Moolenaardc1f1642016-08-16 18:33:43 +02002300cscope_connection([{num}, {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002301 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02002302cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002303 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002304cursor({list}) Number move cursor to position in {list}
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02002305debugbreak({pid}) Number interrupt process being debugged
Bram Moolenaar81edd172016-04-14 13:51:37 +02002306deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2307delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002308deletebufline({expr}, {first} [, {last}])
Bram Moolenaard79a2622018-06-07 18:17:46 +02002309 Number delete lines from buffer {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002310did_filetype() Number |TRUE| if FileType autocmd event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002311diff_filler({lnum}) Number diff filler lines about {lnum}
2312diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002313empty({expr}) Number |TRUE| if {expr} is empty
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002314environ() Dict return environment variables
Bram Moolenaar81edd172016-04-14 13:51:37 +02002315escape({string}, {chars}) String escape {chars} in {string} with '\'
2316eval({string}) any evaluate {string} into its value
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002317eventhandler() Number |TRUE| if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02002318executable({expr}) Number 1 if executable {expr} exists
Bram Moolenaar79815f12016-07-09 17:07:29 +02002319execute({command}) String execute {command} and get the output
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002320exepath({expr}) String full path of the command {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002321exists({expr}) Number |TRUE| if {expr} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002322extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002323 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002324exp({expr}) Float exponential of {expr}
2325expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002326 any expand special keywords in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002327feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002328filereadable({file}) Number |TRUE| if {file} is a readable file
2329filewritable({file}) Number |TRUE| if {file} is a writable file
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002330filter({expr1}, {expr2}) List/Dict remove items from {expr1} where
2331 {expr2} is 0
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002332finddir({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002333 String find directory {name} in {path}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002334findfile({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002335 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002336float2nr({expr}) Number convert Float {expr} to a Number
2337floor({expr}) Float round {expr} down
2338fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2339fnameescape({fname}) String escape special characters in {fname}
2340fnamemodify({fname}, {mods}) String modify file name
2341foldclosed({lnum}) Number first line of fold at {lnum} if closed
2342foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2343foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002344foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02002345foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002346foreground() Number bring the Vim window to the foreground
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002347funcref({name} [, {arglist}] [, {dict}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002348 Funcref reference to function {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002349function({name} [, {arglist}] [, {dict}])
2350 Funcref named reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002351garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02002352get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2353get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02002354get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002355getbufinfo([{expr}]) List information about buffers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002356getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00002357 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002358getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002359 any variable {varname} in buffer {expr}
Bram Moolenaar07ad8162018-02-13 13:59:59 +01002360getchangelist({expr}) List list of change list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002361getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002362getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02002363getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002364getcmdline() String return the current command-line
2365getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02002366getcmdtype() String return current command-line type
2367getcmdwintype() String return current command-line window type
Bram Moolenaare9d58a62016-08-13 15:07:41 +02002368getcompletion({pat}, {type} [, {filtered}])
2369 List list of cmdline completion matches
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002370getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002371getcwd([{winnr} [, {tabnr}]]) String get the current working directory
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002372getenv({name}) String return environment variable
Bram Moolenaar81edd172016-04-14 13:51:37 +02002373getfontname([{name}]) String name of font being used
2374getfperm({fname}) String file permissions of file {fname}
2375getfsize({fname}) Number size in bytes of file {fname}
2376getftime({fname}) Number last modification time of file
2377getftype({fname}) String description of type of file {fname}
Bram Moolenaar4f505882018-02-10 21:06:32 +01002378getjumplist([{winnr} [, {tabnr}]])
2379 List list of jump list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002380getline({lnum}) String line {lnum} of current buffer
2381getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002382getloclist({nr} [, {what}]) List list of location list items
Bram Moolenaaraff74912019-03-30 18:11:49 +01002383getmatches([{win}]) List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00002384getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002385getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaard823fa92016-08-12 16:29:27 +02002386getqflist([{what}]) List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002387getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02002388 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02002389getregtype([{regname}]) String type of register
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002390gettabinfo([{expr}]) List list of tab pages
Bram Moolenaar81edd172016-04-14 13:51:37 +02002391gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002392 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002393gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002394 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002395gettagstack([{nr}]) Dict get the tag stack of window {nr}
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02002396getwininfo([{winid}]) List list of info about each window
Bram Moolenaar98ef2332018-03-18 14:44:37 +01002397getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01002398getwinposx() Number X coord in pixels of the Vim window
2399getwinposy() Number Y coord in pixels of the Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002400getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002401 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002402glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002403 any expand file wildcards in {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002404glob2regpat({expr}) String convert a glob pat into a search pat
Bram Moolenaar81edd172016-04-14 13:51:37 +02002405globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002406 String do glob({expr}) for all dirs in {path}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002407has({feature}) Number |TRUE| if feature {feature} supported
2408has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002409haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002410 Number |TRUE| if the window executed |:lcd|
Bram Moolenaar00aa0692019-04-27 20:37:57 +02002411 or |:tcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002412hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002413 Number |TRUE| if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002414histadd({history}, {item}) String add an item to a history
2415histdel({history} [, {item}]) String remove an item from a history
2416histget({history} [, {index}]) String get the item {index} from a history
2417histnr({history}) Number highest index of a history
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002418hlexists({name}) Number |TRUE| if highlight group {name} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002419hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002420hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002421iconv({expr}, {from}, {to}) String convert encoding of {expr}
2422indent({lnum}) Number indent of line {lnum}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002423index({object}, {expr} [, {start} [, {ic}]])
2424 Number index in {object} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002425input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002426 String get input from the user
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02002427inputdialog({prompt} [, {text} [, {completion}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002428 String like input() but in a GUI dialog
Bram Moolenaar81edd172016-04-14 13:51:37 +02002429inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002430inputrestore() Number restore typeahead
2431inputsave() Number save and clear typeahead
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002432inputsecret({prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002433insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002434invert({expr}) Number bitwise invert
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002435isdirectory({directory}) Number |TRUE| if {directory} is a directory
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02002436isinf({expr}) Number determine if {expr} is infinity value
2437 (positive or negative)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002438islocked({expr}) Number |TRUE| if {expr} is locked
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002439isnan({expr}) Number |TRUE| if {expr} is NaN
Bram Moolenaar81edd172016-04-14 13:51:37 +02002440items({dict}) List key-value pairs in {dict}
2441job_getchannel({job}) Channel get the channel handle for {job}
Bram Moolenaare1fc5152018-04-21 19:49:08 +02002442job_info([{job}]) Dict get information about {job}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002443job_setoptions({job}, {options}) none set options for {job}
2444job_start({command} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002445 Job start a job
Bram Moolenaar81edd172016-04-14 13:51:37 +02002446job_status({job}) String get the status of {job}
2447job_stop({job} [, {how}]) Number stop {job}
2448join({list} [, {sep}]) String join {list} items into one String
2449js_decode({string}) any decode JS style JSON
2450js_encode({expr}) String encode JS style JSON
2451json_decode({string}) any decode JSON
2452json_encode({expr}) String encode JSON
2453keys({dict}) List keys in {dict}
2454len({expr}) Number the length of {expr}
2455libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002456libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002457line({expr}) Number line nr of cursor, last line or mark
2458line2byte({lnum}) Number byte count of line {lnum}
2459lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar9d401282019-04-06 13:18:12 +02002460list2str({list} [, {utf8}]) String turn numbers in {list} into a String
Bram Moolenaara3347722019-05-11 21:14:24 +02002461listener_add({callback} [, {buf}])
2462 Number add a callback to listen to changes
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02002463listener_flush([{buf}]) none invoke listener callbacks
Bram Moolenaara3347722019-05-11 21:14:24 +02002464listener_remove({id}) none remove a listener callback
Bram Moolenaar071d4272004-06-13 20:20:40 +00002465localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002466log({expr}) Float natural logarithm (base e) of {expr}
2467log10({expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002468luaeval({expr} [, {expr}]) any evaluate |Lua| expression
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002469map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002470maparg({name} [, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002471 String or Dict
2472 rhs of mapping {name} in mode {mode}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002473mapcheck({name} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002474 String check for mappings matching {name}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002475match({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002476 Number position where {pat} matches in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002477matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002478 Number highlight {pattern} with {group}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002479matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002480 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002481matcharg({nr}) List arguments of |:match|
Bram Moolenaaraff74912019-03-30 18:11:49 +01002482matchdelete({id} [, {win}]) Number delete match identified by {id}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002483matchend({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002484 Number position where {pat} ends in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002485matchlist({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002486 List match and submatches of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002487matchstr({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002488 String {count}'th match of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002489matchstrpos({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002490 List {count}'th match of {pat} in {expr}
Bram Moolenaar690afe12017-01-28 18:34:47 +01002491max({expr}) Number maximum value of items in {expr}
2492min({expr}) Number minimum value of items in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002493mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002494 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002495mode([expr]) String current editing mode
2496mzeval({expr}) any evaluate |MzScheme| expression
2497nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002498nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002499or({expr}, {expr}) Number bitwise OR
Bram Moolenaar81edd172016-04-14 13:51:37 +02002500pathshorten({expr}) String shorten directory names in a path
2501perleval({expr}) any evaluate |Perl| expression
2502pow({x}, {y}) Float {x} to the power of {y}
2503prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2504printf({fmt}, {expr1}...) String format text
Bram Moolenaarf2732452018-06-03 14:47:35 +02002505prompt_setcallback({buf}, {expr}) none set prompt callback function
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02002506prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
2507prompt_setprompt({buf}, {text}) none set prompt text
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002508prop_add({lnum}, {col}, {props}) none add a text property
Bram Moolenaare3d31b02018-12-24 23:07:04 +01002509prop_clear({lnum} [, {lnum-end} [, {props}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002510 none remove all text properties
2511prop_find({props} [, {direction}])
2512 Dict search for a text property
Bram Moolenaar5b69c222019-01-11 14:50:06 +01002513prop_list({lnum} [, {props}) List text properties in {lnum}
Bram Moolenaarc8c88492018-12-27 23:59:26 +01002514prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002515 Number remove a text property
2516prop_type_add({name}, {props}) none define a new property type
2517prop_type_change({name}, {props})
2518 none change an existing property type
2519prop_type_delete({name} [, {props}])
2520 none delete a property type
2521prop_type_get([{name} [, {props}])
2522 Dict get property type values
2523prop_type_list([{props}]) List get list of property types
Bram Moolenaar446cb832008-06-24 21:56:24 +00002524pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002525pyeval({expr}) any evaluate |Python| expression
2526py3eval({expr}) any evaluate |python3| expression
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01002527pyxeval({expr}) any evaluate |python_x| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002528range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002529 List items from {expr} to {max}
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02002530readdir({dir} [, {expr}]) List file names in {dir} selected by {expr}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002531readfile({fname} [, {type} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002532 List get list of lines from file {fname}
Bram Moolenaarf2732452018-06-03 14:47:35 +02002533reg_executing() String get the executing register name
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02002534reg_recording() String get the recording register name
Bram Moolenaar81edd172016-04-14 13:51:37 +02002535reltime([{start} [, {end}]]) List get time value
2536reltimefloat({time}) Float turn the time value into a Float
2537reltimestr({time}) String turn time value into a String
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002538remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002539 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002540remote_foreground({server}) Number bring Vim server to the foreground
2541remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002542 Number check for reply string
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002543remote_read({serverid} [, {timeout}])
2544 String read reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002545remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002546 String send key sequence
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01002547remote_startserver({name}) none become server {name}
Bram Moolenaar39536dd2019-01-29 22:58:21 +01002548remove({list}, {idx} [, {end}]) any/List
2549 remove items {idx}-{end} from {list}
2550remove({blob}, {idx} [, {end}]) Number/Blob
2551 remove bytes {idx}-{end} from {blob}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002552remove({dict}, {key}) any remove entry {key} from {dict}
2553rename({from}, {to}) Number rename (move) file from {from} to {to}
2554repeat({expr}, {count}) String repeat {expr} {count} times
2555resolve({filename}) String get filename a shortcut points to
2556reverse({list}) List reverse {list} in-place
2557round({expr}) Float round off {expr}
Bram Moolenaare99be0e2019-03-26 22:51:09 +01002558rubyeval({expr}) any evaluate |Ruby| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002559screenattr({row}, {col}) Number attribute at screen position
2560screenchar({row}, {col}) Number character at screen position
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002561screenchars({row}, {col}) List List of characters at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002562screencol() Number current cursor column
2563screenrow() Number current cursor row
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002564screenstring({row}, {col}) String characters at screen position
Bram Moolenaar81edd172016-04-14 13:51:37 +02002565search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002566 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002567searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002568 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002569searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002570 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002571searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002572 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002573searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002574 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002575server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002576 Number send reply string
2577serverlist() String get a list of available servers
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002578setbufline({expr}, {lnum}, {text})
2579 Number set line {lnum} to {text} in buffer
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02002580 {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002581setbufvar({expr}, {varname}, {val})
2582 none set {varname} in buffer {expr} to {val}
2583setcharsearch({dict}) Dict set character search from {dict}
2584setcmdpos({pos}) Number set cursor position in command-line
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002585setenv({name}, {val}) none set environment variable
Bram Moolenaar81edd172016-04-14 13:51:37 +02002586setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2587setline({lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002588setloclist({nr}, {list} [, {action} [, {what}]])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002589 Number modify location list using {list}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002590setmatches({list} [, {win}]) Number restore a list of matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002591setpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002592setqflist({list} [, {action} [, {what}]])
Bram Moolenaard823fa92016-08-12 16:29:27 +02002593 Number modify quickfix list using {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002594setreg({n}, {v} [, {opt}]) Number set register to value and type
Bram Moolenaar81edd172016-04-14 13:51:37 +02002595settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2596settabwinvar({tabnr}, {winnr}, {varname}, {val})
2597 none set {varname} in window {winnr} in tab
2598 page {tabnr} to {val}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002599settagstack({nr}, {dict} [, {action}])
2600 Number modify tag stack using {dict}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002601setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2602sha256({string}) String SHA256 checksum of {string}
2603shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002604 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002605 command argument
Bram Moolenaarf9514162018-11-22 03:08:29 +01002606shiftwidth([{col}]) Number effective value of 'shiftwidth'
Bram Moolenaar162b7142018-12-21 15:17:36 +01002607sign_define({name} [, {dict}]) Number define or update a sign
2608sign_getdefined([{name}]) List get a list of defined signs
2609sign_getplaced([{expr} [, {dict}]])
2610 List get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01002611sign_jump({id}, {group}, {expr})
2612 Number jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01002613sign_place({id}, {group}, {name}, {expr} [, {dict}])
2614 Number place a sign
2615sign_undefine([{name}]) Number undefine a sign
2616sign_unplace({group} [, {dict}])
2617 Number unplace a sign
Bram Moolenaar81edd172016-04-14 13:51:37 +02002618simplify({filename}) String simplify filename as much as possible
2619sin({expr}) Float sine of {expr}
2620sinh({expr}) Float hyperbolic sine of {expr}
2621sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002622 List sort {list}, using {func} to compare
Bram Moolenaar81edd172016-04-14 13:51:37 +02002623soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002624spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002625spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002626 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002627split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002628 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002629sqrt({expr}) Float square root of {expr}
2630str2float({expr}) Float convert String to Float
Bram Moolenaar9d401282019-04-06 13:18:12 +02002631str2list({expr} [, {utf8}]) List convert each character of {expr} to
2632 ASCII/UTF8 value
Bram Moolenaar81edd172016-04-14 13:51:37 +02002633str2nr({expr} [, {base}]) Number convert String to Number
2634strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002635strcharpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002636 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002637strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002638strftime({format} [, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002639strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002640stridx({haystack}, {needle} [, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002641 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002642string({expr}) String String representation of {expr} value
2643strlen({expr}) Number length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002644strpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002645 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002646strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002647 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002648strtrans({expr}) String translate string to make it printable
2649strwidth({expr}) Number display cell length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002650submatch({nr} [, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002651 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002652substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002653 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar00f123a2018-08-21 20:28:54 +02002654swapinfo({fname}) Dict information about swap file {fname}
Bram Moolenaar110bd602018-09-16 18:46:59 +02002655swapname({expr}) String swap file of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002656synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2657synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002658 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002659synIDtrans({synID}) Number translated syntax ID of {synID}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002660synconcealed({lnum}, {col}) List info about concealing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002661synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2662system({expr} [, {input}]) String output of shell command/filter {expr}
2663systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002664tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002665tabpagenr([{arg}]) Number number of current or last tab page
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002666tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
2667taglist({expr} [, {filename}]) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002668tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002669tan({expr}) Float tangent of {expr}
2670tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002671tempname() String name for a temporary file
Bram Moolenaard96ff162018-02-18 22:13:29 +01002672term_dumpdiff({filename}, {filename} [, {options}])
2673 Number display difference between two dumps
2674term_dumpload({filename} [, {options}])
2675 Number displaying a screen dump
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01002676term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01002677 none dump terminal window contents
Bram Moolenaare41e3b42017-08-11 16:24:50 +02002678term_getaltscreen({buf}) Number get the alternate screen flag
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002679term_getansicolors({buf}) List get ANSI palette in GUI color mode
Bram Moolenaar45356542017-08-06 17:53:31 +02002680term_getattr({attr}, {what}) Number get the value of attribute {what}
Bram Moolenaar97870002017-07-30 18:28:38 +02002681term_getcursor({buf}) List get the cursor position of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002682term_getjob({buf}) Job get the job associated with a terminal
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002683term_getline({buf}, {row}) String get a line of text from a terminal
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02002684term_getscrolled({buf}) Number get the scroll count of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002685term_getsize({buf}) List get the size of a terminal
Bram Moolenaarb000e322017-07-30 19:38:21 +02002686term_getstatus({buf}) String get the status of a terminal
2687term_gettitle({buf}) String get the title of a terminal
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002688term_gettty({buf}, [{input}]) String get the tty name of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002689term_list() List get the list of terminal buffers
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002690term_scrape({buf}, {row}) List get row of a terminal screen
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002691term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002692term_setansicolors({buf}, {colors})
2693 none set ANSI palette in GUI color mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002694term_setkill({buf}, {how}) none set signal to stop job in terminal
Bram Moolenaarb5b75622018-03-09 22:22:21 +01002695term_setrestore({buf}, {command}) none set command to restore terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002696term_setsize({buf}, {rows}, {cols})
2697 none set the size of a terminal
Bram Moolenaar911ead12019-04-21 00:03:35 +02002698term_start({cmd} [, {options}]) Number open a terminal window and run a job
Bram Moolenaarf3402b12017-08-06 19:07:08 +02002699term_wait({buf} [, {time}]) Number wait for screen to be updated
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002700test_alloc_fail({id}, {countdown}, {repeat})
2701 none make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02002702test_autochdir() none enable 'autochdir' during startup
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002703test_feedinput({string}) none add key sequence to input buffer
Bram Moolenaar574860b2016-05-24 17:33:34 +02002704test_garbagecollect_now() none free memory right now for testing
Bram Moolenaareda65222019-05-16 20:29:44 +02002705test_getvalue({string}) any get value of an internal variable
Bram Moolenaare0c31f62017-03-01 15:07:05 +01002706test_ignore_error({expr}) none ignore a specific error
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01002707test_null_blob() Blob null value for testing
Bram Moolenaar574860b2016-05-24 17:33:34 +02002708test_null_channel() Channel null value for testing
2709test_null_dict() Dict null value for testing
2710test_null_job() Job null value for testing
2711test_null_list() List null value for testing
2712test_null_partial() Funcref null value for testing
2713test_null_string() String null value for testing
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002714test_option_not_set({name}) none reset flag indicating option was set
2715test_override({expr}, {val}) none test with Vim internal overrides
Bram Moolenaarc3e92c12019-03-23 14:23:07 +01002716test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaarab186732018-09-14 21:27:06 +02002717test_scrollbar({which}, {value}, {dragging})
2718 none scroll in the GUI for testing
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02002719test_setmouse({row}, {col}) none set the mouse position for testing
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002720test_settime({expr}) none set current time for testing
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02002721timer_info([{id}]) List information about timers
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002722timer_pause({id}, {pause}) none pause or unpause a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002723timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002724 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002725timer_stop({timer}) none stop a timer
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002726timer_stopall() none stop all timers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002727tolower({expr}) String the String {expr} switched to lowercase
2728toupper({expr}) String the String {expr} switched to uppercase
2729tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002730 to chars in {tostr}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002731trim({text} [, {mask}]) String trim characters in {mask} from {text}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002732trunc({expr}) Float truncate Float {expr}
2733type({name}) Number type of variable {name}
2734undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002735undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002736uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002737 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002738values({dict}) List values in {dict}
2739virtcol({expr}) Number screen column of cursor or mark
2740visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002741wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar868b7b62019-05-29 21:44:40 +02002742win_execute({id}, {command} [, {silent}])
2743 String execute {command} in window {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002744win_findbuf({bufnr}) List find windows containing {bufnr}
2745win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2746win_gotoid({expr}) Number go to window with ID {expr}
2747win_id2tabwin({expr}) List get tab and window nr from window ID
2748win_id2win({expr}) Number get window nr from window ID
Bram Moolenaar22044dc2017-12-02 15:43:37 +01002749win_screenpos({nr}) List get screen position of window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002750winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002751wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002752winheight({nr}) Number height of window {nr}
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +02002753winlayout([{tabnr}]) List layout of windows in tab {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002754winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002755winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002756winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002757winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002758winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002759winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002760wordcount() Dict get byte/char/word statistics
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002761writefile({object}, {fname} [, {flags}])
2762 Number write |Blob| or |List| of lines to file
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002763xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002764
Bram Moolenaar03413f42016-04-12 21:07:15 +02002765
Bram Moolenaar446cb832008-06-24 21:56:24 +00002766abs({expr}) *abs()*
2767 Return the absolute value of {expr}. When {expr} evaluates to
2768 a |Float| abs() returns a |Float|. When {expr} can be
2769 converted to a |Number| abs() returns a |Number|. Otherwise
2770 abs() gives an error message and returns -1.
2771 Examples: >
2772 echo abs(1.456)
2773< 1.456 >
2774 echo abs(-5.456)
2775< 5.456 >
2776 echo abs(-4)
2777< 4
2778 {only available when compiled with the |+float| feature}
2779
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002780
2781acos({expr}) *acos()*
2782 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002783 |Float| in the range of [0, pi].
2784 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002785 [-1, 1].
2786 Examples: >
2787 :echo acos(0)
2788< 1.570796 >
2789 :echo acos(-0.5)
2790< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002791 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002792
2793
Bram Moolenaard8968242019-01-15 22:51:57 +01002794add({object}, {expr}) *add()*
2795 Append the item {expr} to |List| or |Blob| {object}. Returns
2796 the resulting |List| or |Blob|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002797 :let alist = add([1, 2, 3], item)
2798 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002799< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002800 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard8968242019-01-15 22:51:57 +01002801 When {object} is a |Blob| then {expr} must be a number.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002802 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002803
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002804
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002805and({expr}, {expr}) *and()*
2806 Bitwise AND on the two arguments. The arguments are converted
2807 to a number. A List, Dict or Float argument causes an error.
2808 Example: >
2809 :let flag = and(bits, 0x80)
2810
2811
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002812append({lnum}, {text}) *append()*
2813 When {text} is a |List|: Append each item of the |List| as a
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002814 text line below line {lnum} in the current buffer.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002815 Otherwise append {text} as one text line below line {lnum} in
Bram Moolenaar748bf032005-02-02 23:04:36 +00002816 the current buffer.
2817 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002818 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar58b85342016-08-14 19:54:54 +02002819 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002820 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002821 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaarca851592018-06-06 21:04:07 +02002822
2823appendbufline({expr}, {lnum}, {text}) *appendbufline()*
2824 Like |append()| but append the text in buffer {expr}.
2825
2826 For the use of {expr}, see |bufname()|.
2827
2828 {lnum} is used like with |append()|. Note that using |line()|
2829 would use the current buffer, not the one appending to.
2830 Use "$" to append at the end of the buffer.
2831
2832 On success 0 is returned, on failure 1 is returned.
2833
2834 If {expr} is not a valid buffer or {lnum} is not valid, an
2835 error message is given. Example: >
2836 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002837<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002838 *argc()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002839argc([{winid}])
2840 The result is the number of files in the argument list. See
2841 |arglist|.
2842 If {winid} is not supplied, the argument list of the current
2843 window is used.
2844 If {winid} is -1, the global argument list is used.
2845 Otherwise {winid} specifies the window of which the argument
2846 list is used: either the window number or the window ID.
2847 Returns -1 if the {winid} argument is invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002848
2849 *argidx()*
2850argidx() The result is the current index in the argument list. 0 is
2851 the first file. argc() - 1 is the last one. See |arglist|.
2852
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002853 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002854arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002855 Return the argument list ID. This is a number which
2856 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002857 global argument list. See |arglist|.
Bram Moolenaare6e39892018-10-25 12:32:11 +02002858 Returns -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002859
2860 Without arguments use the current window.
2861 With {winnr} only use this window in the current tab page.
2862 With {winnr} and {tabnr} use the window in the specified tab
2863 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002864 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002865
Bram Moolenaar071d4272004-06-13 20:20:40 +00002866 *argv()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002867argv([{nr} [, {winid}])
2868 The result is the {nr}th file in the argument list. See
2869 |arglist|. "argv(0)" is the first one. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002870 :let i = 0
2871 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002872 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002873 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2874 : let i = i + 1
2875 :endwhile
Bram Moolenaare6e39892018-10-25 12:32:11 +02002876< Without the {nr} argument, or when {nr} is -1, a |List| with
2877 the whole |arglist| is returned.
2878
2879 The {winid} argument specifies the window ID, see |argc()|.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002880
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002881assert_beeps({cmd}) *assert_beeps()*
2882 Run {cmd} and add an error message to |v:errors| if it does
2883 NOT produce a beep or visual bell.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002884 Also see |assert_fails()| and |assert-return|.
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002885
Bram Moolenaar683fa182015-11-30 21:38:24 +01002886 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002887assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002888 When {expected} and {actual} are not equal an error message is
Bram Moolenaar65a54642018-04-28 16:56:53 +02002889 added to |v:errors| and 1 is returned. Otherwise zero is
2890 returned |assert-return|.
Bram Moolenaar43345542015-11-29 17:35:35 +01002891 There is no automatic conversion, the String "4" is different
2892 from the Number 4. And the number 4 is different from the
2893 Float 4.0. The value of 'ignorecase' is not used here, case
2894 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002895 When {msg} is omitted an error in the form "Expected
2896 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002897 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002898 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002899< Will result in a string to be added to |v:errors|:
2900 test.vim line 12: Expected 'foo' but got 'bar' ~
2901
Bram Moolenaard96ff162018-02-18 22:13:29 +01002902 *assert_equalfile()*
2903assert_equalfile({fname-one}, {fname-two})
2904 When the files {fname-one} and {fname-two} do not contain
2905 exactly the same text an error message is added to |v:errors|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002906 Also see |assert-return|.
Bram Moolenaard96ff162018-02-18 22:13:29 +01002907 When {fname-one} or {fname-two} does not exist the error will
2908 mention that.
2909 Mainly useful with |terminal-diff|.
2910
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002911assert_exception({error} [, {msg}]) *assert_exception()*
2912 When v:exception does not contain the string {error} an error
Bram Moolenaar65a54642018-04-28 16:56:53 +02002913 message is added to |v:errors|. Also see |assert-return|.
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002914 This can be used to assert that a command throws an exception.
2915 Using the error number, followed by a colon, avoids problems
2916 with translations: >
2917 try
2918 commandthatfails
2919 call assert_false(1, 'command should have failed')
2920 catch
2921 call assert_exception('E492:')
2922 endtry
2923
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002924assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()*
Bram Moolenaara260b872016-01-15 20:48:22 +01002925 Run {cmd} and add an error message to |v:errors| if it does
Bram Moolenaar65a54642018-04-28 16:56:53 +02002926 NOT produce an error. Also see |assert-return|.
Bram Moolenaar25de4c22016-11-06 14:48:06 +01002927 When {error} is given it must match in |v:errmsg|.
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002928 Note that beeping is not considered an error, and some failing
2929 commands only beep. Use |assert_beeps()| for those.
Bram Moolenaara260b872016-01-15 20:48:22 +01002930
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002931assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002932 When {actual} is not false an error message is added to
Bram Moolenaar9d87a372018-12-18 21:41:50 +01002933 |v:errors|, like with |assert_equal()|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002934 Also see |assert-return|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002935 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002936 number the assert fails.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002937 When {msg} is omitted an error in the form
2938 "Expected False but got {actual}" is produced.
2939
2940assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()*
Bram Moolenaarf6b40102019-02-22 15:24:03 +01002941 This asserts number and |Float| values. When {actual} is lower
2942 than {lower} or higher than {upper} an error message is added
2943 to |v:errors|. Also see |assert-return|.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002944 When {msg} is omitted an error in the form
2945 "Expected range {lower} - {upper}, but got {actual}" is
2946 produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002947
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002948 *assert_match()*
2949assert_match({pattern}, {actual} [, {msg}])
2950 When {pattern} does not match {actual} an error message is
Bram Moolenaar65a54642018-04-28 16:56:53 +02002951 added to |v:errors|. Also see |assert-return|.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002952
2953 {pattern} is used as with |=~|: The matching is always done
2954 like 'magic' was set and 'cpoptions' is empty, no matter what
2955 the actual value of 'magic' or 'cpoptions' is.
2956
2957 {actual} is used as a string, automatic conversion applies.
2958 Use "^" and "$" to match with the start and end of the text.
2959 Use both to match the whole text.
2960
Bram Moolenaar61c04492016-07-23 15:35:35 +02002961 When {msg} is omitted an error in the form
2962 "Pattern {pattern} does not match {actual}" is produced.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002963 Example: >
2964 assert_match('^f.*o$', 'foobar')
2965< Will result in a string to be added to |v:errors|:
2966 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
2967
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002968 *assert_notequal()*
2969assert_notequal({expected}, {actual} [, {msg}])
2970 The opposite of `assert_equal()`: add an error message to
2971 |v:errors| when {expected} and {actual} are equal.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002972 Also see |assert-return|.
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002973
2974 *assert_notmatch()*
2975assert_notmatch({pattern}, {actual} [, {msg}])
2976 The opposite of `assert_match()`: add an error message to
2977 |v:errors| when {pattern} matches {actual}.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002978 Also see |assert-return|.
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002979
Bram Moolenaar42205552017-03-18 19:42:22 +01002980assert_report({msg}) *assert_report()*
2981 Report a test failure directly, using {msg}.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002982 Always returns one.
Bram Moolenaar42205552017-03-18 19:42:22 +01002983
2984assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002985 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002986 |v:errors|, like with |assert_equal()|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002987 Also see |assert-return|.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002988 A value is TRUE when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002989 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002990 When {msg} is omitted an error in the form "Expected True but
2991 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002992
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002993asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002994 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002995 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002996 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002997 [-1, 1].
2998 Examples: >
2999 :echo asin(0.8)
3000< 0.927295 >
3001 :echo asin(-0.5)
3002< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02003003 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003004
3005
Bram Moolenaar446cb832008-06-24 21:56:24 +00003006atan({expr}) *atan()*
3007 Return the principal value of the arc tangent of {expr}, in
3008 the range [-pi/2, +pi/2] radians, as a |Float|.
3009 {expr} must evaluate to a |Float| or a |Number|.
3010 Examples: >
3011 :echo atan(100)
3012< 1.560797 >
3013 :echo atan(-4.01)
3014< -1.326405
3015 {only available when compiled with the |+float| feature}
3016
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003017
3018atan2({expr1}, {expr2}) *atan2()*
3019 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003020 radians, as a |Float| in the range [-pi, pi].
3021 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003022 Examples: >
3023 :echo atan2(-1, 1)
3024< -0.785398 >
3025 :echo atan2(1, -1)
3026< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02003027 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003028
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003029balloon_gettext() *balloon_gettext()*
3030 Return the current text in the balloon. Only for the string,
3031 not used for the List.
3032
Bram Moolenaar246fe032017-11-19 19:56:27 +01003033balloon_show({expr}) *balloon_show()*
3034 Show {expr} inside the balloon. For the GUI {expr} is used as
3035 a string. For a terminal {expr} can be a list, which contains
3036 the lines of the balloon. If {expr} is not a list it will be
3037 split with |balloon_split()|.
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003038 If {expr} is an empty string any existing balloon is removed.
Bram Moolenaar246fe032017-11-19 19:56:27 +01003039
Bram Moolenaar214641f2017-03-05 17:04:09 +01003040 Example: >
Bram Moolenaar59716a22017-03-01 20:32:44 +01003041 func GetBalloonContent()
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003042 " ... initiate getting the content
Bram Moolenaar59716a22017-03-01 20:32:44 +01003043 return ''
3044 endfunc
3045 set balloonexpr=GetBalloonContent()
3046
3047 func BalloonCallback(result)
Bram Moolenaar214641f2017-03-05 17:04:09 +01003048 call balloon_show(a:result)
Bram Moolenaar59716a22017-03-01 20:32:44 +01003049 endfunc
3050<
3051 The intended use is that fetching the content of the balloon
3052 is initiated from 'balloonexpr'. It will invoke an
3053 asynchronous method, in which a callback invokes
3054 balloon_show(). The 'balloonexpr' itself can return an
3055 empty string or a placeholder.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003056
3057 When showing a balloon is not possible nothing happens, no
3058 error message.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003059 {only available when compiled with the |+balloon_eval| or
3060 |+balloon_eval_term| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003061
Bram Moolenaar246fe032017-11-19 19:56:27 +01003062balloon_split({msg}) *balloon_split()*
3063 Split {msg} into lines to be displayed in a balloon. The
3064 splits are made for the current window size and optimize to
3065 show debugger output.
3066 Returns a |List| with the split lines.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003067 {only available when compiled with the |+balloon_eval_term|
Bram Moolenaar669a8282017-11-19 20:13:05 +01003068 feature}
Bram Moolenaar246fe032017-11-19 19:56:27 +01003069
Bram Moolenaar071d4272004-06-13 20:20:40 +00003070 *browse()*
3071browse({save}, {title}, {initdir}, {default})
3072 Put up a file requester. This only works when "has("browse")"
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003073 returns |TRUE| (only in some GUI versions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003074 The input fields are:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003075 {save} when |TRUE|, select file to write
Bram Moolenaar071d4272004-06-13 20:20:40 +00003076 {title} title for the requester
3077 {initdir} directory to start browsing in
3078 {default} default file name
3079 When the "Cancel" button is hit, something went wrong, or
3080 browsing is not possible, an empty string is returned.
3081
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003082 *browsedir()*
3083browsedir({title}, {initdir})
3084 Put up a directory requester. This only works when
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003085 "has("browse")" returns |TRUE| (only in some GUI versions).
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003086 On systems where a directory browser is not supported a file
3087 browser is used. In that case: select a file in the directory
3088 to be used.
3089 The input fields are:
3090 {title} title for the requester
3091 {initdir} directory to start browsing in
3092 When the "Cancel" button is hit, something went wrong, or
3093 browsing is not possible, an empty string is returned.
3094
Bram Moolenaar071d4272004-06-13 20:20:40 +00003095bufexists({expr}) *bufexists()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003096 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003097 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003098 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaara2a80162017-11-21 23:09:50 +01003099 Number zero is the alternate buffer for the current window.
3100
Bram Moolenaar071d4272004-06-13 20:20:40 +00003101 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003102 exactly. The name can be:
3103 - Relative to the current directory.
3104 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003105 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003106 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003107 Unlisted buffers will be found.
3108 Note that help files are listed by their short name in the
3109 output of |:buffers|, but bufexists() requires using their
3110 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003111 bufexists() may report a buffer exists, but to use the name
3112 with a |:buffer| command you may need to use |expand()|. Esp
3113 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003114 Use "bufexists(0)" to test for the existence of an alternate
3115 file name.
3116 *buffer_exists()*
3117 Obsolete name: buffer_exists().
3118
3119buflisted({expr}) *buflisted()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003120 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003121 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003122 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003123
3124bufloaded({expr}) *bufloaded()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003125 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003126 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003127 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003128
3129bufname({expr}) *bufname()*
3130 The result is the name of a buffer, as it is displayed by the
3131 ":ls" command.
3132 If {expr} is a Number, that buffer number's name is given.
3133 Number zero is the alternate buffer for the current window.
3134 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar58b85342016-08-14 19:54:54 +02003135 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003136 set and 'cpoptions' is empty. When there is more than one
3137 match an empty string is returned.
3138 "" or "%" can be used for the current buffer, "#" for the
3139 alternate buffer.
3140 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003141 or middle of the buffer name is accepted. If you only want a
3142 full match then put "^" at the start and "$" at the end of the
3143 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003144 Listed buffers are found first. If there is a single match
3145 with a listed buffer, that one is returned. Next unlisted
3146 buffers are searched for.
3147 If the {expr} is a String, but you want to use it as a buffer
3148 number, force it to be a Number by adding zero to it: >
3149 :echo bufname("3" + 0)
3150< If the buffer doesn't exist, or doesn't have a name, an empty
3151 string is returned. >
3152 bufname("#") alternate buffer name
3153 bufname(3) name of buffer 3
3154 bufname("%") name of current buffer
3155 bufname("file2") name of buffer where "file2" matches.
3156< *buffer_name()*
3157 Obsolete name: buffer_name().
3158
3159 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003160bufnr({expr} [, {create}])
3161 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00003162 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003163 above.
3164 If the buffer doesn't exist, -1 is returned. Or, if the
3165 {create} argument is present and not zero, a new, unlisted,
3166 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003167 bufnr("$") is the last buffer: >
3168 :let last_buffer = bufnr("$")
3169< The result is a Number, which is the highest buffer number
3170 of existing buffers. Note that not all buffers with a smaller
3171 number necessarily exist, because ":bwipeout" may have removed
3172 them. Use bufexists() to test for the existence of a buffer.
3173 *buffer_number()*
3174 Obsolete name: buffer_number().
3175 *last_buffer_nr()*
3176 Obsolete name for bufnr("$"): last_buffer_nr().
3177
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003178bufwinid({expr}) *bufwinid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02003179 The result is a Number, which is the |window-ID| of the first
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003180 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003181 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003182 there is no such window, -1 is returned. Example: >
3183
3184 echo "A window containing buffer 1 is " . (bufwinid(1))
3185<
3186 Only deals with the current tab page.
3187
Bram Moolenaar071d4272004-06-13 20:20:40 +00003188bufwinnr({expr}) *bufwinnr()*
3189 The result is a Number, which is the number of the first
3190 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003191 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00003192 there is no such window, -1 is returned. Example: >
3193
3194 echo "A window containing buffer 1 is " . (bufwinnr(1))
3195
3196< The number can be used with |CTRL-W_w| and ":wincmd w"
3197 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003198 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003199
Bram Moolenaar071d4272004-06-13 20:20:40 +00003200byte2line({byte}) *byte2line()*
3201 Return the line number that contains the character at byte
3202 count {byte} in the current buffer. This includes the
3203 end-of-line character, depending on the 'fileformat' option
3204 for the current buffer. The first character has byte count
3205 one.
3206 Also see |line2byte()|, |go| and |:goto|.
3207 {not available when compiled without the |+byte_offset|
3208 feature}
3209
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003210byteidx({expr}, {nr}) *byteidx()*
3211 Return byte index of the {nr}'th character in the string
3212 {expr}. Use zero for the first character, it returns zero.
3213 This function is only useful when there are multibyte
3214 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003215 Composing characters are not counted separately, their byte
3216 length is added to the preceding base character. See
3217 |byteidxcomp()| below for counting composing characters
3218 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003219 Example : >
3220 echo matchstr(str, ".", byteidx(str, 3))
3221< will display the fourth character. Another way to do the
3222 same: >
3223 let s = strpart(str, byteidx(str, 3))
3224 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003225< Also see |strgetchar()| and |strcharpart()|.
3226
3227 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003228 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003229 in bytes is returned.
3230
3231byteidxcomp({expr}, {nr}) *byteidxcomp()*
3232 Like byteidx(), except that a composing character is counted
3233 as a separate character. Example: >
3234 let s = 'e' . nr2char(0x301)
3235 echo byteidx(s, 1)
3236 echo byteidxcomp(s, 1)
3237 echo byteidxcomp(s, 2)
3238< The first and third echo result in 3 ('e' plus composing
3239 character is 3 bytes), the second echo results in 1 ('e' is
3240 one byte).
3241 Only works different from byteidx() when 'encoding' is set to
3242 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003243
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003244call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003245 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003246 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003247 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003248 a:firstline and a:lastline are set to the cursor line.
3249 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003250 {dict} is for functions with the "dict" attribute. It will be
3251 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003252
Bram Moolenaar446cb832008-06-24 21:56:24 +00003253ceil({expr}) *ceil()*
3254 Return the smallest integral value greater than or equal to
3255 {expr} as a |Float| (round up).
3256 {expr} must evaluate to a |Float| or a |Number|.
3257 Examples: >
3258 echo ceil(1.456)
3259< 2.0 >
3260 echo ceil(-5.456)
3261< -5.0 >
3262 echo ceil(4.0)
3263< 4.0
3264 {only available when compiled with the |+float| feature}
3265
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003266ch_canread({handle}) *ch_canread()*
3267 Return non-zero when there is something to read from {handle}.
3268 {handle} can be a Channel or a Job that has a Channel.
3269
3270 This is useful to read from a channel at a convenient time,
3271 e.g. from a timer.
3272
3273 Note that messages are dropped when the channel does not have
3274 a callback. Add a close callback to avoid that.
3275
3276 {only available when compiled with the |+channel| feature}
3277
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003278ch_close({handle}) *ch_close()*
3279 Close {handle}. See |channel-close|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003280 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02003281 A close callback is not invoked.
3282
3283 {only available when compiled with the |+channel| feature}
3284
3285ch_close_in({handle}) *ch_close_in()*
3286 Close the "in" part of {handle}. See |channel-close-in|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003287 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02003288 A close callback is not invoked.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003289
Bram Moolenaar835dc632016-02-07 14:27:38 +01003290 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003291
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003292ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
3293 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003294 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01003295 with a raw channel. See |channel-use|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003296 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003297 *E917*
3298 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003299 entry. It can have a "timeout" entry to specify the timeout
3300 for this specific request.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003301
3302 ch_evalexpr() waits for a response and returns the decoded
3303 expression. When there is an error or timeout it returns an
3304 empty string.
3305
3306 {only available when compiled with the |+channel| feature}
3307
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003308ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
3309 Send {string} over {handle}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003310 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003311
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003312 Works like |ch_evalexpr()|, but does not encode the request or
3313 decode the response. The caller is responsible for the
3314 correct contents. Also does not add a newline for a channel
3315 in NL mode, the caller must do that. The NL in the response
3316 is removed.
Bram Moolenaar01164a62017-11-02 22:58:42 +01003317 Note that Vim does not know when the text received on a raw
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003318 channel is complete, it may only return the first part and you
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01003319 need to use |ch_readraw()| to fetch the rest.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003320 See |channel-use|.
3321
3322 {only available when compiled with the |+channel| feature}
3323
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003324ch_getbufnr({handle}, {what}) *ch_getbufnr()*
3325 Get the buffer number that {handle} is using for {what}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003326 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01003327 {what} can be "err" for stderr, "out" for stdout or empty for
3328 socket output.
3329 Returns -1 when there is no buffer.
3330 {only available when compiled with the |+channel| feature}
3331
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003332ch_getjob({channel}) *ch_getjob()*
3333 Get the Job associated with {channel}.
3334 If there is no job calling |job_status()| on the returned Job
3335 will result in "fail".
3336
3337 {only available when compiled with the |+channel| and
3338 |+job| features}
3339
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003340ch_info({handle}) *ch_info()*
3341 Returns a Dictionary with information about {handle}. The
3342 items are:
3343 "id" number of the channel
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003344 "status" "open", "buffered" or "closed", like
3345 ch_status()
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003346 When opened with ch_open():
3347 "hostname" the hostname of the address
3348 "port" the port of the address
3349 "sock_status" "open" or "closed"
3350 "sock_mode" "NL", "RAW", "JSON" or "JS"
3351 "sock_io" "socket"
3352 "sock_timeout" timeout in msec
3353 When opened with job_start():
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003354 "out_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003355 "out_mode" "NL", "RAW", "JSON" or "JS"
3356 "out_io" "null", "pipe", "file" or "buffer"
3357 "out_timeout" timeout in msec
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003358 "err_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003359 "err_mode" "NL", "RAW", "JSON" or "JS"
3360 "err_io" "out", "null", "pipe", "file" or "buffer"
3361 "err_timeout" timeout in msec
3362 "in_status" "open" or "closed"
3363 "in_mode" "NL", "RAW", "JSON" or "JS"
3364 "in_io" "null", "pipe", "file" or "buffer"
3365 "in_timeout" timeout in msec
3366
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003367ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003368 Write {msg} in the channel log file, if it was opened with
3369 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003370 When {handle} is passed the channel number is used for the
3371 message.
Bram Moolenaar51628222016-12-01 23:03:28 +01003372 {handle} can be a Channel or a Job that has a Channel. The
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02003373 Channel must be open for the channel number to be used.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003374
3375ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003376 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003377 When {fname} is an empty string: stop logging.
3378
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003379 When {mode} is omitted or "a" append to the file.
3380 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003381
Bram Moolenaar98aefe72018-12-13 22:20:09 +01003382 Use |ch_log()| to write log messages. The file is flushed
3383 after every message, on Unix you can use "tail -f" to see what
3384 is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003385
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02003386 This function is not available in the |sandbox|.
3387 NOTE: the channel communication is stored in the file, be
3388 aware that this may contain confidential and privacy sensitive
3389 information, e.g. a password you type in a terminal window.
3390
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003391
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003392ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003393 Open a channel to {address}. See |channel|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003394 Returns a Channel. Use |ch_status()| to check for failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003395
3396 {address} has the form "hostname:port", e.g.,
3397 "localhost:8765".
3398
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003399 If {options} is given it must be a |Dictionary|.
3400 See |channel-open-options|.
3401
Bram Moolenaar835dc632016-02-07 14:27:38 +01003402 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003403
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003404ch_read({handle} [, {options}]) *ch_read()*
3405 Read from {handle} and return the received message.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003406 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar74240d32017-12-10 15:26:15 +01003407 For a NL channel this waits for a NL to arrive, except when
3408 there is nothing more to read (channel was closed).
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003409 See |channel-more|.
3410 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003411
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003412ch_readblob({handle} [, {options}]) *ch_readblob()*
Bram Moolenaard09091d2019-01-17 16:07:22 +01003413 Like ch_read() but reads binary data and returns a |Blob|.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003414 See |channel-more|.
3415 {only available when compiled with the |+channel| feature}
3416
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003417ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003418 Like ch_read() but for a JS and JSON channel does not decode
Bram Moolenaar74240d32017-12-10 15:26:15 +01003419 the message. For a NL channel it does not block waiting for
3420 the NL to arrive, but otherwise works like ch_read().
3421 See |channel-more|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003422 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003423
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003424ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
3425 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003426 according to the type of channel. The function cannot be used
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003427 with a raw channel.
3428 See |channel-use|. *E912*
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003429 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003430
Bram Moolenaar835dc632016-02-07 14:27:38 +01003431 {only available when compiled with the |+channel| feature}
3432
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003433ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
Bram Moolenaard09091d2019-01-17 16:07:22 +01003434 Send |String| or |Blob| {expr} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003435 Works like |ch_sendexpr()|, but does not encode the request or
3436 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01003437 correct contents. Also does not add a newline for a channel
3438 in NL mode, the caller must do that. The NL in the response
3439 is removed.
3440 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003441
Bram Moolenaar835dc632016-02-07 14:27:38 +01003442 {only available when compiled with the |+channel| feature}
3443
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003444ch_setoptions({handle}, {options}) *ch_setoptions()*
3445 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003446 "callback" the channel callback
3447 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003448 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003449 See |ch_open()| for more explanation.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003450 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003451
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003452 Note that changing the mode may cause queued messages to be
3453 lost.
3454
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003455 These options cannot be changed:
Bram Moolenaar7571d552016-08-18 22:54:46 +02003456 "waittime" only applies to |ch_open()|
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003457
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003458ch_status({handle} [, {options}]) *ch_status()*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003459 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01003460 "fail" failed to open the channel
3461 "open" channel can be used
Bram Moolenaar06481422016-04-30 15:13:38 +02003462 "buffered" channel can be read, not written to
Bram Moolenaar38a55632016-02-15 22:07:32 +01003463 "closed" channel can not be used
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003464 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar06481422016-04-30 15:13:38 +02003465 "buffered" is used when the channel was closed but there is
3466 still data that can be obtained with |ch_read()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003467
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003468 If {options} is given it can contain a "part" entry to specify
3469 the part of the channel to return the status for: "out" or
3470 "err". For example, to get the error status: >
3471 ch_status(job, {"part": "err"})
3472<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003473changenr() *changenr()*
3474 Return the number of the most recent change. This is the same
3475 number as what is displayed with |:undolist| and can be used
3476 with the |:undo| command.
3477 When a change was made it is the number of that change. After
3478 redo it is the number of the redone change. After undo it is
3479 one less than the number of the undone change.
3480
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003481char2nr({expr} [, {utf8}]) *char2nr()*
Bram Moolenaar214641f2017-03-05 17:04:09 +01003482 Return number value of the first char in {expr}. Examples: >
3483 char2nr(" ") returns 32
3484 char2nr("ABC") returns 65
3485< When {utf8} is omitted or zero, the current 'encoding' is used.
3486 Example for "utf-8": >
Bram Moolenaar98ef2332018-03-18 14:44:37 +01003487 char2nr("á") returns 225
3488 char2nr("á"[0]) returns 195
Bram Moolenaar214641f2017-03-05 17:04:09 +01003489< With {utf8} set to 1, always treat as utf-8 characters.
3490 A combining character is a separate character.
3491 |nr2char()| does the opposite.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003492 To turn a string into a list of character numbers: >
3493 let str = "ABC"
3494 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
3495< Result: [65, 66, 67]
Bram Moolenaar214641f2017-03-05 17:04:09 +01003496
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003497chdir({dir}) *chdir()*
3498 Change the current working directory to {dir}. The scope of
3499 the directory change depends on the directory of the current
3500 window:
3501 - If the current window has a window-local directory
3502 (|:lcd|), then changes the window local directory.
3503 - Otherwise, if the current tabpage has a local
3504 directory (|:tcd|) then changes the tabpage local
3505 directory.
3506 - Otherwise, changes the global directory.
3507 If successful, returns the previous working directory. Pass
3508 this to another chdir() to restore the directory.
3509 On failure, returns an empty string.
3510
3511 Example: >
3512 let save_dir = chdir(newdir)
Bram Moolenaar68e65602019-05-26 21:33:31 +02003513 if save_dir != ""
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003514 " ... do some work
3515 call chdir(save_dir)
3516 endif
3517<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003518cindent({lnum}) *cindent()*
3519 Get the amount of indent for line {lnum} according the C
3520 indenting rules, as with 'cindent'.
3521 The indent is counted in spaces, the value of 'tabstop' is
3522 relevant. {lnum} is used just like in |getline()|.
3523 When {lnum} is invalid or Vim was not compiled the |+cindent|
3524 feature, -1 is returned.
3525 See |C-indenting|.
3526
Bram Moolenaaraff74912019-03-30 18:11:49 +01003527clearmatches([{win}]) *clearmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01003528 Clears all matches previously defined for the current window
3529 by |matchadd()| and the |:match| commands.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003530 If {win} is specified, use the window with this number or
3531 window ID instead of the current window.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003532
3533 *col()*
3534col({expr}) The result is a Number, which is the byte index of the column
3535 position given with {expr}. The accepted positions are:
3536 . the cursor position
3537 $ the end of the cursor line (the result is the
3538 number of bytes in the cursor line plus one)
3539 'x position of mark x (if the mark is not set, 0 is
3540 returned)
3541 v In Visual mode: the start of the Visual area (the
3542 cursor is the end). When not in Visual mode
3543 returns the cursor position. Differs from |'<| in
3544 that it's updated right away.
3545 Additionally {expr} can be [lnum, col]: a |List| with the line
3546 and column number. Most useful when the column is "$", to get
3547 the last column of a specific line. When "lnum" or "col" is
3548 out of range then col() returns zero.
3549 To get the line number use |line()|. To get both use
3550 |getpos()|.
3551 For the screen column position use |virtcol()|.
3552 Note that only marks in the current file can be used.
3553 Examples: >
3554 col(".") column of cursor
3555 col("$") length of cursor line plus one
3556 col("'t") column of mark t
3557 col("'" . markname) column of mark markname
3558< The first column is 1. 0 is returned for an error.
3559 For an uppercase mark the column may actually be in another
3560 buffer.
3561 For the cursor position, when 'virtualedit' is active, the
3562 column is one higher if the cursor is after the end of the
3563 line. This can be used to obtain the column in Insert mode: >
3564 :imap <F2> <C-O>:let save_ve = &ve<CR>
3565 \<C-O>:set ve=all<CR>
3566 \<C-O>:echo col(".") . "\n" <Bar>
3567 \let &ve = save_ve<CR>
3568<
3569
3570complete({startcol}, {matches}) *complete()* *E785*
3571 Set the matches for Insert mode completion.
3572 Can only be used in Insert mode. You need to use a mapping
3573 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3574 or with an expression mapping.
3575 {startcol} is the byte offset in the line where the completed
3576 text start. The text up to the cursor is the original text
3577 that will be replaced by the matches. Use col('.') for an
3578 empty string. "col('.') - 1" will replace one character by a
3579 match.
3580 {matches} must be a |List|. Each |List| item is one match.
3581 See |complete-items| for the kind of items that are possible.
3582 Note that the after calling this function you need to avoid
3583 inserting anything that would cause completion to stop.
3584 The match can be selected with CTRL-N and CTRL-P as usual with
3585 Insert mode completion. The popup menu will appear if
3586 specified, see |ins-completion-menu|.
3587 Example: >
3588 inoremap <F5> <C-R>=ListMonths()<CR>
3589
3590 func! ListMonths()
3591 call complete(col('.'), ['January', 'February', 'March',
3592 \ 'April', 'May', 'June', 'July', 'August', 'September',
3593 \ 'October', 'November', 'December'])
3594 return ''
3595 endfunc
3596< This isn't very useful, but it shows how it works. Note that
3597 an empty string is returned to avoid a zero being inserted.
3598
3599complete_add({expr}) *complete_add()*
3600 Add {expr} to the list of matches. Only to be used by the
3601 function specified with the 'completefunc' option.
3602 Returns 0 for failure (empty string or out of memory),
3603 1 when the match was added, 2 when the match was already in
3604 the list.
3605 See |complete-functions| for an explanation of {expr}. It is
3606 the same as one item in the list that 'omnifunc' would return.
3607
3608complete_check() *complete_check()*
3609 Check for a key typed while looking for completion matches.
3610 This is to be used when looking for matches takes some time.
3611 Returns |TRUE| when searching for matches is to be aborted,
3612 zero otherwise.
3613 Only to be used by the function specified with the
3614 'completefunc' option.
3615
Bram Moolenaarfd133322019-03-29 12:20:27 +01003616 *complete_info()*
3617complete_info([{what}])
3618 Returns a Dictionary with information about Insert mode
3619 completion. See |ins-completion|.
3620 The items are:
3621 mode Current completion mode name string.
Bram Moolenaar723dd942019-04-04 13:11:03 +02003622 See |complete_info_mode| for the values.
Bram Moolenaarfd133322019-03-29 12:20:27 +01003623 pum_visible |TRUE| if popup menu is visible.
3624 See |pumvisible()|.
3625 items List of completion matches. Each item is a
3626 dictionary containing the entries "word",
3627 "abbr", "menu", "kind", "info" and "user_data".
3628 See |complete-items|.
3629 selected Selected item index. First index is zero.
3630 Index is -1 if no item is selected (showing
3631 typed text only)
3632 inserted Inserted string. [NOT IMPLEMENT YET]
3633
3634 *complete_info_mode*
3635 mode values are:
3636 "" Not in completion mode
3637 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
3638 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
3639 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
3640 "files" File names |i_CTRL-X_CTRL-F|
3641 "tags" Tags |i_CTRL-X_CTRL-]|
3642 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
3643 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
3644 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
3645 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
3646 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
3647 "function" User defined completion |i_CTRL-X_CTRL-U|
3648 "omni" Omni completion |i_CTRL-X_CTRL-O|
3649 "spell" Spelling suggestions |i_CTRL-X_s|
3650 "eval" |complete()| completion
3651 "unknown" Other internal modes
3652
3653 If the optional {what} list argument is supplied, then only
3654 the items listed in {what} are returned. Unsupported items in
3655 {what} are silently ignored.
3656
3657 Examples: >
3658 " Get all items
3659 call complete_info()
3660 " Get only 'mode'
3661 call complete_info(['mode'])
3662 " Get only 'mode' and 'pum_visible'
3663 call complete_info(['mode', 'pum_visible'])
3664<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003665 *confirm()*
3666confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar647e24b2019-03-17 16:39:46 +01003667 confirm() offers the user a dialog, from which a choice can be
Bram Moolenaar214641f2017-03-05 17:04:09 +01003668 made. It returns the number of the choice. For the first
3669 choice this is 1.
3670 Note: confirm() is only supported when compiled with dialog
3671 support, see |+dialog_con| and |+dialog_gui|.
3672
3673 {msg} is displayed in a |dialog| with {choices} as the
3674 alternatives. When {choices} is missing or empty, "&OK" is
3675 used (and translated).
3676 {msg} is a String, use '\n' to include a newline. Only on
3677 some systems the string is wrapped when it doesn't fit.
3678
3679 {choices} is a String, with the individual choices separated
3680 by '\n', e.g. >
3681 confirm("Save changes?", "&Yes\n&No\n&Cancel")
3682< The letter after the '&' is the shortcut key for that choice.
3683 Thus you can type 'c' to select "Cancel". The shortcut does
3684 not need to be the first letter: >
3685 confirm("file has been modified", "&Save\nSave &All")
3686< For the console, the first letter of each choice is used as
3687 the default shortcut key.
3688
3689 The optional {default} argument is the number of the choice
3690 that is made if the user hits <CR>. Use 1 to make the first
3691 choice the default one. Use 0 to not set a default. If
3692 {default} is omitted, 1 is used.
3693
3694 The optional {type} argument gives the type of dialog. This
3695 is only used for the icon of the GTK, Mac, Motif and Win32
3696 GUI. It can be one of these values: "Error", "Question",
3697 "Info", "Warning" or "Generic". Only the first character is
3698 relevant. When {type} is omitted, "Generic" is used.
3699
3700 If the user aborts the dialog by pressing <Esc>, CTRL-C,
3701 or another valid interrupt key, confirm() returns 0.
3702
3703 An example: >
3704 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
3705 :if choice == 0
3706 : echo "make up your mind!"
3707 :elseif choice == 3
3708 : echo "tasteful"
3709 :else
3710 : echo "I prefer bananas myself."
3711 :endif
3712< In a GUI dialog, buttons are used. The layout of the buttons
3713 depends on the 'v' flag in 'guioptions'. If it is included,
3714 the buttons are always put vertically. Otherwise, confirm()
3715 tries to put the buttons in one horizontal line. If they
3716 don't fit, a vertical layout is used anyway. For some systems
3717 the horizontal layout is always used.
3718
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003719 *copy()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003720copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003721 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003722 When {expr} is a |List| a shallow copy is created. This means
3723 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003724 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003725 changing an item changes the contents of both |Lists|.
3726 A |Dictionary| is copied in a similar way as a |List|.
3727 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003728
Bram Moolenaar446cb832008-06-24 21:56:24 +00003729cos({expr}) *cos()*
3730 Return the cosine of {expr}, measured in radians, as a |Float|.
3731 {expr} must evaluate to a |Float| or a |Number|.
3732 Examples: >
3733 :echo cos(100)
3734< 0.862319 >
3735 :echo cos(-4.01)
3736< -0.646043
3737 {only available when compiled with the |+float| feature}
3738
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003739
3740cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003741 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003742 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003743 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003744 Examples: >
3745 :echo cosh(0.5)
3746< 1.127626 >
3747 :echo cosh(-0.5)
3748< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02003749 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003750
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003751
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003752count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003753 Return the number of times an item with value {expr} appears
Bram Moolenaar9966b212017-07-28 16:46:57 +02003754 in |String|, |List| or |Dictionary| {comp}.
3755
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003756 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003757 {start} can only be used with a |List|.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003758
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003759 When {ic} is given and it's |TRUE| then case is ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003760
Bram Moolenaar9966b212017-07-28 16:46:57 +02003761 When {comp} is a string then the number of not overlapping
Bram Moolenaar338e47f2017-12-19 11:55:26 +01003762 occurrences of {expr} is returned. Zero is returned when
3763 {expr} is an empty string.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003764
Bram Moolenaar071d4272004-06-13 20:20:40 +00003765 *cscope_connection()*
3766cscope_connection([{num} , {dbpath} [, {prepend}]])
3767 Checks for the existence of a |cscope| connection. If no
3768 parameters are specified, then the function returns:
3769 0, if cscope was not available (not compiled in), or
3770 if there are no cscope connections;
3771 1, if there is at least one cscope connection.
3772
3773 If parameters are specified, then the value of {num}
3774 determines how existence of a cscope connection is checked:
3775
3776 {num} Description of existence check
3777 ----- ------------------------------
3778 0 Same as no parameters (e.g., "cscope_connection()").
3779 1 Ignore {prepend}, and use partial string matches for
3780 {dbpath}.
3781 2 Ignore {prepend}, and use exact string matches for
3782 {dbpath}.
3783 3 Use {prepend}, use partial string matches for both
3784 {dbpath} and {prepend}.
3785 4 Use {prepend}, use exact string matches for both
3786 {dbpath} and {prepend}.
3787
3788 Note: All string comparisons are case sensitive!
3789
3790 Examples. Suppose we had the following (from ":cs show"): >
3791
3792 # pid database name prepend path
3793 0 27664 cscope.out /usr/local
3794<
3795 Invocation Return Val ~
3796 ---------- ---------- >
3797 cscope_connection() 1
3798 cscope_connection(1, "out") 1
3799 cscope_connection(2, "out") 0
3800 cscope_connection(3, "out") 0
3801 cscope_connection(3, "out", "local") 1
3802 cscope_connection(4, "out") 0
3803 cscope_connection(4, "out", "local") 0
3804 cscope_connection(4, "cscope.out", "/usr/local") 1
3805<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003806cursor({lnum}, {col} [, {off}]) *cursor()*
3807cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003808 Positions the cursor at the column (byte count) {col} in the
3809 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003810
Bram Moolenaar0b238792006-03-02 22:49:12 +00003811 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003812 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003813 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003814 [{lnum}, {col}, {off}]
3815 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003816 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003817 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003818
Bram Moolenaar071d4272004-06-13 20:20:40 +00003819 Does not change the jumplist.
3820 If {lnum} is greater than the number of lines in the buffer,
3821 the cursor will be positioned at the last line in the buffer.
3822 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003823 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003824 the cursor will be positioned at the last character in the
3825 line.
3826 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003827 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003828 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003829
Bram Moolenaar0b238792006-03-02 22:49:12 +00003830 When 'virtualedit' is used {off} specifies the offset in
3831 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003832 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003833 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003834
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02003835debugbreak({pid}) *debugbreak()*
3836 Specifically used to interrupt a program being debugged. It
3837 will cause process {pid} to get a SIGTRAP. Behavior for other
3838 processes is undefined. See |terminal-debugger|.
3839 {only available on MS-Windows}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003840
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003841deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003842 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003843 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003844 When {expr} is a |List| a full copy is created. This means
3845 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003846 copy, and vice versa. When an item is a |List| or
3847 |Dictionary|, a copy for it is made, recursively. Thus
3848 changing an item in the copy does not change the contents of
3849 the original |List|.
3850 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003851 When {noref} is omitted or zero a contained |List| or
3852 |Dictionary| is only copied once. All references point to
3853 this single copy. With {noref} set to 1 every occurrence of a
3854 |List| or |Dictionary| results in a new copy. This also means
3855 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003856 *E724*
3857 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003858 that refers back to a higher level making a deep copy with
3859 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003860 Also see |copy()|.
3861
Bram Moolenaarda440d22016-01-16 21:27:23 +01003862delete({fname} [, {flags}]) *delete()*
3863 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003864 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003865
3866 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003867 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003868
Bram Moolenaarda440d22016-01-16 21:27:23 +01003869 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003870 {fname} and everything in it, recursively. BE CAREFUL!
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003871 Note: on MS-Windows it is not possible to delete a directory
3872 that is being used.
Bram Moolenaar818078d2016-08-27 21:58:42 +02003873
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003874 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003875
Bram Moolenaarda440d22016-01-16 21:27:23 +01003876 The result is a Number, which is 0 if the delete operation was
3877 successful and -1 when the deletion failed or partly failed.
3878
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003879 Use |remove()| to delete an item from a |List|.
Bram Moolenaard79a2622018-06-07 18:17:46 +02003880 To delete a line from the buffer use |:delete| or
3881 |deletebufline()|.
3882
Bram Moolenaard473c8c2018-08-11 18:00:22 +02003883deletebufline({expr}, {first} [, {last}]) *deletebufline()*
Bram Moolenaard79a2622018-06-07 18:17:46 +02003884 Delete lines {first} to {last} (inclusive) from buffer {expr}.
3885 If {last} is omitted then delete line {first} only.
3886 On success 0 is returned, on failure 1 is returned.
3887
3888 For the use of {expr}, see |bufname()| above.
3889
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003890 {first} and {last} are used like with |getline()|. Note that
Bram Moolenaard79a2622018-06-07 18:17:46 +02003891 when using |line()| this refers to the current buffer. Use "$"
3892 to refer to the last line in buffer {expr}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003893
3894 *did_filetype()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003895did_filetype() Returns |TRUE| when autocommands are being executed and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003896 FileType event has been triggered at least once. Can be used
3897 to avoid triggering the FileType event again in the scripts
3898 that detect the file type. |FileType|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02003899 Returns |FALSE| when `:setf FALLBACK` was used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003900 When editing another file, the counter is reset, thus this
3901 really checks if the FileType event has been triggered for the
3902 current buffer. This allows an autocommand that starts
3903 editing another buffer to set 'filetype' and load a syntax
3904 file.
3905
Bram Moolenaar47136d72004-10-12 20:02:24 +00003906diff_filler({lnum}) *diff_filler()*
3907 Returns the number of filler lines above line {lnum}.
3908 These are the lines that were inserted at this point in
3909 another diff'ed window. These filler lines are shown in the
3910 display but don't exist in the buffer.
3911 {lnum} is used like with |getline()|. Thus "." is the current
3912 line, "'m" mark m, etc.
3913 Returns 0 if the current window is not in diff mode.
3914
3915diff_hlID({lnum}, {col}) *diff_hlID()*
3916 Returns the highlight ID for diff mode at line {lnum} column
3917 {col} (byte index). When the current line does not have a
3918 diff change zero is returned.
3919 {lnum} is used like with |getline()|. Thus "." is the current
3920 line, "'m" mark m, etc.
3921 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3922 line.
3923 The highlight ID can be used with |synIDattr()| to obtain
3924 syntax information about the highlighting.
3925
Bram Moolenaar691ddee2019-05-09 14:52:41 +02003926environ() *environ()*
3927 Return all of environment variables as dictionary. You can
3928 check if an environment variable exists like this: >
3929 :echo has_key(environ(), 'HOME')
3930< Note that the variable name may be CamelCase; to ignore case
3931 use this: >
3932 :echo index(keys(environ()), 'HOME', 0, 1) != -1
3933
Bram Moolenaar13065c42005-01-08 16:08:21 +00003934empty({expr}) *empty()*
3935 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003936 - A |List| or |Dictionary| is empty when it does not have any
3937 items.
Bram Moolenaard8968242019-01-15 22:51:57 +01003938 - A |String| is empty when its length is zero.
3939 - A |Number| and |Float| are empty when their value is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003940 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
Bram Moolenaard8968242019-01-15 22:51:57 +01003941 - A |Job| is empty when it failed to start.
3942 - A |Channel| is empty when it is closed.
Bram Moolenaard09091d2019-01-17 16:07:22 +01003943 - A |Blob| is empty when its length is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003944
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003945 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003946 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003947
Bram Moolenaar071d4272004-06-13 20:20:40 +00003948escape({string}, {chars}) *escape()*
3949 Escape the characters in {chars} that occur in {string} with a
3950 backslash. Example: >
3951 :echo escape('c:\program files\vim', ' \')
3952< results in: >
3953 c:\\program\ files\\vim
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003954< Also see |shellescape()| and |fnameescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003955
Bram Moolenaar446cb832008-06-24 21:56:24 +00003956 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003957eval({string}) Evaluate {string} and return the result. Especially useful to
3958 turn the result of |string()| back into the original value.
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01003959 This works for Numbers, Floats, Strings, Blobs and composites
3960 of them. Also works for |Funcref|s that refer to existing
Bram Moolenaar446cb832008-06-24 21:56:24 +00003961 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003962
Bram Moolenaar071d4272004-06-13 20:20:40 +00003963eventhandler() *eventhandler()*
3964 Returns 1 when inside an event handler. That is that Vim got
3965 interrupted while waiting for the user to type a character,
3966 e.g., when dropping a file on Vim. This means interactive
3967 commands cannot be used. Otherwise zero is returned.
3968
3969executable({expr}) *executable()*
3970 This function checks if an executable with the name {expr}
3971 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003972 arguments.
3973 executable() uses the value of $PATH and/or the normal
3974 searchpath for programs. *PATHEXT*
3975 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3976 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar58b85342016-08-14 19:54:54 +02003977 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3978 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003979 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar58b85342016-08-14 19:54:54 +02003980 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003981 Unix shell, then the name is also tried without adding an
3982 extension.
3983 On MS-DOS and MS-Windows it only checks if the file exists and
3984 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003985 On MS-Windows an executable in the same directory as Vim is
3986 always found. Since this directory is added to $PATH it
3987 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003988 The result is a Number:
3989 1 exists
3990 0 does not exist
3991 -1 not implemented on this system
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02003992 |exepath()| can be used to get the full path of an executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003993
Bram Moolenaar79815f12016-07-09 17:07:29 +02003994execute({command} [, {silent}]) *execute()*
3995 Execute an Ex command or commands and return the output as a
3996 string.
3997 {command} can be a string or a List. In case of a List the
3998 lines are executed one by one.
3999 This is equivalent to: >
4000 redir => var
4001 {command}
4002 redir END
4003<
4004 The optional {silent} argument can have these values:
4005 "" no `:silent` used
4006 "silent" `:silent` used
4007 "silent!" `:silent!` used
Bram Moolenaar214641f2017-03-05 17:04:09 +01004008 The default is "silent". Note that with "silent!", unlike
Bram Moolenaar069c1e72016-07-15 21:25:08 +02004009 `:redir`, error messages are dropped. When using an external
4010 command the screen may be messed up, use `system()` instead.
Bram Moolenaar79815f12016-07-09 17:07:29 +02004011 *E930*
4012 It is not possible to use `:redir` anywhere in {command}.
4013
4014 To get a list of lines use |split()| on the result: >
Bram Moolenaar063b9d12016-07-09 20:21:48 +02004015 split(execute('args'), "\n")
Bram Moolenaar79815f12016-07-09 17:07:29 +02004016
Bram Moolenaar868b7b62019-05-29 21:44:40 +02004017< To execute a command in another window than the current one
4018 use `win_execute()`.
4019
4020 When used recursively the output of the recursive call is not
Bram Moolenaar79815f12016-07-09 17:07:29 +02004021 included in the output of the higher level call.
4022
Bram Moolenaarc7f02552014-04-01 21:00:59 +02004023exepath({expr}) *exepath()*
4024 If {expr} is an executable and is either an absolute path, a
4025 relative path or found in $PATH, return the full path.
4026 Note that the current directory is used when {expr} starts
4027 with "./", which may be a problem for Vim: >
4028 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02004029< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02004030 an empty string is returned.
4031
Bram Moolenaar071d4272004-06-13 20:20:40 +00004032 *exists()*
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02004033exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
4034 zero otherwise.
4035
4036 For checking for a supported feature use |has()|.
4037 For checking if a file exists use |filereadable()|.
4038
4039 The {expr} argument is a string, which contains one of these:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004040 &option-name Vim option (only checks if it exists,
4041 not if it really works)
4042 +option-name Vim option that works.
4043 $ENVNAME environment variable (could also be
4044 done by comparing with an empty
4045 string)
4046 *funcname built-in function (see |functions|)
4047 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02004048 |user-functions|). Also works for a
4049 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004050 varname internal variable (see
Bram Moolenaar58b85342016-08-14 19:54:54 +02004051 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004052 for |curly-braces-names|, |Dictionary|
4053 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00004054 that evaluating an index may cause an
4055 error message for an invalid
4056 expression. E.g.: >
4057 :let l = [1, 2, 3]
4058 :echo exists("l[5]")
4059< 0 >
4060 :echo exists("l[xx]")
4061< E121: Undefined variable: xx
4062 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00004063 :cmdname Ex command: built-in command, user
4064 command or command modifier |:command|.
4065 Returns:
4066 1 for match with start of a command
4067 2 full match with a command
4068 3 matches several user commands
4069 To check for a supported command
4070 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00004071 :2match The |:2match| command.
4072 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004073 #event autocommand defined for this event
4074 #event#pattern autocommand defined for this event and
4075 pattern (the pattern is taken
4076 literally and compared to the
4077 autocommand patterns character by
4078 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004079 #group autocommand group exists
4080 #group#event autocommand defined for this group and
4081 event.
4082 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004083 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004084 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004085 ##event autocommand for this event is
4086 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004087
4088 Examples: >
4089 exists("&shortname")
4090 exists("$HOSTNAME")
4091 exists("*strftime")
4092 exists("*s:MyFunc")
4093 exists("bufcount")
4094 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004095 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004096 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004097 exists("#filetypeindent")
4098 exists("#filetypeindent#FileType")
4099 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004100 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004101< There must be no space between the symbol (&/$/*/#) and the
4102 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004103 There must be no extra characters after the name, although in
4104 a few cases this is ignored. That may become more strict in
4105 the future, thus don't count on it!
4106 Working example: >
4107 exists(":make")
4108< NOT working example: >
4109 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00004110
4111< Note that the argument must be a string, not the name of the
4112 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004113 exists(bufcount)
4114< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00004115 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004116
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004117exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004118 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004119 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004120 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004121 Examples: >
4122 :echo exp(2)
4123< 7.389056 >
4124 :echo exp(-1)
4125< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02004126 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004127
4128
Bram Moolenaar84f72352012-03-11 15:57:40 +01004129expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004130 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004131 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004132
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004133 If {list} is given and it is |TRUE|, a List will be returned.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004134 Otherwise the result is a String and when there are several
4135 matches, they are separated by <NL> characters. [Note: in
4136 version 5.0 a space was used, which caused problems when a
4137 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004138
Bram Moolenaar58b85342016-08-14 19:54:54 +02004139 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02004140 for a non-existing file is not included, unless {expr} does
4141 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004142
4143 When {expr} starts with '%', '#' or '<', the expansion is done
4144 like for the |cmdline-special| variables with their associated
4145 modifiers. Here is a short overview:
4146
4147 % current file name
4148 # alternate file name
4149 #n alternate file name n
4150 <cfile> file name under the cursor
4151 <afile> autocmd file name
4152 <abuf> autocmd buffer number (as a String!)
4153 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01004154 <sfile> sourced script file or function name
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02004155 <slnum> sourced script line number or function
4156 line number
4157 <sflnum> script file line number, also when in
4158 a function
Bram Moolenaar071d4272004-06-13 20:20:40 +00004159 <cword> word under the cursor
4160 <cWORD> WORD under the cursor
4161 <client> the {clientid} of the last received
4162 message |server2client()|
4163 Modifiers:
4164 :p expand to full path
4165 :h head (last path component removed)
4166 :t tail (last path component only)
4167 :r root (one extension removed)
4168 :e extension only
4169
4170 Example: >
4171 :let &tags = expand("%:p:h") . "/tags"
4172< Note that when expanding a string that starts with '%', '#' or
4173 '<', any following text is ignored. This does NOT work: >
4174 :let doesntwork = expand("%:h.bak")
4175< Use this: >
4176 :let doeswork = expand("%:h") . ".bak"
4177< Also note that expanding "<cfile>" and others only returns the
4178 referenced file name without further expansion. If "<cfile>"
4179 is "~/.cshrc", you need to do another expand() to have the
4180 "~/" expanded into the path of the home directory: >
4181 :echo expand(expand("<cfile>"))
4182<
4183 There cannot be white space between the variables and the
4184 following modifier. The |fnamemodify()| function can be used
4185 to modify normal file names.
4186
4187 When using '%' or '#', and the current or alternate file name
4188 is not defined, an empty string is used. Using "%:p" in a
4189 buffer with no name, results in the current directory, with a
4190 '/' added.
4191
4192 When {expr} does not start with '%', '#' or '<', it is
4193 expanded like a file name is expanded on the command line.
4194 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004195 {nosuf} argument is given and it is |TRUE|.
Bram Moolenaar146e9c32012-03-07 19:18:23 +01004196 Names for non-existing files are included. The "**" item can
4197 be used to search in a directory tree. For example, to find
4198 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00004199 :echo expand("**/README")
4200<
Bram Moolenaar647e24b2019-03-17 16:39:46 +01004201 expand() can also be used to expand variables and environment
Bram Moolenaar071d4272004-06-13 20:20:40 +00004202 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02004203 slow, because a shell may be used to do the expansion. See
4204 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004205 The expanded variable is still handled like a list of file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004206 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004207 left unchanged. Thus ":echo expand('$FOOBAR')" results in
4208 "$FOOBAR".
4209
4210 See |glob()| for finding existing files. See |system()| for
4211 getting the raw output of an external command.
4212
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004213extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004214 {expr1} and {expr2} must be both |Lists| or both
4215 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004216
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004217 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004218 If {expr3} is given insert the items of {expr2} before item
4219 {expr3} in {expr1}. When {expr3} is zero insert before the
4220 first item. When {expr3} is equal to len({expr1}) then
4221 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004222 Examples: >
4223 :echo sort(extend(mylist, [7, 5]))
4224 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00004225< When {expr1} is the same List as {expr2} then the number of
4226 items copied is equal to the original length of the List.
4227 E.g., when {expr3} is 1 you get N new copies of the first item
4228 (where N is the original length of the List).
Bram Moolenaar58b85342016-08-14 19:54:54 +02004229 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004230 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004231 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004232<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004233 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004234 Add all entries from {expr2} to {expr1}.
4235 If a key exists in both {expr1} and {expr2} then {expr3} is
4236 used to decide what to do:
4237 {expr3} = "keep": keep the value of {expr1}
4238 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004239 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004240 When {expr3} is omitted then "force" is assumed.
4241
4242 {expr1} is changed when {expr2} is not empty. If necessary
4243 make a copy of {expr1} first.
4244 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02004245 When {expr1} is locked and {expr2} is not empty the operation
4246 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004247 Returns {expr1}.
4248
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004249
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004250feedkeys({string} [, {mode}]) *feedkeys()*
4251 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004252 come from a mapping or were typed by the user.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004253
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004254 By default the string is added to the end of the typeahead
4255 buffer, thus if a mapping is still being executed the
4256 characters come after them. Use the 'i' flag to insert before
4257 other characters, they will be executed next, before any
4258 characters from a mapping.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004259
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004260 The function does not wait for processing of keys contained in
4261 {string}.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004262
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004263 To include special keys into {string}, use double-quotes
4264 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00004265 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004266 feedkeys('\<CR>') pushes 5 characters.
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02004267 A special code that might be useful is <Ignore>, it exits the
4268 wait for a character without doing anything. *<Ignore>*
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004269
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004270 {mode} is a String, which can contain these character flags:
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004271 'm' Remap keys. This is default. If {mode} is absent,
4272 keys are remapped.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004273 'n' Do not remap keys.
4274 't' Handle keys as if typed; otherwise they are handled as
4275 if coming from a mapping. This matters for undo,
4276 opening folds, etc.
Bram Moolenaar5e66b422019-01-24 21:58:10 +01004277 'L' Lowlevel input. Only works for Unix or when using the
4278 GUI. Keys are used as if they were coming from the
4279 terminal. Other flags are not used. *E980*
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004280 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01004281 'x' Execute commands until typeahead is empty. This is
4282 similar to using ":normal!". You can call feedkeys()
4283 several times without 'x' and then one time with 'x'
4284 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02004285 typeahead. Note that when Vim ends in Insert mode it
4286 will behave as if <Esc> is typed, to avoid getting
4287 stuck, waiting for a character to be typed before the
4288 script continues.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004289 Note that if you manage to call feedkeys() while
Bram Moolenaar5b69c222019-01-11 14:50:06 +01004290 executing commands, thus calling it recursively, then
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004291 all typehead will be consumed by the last call.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004292 '!' When used with 'x' will not end Insert mode. Can be
4293 used in a test when a timer is set to exit Insert mode
4294 a little later. Useful for testing CursorHoldI.
4295
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004296 Return value is always 0.
4297
Bram Moolenaar071d4272004-06-13 20:20:40 +00004298filereadable({file}) *filereadable()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004299 The result is a Number, which is |TRUE| when a file with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004300 name {file} exists, and can be read. If {file} doesn't exist,
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004301 or is a directory, the result is |FALSE|. {file} is any
Bram Moolenaar071d4272004-06-13 20:20:40 +00004302 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004303 If you don't care about the file being readable you can use
4304 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004305 *file_readable()*
4306 Obsolete name: file_readable().
4307
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004308
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004309filewritable({file}) *filewritable()*
4310 The result is a Number, which is 1 when a file with the
4311 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00004312 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004313 directory, and we can write to it, the result is 2.
4314
4315
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004316filter({expr1}, {expr2}) *filter()*
4317 {expr1} must be a |List| or a |Dictionary|.
4318 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004319 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004320 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004321
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004322 If {expr2} is a |string|, inside {expr2} |v:val| has the value
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004323 of the current item. For a |Dictionary| |v:key| has the key
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004324 of the current item and for a |List| |v:key| has the index of
4325 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004326 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004327 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004328< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004329 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004330< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004331 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004332< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004333
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004334 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004335 used as an expression again. Often it is good to use a
4336 |literal-string| to avoid having to double backslashes.
4337
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004338 If {expr2} is a |Funcref| it must take two arguments:
4339 1. the key or the index of the current item.
4340 2. the value of the current item.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004341 The function must return |TRUE| if the item should be kept.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004342 Example that keeps the odd items of a list: >
4343 func Odd(idx, val)
4344 return a:idx % 2 == 1
4345 endfunc
4346 call filter(mylist, function('Odd'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004347< It is shorter when using a |lambda|: >
4348 call filter(myList, {idx, val -> idx * val <= 42})
4349< If you do not use "val" you can leave it out: >
4350 call filter(myList, {idx -> idx % 2 == 1})
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004351<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004352 The operation is done in-place. If you want a |List| or
4353 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00004354 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004355
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004356< Returns {expr1}, the |List| or |Dictionary| that was filtered.
4357 When an error is encountered while evaluating {expr2} no
4358 further items in {expr1} are processed. When {expr2} is a
4359 Funcref errors inside a function are ignored, unless it was
4360 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004361
4362
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004363finddir({name} [, {path} [, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00004364 Find directory {name} in {path}. Supports both downwards and
4365 upwards recursive directory searches. See |file-searching|
4366 for the syntax of {path}.
4367 Returns the path of the first found match. When the found
4368 directory is below the current directory a relative path is
4369 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004370 If {path} is omitted or empty then 'path' is used.
4371 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004372 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00004373 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004374 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004375 {only available when compiled with the |+file_in_path|
4376 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004377
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004378findfile({name} [, {path} [, {count}]]) *findfile()*
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004379 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004380 Uses 'suffixesadd'.
4381 Example: >
4382 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004383< Searches from the directory of the current file upwards until
4384 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004385
Bram Moolenaar446cb832008-06-24 21:56:24 +00004386float2nr({expr}) *float2nr()*
4387 Convert {expr} to a Number by omitting the part after the
4388 decimal point.
4389 {expr} must evaluate to a |Float| or a Number.
4390 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004391 result is truncated to 0x7fffffff or -0x7fffffff (or when
4392 64-bit Number support is enabled, 0x7fffffffffffffff or
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004393 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004394 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00004395 Examples: >
4396 echo float2nr(3.95)
4397< 3 >
4398 echo float2nr(-23.45)
4399< -23 >
4400 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004401< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004402 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004403< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004404 echo float2nr(1.0e-100)
4405< 0
4406 {only available when compiled with the |+float| feature}
4407
4408
4409floor({expr}) *floor()*
4410 Return the largest integral value less than or equal to
4411 {expr} as a |Float| (round down).
4412 {expr} must evaluate to a |Float| or a |Number|.
4413 Examples: >
4414 echo floor(1.856)
4415< 1.0 >
4416 echo floor(-5.456)
4417< -6.0 >
4418 echo floor(4.0)
4419< 4.0
4420 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004421
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004422
4423fmod({expr1}, {expr2}) *fmod()*
4424 Return the remainder of {expr1} / {expr2}, even if the
4425 division is not representable. Returns {expr1} - i * {expr2}
4426 for some integer i such that if {expr2} is non-zero, the
4427 result has the same sign as {expr1} and magnitude less than
4428 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004429 returned is zero. The value returned is a |Float|.
4430 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004431 Examples: >
4432 :echo fmod(12.33, 1.22)
4433< 0.13 >
4434 :echo fmod(-12.33, 1.22)
4435< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02004436 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004437
4438
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004439fnameescape({string}) *fnameescape()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004440 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004441 characters that have a special meaning, such as '%' and '|'
4442 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004443 For most systems the characters escaped are
4444 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
4445 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004446 A leading '+' and '>' is also escaped (special after |:edit|
4447 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004448 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004449 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004450 :exe "edit " . fnameescape(fname)
4451< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004452 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004453
Bram Moolenaar071d4272004-06-13 20:20:40 +00004454fnamemodify({fname}, {mods}) *fnamemodify()*
4455 Modify file name {fname} according to {mods}. {mods} is a
4456 string of characters like it is used for file names on the
4457 command line. See |filename-modifiers|.
4458 Example: >
4459 :echo fnamemodify("main.c", ":p:h")
4460< results in: >
4461 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00004462< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00004463 |expand()| first then.
4464
4465foldclosed({lnum}) *foldclosed()*
4466 The result is a Number. If the line {lnum} is in a closed
4467 fold, the result is the number of the first line in that fold.
4468 If the line {lnum} is not in a closed fold, -1 is returned.
4469
4470foldclosedend({lnum}) *foldclosedend()*
4471 The result is a Number. If the line {lnum} is in a closed
4472 fold, the result is the number of the last line in that fold.
4473 If the line {lnum} is not in a closed fold, -1 is returned.
4474
4475foldlevel({lnum}) *foldlevel()*
4476 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar58b85342016-08-14 19:54:54 +02004477 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004478 returned. If there is no fold at line {lnum}, zero is
4479 returned. It doesn't matter if the folds are open or closed.
4480 When used while updating folds (from 'foldexpr') -1 is
4481 returned for lines where folds are still to be updated and the
4482 foldlevel is unknown. As a special case the level of the
4483 previous line is usually available.
4484
4485 *foldtext()*
4486foldtext() Returns a String, to be displayed for a closed fold. This is
4487 the default function used for the 'foldtext' option and should
4488 only be called from evaluating 'foldtext'. It uses the
4489 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
4490 The returned string looks like this: >
4491 +-- 45 lines: abcdef
Bram Moolenaar42205552017-03-18 19:42:22 +01004492< The number of leading dashes depends on the foldlevel. The
4493 "45" is the number of lines in the fold. "abcdef" is the text
4494 in the first non-blank line of the fold. Leading white space,
4495 "//" or "/*" and the text from the 'foldmarker' and
4496 'commentstring' options is removed.
4497 When used to draw the actual foldtext, the rest of the line
4498 will be filled with the fold char from the 'fillchars'
4499 setting.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004500 {not available when compiled without the |+folding| feature}
4501
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004502foldtextresult({lnum}) *foldtextresult()*
4503 Returns the text that is displayed for the closed fold at line
4504 {lnum}. Evaluates 'foldtext' in the appropriate context.
4505 When there is no closed fold at {lnum} an empty string is
4506 returned.
4507 {lnum} is used like with |getline()|. Thus "." is the current
4508 line, "'m" mark m, etc.
4509 Useful when exporting folded text, e.g., to HTML.
4510 {not available when compiled without the |+folding| feature}
4511
Bram Moolenaar071d4272004-06-13 20:20:40 +00004512 *foreground()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004513foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00004514 a client to a Vim server. |remote_send()|
4515 On Win32 systems this might not work, the OS does not always
4516 allow a window to bring itself to the foreground. Use
4517 |remote_foreground()| instead.
4518 {only in the Win32, Athena, Motif and GTK GUI versions and the
4519 Win32 console version}
4520
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004521 *funcref()*
4522funcref({name} [, {arglist}] [, {dict}])
4523 Just like |function()|, but the returned Funcref will lookup
4524 the function by reference, not by name. This matters when the
4525 function {name} is redefined later.
4526
4527 Unlike |function()|, {name} must be an existing user function.
4528 Also for autoloaded functions. {name} cannot be a builtin
4529 function.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004530
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004531 *function()* *E700* *E922* *E923*
4532function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004533 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01004534 {name} can be the name of a user defined function or an
4535 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004536
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004537 {name} can also be a Funcref or a partial. When it is a
Bram Moolenaar975b5272016-03-15 23:10:59 +01004538 partial the dict stored in it will be used and the {dict}
4539 argument is not allowed. E.g.: >
4540 let FuncWithArg = function(dict.Func, [arg])
4541 let Broken = function(dict.Func, [arg], dict)
4542<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004543 When using the Funcref the function will be found by {name},
4544 also when it was redefined later. Use |funcref()| to keep the
4545 same function.
4546
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004547 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02004548 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004549 the Funcref and will be used when the Funcref is called.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004550
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004551 The arguments are passed to the function in front of other
4552 arguments. Example: >
4553 func Callback(arg1, arg2, name)
4554 ...
4555 let Func = function('Callback', ['one', 'two'])
4556 ...
4557 call Func('name')
4558< Invokes the function as with: >
4559 call Callback('one', 'two', 'name')
4560
Bram Moolenaar03602ec2016-03-20 20:57:45 +01004561< The function() call can be nested to add more arguments to the
4562 Funcref. The extra arguments are appended to the list of
4563 arguments. Example: >
4564 func Callback(arg1, arg2, name)
4565 ...
4566 let Func = function('Callback', ['one'])
4567 let Func2 = function(Func, ['two'])
4568 ...
4569 call Func2('name')
4570< Invokes the function as with: >
4571 call Callback('one', 'two', 'name')
4572
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004573< The Dictionary is only useful when calling a "dict" function.
4574 In that case the {dict} is passed in as "self". Example: >
4575 function Callback() dict
4576 echo "called for " . self.name
4577 endfunction
4578 ...
4579 let context = {"name": "example"}
4580 let Func = function('Callback', context)
4581 ...
4582 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01004583< The use of function() is not needed when there are no extra
4584 arguments, these two are equivalent: >
4585 let Func = function('Callback', context)
4586 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004587
4588< The argument list and the Dictionary can be combined: >
4589 function Callback(arg1, count) dict
4590 ...
4591 let context = {"name": "example"}
4592 let Func = function('Callback', ['one'], context)
4593 ...
4594 call Func(500)
4595< Invokes the function as with: >
4596 call context.Callback('one', 500)
4597
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004598
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004599garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004600 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
4601 that have circular references.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004602
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004603 There is hardly ever a need to invoke this function, as it is
4604 automatically done when Vim runs out of memory or is waiting
4605 for the user to press a key after 'updatetime'. Items without
4606 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004607 This is useful if you have deleted a very big |List| and/or
4608 |Dictionary| with circular references in a script that runs
4609 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004610
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004611 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00004612 collection will also be done when exiting Vim, if it wasn't
4613 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00004614
Bram Moolenaar574860b2016-05-24 17:33:34 +02004615 The garbage collection is not done immediately but only when
4616 it's safe to perform. This is when waiting for the user to
4617 type a character. To force garbage collection immediately use
4618 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004619
Bram Moolenaar677ee682005-01-27 14:41:15 +00004620get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004621 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004622 available return {default}. Return zero when {default} is
4623 omitted.
Bram Moolenaard8968242019-01-15 22:51:57 +01004624get({blob}, {idx} [, {default}])
4625 Get byte {idx} from |Blob| {blob}. When this byte is not
4626 available return {default}. Return -1 when {default} is
4627 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004628get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004629 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004630 item is not available return {default}. Return zero when
4631 {default} is omitted.
Bram Moolenaar03e19a02016-05-24 22:29:49 +02004632get({func}, {what})
4633 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02004634 {what} are:
Bram Moolenaar214641f2017-03-05 17:04:09 +01004635 "name" The function name
4636 "func" The function
4637 "dict" The dictionary
4638 "args" The list with arguments
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004639
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004640 *getbufinfo()*
4641getbufinfo([{expr}])
4642getbufinfo([{dict}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02004643 Get information about buffers as a List of Dictionaries.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004644
4645 Without an argument information about all the buffers is
4646 returned.
4647
4648 When the argument is a Dictionary only the buffers matching
4649 the specified criteria are returned. The following keys can
4650 be specified in {dict}:
4651 buflisted include only listed buffers.
4652 bufloaded include only loaded buffers.
Bram Moolenaar8e6a31d2017-12-10 21:06:22 +01004653 bufmodified include only modified buffers.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004654
4655 Otherwise, {expr} specifies a particular buffer to return
4656 information for. For the use of {expr}, see |bufname()|
4657 above. If the buffer is found the returned List has one item.
4658 Otherwise the result is an empty list.
4659
4660 Each returned List item is a dictionary with the following
4661 entries:
Bram Moolenaar33928832016-08-18 21:22:04 +02004662 bufnr buffer number.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004663 changed TRUE if the buffer is modified.
4664 changedtick number of changes made to the buffer.
4665 hidden TRUE if the buffer is hidden.
4666 listed TRUE if the buffer is listed.
4667 lnum current line number in buffer.
4668 loaded TRUE if the buffer is loaded.
4669 name full path to the file in the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004670 signs list of signs placed in the buffer.
4671 Each list item is a dictionary with
4672 the following fields:
4673 id sign identifier
4674 lnum line number
4675 name sign name
Bram Moolenaar30567352016-08-27 21:25:44 +02004676 variables a reference to the dictionary with
4677 buffer-local variables.
4678 windows list of |window-ID|s that display this
4679 buffer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004680
4681 Examples: >
4682 for buf in getbufinfo()
4683 echo buf.name
4684 endfor
4685 for buf in getbufinfo({'buflisted':1})
Bram Moolenaar30567352016-08-27 21:25:44 +02004686 if buf.changed
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004687 ....
4688 endif
4689 endfor
4690<
Bram Moolenaar30567352016-08-27 21:25:44 +02004691 To get buffer-local options use: >
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004692 getbufvar({bufnr}, '&option_name')
Bram Moolenaar30567352016-08-27 21:25:44 +02004693
4694<
Bram Moolenaar45360022005-07-21 21:08:21 +00004695 *getbufline()*
4696getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004697 Return a |List| with the lines starting from {lnum} to {end}
4698 (inclusive) in the buffer {expr}. If {end} is omitted, a
4699 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004700
4701 For the use of {expr}, see |bufname()| above.
4702
Bram Moolenaar661b1822005-07-28 22:36:45 +00004703 For {lnum} and {end} "$" can be used for the last line of the
4704 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00004705
4706 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004707 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004708
4709 When {end} is greater than the number of lines in the buffer,
4710 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004711 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00004712 returned.
4713
Bram Moolenaar661b1822005-07-28 22:36:45 +00004714 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004715 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004716
4717 Example: >
4718 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004719
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004720getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004721 The result is the value of option or local buffer variable
4722 {varname} in buffer {expr}. Note that the name without "b:"
4723 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004724 When {varname} is empty returns a dictionary with all the
4725 buffer-local variables.
Bram Moolenaar30567352016-08-27 21:25:44 +02004726 When {varname} is equal to "&" returns a dictionary with all
4727 the buffer-local options.
4728 Otherwise, when {varname} starts with "&" returns the value of
4729 a buffer-local option.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004730 This also works for a global or buffer-local option, but it
4731 doesn't work for a global variable, window-local variable or
4732 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004733 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004734 When the buffer or variable doesn't exist {def} or an empty
4735 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004736 Examples: >
4737 :let bufmodified = getbufvar(1, "&mod")
4738 :echo "todo myvar = " . getbufvar("todo", "myvar")
4739<
Bram Moolenaar07ad8162018-02-13 13:59:59 +01004740getchangelist({expr}) *getchangelist()*
4741 Returns the |changelist| for the buffer {expr}. For the use
4742 of {expr}, see |bufname()| above. If buffer {expr} doesn't
4743 exist, an empty list is returned.
4744
4745 The returned list contains two entries: a list with the change
4746 locations and the current position in the list. Each
4747 entry in the change list is a dictionary with the following
4748 entries:
4749 col column number
4750 coladd column offset for 'virtualedit'
4751 lnum line number
4752 If buffer {expr} is the current buffer, then the current
4753 position refers to the position in the list. For other
4754 buffers, it is set to the length of the list.
4755
Bram Moolenaar071d4272004-06-13 20:20:40 +00004756getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00004757 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004758 If [expr] is omitted, wait until a character is available.
4759 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004760 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004761 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00004762 not consumed. Return zero if no character available.
4763
Bram Moolenaardfb18412013-12-11 18:53:29 +01004764 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaarc577d812017-07-08 22:37:34 +02004765 special key is returned. If it is a single character, the
Bram Moolenaar91170f82006-05-05 21:15:17 +00004766 result is a number. Use nr2char() to convert it to a String.
4767 Otherwise a String is returned with the encoded character.
Bram Moolenaarc577d812017-07-08 22:37:34 +02004768 For a special key it's a String with a sequence of bytes
4769 starting with 0x80 (decimal: 128). This is the same value as
4770 the String "\<Key>", e.g., "\<Left>". The returned value is
4771 also a String when a modifier (shift, control, alt) was used
4772 that is not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004773
Bram Moolenaar822ff862014-06-12 21:46:14 +02004774 When [expr] is 0 and Esc is typed, there will be a short delay
4775 while Vim waits to see if this is the start of an escape
4776 sequence.
4777
Bram Moolenaardfb18412013-12-11 18:53:29 +01004778 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00004779 one-byte character it is the character itself as a number.
4780 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004781
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004782 Use getcharmod() to obtain any additional modifiers.
4783
Bram Moolenaar219b8702006-11-01 14:32:36 +00004784 When the user clicks a mouse button, the mouse event will be
4785 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaar511972d2016-06-04 18:09:59 +02004786 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This
4787 example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00004788 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00004789 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00004790 exe v:mouse_win . "wincmd w"
4791 exe v:mouse_lnum
4792 exe "normal " . v:mouse_col . "|"
4793 endif
4794<
Bram Moolenaar690afe12017-01-28 18:34:47 +01004795 When using bracketed paste only the first character is
4796 returned, the rest of the pasted text is dropped.
4797 |xterm-bracketed-paste|.
4798
Bram Moolenaar071d4272004-06-13 20:20:40 +00004799 There is no prompt, you will somehow have to make clear to the
4800 user that a character has to be typed.
4801 There is no mapping for the character.
4802 Key codes are replaced, thus when the user presses the <Del>
4803 key you get the code for the <Del> key, not the raw character
4804 sequence. Examples: >
4805 getchar() == "\<Del>"
4806 getchar() == "\<S-Left>"
4807< This example redefines "f" to ignore case: >
4808 :nmap f :call FindChar()<CR>
4809 :function FindChar()
4810 : let c = nr2char(getchar())
4811 : while col('.') < col('$') - 1
4812 : normal l
4813 : if getline('.')[col('.') - 1] ==? c
4814 : break
4815 : endif
4816 : endwhile
4817 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01004818<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004819 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01004820 |<CursorHold>|. Often you will want to ignore this and get
4821 another character: >
4822 :function GetKey()
4823 : let c = getchar()
4824 : while c == "\<CursorHold>"
4825 : let c = getchar()
4826 : endwhile
4827 : return c
4828 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00004829
4830getcharmod() *getcharmod()*
4831 The result is a Number which is the state of the modifiers for
4832 the last obtained character with getchar() or in another way.
4833 These values are added together:
4834 2 shift
4835 4 control
4836 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004837 16 meta (when it's different from ALT)
4838 32 mouse double click
4839 64 mouse triple click
4840 96 mouse quadruple click (== 32 + 64)
4841 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004842 Only the modifiers that have not been included in the
Bram Moolenaar58b85342016-08-14 19:54:54 +02004843 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004844 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004845
Bram Moolenaardbd24b52015-08-11 14:26:19 +02004846getcharsearch() *getcharsearch()*
4847 Return the current character search information as a {dict}
4848 with the following entries:
4849
4850 char character previously used for a character
4851 search (|t|, |f|, |T|, or |F|); empty string
4852 if no character search has been performed
4853 forward direction of character search; 1 for forward,
4854 0 for backward
4855 until type of character search; 1 for a |t| or |T|
4856 character search, 0 for an |f| or |F|
4857 character search
4858
4859 This can be useful to always have |;| and |,| search
4860 forward/backward regardless of the direction of the previous
4861 character search: >
4862 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4863 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4864< Also see |setcharsearch()|.
4865
Bram Moolenaar071d4272004-06-13 20:20:40 +00004866getcmdline() *getcmdline()*
4867 Return the current command-line. Only works when the command
4868 line is being edited, thus requires use of |c_CTRL-\_e| or
4869 |c_CTRL-R_=|.
4870 Example: >
4871 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004872< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004873 Returns an empty string when entering a password or using
4874 |inputsecret()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004875
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004876getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004877 Return the position of the cursor in the command line as a
4878 byte count. The first column is 1.
4879 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004880 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4881 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004882 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
4883
4884getcmdtype() *getcmdtype()*
4885 Return the current command-line type. Possible return values
4886 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00004887 : normal Ex command
4888 > debug mode command |debug-mode|
4889 / forward search command
4890 ? backward search command
4891 @ |input()| command
4892 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02004893 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004894 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004895 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4896 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004897 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004898
Bram Moolenaarfb539272014-08-22 19:21:47 +02004899getcmdwintype() *getcmdwintype()*
4900 Return the current |command-line-window| type. Possible return
4901 values are the same as |getcmdtype()|. Returns an empty string
4902 when not in the command-line window.
4903
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004904getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004905 Return a list of command-line completion matches. {type}
4906 specifies what for. The following completion types are
4907 supported:
4908
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02004909 arglist file names in argument list
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004910 augroup autocmd groups
4911 buffer buffer names
4912 behave :behave suboptions
4913 color color schemes
4914 command Ex command (and arguments)
4915 compiler compilers
4916 cscope |:cscope| suboptions
4917 dir directory names
4918 environment environment variable names
4919 event autocommand events
4920 expression Vim expression
4921 file file and directory names
4922 file_in_path file and directory names in |'path'|
4923 filetype filetype names |'filetype'|
4924 function function name
4925 help help subjects
4926 highlight highlight groups
4927 history :history suboptions
4928 locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02004929 mapclear buffer argument
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004930 mapping mapping name
4931 menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004932 messages |:messages| suboptions
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004933 option options
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004934 packadd optional package |pack-add| names
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004935 shellcmd Shell command
4936 sign |:sign| suboptions
4937 syntax syntax file names |'syntax'|
4938 syntime |:syntime| suboptions
4939 tag tags
4940 tag_listfiles tags, file names
4941 user user names
4942 var user variables
4943
4944 If {pat} is an empty string, then all the matches are returned.
4945 Otherwise only items matching {pat} are returned. See
4946 |wildcards| for the use of special characters in {pat}.
4947
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004948 If the optional {filtered} flag is set to 1, then 'wildignore'
4949 is applied to filter the results. Otherwise all the matches
4950 are returned. The 'wildignorecase' option always applies.
4951
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004952 If there are no matches, an empty list is returned. An
4953 invalid value for {type} produces an error.
4954
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004955 *getcurpos()*
4956getcurpos() Get the position of the cursor. This is like getpos('.'), but
4957 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01004958 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004959 The "curswant" number is the preferred column when moving the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004960 cursor vertically. Also see |getpos()|.
4961
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004962 This can be used to save and restore the cursor position: >
4963 let save_cursor = getcurpos()
4964 MoveTheCursorAround
4965 call setpos('.', save_cursor)
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004966< Note that this only works within the window. See
4967 |winrestview()| for restoring more state.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004968 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01004969getcwd([{winnr} [, {tabnr}]])
4970 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00004971 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004972
4973 With {winnr} return the local current directory of this window
Bram Moolenaar54591292018-02-09 20:53:59 +01004974 in the current tab page. {winnr} can be the window number or
4975 the |window-ID|.
4976 If {winnr} is -1 return the name of the global working
4977 directory. See also |haslocaldir()|.
4978
Bram Moolenaarc9703302016-01-17 21:49:33 +01004979 With {winnr} and {tabnr} return the local current directory of
Bram Moolenaar00aa0692019-04-27 20:37:57 +02004980 the window in the specified tab page. If {winnr} is -1 return
4981 the working directory of the tabpage.
4982 If {winnr} is zero use the current window, if {tabnr} is zero
4983 use the current tabpage.
4984 Without any arguments, return the working directory of the
4985 current window.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004986 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004987
Bram Moolenaar00aa0692019-04-27 20:37:57 +02004988 Examples: >
4989 " Get the working directory of the current window
4990 :echo getcwd()
4991 :echo getcwd(0)
4992 :echo getcwd(0, 0)
4993 " Get the working directory of window 3 in tabpage 2
4994 :echo getcwd(3, 2)
4995 " Get the global working directory
4996 :echo getcwd(-1)
4997 " Get the working directory of tabpage 3
4998 :echo getcwd(-1, 3)
4999 " Get the working directory of current tabpage
5000 :echo getcwd(-1, 0)
5001<
Bram Moolenaar691ddee2019-05-09 14:52:41 +02005002getenv({name}) *getenv()*
5003 Return the value of environment variable {name}.
5004 When the variable does not exist |v:null| is returned. That
5005 is different from a variable set to an empty string.
5006 See also |expr-env|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005007
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005008getfontname([{name}]) *getfontname()*
5009 Without an argument returns the name of the normal font being
5010 used. Like what is used for the Normal highlight group
5011 |hl-Normal|.
5012 With an argument a check is done whether {name} is a valid
5013 font name. If not then an empty string is returned.
5014 Otherwise the actual font name is returned, or {name} if the
5015 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00005016 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005017 gvimrc file. Use the |GUIEnter| autocommand to use this
5018 function just after the GUI has started.
Bram Moolenaar3df01732017-02-17 22:47:16 +01005019 Note that the GTK GUI accepts any font name, thus checking for
5020 a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005021
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005022getfperm({fname}) *getfperm()*
5023 The result is a String, which is the read, write, and execute
5024 permissions of the given file {fname}.
5025 If {fname} does not exist or its directory cannot be read, an
5026 empty string is returned.
5027 The result is of the form "rwxrwxrwx", where each group of
5028 "rwx" flags represent, in turn, the permissions of the owner
5029 of the file, the group the file belongs to, and other users.
5030 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02005031 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005032 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02005033 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005034< This will hopefully (from a security point of view) display
5035 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005036
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02005037 For setting permissions use |setfperm()|.
Bram Moolenaar80492532016-03-08 17:08:53 +01005038
Bram Moolenaar691ddee2019-05-09 14:52:41 +02005039getfsize({fname}) *getfsize()*
5040 The result is a Number, which is the size in bytes of the
5041 given file {fname}.
5042 If {fname} is a directory, 0 is returned.
5043 If the file {fname} can't be found, -1 is returned.
5044 If the size of {fname} is too big to fit in a Number then -2
5045 is returned.
5046
Bram Moolenaar071d4272004-06-13 20:20:40 +00005047getftime({fname}) *getftime()*
5048 The result is a Number, which is the last modification time of
5049 the given file {fname}. The value is measured as seconds
5050 since 1st Jan 1970, and may be passed to strftime(). See also
5051 |localtime()| and |strftime()|.
5052 If the file {fname} can't be found -1 is returned.
5053
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005054getftype({fname}) *getftype()*
5055 The result is a String, which is a description of the kind of
5056 file of the given file {fname}.
5057 If {fname} does not exist an empty string is returned.
5058 Here is a table over different kinds of files and their
5059 results:
5060 Normal file "file"
5061 Directory "dir"
5062 Symbolic link "link"
5063 Block device "bdev"
5064 Character device "cdev"
5065 Socket "socket"
5066 FIFO "fifo"
5067 All other "other"
5068 Example: >
5069 getftype("/home")
5070< Note that a type such as "link" will only be returned on
5071 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01005072 "file" are returned. On MS-Windows a symbolic link to a
5073 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005074
Bram Moolenaard96ff162018-02-18 22:13:29 +01005075getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
Bram Moolenaar4f505882018-02-10 21:06:32 +01005076 Returns the |jumplist| for the specified window.
5077
5078 Without arguments use the current window.
5079 With {winnr} only use this window in the current tab page.
5080 {winnr} can also be a |window-ID|.
5081 With {winnr} and {tabnr} use the window in the specified tab
5082 page.
5083
5084 The returned list contains two entries: a list with the jump
5085 locations and the last used jump position number in the list.
5086 Each entry in the jump location list is a dictionary with
5087 the following entries:
5088 bufnr buffer number
5089 col column number
5090 coladd column offset for 'virtualedit'
5091 filename filename if available
5092 lnum line number
5093
Bram Moolenaar071d4272004-06-13 20:20:40 +00005094 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005095getline({lnum} [, {end}])
5096 Without {end} the result is a String, which is line {lnum}
5097 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005098 getline(1)
5099< When {lnum} is a String that doesn't start with a
Bram Moolenaarf2732452018-06-03 14:47:35 +02005100 digit, |line()| is called to translate the String into a Number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005101 To get the line under the cursor: >
5102 getline(".")
5103< When {lnum} is smaller than 1 or bigger than the number of
5104 lines in the buffer, an empty string is returned.
5105
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005106 When {end} is given the result is a |List| where each item is
5107 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005108 including line {end}.
5109 {end} is used in the same way as {lnum}.
5110 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005111 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005112 Example: >
5113 :let start = line('.')
5114 :let end = search("^$") - 1
5115 :let lines = getline(start, end)
5116
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005117< To get lines from another buffer see |getbufline()|
5118
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005119getloclist({nr} [, {what}]) *getloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005120 Returns a list with all the entries in the location list for
Bram Moolenaar7571d552016-08-18 22:54:46 +02005121 window {nr}. {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02005122 When {nr} is zero the current window is used.
5123
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005124 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00005125 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005126 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005127
Bram Moolenaard823fa92016-08-12 16:29:27 +02005128 If the optional {what} dictionary argument is supplied, then
5129 returns the items listed in {what} as a dictionary. Refer to
5130 |getqflist()| for the supported items in {what}.
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005131
5132 In addition to the items supported by |getqflist()| in {what},
5133 the following item is supported by |getloclist()|:
5134
Bram Moolenaar68e65602019-05-26 21:33:31 +02005135 filewinid id of the window used to display files
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005136 from the location list. This field is
5137 applicable only when called from a
5138 location list window. See
5139 |location-list-file-window| for more
5140 details.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005141
Bram Moolenaaraff74912019-03-30 18:11:49 +01005142getmatches([{win}]) *getmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01005143 Returns a |List| with all matches previously defined for the
5144 current window by |matchadd()| and the |:match| commands.
5145 |getmatches()| is useful in combination with |setmatches()|,
5146 as |setmatches()| can restore a list of matches saved by
5147 |getmatches()|.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005148 Example: >
5149 :echo getmatches()
5150< [{'group': 'MyGroup1', 'pattern': 'TODO',
5151 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5152 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5153 :let m = getmatches()
5154 :call clearmatches()
5155 :echo getmatches()
5156< [] >
5157 :call setmatches(m)
5158 :echo getmatches()
5159< [{'group': 'MyGroup1', 'pattern': 'TODO',
5160 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5161 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5162 :unlet m
5163<
Bram Moolenaar822ff862014-06-12 21:46:14 +02005164 *getpid()*
5165getpid() Return a Number which is the process ID of the Vim process.
5166 On Unix and MS-Windows this is a unique number, until Vim
Bram Moolenaar58b85342016-08-14 19:54:54 +02005167 exits. On MS-DOS it's always zero.
Bram Moolenaar822ff862014-06-12 21:46:14 +02005168
5169 *getpos()*
5170getpos({expr}) Get the position for {expr}. For possible values of {expr}
5171 see |line()|. For getting the cursor position see
5172 |getcurpos()|.
5173 The result is a |List| with four numbers:
5174 [bufnum, lnum, col, off]
5175 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
5176 is the buffer number of the mark.
5177 "lnum" and "col" are the position in the buffer. The first
5178 column is 1.
5179 The "off" number is zero, unless 'virtualedit' is used. Then
5180 it is the offset in screen columns from the start of the
5181 character. E.g., a position within a <Tab> or after the last
5182 character.
5183 Note that for '< and '> Visual mode matters: when it is "V"
5184 (visual line mode) the column of '< is zero and the column of
5185 '> is a large number.
5186 This can be used to save and restore the position of a mark: >
5187 let save_a_mark = getpos("'a")
5188 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01005189 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02005190< Also see |getcurpos()| and |setpos()|.
5191
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005192
Bram Moolenaard823fa92016-08-12 16:29:27 +02005193getqflist([{what}]) *getqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005194 Returns a list with all the current quickfix errors. Each
5195 list item is a dictionary with these entries:
5196 bufnr number of buffer that has the file name, use
5197 bufname() to get the name
Bram Moolenaard76ce852018-05-01 15:02:04 +02005198 module module name
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005199 lnum line number in the buffer (first line is 1)
5200 col column number (first column is 1)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005201 vcol |TRUE|: "col" is visual column
5202 |FALSE|: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005203 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005204 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005205 text description of the error
5206 type type of the error, 'E', '1', etc.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005207 valid |TRUE|: recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005208
Bram Moolenaar7571d552016-08-18 22:54:46 +02005209 When there is no error list or it's empty, an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005210 returned. Quickfix list entries with non-existing buffer
5211 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00005212
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005213 Useful application: Find pattern matches in multiple files and
5214 do something with them: >
5215 :vimgrep /theword/jg *.c
5216 :for d in getqflist()
5217 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
5218 :endfor
Bram Moolenaard823fa92016-08-12 16:29:27 +02005219<
5220 If the optional {what} dictionary argument is supplied, then
5221 returns only the items listed in {what} as a dictionary. The
5222 following string items are supported in {what}:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005223 changedtick get the total number of changes made
Bram Moolenaar15142e22018-04-30 22:19:58 +02005224 to the list |quickfix-changedtick|
5225 context get the |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02005226 efm errorformat to use when parsing "lines". If
Bram Moolenaar2f058492017-11-30 20:27:52 +01005227 not present, then the 'errorformat' option
Bram Moolenaar36538222017-09-02 19:51:44 +02005228 value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005229 id get information for the quickfix list with
5230 |quickfix-ID|; zero means the id for the
Bram Moolenaar2f058492017-11-30 20:27:52 +01005231 current list or the list specified by "nr"
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005232 idx index of the current entry in the quickfix
5233 list specified by 'id' or 'nr'.
5234 See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02005235 items quickfix list entries
Bram Moolenaar15142e22018-04-30 22:19:58 +02005236 lines parse a list of lines using 'efm' and return
5237 the resulting entries. Only a |List| type is
5238 accepted. The current quickfix list is not
5239 modified. See |quickfix-parse|.
Bram Moolenaar890680c2016-09-27 21:28:56 +02005240 nr get information for this quickfix list; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02005241 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02005242 the last quickfix list
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005243 qfbufnr number of the buffer displayed in the quickfix
5244 window. Returns 0 if the quickfix buffer is
5245 not present. See |quickfix-buffer|.
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02005246 size number of entries in the quickfix list
Bram Moolenaar15142e22018-04-30 22:19:58 +02005247 title get the list title |quickfix-title|
Bram Moolenaar74240d32017-12-10 15:26:15 +01005248 winid get the quickfix |window-ID|
Bram Moolenaard823fa92016-08-12 16:29:27 +02005249 all all of the above quickfix properties
Bram Moolenaar74240d32017-12-10 15:26:15 +01005250 Non-string items in {what} are ignored. To get the value of a
Bram Moolenaara6d48492017-12-12 22:45:31 +01005251 particular item, set it to zero.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005252 If "nr" is not present then the current quickfix list is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005253 If both "nr" and a non-zero "id" are specified, then the list
5254 specified by "id" is used.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005255 To get the number of lists in the quickfix stack, set "nr" to
5256 "$" in {what}. The "nr" value in the returned dictionary
Bram Moolenaar875feea2017-06-11 16:07:51 +02005257 contains the quickfix stack size.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005258 When "lines" is specified, all the other items except "efm"
5259 are ignored. The returned dictionary contains the entry
5260 "items" with the list of entries.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005261
Bram Moolenaard823fa92016-08-12 16:29:27 +02005262 The returned dictionary contains the following entries:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005263 changedtick total number of changes made to the
5264 list |quickfix-changedtick|
Bram Moolenaar15142e22018-04-30 22:19:58 +02005265 context quickfix list context. See |quickfix-context|
Bram Moolenaara6d48492017-12-12 22:45:31 +01005266 If not present, set to "".
5267 id quickfix list ID |quickfix-ID|. If not
5268 present, set to 0.
5269 idx index of the current entry in the list. If not
5270 present, set to 0.
5271 items quickfix list entries. If not present, set to
5272 an empty list.
5273 nr quickfix list number. If not present, set to 0
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005274 qfbufnr number of the buffer displayed in the quickfix
5275 window. If not present, set to 0.
Bram Moolenaara6d48492017-12-12 22:45:31 +01005276 size number of entries in the quickfix list. If not
5277 present, set to 0.
5278 title quickfix list title text. If not present, set
5279 to "".
Bram Moolenaar74240d32017-12-10 15:26:15 +01005280 winid quickfix |window-ID|. If not present, set to 0
Bram Moolenaard823fa92016-08-12 16:29:27 +02005281
Bram Moolenaar15142e22018-04-30 22:19:58 +02005282 Examples (See also |getqflist-examples|): >
Bram Moolenaard823fa92016-08-12 16:29:27 +02005283 :echo getqflist({'all': 1})
5284 :echo getqflist({'nr': 2, 'title': 1})
Bram Moolenaar2c809b72017-09-01 18:34:02 +02005285 :echo getqflist({'lines' : ["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02005286<
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005287getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005288 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005289 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005290 :let cliptext = getreg('*')
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005291< When {regname} was not set the result is an empty string.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005292
5293 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005294 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005295 getreg('=', 1) returns the expression itself, so that it can
5296 be restored with |setreg()|. For other registers the extra
5297 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005298
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005299 If {list} is present and |TRUE|, the result type is changed
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005300 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005301 about zero bytes possibly present inside register: without
5302 third argument both NLs and zero bytes are represented as NLs
5303 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005304 When the register was not set an empty list is returned.
5305
Bram Moolenaar071d4272004-06-13 20:20:40 +00005306 If {regname} is not specified, |v:register| is used.
5307
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005308
Bram Moolenaar071d4272004-06-13 20:20:40 +00005309getregtype([{regname}]) *getregtype()*
5310 The result is a String, which is type of register {regname}.
5311 The value will be one of:
5312 "v" for |characterwise| text
5313 "V" for |linewise| text
5314 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01005315 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00005316 <CTRL-V> is one character with value 0x16.
5317 If {regname} is not specified, |v:register| is used.
5318
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005319gettabinfo([{arg}]) *gettabinfo()*
5320 If {arg} is not specified, then information about all the tab
5321 pages is returned as a List. Each List item is a Dictionary.
5322 Otherwise, {arg} specifies the tab page number and information
5323 about that one is returned. If the tab page does not exist an
5324 empty List is returned.
5325
5326 Each List item is a Dictionary with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02005327 tabnr tab page number.
Bram Moolenaar30567352016-08-27 21:25:44 +02005328 variables a reference to the dictionary with
5329 tabpage-local variables
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005330 windows List of |window-ID|s in the tab page.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005331
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005332gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005333 Get the value of a tab-local variable {varname} in tab page
5334 {tabnr}. |t:var|
5335 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02005336 When {varname} is empty a dictionary with all tab-local
5337 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005338 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005339 When the tab or variable doesn't exist {def} or an empty
5340 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005341
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005342gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005343 Get the value of window-local variable {varname} in window
5344 {winnr} in tab page {tabnr}.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005345 When {varname} is empty a dictionary with all window-local
5346 variables is returned.
Bram Moolenaar30567352016-08-27 21:25:44 +02005347 When {varname} is equal to "&" get the values of all
5348 window-local options in a Dictionary.
5349 Otherwise, when {varname} starts with "&" get the value of a
5350 window-local option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005351 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005352 Tabs are numbered starting with one. For the current tabpage
5353 use |getwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005354 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005355 When {winnr} is zero the current window is used.
5356 This also works for a global option, buffer-local option and
5357 window-local option, but it doesn't work for a global variable
5358 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005359 When the tab, window or variable doesn't exist {def} or an
5360 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005361 Examples: >
5362 :let list_is_on = gettabwinvar(1, 2, '&list')
5363 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005364<
Bram Moolenaarb477af22018-07-15 20:20:18 +02005365 To obtain all window-local variables use: >
5366 gettabwinvar({tabnr}, {winnr}, '&')
5367
Bram Moolenaarf49cc602018-11-11 15:21:05 +01005368gettagstack([{nr}]) *gettagstack()*
5369 The result is a Dict, which is the tag stack of window {nr}.
5370 {nr} can be the window number or the |window-ID|.
5371 When {nr} is not specified, the current window is used.
5372 When window {nr} doesn't exist, an empty Dict is returned.
5373
5374 The returned dictionary contains the following entries:
5375 curidx Current index in the stack. When at
5376 top of the stack, set to (length + 1).
5377 Index of bottom of the stack is 1.
5378 items List of items in the stack. Each item
5379 is a dictionary containing the
5380 entries described below.
5381 length Number of entries in the stack.
5382
5383 Each item in the stack is a dictionary with the following
5384 entries:
5385 bufnr buffer number of the current jump
5386 from cursor position before the tag jump.
5387 See |getpos()| for the format of the
5388 returned list.
5389 matchnr current matching tag number. Used when
5390 multiple matching tags are found for a
5391 name.
5392 tagname name of the tag
5393
5394 See |tagstack| for more information about the tag stack.
5395
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005396getwininfo([{winid}]) *getwininfo()*
5397 Returns information about windows as a List with Dictionaries.
5398
5399 If {winid} is given Information about the window with that ID
5400 is returned. If the window does not exist the result is an
5401 empty list.
5402
5403 Without {winid} information about all the windows in all the
5404 tab pages is returned.
5405
5406 Each List item is a Dictionary with the following entries:
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01005407 botline last displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005408 bufnr number of buffer in the window
5409 height window height (excluding winbar)
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005410 loclist 1 if showing a location list
5411 {only with the +quickfix feature}
5412 quickfix 1 if quickfix or location list window
5413 {only with the +quickfix feature}
5414 terminal 1 if a terminal window
5415 {only with the +terminal feature}
5416 tabnr tab page number
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01005417 topline first displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005418 variables a reference to the dictionary with
5419 window-local variables
5420 width window width
Bram Moolenaarb477af22018-07-15 20:20:18 +02005421 winbar 1 if the window has a toolbar, 0
5422 otherwise
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005423 wincol leftmost screen column of the window,
5424 col from |win_screenpos()|
5425 winid |window-ID|
5426 winnr window number
5427 winrow topmost screen column of the window,
5428 row from |win_screenpos()|
5429
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005430getwinpos([{timeout}]) *getwinpos()*
5431 The result is a list with two numbers, the result of
Bram Moolenaar9d87a372018-12-18 21:41:50 +01005432 getwinposx() and getwinposy() combined:
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005433 [x-pos, y-pos]
5434 {timeout} can be used to specify how long to wait in msec for
5435 a response from the terminal. When omitted 100 msec is used.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005436 Use a longer time for a remote terminal.
5437 When using a value less than 10 and no response is received
5438 within that time, a previously reported position is returned,
5439 if available. This can be used to poll for the position and
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005440 do some work in the meantime: >
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005441 while 1
5442 let res = getwinpos(1)
5443 if res[0] >= 0
5444 break
5445 endif
5446 " Do some work here
5447 endwhile
5448<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005449 *getwinposx()*
5450getwinposx() The result is a Number, which is the X coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005451 the left hand side of the GUI Vim window. Also works for an
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005452 xterm (uses a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005453 The result will be -1 if the information is not available.
5454 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005455
5456 *getwinposy()*
5457getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005458 the top of the GUI Vim window. Also works for an xterm (uses
5459 a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005460 The result will be -1 if the information is not available.
5461 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005462
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005463getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005464 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005465 Examples: >
5466 :let list_is_on = getwinvar(2, '&list')
5467 :echo "myvar = " . getwinvar(1, 'myvar')
5468<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005469glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005470 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005471 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005472
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005473 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005474 the 'suffixes' and 'wildignore' options apply: Names matching
5475 one of the patterns in 'wildignore' will be skipped and
5476 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01005477 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005478
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005479 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar84f72352012-03-11 15:57:40 +01005480 with all matching files. The advantage of using a List is,
5481 you also get filenames containing newlines correctly.
5482 Otherwise the result is a String and when there are several
5483 matches, they are separated by <NL> characters.
5484
5485 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005486
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02005487 You can also use |readdir()| if you need to do complicated
5488 things, such as limiting the number of matches.
5489
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005490 A name for a non-existing file is not included. A symbolic
5491 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005492 However, when the {alllinks} argument is present and it is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005493 |TRUE| then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005494
5495 For most systems backticks can be used to get files names from
5496 any external command. Example: >
5497 :let tagfiles = glob("`find . -name tags -print`")
5498 :let &tags = substitute(tagfiles, "\n", ",", "g")
5499< The result of the program inside the backticks should be one
Bram Moolenaar58b85342016-08-14 19:54:54 +02005500 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005501
5502 See |expand()| for expanding special Vim variables. See
5503 |system()| for getting the raw output of an external command.
5504
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01005505glob2regpat({expr}) *glob2regpat()*
5506 Convert a file pattern, as used by glob(), into a search
5507 pattern. The result can be used to match with a string that
5508 is a file name. E.g. >
5509 if filename =~ glob2regpat('Make*.mak')
5510< This is equivalent to: >
5511 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005512< When {expr} is an empty string the result is "^$", match an
5513 empty string.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005514 Note that the result depends on the system. On MS-Windows
Bram Moolenaar58b85342016-08-14 19:54:54 +02005515 a backslash usually means a path separator.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005516
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005517 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005518globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00005519 Perform glob() on all directories in {path} and concatenate
5520 the results. Example: >
5521 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005522<
5523 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00005524 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005525 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005526 To add a comma inside a directory name escape it with a
5527 backslash. Note that on MS-Windows a directory may have a
5528 trailing backslash, remove it if you put a comma after it.
5529 If the expansion fails for one of the directories, there is no
5530 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005531
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005532 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005533 the 'suffixes' and 'wildignore' options apply: Names matching
5534 one of the patterns in 'wildignore' will be skipped and
5535 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005536
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005537 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005538 with all matching files. The advantage of using a List is, you
5539 also get filenames containing newlines correctly. Otherwise
5540 the result is a String and when there are several matches,
5541 they are separated by <NL> characters. Example: >
5542 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5543<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005544 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005545
Bram Moolenaar02743632005-07-25 20:42:36 +00005546 The "**" item can be used to search in a directory tree.
5547 For example, to find all "README.txt" files in the directories
5548 in 'runtimepath' and below: >
5549 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00005550< Upwards search and limiting the depth of "**" is not
5551 supported, thus using 'path' will not always work properly.
5552
Bram Moolenaar071d4272004-06-13 20:20:40 +00005553 *has()*
5554has({feature}) The result is a Number, which is 1 if the feature {feature} is
5555 supported, zero otherwise. The {feature} argument is a
5556 string. See |feature-list| below.
5557 Also see |exists()|.
5558
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005559
5560has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005561 The result is a Number, which is 1 if |Dictionary| {dict} has
5562 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005563
Bram Moolenaarc9703302016-01-17 21:49:33 +01005564haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005565 The result is a Number:
5566 1 when the window has set a local directory via |:lcd|
5567 2 when the tab-page has set a local directory via |:tcd|
5568 0 otherwise.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005569
5570 Without arguments use the current window.
5571 With {winnr} use this window in the current tab page.
5572 With {winnr} and {tabnr} use the window in the specified tab
5573 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005574 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005575 If {winnr} is -1 it is ignored and only the tabpage is used.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005576 Return 0 if the arguments are invalid.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005577 Examples: >
5578 if haslocaldir() == 1
5579 " window local directory case
5580 elseif haslocaldir() == 2
5581 " tab-local directory case
5582 else
5583 " global directory case
5584 endif
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005585
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005586 " current window
5587 :echo haslocaldir()
5588 :echo haslocaldir(0)
5589 :echo haslocaldir(0, 0)
5590 " window n in current tab page
5591 :echo haslocaldir(n)
5592 :echo haslocaldir(n, 0)
5593 " window n in tab page m
5594 :echo haslocaldir(n, m)
5595 " tab page m
5596 :echo haslocaldir(-1, m)
5597<
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005598hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005599 The result is a Number, which is 1 if there is a mapping that
5600 contains {what} in somewhere in the rhs (what it is mapped to)
5601 and this mapping exists in one of the modes indicated by
5602 {mode}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005603 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00005604 instead of mappings. Don't forget to specify Insert and/or
5605 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005606 Both the global mappings and the mappings local to the current
5607 buffer are checked for a match.
5608 If no matching mapping is found 0 is returned.
5609 The following characters are recognized in {mode}:
5610 n Normal mode
5611 v Visual mode
5612 o Operator-pending mode
5613 i Insert mode
5614 l Language-Argument ("r", "f", "t", etc.)
5615 c Command-line mode
5616 When {mode} is omitted, "nvo" is used.
5617
5618 This function is useful to check if a mapping already exists
Bram Moolenaar58b85342016-08-14 19:54:54 +02005619 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005620 :if !hasmapto('\ABCdoit')
5621 : map <Leader>d \ABCdoit
5622 :endif
5623< This installs the mapping to "\ABCdoit" only if there isn't
5624 already a mapping to "\ABCdoit".
5625
5626histadd({history}, {item}) *histadd()*
5627 Add the String {item} to the history {history} which can be
5628 one of: *hist-names*
5629 "cmd" or ":" command line history
5630 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00005631 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00005632 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005633 "debug" or ">" debug command history
Bram Moolenaar3e496b02016-09-25 22:11:48 +02005634 empty the current or last used history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005635 The {history} string does not need to be the whole name, one
5636 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005637 If {item} does already exist in the history, it will be
5638 shifted to become the newest entry.
5639 The result is a Number: 1 if the operation was successful,
5640 otherwise 0 is returned.
5641
5642 Example: >
5643 :call histadd("input", strftime("%Y %b %d"))
5644 :let date=input("Enter date: ")
5645< This function is not available in the |sandbox|.
5646
5647histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005648 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005649 for the possible values of {history}.
5650
Bram Moolenaarc236c162008-07-13 17:41:49 +00005651 If the parameter {item} evaluates to a String, it is used as a
5652 regular expression. All entries matching that expression will
5653 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005654 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00005655 If {item} evaluates to a Number, it will be interpreted as
5656 an index, see |:history-indexing|. The respective entry will
5657 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005658
5659 The result is a Number: 1 for a successful operation,
5660 otherwise 0 is returned.
5661
5662 Examples:
5663 Clear expression register history: >
5664 :call histdel("expr")
5665<
5666 Remove all entries starting with "*" from the search history: >
5667 :call histdel("/", '^\*')
5668<
5669 The following three are equivalent: >
5670 :call histdel("search", histnr("search"))
5671 :call histdel("search", -1)
5672 :call histdel("search", '^'.histget("search", -1).'$')
5673<
5674 To delete the last search pattern and use the last-but-one for
5675 the "n" command and 'hlsearch': >
5676 :call histdel("search", -1)
5677 :let @/ = histget("search", -1)
5678
5679histget({history} [, {index}]) *histget()*
5680 The result is a String, the entry with Number {index} from
5681 {history}. See |hist-names| for the possible values of
5682 {history}, and |:history-indexing| for {index}. If there is
5683 no such entry, an empty String is returned. When {index} is
5684 omitted, the most recent item from the history is used.
5685
5686 Examples:
5687 Redo the second last search from history. >
5688 :execute '/' . histget("search", -2)
5689
5690< Define an Ex command ":H {num}" that supports re-execution of
5691 the {num}th entry from the output of |:history|. >
5692 :command -nargs=1 H execute histget("cmd", 0+<args>)
5693<
5694histnr({history}) *histnr()*
5695 The result is the Number of the current entry in {history}.
5696 See |hist-names| for the possible values of {history}.
5697 If an error occurred, -1 is returned.
5698
5699 Example: >
5700 :let inp_index = histnr("expr")
5701<
5702hlexists({name}) *hlexists()*
5703 The result is a Number, which is non-zero if a highlight group
5704 called {name} exists. This is when the group has been
5705 defined in some way. Not necessarily when highlighting has
5706 been defined for it, it may also have been used for a syntax
5707 item.
5708 *highlight_exists()*
5709 Obsolete name: highlight_exists().
5710
5711 *hlID()*
5712hlID({name}) The result is a Number, which is the ID of the highlight group
5713 with name {name}. When the highlight group doesn't exist,
5714 zero is returned.
5715 This can be used to retrieve information about the highlight
Bram Moolenaar58b85342016-08-14 19:54:54 +02005716 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005717 "Comment" group: >
5718 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5719< *highlightID()*
5720 Obsolete name: highlightID().
5721
5722hostname() *hostname()*
5723 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005724 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00005725 256 characters long are truncated.
5726
5727iconv({expr}, {from}, {to}) *iconv()*
5728 The result is a String, which is the text {expr} converted
5729 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005730 When the conversion completely fails an empty string is
5731 returned. When some characters could not be converted they
5732 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005733 The encoding names are whatever the iconv() library function
5734 can accept, see ":!man 3 iconv".
5735 Most conversions require Vim to be compiled with the |+iconv|
5736 feature. Otherwise only UTF-8 to latin1 conversion and back
5737 can be done.
5738 This can be used to display messages with special characters,
5739 no matter what 'encoding' is set to. Write the message in
5740 UTF-8 and use: >
5741 echo iconv(utf8_str, "utf-8", &enc)
5742< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5743 from/to UCS-2 is automatically changed to use UTF-8. You
5744 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005745
5746 *indent()*
5747indent({lnum}) The result is a Number, which is indent of line {lnum} in the
5748 current buffer. The indent is counted in spaces, the value
5749 of 'tabstop' is relevant. {lnum} is used just like in
5750 |getline()|.
5751 When {lnum} is invalid -1 is returned.
5752
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005753
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005754index({object}, {expr} [, {start} [, {ic}]]) *index()*
5755 If {object} is a |List| return the lowest index where the item
5756 has a value equal to {expr}. There is no automatic
5757 conversion, so the String "4" is different from the Number 4.
5758 And the number 4 is different from the Float 4.0. The value
5759 of 'ignorecase' is not used here, case always matters.
5760
5761 If {object} is |Blob| return the lowest index where the byte
5762 value is equal to {expr}.
5763
Bram Moolenaar748bf032005-02-02 23:04:36 +00005764 If {start} is given then start looking at the item with index
5765 {start} (may be negative for an item relative to the end).
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005766 When {ic} is given and it is |TRUE|, ignore case. Otherwise
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005767 case must match.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005768 -1 is returned when {expr} is not found in {object}.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005769 Example: >
5770 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005771 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005772
5773
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005774input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005775 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005776 the command-line. The {prompt} argument is either a prompt
5777 string, or a blank string (for no prompt). A '\n' can be used
5778 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005779 The highlighting set with |:echohl| is used for the prompt.
5780 The input is entered just like a command-line, with the same
Bram Moolenaar58b85342016-08-14 19:54:54 +02005781 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005782 for lines typed for input().
5783 Example: >
5784 :if input("Coffee or beer? ") == "beer"
5785 : echo "Cheers!"
5786 :endif
5787<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005788 If the optional {text} argument is present and not empty, this
5789 is used for the default reply, as if the user typed this.
5790 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005791 :let color = input("Color? ", "white")
5792
5793< The optional {completion} argument specifies the type of
5794 completion supported for the input. Without it completion is
Bram Moolenaar58b85342016-08-14 19:54:54 +02005795 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005796 that can be supplied to a user-defined command using the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005797 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005798 more information. Example: >
5799 let fname = input("File: ", "", "file")
5800<
5801 NOTE: This function must not be used in a startup file, for
5802 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005803 Note: When input() is called from within a mapping it will
5804 consume remaining characters from that mapping, because a
5805 mapping is handled like the characters were typed.
5806 Use |inputsave()| before input() and |inputrestore()|
5807 after input() to avoid that. Another solution is to avoid
5808 that further characters follow in the mapping, e.g., by using
5809 |:execute| or |:normal|.
5810
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005811 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005812 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
5813 :function GetFoo()
5814 : call inputsave()
5815 : let g:Foo = input("enter search pattern: ")
5816 : call inputrestore()
5817 :endfunction
5818
5819inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005820 Like |input()|, but when the GUI is running and text dialogs
5821 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005822 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02005823 :let n = inputdialog("value for shiftwidth", shiftwidth())
5824 :if n != ""
5825 : let &sw = n
5826 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00005827< When the dialog is cancelled {cancelreturn} is returned. When
5828 omitted an empty string is returned.
5829 Hitting <Enter> works like pressing the OK button. Hitting
5830 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005831 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005832
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005833inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005834 {textlist} must be a |List| of strings. This |List| is
5835 displayed, one string per line. The user will be prompted to
5836 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005837 The user can also select an item by clicking on it with the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005838 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005839 above the first item a negative number is returned. When
5840 clicking on the prompt one more than the length of {textlist}
5841 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005842 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar58b85342016-08-14 19:54:54 +02005843 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005844 the start of the string. And put a prompt in the first item.
5845 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005846 let color = inputlist(['Select color:', '1. red',
5847 \ '2. green', '3. blue'])
5848
Bram Moolenaar071d4272004-06-13 20:20:40 +00005849inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005850 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005851 Should be called the same number of times inputsave() is
5852 called. Calling it more often is harmless though.
5853 Returns 1 when there is nothing to restore, 0 otherwise.
5854
5855inputsave() *inputsave()*
5856 Preserve typeahead (also from mappings) and clear it, so that
5857 a following prompt gets input from the user. Should be
5858 followed by a matching inputrestore() after the prompt. Can
5859 be used several times, in which case there must be just as
5860 many inputrestore() calls.
5861 Returns 1 when out of memory, 0 otherwise.
5862
5863inputsecret({prompt} [, {text}]) *inputsecret()*
5864 This function acts much like the |input()| function with but
5865 two exceptions:
5866 a) the user's response will be displayed as a sequence of
5867 asterisks ("*") thereby keeping the entry secret, and
5868 b) the user's response will not be recorded on the input
5869 |history| stack.
5870 The result is a String, which is whatever the user actually
5871 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005872 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005873
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005874insert({object}, {item} [, {idx}]) *insert()*
5875 When {object} is a |List| or a |Blob| insert {item} at the start
5876 of it.
5877
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005878 If {idx} is specified insert {item} before the item with index
Bram Moolenaar58b85342016-08-14 19:54:54 +02005879 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005880 like omitting {idx}. A negative {idx} is also possible, see
5881 |list-index|. -1 inserts just before the last item.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005882
5883 Returns the resulting |List| or |Blob|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005884 :let mylist = insert([2, 3, 5], 1)
5885 :call insert(mylist, 4, -1)
5886 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005887< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005888 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005889 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005890
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005891invert({expr}) *invert()*
5892 Bitwise invert. The argument is converted to a number. A
5893 List, Dict or Float argument causes an error. Example: >
5894 :let bits = invert(bits)
5895
Bram Moolenaar071d4272004-06-13 20:20:40 +00005896isdirectory({directory}) *isdirectory()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005897 The result is a Number, which is |TRUE| when a directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00005898 with the name {directory} exists. If {directory} doesn't
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005899 exist, or isn't a directory, the result is |FALSE|. {directory}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005900 is any expression, which is used as a String.
5901
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02005902isinf({expr}) *isinf()*
5903 Return 1 if {expr} is a positive infinity, or -1 a negative
5904 infinity, otherwise 0. >
5905 :echo isinf(1.0 / 0.0)
5906< 1 >
5907 :echo isinf(-1.0 / 0.0)
5908< -1
5909
5910 {only available when compiled with the |+float| feature}
5911
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005912islocked({expr}) *islocked()* *E786*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005913 The result is a Number, which is |TRUE| when {expr} is the
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005914 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005915 {expr} must be the name of a variable, |List| item or
5916 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005917 :let alist = [0, ['a', 'b'], 2, 3]
5918 :lockvar 1 alist
5919 :echo islocked('alist') " 1
5920 :echo islocked('alist[1]') " 0
5921
5922< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005923 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005924
Bram Moolenaarf3913272016-02-25 00:00:01 +01005925isnan({expr}) *isnan()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005926 Return |TRUE| if {expr} is a float with value NaN. >
Bram Moolenaarf3913272016-02-25 00:00:01 +01005927 echo isnan(0.0 / 0.0)
Bram Moolenaar0f248b02019-04-04 15:36:05 +02005928< 1
Bram Moolenaarf3913272016-02-25 00:00:01 +01005929
5930 {only available when compiled with the |+float| feature}
5931
Bram Moolenaar677ee682005-01-27 14:41:15 +00005932items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005933 Return a |List| with all the key-value pairs of {dict}. Each
5934 |List| item is a list with two items: the key of a {dict}
5935 entry and the value of this entry. The |List| is in arbitrary
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01005936 order. Also see |keys()| and |values()|.
5937 Example: >
5938 for [key, value] in items(mydict)
5939 echo key . ': ' . value
5940 endfor
Bram Moolenaar677ee682005-01-27 14:41:15 +00005941
Bram Moolenaar38a55632016-02-15 22:07:32 +01005942job_getchannel({job}) *job_getchannel()*
5943 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01005944 To check if the job has no channel: >
5945 if string(job_getchannel()) == 'channel fail'
5946<
Bram Moolenaar38a55632016-02-15 22:07:32 +01005947 {only available when compiled with the |+job| feature}
5948
Bram Moolenaar65a54642018-04-28 16:56:53 +02005949job_info([{job}]) *job_info()*
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005950 Returns a Dictionary with information about {job}:
5951 "status" what |job_status()| returns
5952 "channel" what |job_getchannel()| returns
Bram Moolenaar65a54642018-04-28 16:56:53 +02005953 "cmd" List of command arguments used to start the job
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02005954 "process" process ID
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02005955 "tty_in" terminal input name, empty when none
5956 "tty_out" terminal output name, empty when none
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005957 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01005958 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005959 "stoponexit" |job-stoponexit|
5960
Bram Moolenaarb3051ce2019-01-31 15:52:11 +01005961 Only in Unix:
5962 "termsig" the signal which terminated the process
5963 (See |job_stop()| for the values)
5964 only valid when "status" is "dead"
5965
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01005966 Only in MS-Windows:
5967 "tty_type" Type of virtual console in use.
5968 Values are "winpty" or "conpty".
5969 See 'termwintype'.
5970
Bram Moolenaar65a54642018-04-28 16:56:53 +02005971 Without any arguments, returns a List with all Job objects.
5972
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005973job_setoptions({job}, {options}) *job_setoptions()*
5974 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005975 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01005976 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005977
Bram Moolenaar38a55632016-02-15 22:07:32 +01005978job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005979 Start a job and return a Job object. Unlike |system()| and
5980 |:!cmd| this does not wait for the job to finish.
Bram Moolenaarc572da52017-08-27 16:52:01 +02005981 To start a job in a terminal window see |term_start()|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005982
Bram Moolenaar5e66b422019-01-24 21:58:10 +01005983 If the job fails to start then |job_status()| on the returned
5984 Job object results in "fail" and none of the callbacks will be
5985 invoked.
5986
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005987 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01005988 Unix it is split up in white-separated parts to be passed to
5989 execvp(). Arguments in double quotes can contain white space.
5990
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005991 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01005992 and further items are the arguments. All items are converted
5993 to String. This works best on Unix.
5994
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005995 On MS-Windows, job_start() makes a GUI application hidden. If
5996 want to show it, Use |:!start| instead.
5997
Bram Moolenaar835dc632016-02-07 14:27:38 +01005998 The command is executed directly, not through a shell, the
5999 'shell' option is not used. To use the shell: >
6000 let job = job_start(["/bin/sh", "-c", "echo hello"])
6001< Or: >
6002 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006003< Note that this will start two processes, the shell and the
6004 command it executes. If you don't want this use the "exec"
6005 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01006006
6007 On Unix $PATH is used to search for the executable only when
6008 the command does not contain a slash.
6009
6010 The job will use the same terminal as Vim. If it reads from
6011 stdin the job and Vim will be fighting over input, that
6012 doesn't work. Redirect stdin and stdout to avoid problems: >
6013 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
6014<
6015 The returned Job object can be used to get the status with
6016 |job_status()| and stop the job with |job_stop()|.
6017
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02006018 Note that the job object will be deleted if there are no
6019 references to it. This closes the stdin and stderr, which may
6020 cause the job to fail with an error. To avoid this keep a
6021 reference to the job. Thus instead of: >
6022 call job_start('my-command')
6023< use: >
6024 let myjob = job_start('my-command')
6025< and unlet "myjob" once the job is not needed or is past the
6026 point where it would fail (e.g. when it prints a message on
6027 startup). Keep in mind that variables local to a function
6028 will cease to exist if the function returns. Use a
6029 script-local variable if needed: >
6030 let s:myjob = job_start('my-command')
6031<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006032 {options} must be a Dictionary. It can contain many optional
6033 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01006034
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006035 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01006036
Bram Moolenaar02e83b42016-02-21 20:10:26 +01006037job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01006038 Returns a String with the status of {job}:
6039 "run" job is running
6040 "fail" job failed to start
6041 "dead" job died or was stopped after running
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006042
Bram Moolenaar511972d2016-06-04 18:09:59 +02006043 On Unix a non-existing command results in "dead" instead of
6044 "fail", because a fork happens before the failure can be
6045 detected.
6046
Bram Moolenaar03413f42016-04-12 21:07:15 +02006047 If an exit callback was set with the "exit_cb" option and the
Bram Moolenaar02e83b42016-02-21 20:10:26 +01006048 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01006049
Bram Moolenaar8950a562016-03-12 15:22:55 +01006050 For more information see |job_info()|.
6051
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006052 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01006053
6054job_stop({job} [, {how}]) *job_stop()*
6055 Stop the {job}. This can also be used to signal the job.
6056
Bram Moolenaar923d9262016-02-25 20:56:01 +01006057 When {how} is omitted or is "term" the job will be terminated.
6058 For Unix SIGTERM is sent. On MS-Windows the job will be
6059 terminated forcedly (there is no "gentle" way).
6060 This goes to the process group, thus children may also be
6061 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006062
Bram Moolenaar923d9262016-02-25 20:56:01 +01006063 Effect for Unix:
6064 "term" SIGTERM (default)
6065 "hup" SIGHUP
6066 "quit" SIGQUIT
6067 "int" SIGINT
6068 "kill" SIGKILL (strongest way to stop)
6069 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01006070
Bram Moolenaar923d9262016-02-25 20:56:01 +01006071 Effect for MS-Windows:
6072 "term" terminate process forcedly (default)
6073 "hup" CTRL_BREAK
6074 "quit" CTRL_BREAK
6075 "int" CTRL_C
6076 "kill" terminate process forcedly
6077 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006078
6079 On Unix the signal is sent to the process group. This means
6080 that when the job is "sh -c command" it affects both the shell
6081 and the command.
6082
Bram Moolenaar835dc632016-02-07 14:27:38 +01006083 The result is a Number: 1 if the operation could be executed,
6084 0 if "how" is not supported on the system.
6085 Note that even when the operation was executed, whether the
6086 job was actually stopped needs to be checked with
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02006087 |job_status()|.
6088
6089 If the status of the job is "dead", the signal will not be
6090 sent. This is to avoid to stop the wrong job (esp. on Unix,
6091 where process numbers are recycled).
6092
6093 When using "kill" Vim will assume the job will die and close
6094 the channel.
Bram Moolenaar835dc632016-02-07 14:27:38 +01006095
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006096 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01006097
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006098join({list} [, {sep}]) *join()*
6099 Join the items in {list} together into one String.
6100 When {sep} is specified it is put in between the items. If
6101 {sep} is omitted a single space is used.
6102 Note that {sep} is not added at the end. You might want to
6103 add it there too: >
6104 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006105< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006106 converted into a string like with |string()|.
6107 The opposite function is |split()|.
6108
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006109js_decode({string}) *js_decode()*
6110 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006111 - Object key names do not have to be in quotes.
Bram Moolenaaree142ad2017-01-11 21:50:08 +01006112 - Strings can be in single quotes.
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006113 - Empty items in an array (between two commas) are allowed and
6114 result in v:none items.
6115
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006116js_encode({expr}) *js_encode()*
6117 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006118 - Object key names are not in quotes.
6119 - v:none items in an array result in an empty item between
6120 commas.
6121 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006122 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006123 Will be encoded as:
6124 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006125 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006126 [1,null,{"one":1},null] ~
6127 This encoding is valid for JavaScript. It is more efficient
6128 than JSON, especially when using an array with optional items.
6129
6130
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006131json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006132 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006133 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01006134 JSON and Vim values.
6135 The decoding is permissive:
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006136 - A trailing comma in an array and object is ignored, e.g.
6137 "[1, 2, ]" is the same as "[1, 2]".
Bram Moolenaard09091d2019-01-17 16:07:22 +01006138 - Integer keys are accepted in objects, e.g. {1:2} is the
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006139 same as {"1":2}.
Bram Moolenaar705ada12016-01-24 17:56:50 +01006140 - More floating point numbers are recognized, e.g. "1." for
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006141 "1.0", or "001.2" for "1.2". Special floating point values
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006142 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6143 are accepted.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006144 - Leading zeroes in integer numbers are ignored, e.g. "012"
6145 for "12" or "-012" for "-12".
6146 - Capitalization is ignored in literal names null, true or
6147 false, e.g. "NULL" for "null", "True" for "true".
6148 - Control characters U+0000 through U+001F which are not
6149 escaped in strings are accepted, e.g. " " (tab
6150 character in string) for "\t".
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006151 - An empty JSON expression or made of only spaces is accepted
6152 and results in v:none.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006153 - Backslash in an invalid 2-character sequence escape is
6154 ignored, e.g. "\a" is decoded as "a".
6155 - A correct surrogate pair in JSON strings should normally be
6156 a 12 character sequence such as "\uD834\uDD1E", but
6157 json_decode() silently accepts truncated surrogate pairs
6158 such as "\uD834" or "\uD834\u"
6159 *E938*
6160 A duplicate key in an object, valid in rfc7159, is not
6161 accepted by json_decode() as the result must be a valid Vim
6162 type, e.g. this fails: {"a":"b", "a":"c"}
6163
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006164
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006165json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006166 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006167 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006168 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006169 Vim values are converted as follows:
Bram Moolenaard09091d2019-01-17 16:07:22 +01006170 |Number| decimal number
6171 |Float| floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006172 Float nan "NaN"
6173 Float inf "Infinity"
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006174 Float -inf "-Infinity"
Bram Moolenaard09091d2019-01-17 16:07:22 +01006175 |String| in double quotes (possibly null)
6176 |Funcref| not possible, error
6177 |List| as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006178 used recursively: []
Bram Moolenaard09091d2019-01-17 16:07:22 +01006179 |Dict| as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006180 used recursively: {}
Bram Moolenaard09091d2019-01-17 16:07:22 +01006181 |Blob| as an array of the individual bytes
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006182 v:false "false"
6183 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006184 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006185 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006186 Note that NaN and Infinity are passed on as values. This is
6187 missing in the JSON standard, but several implementations do
6188 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006189
Bram Moolenaard8b02732005-01-14 21:48:43 +00006190keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006191 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006192 arbitrary order. Also see |items()| and |values()|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00006193
Bram Moolenaar13065c42005-01-08 16:08:21 +00006194 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006195len({expr}) The result is a Number, which is the length of the argument.
6196 When {expr} is a String or a Number the length in bytes is
6197 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006198 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006199 returned.
Bram Moolenaard09091d2019-01-17 16:07:22 +01006200 When {expr} is a |Blob| the number of bytes is returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006201 When {expr} is a |Dictionary| the number of entries in the
6202 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006203 Otherwise an error is given.
6204
Bram Moolenaar071d4272004-06-13 20:20:40 +00006205 *libcall()* *E364* *E368*
6206libcall({libname}, {funcname}, {argument})
6207 Call function {funcname} in the run-time library {libname}
6208 with single argument {argument}.
6209 This is useful to call functions in a library that you
6210 especially made to be used with Vim. Since only one argument
6211 is possible, calling standard library functions is rather
6212 limited.
6213 The result is the String returned by the function. If the
6214 function returns NULL, this will appear as an empty string ""
6215 to Vim.
6216 If the function returns a number, use libcallnr()!
6217 If {argument} is a number, it is passed to the function as an
6218 int; if {argument} is a string, it is passed as a
6219 null-terminated string.
6220 This function will fail in |restricted-mode|.
6221
6222 libcall() allows you to write your own 'plug-in' extensions to
6223 Vim without having to recompile the program. It is NOT a
6224 means to call system functions! If you try to do so Vim will
6225 very probably crash.
6226
6227 For Win32, the functions you write must be placed in a DLL
6228 and use the normal C calling convention (NOT Pascal which is
6229 used in Windows System DLLs). The function must take exactly
6230 one parameter, either a character pointer or a long integer,
6231 and must return a character pointer or NULL. The character
6232 pointer returned must point to memory that will remain valid
6233 after the function has returned (e.g. in static data in the
6234 DLL). If it points to allocated memory, that memory will
6235 leak away. Using a static buffer in the function should work,
6236 it's then freed when the DLL is unloaded.
6237
6238 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00006239 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006240 because Vim thinks it's a pointer.
6241 For Win32 systems, {libname} should be the filename of the DLL
6242 without the ".DLL" suffix. A full path is only required if
6243 the DLL is not in the usual places.
6244 For Unix: When compiling your own plugins, remember that the
6245 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006246 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006247 feature is present}
6248 Examples: >
6249 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006250<
6251 *libcallnr()*
6252libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006253 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00006254 int instead of a string.
6255 {only in Win32 on some Unix versions, when the |+libcall|
6256 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006257 Examples: >
6258 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006259 :call libcallnr("libc.so", "printf", "Hello World!\n")
6260 :call libcallnr("libc.so", "sleep", 10)
6261<
6262 *line()*
6263line({expr}) The result is a Number, which is the line number of the file
6264 position given with {expr}. The accepted positions are:
6265 . the cursor position
6266 $ the last line in the current buffer
6267 'x position of mark x (if the mark is not set, 0 is
6268 returned)
Bram Moolenaara1d5fa62017-04-03 22:02:55 +02006269 w0 first line visible in current window (one if the
6270 display isn't updated, e.g. in silent Ex mode)
6271 w$ last line visible in current window (this is one
6272 less than "w0" if no lines are visible)
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00006273 v In Visual mode: the start of the Visual area (the
6274 cursor is the end). When not in Visual mode
6275 returns the cursor position. Differs from |'<| in
6276 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006277 Note that a mark in another file can be used. The line number
6278 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006279 To get the column number use |col()|. To get both use
6280 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006281 Examples: >
6282 line(".") line number of the cursor
6283 line("'t") line number of mark t
6284 line("'" . marker) line number of mark marker
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006285<
6286 To jump to the last known position when opening a file see
6287 |last-position-jump|.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006288
Bram Moolenaar071d4272004-06-13 20:20:40 +00006289line2byte({lnum}) *line2byte()*
6290 Return the byte count from the start of the buffer for line
6291 {lnum}. This includes the end-of-line character, depending on
6292 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006293 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006294 This can also be used to get the byte count for the line just
6295 below the last line: >
6296 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006297< This is the buffer size plus one. If 'fileencoding' is empty
6298 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006299 When {lnum} is invalid, or the |+byte_offset| feature has been
6300 disabled at compile time, -1 is returned.
6301 Also see |byte2line()|, |go| and |:goto|.
6302
6303lispindent({lnum}) *lispindent()*
6304 Get the amount of indent for line {lnum} according the lisp
6305 indenting rules, as with 'lisp'.
6306 The indent is counted in spaces, the value of 'tabstop' is
6307 relevant. {lnum} is used just like in |getline()|.
6308 When {lnum} is invalid or Vim was not compiled the
6309 |+lispindent| feature, -1 is returned.
6310
Bram Moolenaar9d401282019-04-06 13:18:12 +02006311list2str({list} [, {utf8}]) *list2str()*
6312 Convert each number in {list} to a character string can
6313 concatenate them all. Examples: >
6314 list2str([32]) returns " "
6315 list2str([65, 66, 67]) returns "ABC"
6316< The same can be done (slowly) with: >
6317 join(map(list, {nr, val -> nr2char(val)}), '')
6318< |str2list()| does the opposite.
6319
6320 When {utf8} is omitted or zero, the current 'encoding' is used.
6321 With {utf8} is 1, always return utf-8 characters.
6322 With utf-8 composing characters work as expected: >
6323 list2str([97, 769]) returns "á"
6324<
Bram Moolenaara3347722019-05-11 21:14:24 +02006325listener_add({callback} [, {buf}]) *listener_add()*
6326 Add a callback function that will be invoked when changes have
6327 been made to buffer {buf}.
6328 {buf} refers to a buffer name or number. For the accepted
6329 values, see |bufname()|. When {buf} is omitted the current
6330 buffer is used.
6331 Returns a unique ID that can be passed to |listener_remove()|.
6332
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006333 The {callback} is invoked with four arguments:
6334 a:bufnr the buffer that was changed
6335 a:start first changed line number
6336 a:end first line number below the change
6337 a:added total number of lines added, negative if lines
6338 were deleted
6339 a:changes a List of items with details about the changes
6340
6341 Example: >
6342 func Listener(bufnr, start, end, added, changes)
6343 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
6344 endfunc
6345 call listener_add('Listener', bufnr)
6346
6347< The List cannot be changed. Each item in a:changes is a
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02006348 dictionary with these entries:
Bram Moolenaara3347722019-05-11 21:14:24 +02006349 lnum the first line number of the change
6350 end the first line below the change
6351 added number of lines added; negative if lines were
6352 deleted
6353 col first column in "lnum" that was affected by
6354 the change; one if unknown or the whole line
6355 was affected; this is a byte index, first
6356 character has a value of one.
6357 When lines are inserted the values are:
Bram Moolenaar68e65602019-05-26 21:33:31 +02006358 lnum line above which the new line is added
Bram Moolenaara3347722019-05-11 21:14:24 +02006359 end equal to "lnum"
6360 added number of lines inserted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006361 col 1
Bram Moolenaara3347722019-05-11 21:14:24 +02006362 When lines are deleted the values are:
6363 lnum the first deleted line
6364 end the line below the first deleted line, before
6365 the deletion was done
6366 added negative, number of lines deleted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006367 col 1
Bram Moolenaara3347722019-05-11 21:14:24 +02006368 When lines are changed:
6369 lnum the first changed line
6370 end the line below the last changed line
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006371 added 0
6372 col first column with a change or 1
Bram Moolenaara3347722019-05-11 21:14:24 +02006373
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006374 The entries are in the order the changes were made, thus the
6375 most recent change is at the end. The line numbers are valid
6376 when the callback is invoked, but later changes may make them
6377 invalid, thus keeping a copy for later might not work.
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02006378
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006379 The {callback} is invoked just before the screen is updated,
6380 when |listener_flush()| is called or when a change is being
6381 made that changes the line count in a way it causes a line
6382 number in the list of changes to become invalid.
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02006383
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006384 The {callback} is invoked with the text locked, see
6385 |textlock|. If you do need to make changes to the buffer, use
6386 a timer to do this later |timer_start()|.
Bram Moolenaara3347722019-05-11 21:14:24 +02006387
6388 The {callback} is not invoked when the buffer is first loaded.
6389 Use the |BufReadPost| autocmd event to handle the initial text
6390 of a buffer.
6391 The {callback} is also not invoked when the buffer is
6392 unloaded, use the |BufUnload| autocmd event for that.
6393
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02006394listener_flush([{buf}]) *listener_flush()*
6395 Invoke listener callbacks for buffer {buf}. If there are no
6396 pending changes then no callbacks are invoked.
6397
6398 {buf} refers to a buffer name or number. For the accepted
6399 values, see |bufname()|. When {buf} is omitted the current
6400 buffer is used.
6401
Bram Moolenaara3347722019-05-11 21:14:24 +02006402listener_remove({id}) *listener_remove()*
6403 Remove a listener previously added with listener_add().
6404
Bram Moolenaar071d4272004-06-13 20:20:40 +00006405localtime() *localtime()*
6406 Return the current time, measured as seconds since 1st Jan
6407 1970. See also |strftime()| and |getftime()|.
6408
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006409
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006410log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006411 Return the natural logarithm (base e) of {expr} as a |Float|.
6412 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006413 (0, inf].
6414 Examples: >
6415 :echo log(10)
6416< 2.302585 >
6417 :echo log(exp(5))
6418< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02006419 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006420
6421
Bram Moolenaar446cb832008-06-24 21:56:24 +00006422log10({expr}) *log10()*
6423 Return the logarithm of Float {expr} to base 10 as a |Float|.
6424 {expr} must evaluate to a |Float| or a |Number|.
6425 Examples: >
6426 :echo log10(1000)
6427< 3.0 >
6428 :echo log10(0.01)
6429< -2.0
6430 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006431
6432luaeval({expr} [, {expr}]) *luaeval()*
6433 Evaluate Lua expression {expr} and return its result converted
6434 to Vim data structures. Second {expr} may hold additional
Bram Moolenaard38b0552012-04-25 19:07:41 +02006435 argument accessible as _A inside first {expr}.
6436 Strings are returned as they are.
6437 Boolean objects are converted to numbers.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006438 Numbers are converted to |Float| values if vim was compiled
Bram Moolenaard38b0552012-04-25 19:07:41 +02006439 with |+float| and to numbers otherwise.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006440 Dictionaries and lists obtained by vim.eval() are returned
Bram Moolenaard38b0552012-04-25 19:07:41 +02006441 as-is.
6442 Other objects are returned as zero without any errors.
6443 See |lua-luaeval| for more details.
6444 {only available when compiled with the |+lua| feature}
6445
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006446map({expr1}, {expr2}) *map()*
6447 {expr1} must be a |List| or a |Dictionary|.
6448 Replace each item in {expr1} with the result of evaluating
6449 {expr2}. {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006450
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006451 If {expr2} is a |string|, inside {expr2} |v:val| has the value
6452 of the current item. For a |Dictionary| |v:key| has the key
6453 of the current item and for a |List| |v:key| has the index of
6454 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006455 Example: >
6456 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006457< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006458
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006459 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006460 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006461 |literal-string| to avoid having to double backslashes. You
6462 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006463
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006464 If {expr2} is a |Funcref| it is called with two arguments:
6465 1. The key or the index of the current item.
6466 2. the value of the current item.
6467 The function must return the new value of the item. Example
6468 that changes each value by "key-value": >
6469 func KeyValue(key, val)
6470 return a:key . '-' . a:val
6471 endfunc
6472 call map(myDict, function('KeyValue'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006473< It is shorter when using a |lambda|: >
6474 call map(myDict, {key, val -> key . '-' . val})
6475< If you do not use "val" you can leave it out: >
6476 call map(myDict, {key -> 'item: ' . key})
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006477<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006478 The operation is done in-place. If you want a |List| or
6479 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02006480 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006481
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006482< Returns {expr1}, the |List| or |Dictionary| that was filtered.
6483 When an error is encountered while evaluating {expr2} no
6484 further items in {expr1} are processed. When {expr2} is a
6485 Funcref errors inside a function are ignored, unless it was
6486 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006487
6488
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006489maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
Bram Moolenaarbd743252010-10-20 21:23:33 +02006490 When {dict} is omitted or zero: Return the rhs of mapping
6491 {name} in mode {mode}. The returned String has special
6492 characters translated like in the output of the ":map" command
6493 listing.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006494
Bram Moolenaarbd743252010-10-20 21:23:33 +02006495 When there is no mapping for {name}, an empty String is
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006496 returned. When the mapping for {name} is empty, then "<Nop>"
6497 is returned.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006498
6499 The {name} can have special key names, like in the ":map"
6500 command.
6501
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006502 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006503 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02006504 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006505 "o" Operator-pending
6506 "i" Insert
6507 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02006508 "s" Select
6509 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00006510 "l" langmap |language-mapping|
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006511 "t" Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +00006512 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006513 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006514
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006515 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006516 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006517
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006518 When {dict} is there and it is |TRUE| return a dictionary
Bram Moolenaarbd743252010-10-20 21:23:33 +02006519 containing all the information of the mapping with the
6520 following items:
6521 "lhs" The {lhs} of the mapping.
6522 "rhs" The {rhs} of the mapping as typed.
6523 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02006524 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006525 "expr" 1 for an expression mapping (|:map-<expr>|).
6526 "buffer" 1 for a buffer local mapping (|:map-local|).
6527 "mode" Modes for which the mapping is defined. In
6528 addition to the modes mentioned above, these
6529 characters will be used:
6530 " " Normal, Visual and Operator-pending
6531 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01006532 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02006533 "sid" The script local ID, used for <sid> mappings
6534 (|<SID>|).
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02006535 "lnum" The line number in "sid", zero if unknown.
Bram Moolenaardfb18412013-12-11 18:53:29 +01006536 "nowait" Do not wait for other, longer mappings.
6537 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02006538
Bram Moolenaar071d4272004-06-13 20:20:40 +00006539 The mappings local to the current buffer are checked first,
6540 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00006541 This function can be used to map a key even when it's already
6542 mapped, and have it do the original mapping too. Sketch: >
6543 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
6544
Bram Moolenaar071d4272004-06-13 20:20:40 +00006545
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006546mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006547 Check if there is a mapping that matches with {name} in mode
6548 {mode}. See |maparg()| for {mode} and special names in
6549 {name}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006550 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006551 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006552 A match happens with a mapping that starts with {name} and
6553 with a mapping which is equal to the start of {name}.
6554
Bram Moolenaar446cb832008-06-24 21:56:24 +00006555 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00006556 mapcheck("a") yes yes yes
6557 mapcheck("abc") yes yes yes
6558 mapcheck("ax") yes no no
6559 mapcheck("b") no no no
6560
6561 The difference with maparg() is that mapcheck() finds a
6562 mapping that matches with {name}, while maparg() only finds a
6563 mapping for {name} exactly.
6564 When there is no mapping that starts with {name}, an empty
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006565 String is returned. If there is one, the RHS of that mapping
Bram Moolenaar071d4272004-06-13 20:20:40 +00006566 is returned. If there are several mappings that start with
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006567 {name}, the RHS of one of them is returned. This will be
6568 "<Nop>" if the RHS is empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006569 The mappings local to the current buffer are checked first,
6570 then the global mappings.
6571 This function can be used to check if a mapping can be added
6572 without being ambiguous. Example: >
6573 :if mapcheck("_vv") == ""
6574 : map _vv :set guifont=7x13<CR>
6575 :endif
6576< This avoids adding the "_vv" mapping when there already is a
6577 mapping for "_v" or for "_vvv".
6578
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006579match({expr}, {pat} [, {start} [, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006580 When {expr} is a |List| then this returns the index of the
6581 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006582 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006583
Bram Moolenaar58b85342016-08-14 19:54:54 +02006584 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006585 Number, which gives the index (byte offset) in {expr} where
6586 {pat} matches.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006587
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006588 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006589 If there is no match -1 is returned.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006590
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006591 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006592 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006593 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006594 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006595< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006596 *strpbrk()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02006597 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00006598 :let sepidx = match(line, '[.,;: \t]')
6599< *strcasestr()*
6600 Vim doesn't have a strcasestr() function. But you can add
6601 "\c" to the pattern to ignore case: >
6602 :let idx = match(haystack, '\cneedle')
6603<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006604 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006605 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006606 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006607 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006608 :echo match("testing", "ing", 2)
6609< result is again "4". >
6610 :echo match("testing", "ing", 4)
6611< result is again "4". >
6612 :echo match("testing", "t", 2)
6613< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006614 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00006615 {start} bytes later, thus "^" will match at {start}. Except
6616 when {count} is given, then it's like matches before the
6617 {start} byte are ignored (this is a bit complicated to keep it
6618 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006619 For a String, if {start} < 0, it will be set to 0. For a list
6620 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006621 If {start} is out of range ({start} > strlen({expr}) for a
6622 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006623
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006624 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006625 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006626 character further. Thus this example results in 1: >
6627 echo match("testing", "..", 0, 2)
6628< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006629 Note that when {count} is added the way {start} works changes,
6630 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006631
Bram Moolenaar071d4272004-06-13 20:20:40 +00006632 See |pattern| for the patterns that are accepted.
6633 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar58b85342016-08-14 19:54:54 +02006634 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00006635 done like 'magic' is set and 'cpoptions' is empty.
6636
Bram Moolenaar95e51472018-07-28 16:55:56 +02006637 *matchadd()* *E798* *E799* *E801* *E957*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006638matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006639 Defines a pattern to be highlighted in the current window (a
6640 "match"). It will be highlighted with {group}. Returns an
6641 identification number (ID), which can be used to delete the
Bram Moolenaaraff74912019-03-30 18:11:49 +01006642 match using |matchdelete()|. The ID is bound to the window.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01006643 Matching is case sensitive and magic, unless case sensitivity
6644 or magicness are explicitly overridden in {pattern}. The
6645 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02006646 The "Conceal" value is special, it causes the match to be
6647 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006648
6649 The optional {priority} argument assigns a priority to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006650 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006651 highlighting overrule that of a match with a lower priority.
6652 A priority is specified as an integer (negative numbers are no
6653 exception). If the {priority} argument is not specified, the
6654 default priority is 10. The priority of 'hlsearch' is zero,
6655 hence all matches with a priority greater than zero will
6656 overrule it. Syntax highlighting (see 'syntax') is a separate
6657 mechanism, and regardless of the chosen priority a match will
6658 always overrule syntax highlighting.
6659
6660 The optional {id} argument allows the request for a specific
6661 match ID. If a specified ID is already taken, an error
6662 message will appear and the match will not be added. An ID
6663 is specified as a positive integer (zero excluded). IDs 1, 2
6664 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02006665 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006666 |matchadd()| automatically chooses a free ID.
6667
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006668 The optional {dict} argument allows for further custom
6669 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02006670 conceal character that will be shown for |hl-Conceal|
6671 highlighted matches. The dict can have the following members:
6672
6673 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006674 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02006675 matches, see |:syn-cchar|)
Bram Moolenaar95e51472018-07-28 16:55:56 +02006676 window Instead of the current window use the
6677 window with this number or window ID.
Bram Moolenaar6561d522015-07-21 15:48:27 +02006678
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006679 The number of matches is not limited, as it is the case with
6680 the |:match| commands.
6681
6682 Example: >
6683 :highlight MyGroup ctermbg=green guibg=green
6684 :let m = matchadd("MyGroup", "TODO")
6685< Deletion of the pattern: >
6686 :call matchdelete(m)
6687
6688< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar58b85342016-08-14 19:54:54 +02006689 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006690 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006691
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02006692 *matchaddpos()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006693matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02006694 Same as |matchadd()|, but requires a list of positions {pos}
6695 instead of a pattern. This command is faster than |matchadd()|
6696 because it does not require to handle regular expressions and
6697 sets buffer line boundaries to redraw screen. It is supposed
6698 to be used when fast match additions and deletions are
6699 required, for example to highlight matching parentheses.
6700
6701 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006702 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02006703 line has number 1.
6704 - A list with one number, e.g., [23]. The whole line with this
6705 number will be highlighted.
6706 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006707 the line number, the second one is the column number (first
6708 column is 1, the value must correspond to the byte index as
6709 |col()| would return). The character at this position will
6710 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006711 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006712 the third number gives the length of the highlight in bytes.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006713
Bram Moolenaarb3414592014-06-17 17:48:32 +02006714 The maximum number of positions is 8.
6715
6716 Example: >
6717 :highlight MyGroup ctermbg=green guibg=green
6718 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6719< Deletion of the pattern: >
6720 :call matchdelete(m)
6721
6722< Matches added by |matchaddpos()| are returned by
6723 |getmatches()| with an entry "pos1", "pos2", etc., with the
6724 value a list like the {pos} item.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006725
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006726matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006727 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006728 |:2match| or |:3match| command.
6729 Return a |List| with two elements:
6730 The name of the highlight group used
6731 The pattern used.
6732 When {nr} is not 1, 2 or 3 returns an empty |List|.
6733 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006734 This is useful to save and restore a |:match|.
6735 Highlighting matches using the |:match| commands are limited
6736 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006737
Bram Moolenaaraff74912019-03-30 18:11:49 +01006738matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006739 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00006740 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006741 otherwise -1. See example for |matchadd()|. All matches can
6742 be deleted in one operation by |clearmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01006743 If {win} is specified, use the window with this number or
6744 window ID instead of the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006745
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006746matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006747 Same as |match()|, but return the index of first character
6748 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006749 :echo matchend("testing", "ing")
6750< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00006751 *strspn()* *strcspn()*
6752 Vim doesn't have a strspn() or strcspn() function, but you can
6753 do it with matchend(): >
6754 :let span = matchend(line, '[a-zA-Z]')
6755 :let span = matchend(line, '[^a-zA-Z]')
6756< Except that -1 is returned when there are no matches.
6757
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006758 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006759 :echo matchend("testing", "ing", 2)
6760< results in "7". >
6761 :echo matchend("testing", "ing", 5)
6762< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006763 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006764
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006765matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006766 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006767 list is the matched string, same as what matchstr() would
6768 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00006769 in |:substitute|. When an optional submatch didn't match an
6770 empty string is used. Example: >
6771 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6772< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006773 When there is no match an empty list is returned.
6774
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006775matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006776 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006777 :echo matchstr("testing", "ing")
6778< results in "ing".
6779 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006780 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006781 :echo matchstr("testing", "ing", 2)
6782< results in "ing". >
6783 :echo matchstr("testing", "ing", 5)
6784< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006785 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006786 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006787
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006788matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02006789 Same as |matchstr()|, but return the matched string, the start
6790 position and the end position of the match. Example: >
6791 :echo matchstrpos("testing", "ing")
6792< results in ["ing", 4, 7].
6793 When there is no match ["", -1, -1] is returned.
6794 The {start}, if given, has the same meaning as for |match()|. >
6795 :echo matchstrpos("testing", "ing", 2)
6796< results in ["ing", 4, 7]. >
6797 :echo matchstrpos("testing", "ing", 5)
6798< result is ["", -1, -1].
6799 When {expr} is a |List| then the matching item, the index
6800 of first item where {pat} matches, the start position and the
6801 end position of the match are returned. >
6802 :echo matchstrpos([1, '__x'], '\a')
6803< result is ["x", 1, 2, 3].
6804 The type isn't changed, it's not necessarily a String.
6805
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006806 *max()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006807max({expr}) Return the maximum value of all items in {expr}.
6808 {expr} can be a list or a dictionary. For a dictionary,
6809 it returns the maximum of all values in the dictionary.
6810 If {expr} is neither a list nor a dictionary, or one of the
6811 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006812 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006813
6814 *min()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006815min({expr}) Return the minimum value of all items in {expr}.
6816 {expr} can be a list or a dictionary. For a dictionary,
6817 it returns the minimum of all values in the dictionary.
6818 If {expr} is neither a list nor a dictionary, or one of the
6819 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006820 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006821
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006822 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006823mkdir({name} [, {path} [, {prot}]])
6824 Create directory {name}.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006825
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006826 If {path} is "p" then intermediate directories are created as
6827 necessary. Otherwise it must be "".
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006828
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006829 If {prot} is given it is used to set the protection bits of
6830 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar58b85342016-08-14 19:54:54 +02006831 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006832 for others. This is only used for the last part of {name}.
6833 Thus if you create /tmp/foo/bar then /tmp/foo will be created
6834 with 0755.
6835 Example: >
6836 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006837
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006838< This function is not available in the |sandbox|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006839
Bram Moolenaar78a16b02018-04-14 13:51:55 +02006840 There is no error if the directory already exists and the "p"
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006841 flag is passed (since patch 8.0.1708). However, without the
6842 "p" option the call will fail.
6843
6844 The function result is a Number, which is 1 if the call was
6845 successful or 0 if the directory creation failed or partly
6846 failed.
6847
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006848 Not available on all systems. To check use: >
6849 :if exists("*mkdir")
6850<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006851 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006852mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006853 If [expr] is supplied and it evaluates to a non-zero Number or
6854 a non-empty String (|non-zero-arg|), then the full mode is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006855 returned, otherwise only the first letter is returned.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006856
Bram Moolenaar612cc382018-07-29 15:34:26 +02006857 n Normal, Terminal-Normal
6858 no Operator-pending
Bram Moolenaar5976f8f2018-12-27 23:44:44 +01006859 nov Operator-pending (forced characterwise |o_v|)
6860 noV Operator-pending (forced linewise |o_V|)
6861 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006862 CTRL-V is one character
Bram Moolenaar612cc382018-07-29 15:34:26 +02006863 niI Normal using |i_CTRL-O| in |Insert-mode|
6864 niR Normal using |i_CTRL-O| in |Replace-mode|
6865 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6866 v Visual by character
6867 V Visual by line
6868 CTRL-V Visual blockwise
6869 s Select by character
6870 S Select by line
6871 CTRL-S Select blockwise
6872 i Insert
6873 ic Insert mode completion |compl-generic|
6874 ix Insert mode |i_CTRL-X| completion
6875 R Replace |R|
6876 Rc Replace mode completion |compl-generic|
6877 Rv Virtual Replace |gR|
6878 Rx Replace mode |i_CTRL-X| completion
6879 c Command-line editing
6880 cv Vim Ex mode |gQ|
6881 ce Normal Ex mode |Q|
6882 r Hit-enter prompt
6883 rm The -- more -- prompt
6884 r? A |:confirm| query of some sort
6885 ! Shell or external command is executing
6886 t Terminal-Job mode: keys go to the job
Bram Moolenaar446cb832008-06-24 21:56:24 +00006887 This is useful in the 'statusline' option or when used
6888 with |remote_expr()| In most other places it always returns
6889 "c" or "n".
Bram Moolenaar612cc382018-07-29 15:34:26 +02006890 Note that in the future more modes and more specific modes may
6891 be added. It's better not to compare the whole string but only
6892 the leading character(s).
Bram Moolenaar446cb832008-06-24 21:56:24 +00006893 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006894
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006895mzeval({expr}) *mzeval()*
6896 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02006897 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006898 Numbers and strings are returned as they are.
6899 Pairs (including lists and improper lists) and vectors are
6900 returned as Vim |Lists|.
6901 Hash tables are represented as Vim |Dictionary| type with keys
6902 converted to strings.
6903 All other types are converted to string with display function.
6904 Examples: >
6905 :mz (define l (list 1 2 3))
6906 :mz (define h (make-hash)) (hash-set! h "list" l)
6907 :echo mzeval("l")
6908 :echo mzeval("h")
6909<
6910 {only available when compiled with the |+mzscheme| feature}
6911
Bram Moolenaar071d4272004-06-13 20:20:40 +00006912nextnonblank({lnum}) *nextnonblank()*
6913 Return the line number of the first line at or below {lnum}
6914 that is not blank. Example: >
6915 if getline(nextnonblank(1)) =~ "Java"
6916< When {lnum} is invalid or there is no non-blank line at or
6917 below it, zero is returned.
6918 See also |prevnonblank()|.
6919
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006920nr2char({expr} [, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006921 Return a string with a single character, which has the number
6922 value {expr}. Examples: >
6923 nr2char(64) returns "@"
6924 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01006925< When {utf8} is omitted or zero, the current 'encoding' is used.
6926 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006927 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01006928< With {utf8} set to 1, always return utf-8 characters.
6929 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006930 nr2char(10), because NULs are represented with newline
6931 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00006932 string, thus results in an empty string.
Bram Moolenaaraff74912019-03-30 18:11:49 +01006933 To turn a list of character numbers into a string: >
6934 let list = [65, 66, 67]
6935 let str = join(map(list, {_, val -> nr2char(val)}), '')
6936< Result: "ABC"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006937
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006938or({expr}, {expr}) *or()*
6939 Bitwise OR on the two arguments. The arguments are converted
6940 to a number. A List, Dict or Float argument causes an error.
6941 Example: >
6942 :let bits = or(bits, 0x80)
6943
6944
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006945pathshorten({expr}) *pathshorten()*
6946 Shorten directory names in the path {expr} and return the
6947 result. The tail, the file name, is kept as-is. The other
6948 components in the path are reduced to single letters. Leading
6949 '~' and '.' characters are kept. Example: >
6950 :echo pathshorten('~/.vim/autoload/myfile.vim')
6951< ~/.v/a/myfile.vim ~
6952 It doesn't matter if the path exists or not.
6953
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006954perleval({expr}) *perleval()*
6955 Evaluate Perl expression {expr} in scalar context and return
6956 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006957 converted, it is returned as a string Perl representation.
6958 Note: If you want an array or hash, {expr} must return a
6959 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006960 Example: >
6961 :echo perleval('[1 .. 4]')
6962< [1, 2, 3, 4]
6963 {only available when compiled with the |+perl| feature}
6964
Bram Moolenaar446cb832008-06-24 21:56:24 +00006965pow({x}, {y}) *pow()*
6966 Return the power of {x} to the exponent {y} as a |Float|.
6967 {x} and {y} must evaluate to a |Float| or a |Number|.
6968 Examples: >
6969 :echo pow(3, 3)
6970< 27.0 >
6971 :echo pow(2, 16)
6972< 65536.0 >
6973 :echo pow(32, 0.20)
6974< 2.0
6975 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006976
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006977prevnonblank({lnum}) *prevnonblank()*
6978 Return the line number of the first line at or above {lnum}
6979 that is not blank. Example: >
6980 let ind = indent(prevnonblank(v:lnum - 1))
6981< When {lnum} is invalid or there is no non-blank line at or
6982 above it, zero is returned.
6983 Also see |nextnonblank()|.
6984
6985
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006986printf({fmt}, {expr1} ...) *printf()*
6987 Return a String with {fmt}, where "%" items are replaced by
6988 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006989 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006990< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006991 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006992
6993 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006994 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006995 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00006996 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006997 %.9s string truncated to 9 bytes
6998 %c single byte
6999 %d decimal number
7000 %5d decimal number padded with spaces to 5 characters
7001 %x hex number
7002 %04x hex number padded with zeros to at least 4 characters
7003 %X hex number using upper case letters
7004 %o octal number
Bram Moolenaar91984b92016-08-16 21:58:41 +02007005 %08b binary number padded with zeros to at least 8 chars
Bram Moolenaar04186092016-08-29 21:55:35 +02007006 %f floating point number as 12.23, inf, -inf or nan
7007 %F floating point number as 12.23, INF, -INF or NAN
7008 %e floating point number as 1.23e3, inf, -inf or nan
7009 %E floating point number as 1.23E3, INF, -INF or NAN
Bram Moolenaar446cb832008-06-24 21:56:24 +00007010 %g floating point number, as %f or %e depending on value
Bram Moolenaar3df01732017-02-17 22:47:16 +01007011 %G floating point number, as %F or %E depending on value
Bram Moolenaar446cb832008-06-24 21:56:24 +00007012 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007013
7014 Conversion specifications start with '%' and end with the
7015 conversion type. All other characters are copied unchanged to
7016 the result.
7017
7018 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007019 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007020
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007021 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007022
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007023 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007024 Zero or more of the following flags:
7025
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007026 # The value should be converted to an "alternate
7027 form". For c, d, and s conversions, this option
7028 has no effect. For o conversions, the precision
7029 of the number is increased to force the first
7030 character of the output string to a zero (except
7031 if a zero value is printed with an explicit
7032 precision of zero).
Bram Moolenaar91984b92016-08-16 21:58:41 +02007033 For b and B conversions, a non-zero result has
7034 the string "0b" (or "0B" for B conversions)
7035 prepended to it.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007036 For x and X conversions, a non-zero result has
7037 the string "0x" (or "0X" for X conversions)
7038 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007039
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007040 0 (zero) Zero padding. For all conversions the converted
7041 value is padded on the left with zeros rather
7042 than blanks. If a precision is given with a
Bram Moolenaar91984b92016-08-16 21:58:41 +02007043 numeric conversion (d, b, B, o, x, and X), the 0
7044 flag is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007045
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007046 - A negative field width flag; the converted value
7047 is to be left adjusted on the field boundary.
7048 The converted value is padded on the right with
7049 blanks, rather than on the left with blanks or
7050 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007051
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007052 ' ' (space) A blank should be left before a positive
7053 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007054
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007055 + A sign must always be placed before a number
Bram Moolenaar58b85342016-08-14 19:54:54 +02007056 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007057 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007058
7059 field-width
7060 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00007061 field width. If the converted value has fewer bytes
7062 than the field width, it will be padded with spaces on
7063 the left (or right, if the left-adjustment flag has
7064 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007065
7066 .precision
7067 An optional precision, in the form of a period '.'
7068 followed by an optional digit string. If the digit
7069 string is omitted, the precision is taken as zero.
7070 This gives the minimum number of digits to appear for
7071 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00007072 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007073 For floating point it is the number of digits after
7074 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007075
7076 type
7077 A character that specifies the type of conversion to
7078 be applied, see below.
7079
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007080 A field width or precision, or both, may be indicated by an
7081 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar58b85342016-08-14 19:54:54 +02007082 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007083 negative field width is treated as a left adjustment flag
7084 followed by a positive field width; a negative precision is
7085 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007086 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007087< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007088 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007089
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007090 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007091
Bram Moolenaar91984b92016-08-16 21:58:41 +02007092 *printf-d* *printf-b* *printf-B* *printf-o*
7093 *printf-x* *printf-X*
7094 dbBoxX The Number argument is converted to signed decimal
7095 (d), unsigned binary (b and B), unsigned octal (o), or
7096 unsigned hexadecimal (x and X) notation. The letters
7097 "abcdef" are used for x conversions; the letters
7098 "ABCDEF" are used for X conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007099 The precision, if any, gives the minimum number of
7100 digits that must appear; if the converted value
7101 requires fewer digits, it is padded on the left with
7102 zeros.
7103 In no case does a non-existent or small field width
7104 cause truncation of a numeric field; if the result of
7105 a conversion is wider than the field width, the field
7106 is expanded to contain the conversion result.
Bram Moolenaar30567352016-08-27 21:25:44 +02007107 The 'h' modifier indicates the argument is 16 bits.
7108 The 'l' modifier indicates the argument is 32 bits.
7109 The 'L' modifier indicates the argument is 64 bits.
7110 Generally, these modifiers are not useful. They are
7111 ignored when type is known from the argument.
7112
7113 i alias for d
7114 D alias for ld
7115 U alias for lu
7116 O alias for lo
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007117
Bram Moolenaar446cb832008-06-24 21:56:24 +00007118 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007119 c The Number argument is converted to a byte, and the
7120 resulting character is written.
7121
Bram Moolenaar446cb832008-06-24 21:56:24 +00007122 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007123 s The text of the String argument is used. If a
7124 precision is specified, no more bytes than the number
7125 specified are used.
Bram Moolenaar7571d552016-08-18 22:54:46 +02007126 If the argument is not a String type, it is
7127 automatically converted to text with the same format
7128 as ":echo".
Bram Moolenaar0122c402015-02-03 19:13:34 +01007129 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01007130 S The text of the String argument is used. If a
7131 precision is specified, no more display cells than the
Bram Moolenaar4c92e752019-02-17 21:18:32 +01007132 number specified are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007133
Bram Moolenaar446cb832008-06-24 21:56:24 +00007134 *printf-f* *E807*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007135 f F The Float argument is converted into a string of the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007136 form 123.456. The precision specifies the number of
7137 digits after the decimal point. When the precision is
7138 zero the decimal point is omitted. When the precision
7139 is not specified 6 is used. A really big number
Bram Moolenaar04186092016-08-29 21:55:35 +02007140 (out of range or dividing by zero) results in "inf"
Bram Moolenaarf8be4612017-06-23 20:52:40 +02007141 or "-inf" with %f (INF or -INF with %F).
7142 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007143 Example: >
7144 echo printf("%.2f", 12.115)
7145< 12.12
7146 Note that roundoff depends on the system libraries.
7147 Use |round()| when in doubt.
7148
7149 *printf-e* *printf-E*
7150 e E The Float argument is converted into a string of the
7151 form 1.234e+03 or 1.234E+03 when using 'E'. The
7152 precision specifies the number of digits after the
7153 decimal point, like with 'f'.
7154
7155 *printf-g* *printf-G*
7156 g G The Float argument is converted like with 'f' if the
7157 value is between 0.001 (inclusive) and 10000000.0
7158 (exclusive). Otherwise 'e' is used for 'g' and 'E'
7159 for 'G'. When no precision is specified superfluous
7160 zeroes and '+' signs are removed, except for the zero
7161 immediately after the decimal point. Thus 10000000.0
7162 results in 1.0e7.
7163
7164 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007165 % A '%' is written. No argument is converted. The
7166 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007167
Bram Moolenaarc236c162008-07-13 17:41:49 +00007168 When a Number argument is expected a String argument is also
7169 accepted and automatically converted.
7170 When a Float or String argument is expected a Number argument
7171 is also accepted and automatically converted.
7172 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007173
Bram Moolenaar83bab712005-08-01 21:58:57 +00007174 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007175 The number of {exprN} arguments must exactly match the number
7176 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007177 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007178
7179
Bram Moolenaarf2732452018-06-03 14:47:35 +02007180prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007181 Set prompt callback for buffer {buf} to {expr}. When {expr}
7182 is an empty string the callback is removed. This has only
Bram Moolenaarf2732452018-06-03 14:47:35 +02007183 effect if {buf} has 'buftype' set to "prompt".
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007184
Bram Moolenaarf2732452018-06-03 14:47:35 +02007185 The callback is invoked when pressing Enter. The current
7186 buffer will always be the prompt buffer. A new line for a
7187 prompt is added before invoking the callback, thus the prompt
7188 for which the callback was invoked will be in the last but one
7189 line.
7190 If the callback wants to add text to the buffer, it must
7191 insert it above the last line, since that is where the current
7192 prompt is. This can also be done asynchronously.
7193 The callback is invoked with one argument, which is the text
7194 that was entered at the prompt. This can be an empty string
7195 if the user only typed Enter.
7196 Example: >
7197 call prompt_setcallback(bufnr(''), function('s:TextEntered'))
7198 func s:TextEntered(text)
7199 if a:text == 'exit' || a:text == 'quit'
7200 stopinsert
7201 close
7202 else
7203 call append(line('$') - 1, 'Entered: "' . a:text . '"')
7204 " Reset 'modified' to allow the buffer to be closed.
7205 set nomodified
7206 endif
7207 endfunc
7208
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007209prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
7210 Set a callback for buffer {buf} to {expr}. When {expr} is an
7211 empty string the callback is removed. This has only effect if
7212 {buf} has 'buftype' set to "prompt".
7213
7214 This callback will be invoked when pressing CTRL-C in Insert
7215 mode. Without setting a callback Vim will exit Insert mode,
7216 as in any buffer.
7217
7218prompt_setprompt({buf}, {text}) *prompt_setprompt()*
7219 Set prompt for buffer {buf} to {text}. You most likely want
7220 {text} to end in a space.
7221 The result is only visible if {buf} has 'buftype' set to
7222 "prompt". Example: >
7223 call prompt_setprompt(bufnr(''), 'command: ')
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007224<
7225 *prop_add()* *E965*
7226prop_add({lnum}, {col}, {props})
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007227 Attach a text property at position {lnum}, {col}. {col} is
7228 counted in bytes, use one for the first column.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007229 If {lnum} is invalid an error is given. *E966*
7230 If {col} is invalid an error is given. *E964*
7231
7232 {props} is a dictionary with these fields:
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007233 length length of text in bytes, can only be used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007234 for a property that does not continue in
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007235 another line; can be zero
7236 end_lnum line number for the end of text
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007237 end_col column just after the text; not used when
7238 "length" is present; when {col} and "end_col"
7239 are equal, and "end_lnum" is omitted or equal
7240 to {lnum}, this is a zero-width text property
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007241 bufnr buffer to add the property to; when omitted
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007242 the current buffer is used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007243 id user defined ID for the property; when omitted
7244 zero is used
7245 type name of the text property type
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007246 All fields except "type" are optional.
7247
7248 It is an error when both "length" and "end_lnum" or "end_col"
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007249 are given. Either use "length" or "end_col" for a property
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007250 within one line, or use "end_lnum" and "end_col" for a
7251 property that spans more than one line.
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007252 When neither "length" nor "end_col" are given the property
7253 will be zero-width. That means it will not be highlighted but
7254 will move with the text, as a kind of mark.
Bram Moolenaare3d31b02018-12-24 23:07:04 +01007255 The property can end exactly at the last character of the
7256 text, or just after it. In the last case, if text is appended
7257 to the line, the text property size will increase, also when
7258 the property type does not have "end_incl" set.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007259
7260 "type" will first be looked up in the buffer the property is
7261 added to. When not found, the global property types are used.
7262 If not found an error is given.
7263
7264 See |text-properties| for information about text properties.
7265
7266
Bram Moolenaar9d87a372018-12-18 21:41:50 +01007267prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007268 Remove all text properties from line {lnum}.
Bram Moolenaar9d87a372018-12-18 21:41:50 +01007269 When {lnum-end} is given, remove all text properties from line
7270 {lnum} to {lnum-end} (inclusive).
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007271
7272 When {props} contains a "bufnr" item use this buffer,
7273 otherwise use the current buffer.
7274
7275 See |text-properties| for information about text properties.
7276
7277 *prop_find()*
7278prop_find({props} [, {direction}])
7279 NOT IMPLEMENTED YET
7280 Search for a text property as specified with {props}:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007281 id property with this ID
7282 type property with this type name
7283 bufnr buffer to search in; when present a
7284 start position with "lnum" and "col"
7285 must be given; when omitted the
7286 current buffer is used
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007287 lnum start in this line (when omitted start
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007288 at the cursor)
7289 col start at this column (when omitted
7290 and "lnum" is given: use column 1,
7291 otherwise start at the cursor)
7292 skipstart do not look for a match at the start
7293 position
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007294
7295 {direction} can be "f" for forward and "b" for backward. When
7296 omitted forward search is performed.
7297
7298 If a match is found then a Dict is returned with the entries
7299 as with prop_list(), and additionally an "lnum" entry.
7300 If no match is found then an empty Dict is returned.
7301
7302 See |text-properties| for information about text properties.
7303
7304
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007305prop_list({lnum} [, {props}]) *prop_list()*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007306 Return a List with all text properties in line {lnum}.
7307
7308 When {props} contains a "bufnr" item, use this buffer instead
7309 of the current buffer.
7310
7311 The properties are ordered by starting column and priority.
7312 Each property is a Dict with these entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007313 col starting column
Bram Moolenaar4c05fa02019-01-01 15:32:17 +01007314 length length in bytes, one more if line break is
7315 included
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007316 id property ID
7317 type name of the property type, omitted if
7318 the type was deleted
7319 start when TRUE property starts in this line
7320 end when TRUE property ends in this line
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007321
7322 When "start" is zero the property started in a previous line,
7323 the current one is a continuation.
7324 When "end" is zero the property continues in the next line.
7325 The line break after this line is included.
7326
7327 See |text-properties| for information about text properties.
7328
7329
7330 *prop_remove()* *E968*
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007331prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007332 Remove a matching text property from line {lnum}. When
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007333 {lnum-end} is given, remove matching text properties from line
7334 {lnum} to {lnum-end} (inclusive).
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007335 When {lnum} is omitted remove matching text properties from
7336 all lines.
7337
7338 {props} is a dictionary with these fields:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007339 id remove text properties with this ID
7340 type remove text properties with this type name
7341 bufnr use this buffer instead of the current one
7342 all when TRUE remove all matching text properties,
7343 not just the first one
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007344 A property matches when either "id" or "type" matches.
Bram Moolenaar68e65602019-05-26 21:33:31 +02007345 If buffer "bufnr" does not exist you get an error message.
7346 If buffer 'bufnr" is not loaded then nothing happens.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007347
7348 Returns the number of properties that were removed.
7349
7350 See |text-properties| for information about text properties.
7351
7352
7353prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970*
7354 Add a text property type {name}. If a property type with this
7355 name already exists an error is given.
7356 {props} is a dictionary with these optional fields:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007357 bufnr define the property only for this buffer; this
7358 avoids name collisions and automatically
7359 clears the property types when the buffer is
7360 deleted.
7361 highlight name of highlight group to use
7362 priority when a character has multiple text
7363 properties the one with the highest priority
7364 will be used; negative values can be used, the
7365 default priority is zero
Bram Moolenaarde24a872019-05-05 15:48:00 +02007366 combine when TRUE combine the highlight with any
Bram Moolenaara6c27c42019-05-09 19:16:22 +02007367 syntax highlight; when omitted or FALSE syntax
Bram Moolenaarde24a872019-05-05 15:48:00 +02007368 highlight will not be used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007369 start_incl when TRUE inserts at the start position will
7370 be included in the text property
7371 end_incl when TRUE inserts at the end position will be
7372 included in the text property
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007373
7374 See |text-properties| for information about text properties.
7375
7376
7377prop_type_change({name}, {props}) *prop_type_change()*
7378 Change properties of an existing text property type. If a
7379 property with this name does not exist an error is given.
7380 The {props} argument is just like |prop_type_add()|.
7381
7382 See |text-properties| for information about text properties.
7383
7384
7385prop_type_delete({name} [, {props}]) *prop_type_delete()*
7386 Remove the text property type {name}. When text properties
7387 using the type {name} are still in place, they will not have
7388 an effect and can no longer be removed by name.
7389
7390 {props} can contain a "bufnr" item. When it is given, delete
7391 a property type from this buffer instead of from the global
7392 property types.
7393
7394 When text property type {name} is not found there is no error.
7395
7396 See |text-properties| for information about text properties.
7397
7398
7399prop_type_get([{name} [, {props}]) *prop_type_get()*
7400 Returns the properties of property type {name}. This is a
7401 dictionary with the same fields as was given to
7402 prop_type_add().
7403 When the property type {name} does not exist, an empty
7404 dictionary is returned.
7405
7406 {props} can contain a "bufnr" item. When it is given, use
7407 this buffer instead of the global property types.
7408
7409 See |text-properties| for information about text properties.
7410
7411
7412prop_type_list([{props}]) *prop_type_list()*
7413 Returns a list with all property type names.
7414
7415 {props} can contain a "bufnr" item. When it is given, use
7416 this buffer instead of the global property types.
7417
7418 See |text-properties| for information about text properties.
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007419
Bram Moolenaarf2732452018-06-03 14:47:35 +02007420
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007421pumvisible() *pumvisible()*
7422 Returns non-zero when the popup menu is visible, zero
7423 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007424 This can be used to avoid some things that would remove the
7425 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007426
Bram Moolenaar30b65812012-07-12 22:01:11 +02007427py3eval({expr}) *py3eval()*
7428 Evaluate Python expression {expr} and return its result
7429 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007430 Numbers and strings are returned as they are (strings are
7431 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02007432 'encoding').
7433 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007434 Dictionaries are represented as Vim |Dictionary| type with
Bram Moolenaar30b65812012-07-12 22:01:11 +02007435 keys converted to strings.
7436 {only available when compiled with the |+python3| feature}
7437
7438 *E858* *E859*
7439pyeval({expr}) *pyeval()*
7440 Evaluate Python expression {expr} and return its result
7441 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007442 Numbers and strings are returned as they are (strings are
Bram Moolenaar30b65812012-07-12 22:01:11 +02007443 copied though).
7444 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007445 Dictionaries are represented as Vim |Dictionary| type,
Bram Moolenaard09acef2012-09-21 14:54:30 +02007446 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02007447 {only available when compiled with the |+python| feature}
7448
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01007449pyxeval({expr}) *pyxeval()*
7450 Evaluate Python expression {expr} and return its result
7451 converted to Vim data structures.
7452 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7453 See also: |pyeval()|, |py3eval()|
7454 {only available when compiled with the |+python| or the
7455 |+python3| feature}
7456
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007457 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00007458range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007459 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00007460 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7461 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7462 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7463 {max}] (increasing {expr} with {stride} each time, not
7464 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00007465 When the maximum is one before the start the result is an
7466 empty list. When the maximum is more than one before the
7467 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00007468 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007469 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00007470 range(2, 4) " [2, 3, 4]
7471 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007472 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00007473 range(0) " []
7474 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00007475<
Bram Moolenaar543c9b12019-04-05 22:50:40 +02007476 *readdir()*
7477readdir({directory} [, {expr}])
7478 Return a list with file and directory names in {directory}.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02007479 You can also use |glob()| if you don't need to do complicated
7480 things, such as limiting the number of matches.
Bram Moolenaar543c9b12019-04-05 22:50:40 +02007481
7482 When {expr} is omitted all entries are included.
7483 When {expr} is given, it is evaluated to check what to do:
7484 If {expr} results in -1 then no further entries will
7485 be handled.
7486 If {expr} results in 0 then this entry will not be
7487 added to the list.
7488 If {expr} results in 1 then this entry will be added
7489 to the list.
7490 Each time {expr} is evaluated |v:val| is set to the entry name.
7491 When {expr} is a function the name is passed as the argument.
7492 For example, to get a list of files ending in ".txt": >
7493 readdir(dirname, {n -> n =~ '.txt$'})
7494< To skip hidden and backup files: >
7495 readdir(dirname, {n -> n !~ '^\.\|\~$'})
7496
7497< If you want to get a directory tree: >
7498 function! s:tree(dir)
7499 return {a:dir : map(readdir(a:dir),
7500 \ {_, x -> isdirectory(x) ?
7501 \ {x : s:tree(a:dir . '/' . x)} : x})}
7502 endfunction
7503 echo s:tree(".")
7504<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007505 *readfile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007506readfile({fname} [, {type} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007507 Read file {fname} and return a |List|, each line of the file
Bram Moolenaar6100d022016-10-02 16:51:57 +02007508 as an item. Lines are broken at NL characters. Macintosh
7509 files separated with CR will result in a single long line
7510 (unless a NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02007511 All NUL characters are replaced with a NL character.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007512 When {type} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007513 - When the last line ends in a NL an extra empty list item is
7514 added.
7515 - No CR characters are removed.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007516 When {type} contains "B" a |Blob| is returned with the binary
7517 data of the file unmodified.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007518 Otherwise:
7519 - CR characters that appear before a NL are removed.
7520 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02007521 - When 'encoding' is Unicode any UTF-8 byte order mark is
7522 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007523 When {max} is given this specifies the maximum number of lines
7524 to be read. Useful if you only want to check the first ten
7525 lines of a file: >
7526 :for line in readfile(fname, '', 10)
7527 : if line =~ 'Date' | echo line | endif
7528 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00007529< When {max} is negative -{max} lines from the end of the file
7530 are returned, or as many as there are.
7531 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007532 Note that without {max} the whole file is read into memory.
7533 Also note that there is no recognition of encoding. Read a
7534 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007535 When the file can't be opened an error message is given and
7536 the result is an empty list.
7537 Also see |writefile()|.
7538
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007539reg_executing() *reg_executing()*
7540 Returns the single letter name of the register being executed.
7541 Returns an empty string when no register is being executed.
7542 See |@|.
7543
7544reg_recording() *reg_recording()*
7545 Returns the single letter name of the register being recorded.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02007546 Returns an empty string when not recording. See |q|.
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007547
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007548reltime([{start} [, {end}]]) *reltime()*
7549 Return an item that represents a time value. The format of
7550 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02007551 |reltimestr()| to convert it to a string or |reltimefloat()|
7552 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007553 Without an argument it returns the current time.
7554 With one argument is returns the time passed since the time
7555 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007556 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007557 and {end}.
7558 The {start} and {end} arguments must be values returned by
7559 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02007560 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007561
Bram Moolenaar03413f42016-04-12 21:07:15 +02007562reltimefloat({time}) *reltimefloat()*
7563 Return a Float that represents the time value of {time}.
7564 Example: >
7565 let start = reltime()
7566 call MyFunction()
7567 let seconds = reltimefloat(reltime(start))
7568< See the note of reltimestr() about overhead.
7569 Also see |profiling|.
7570 {only available when compiled with the |+reltime| feature}
7571
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007572reltimestr({time}) *reltimestr()*
7573 Return a String that represents the time value of {time}.
7574 This is the number of seconds, a dot and the number of
7575 microseconds. Example: >
7576 let start = reltime()
7577 call MyFunction()
7578 echo reltimestr(reltime(start))
7579< Note that overhead for the commands will be added to the time.
7580 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007581 Leading spaces are used to make the string align nicely. You
7582 can use split() to remove it. >
7583 echo split(reltimestr(reltime(start)))[0]
7584< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02007585 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007586
Bram Moolenaar071d4272004-06-13 20:20:40 +00007587 *remote_expr()* *E449*
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007588remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007589 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00007590 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007591 The result must be a String or a |List|. A |List| is turned
7592 into a String by joining the items with a line break in
7593 between (not at the end), like with join(expr, "\n").
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007594 If {idvar} is present and not empty, it is taken as the name
7595 of a variable and a {serverid} for later use with
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01007596 |remote_read()| is stored there.
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007597 If {timeout} is given the read times out after this many
7598 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007599 See also |clientserver| |RemoteReply|.
7600 This function is not available in the |sandbox|.
7601 {only available when compiled with the |+clientserver| feature}
7602 Note: Any errors will cause a local error message to be issued
7603 and the result will be the empty string.
Bram Moolenaar01164a62017-11-02 22:58:42 +01007604
7605 Variables will be evaluated in the global namespace,
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007606 independent of a function currently being active. Except
Bram Moolenaar01164a62017-11-02 22:58:42 +01007607 when in debug mode, then local function variables and
7608 arguments can be evaluated.
7609
Bram Moolenaar071d4272004-06-13 20:20:40 +00007610 Examples: >
7611 :echo remote_expr("gvim", "2+2")
7612 :echo remote_expr("gvim1", "b:current_syntax")
7613<
7614
7615remote_foreground({server}) *remote_foreground()*
7616 Move the Vim server with the name {server} to the foreground.
7617 This works like: >
7618 remote_expr({server}, "foreground()")
7619< Except that on Win32 systems the client does the work, to work
7620 around the problem that the OS doesn't always allow the server
7621 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00007622 Note: This does not restore the window if it was minimized,
7623 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007624 This function is not available in the |sandbox|.
7625 {only in the Win32, Athena, Motif and GTK GUI versions and the
7626 Win32 console version}
7627
7628
7629remote_peek({serverid} [, {retvar}]) *remote_peek()*
7630 Returns a positive number if there are available strings
7631 from {serverid}. Copies any reply string into the variable
Bram Moolenaar58b85342016-08-14 19:54:54 +02007632 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007633 name of a variable.
7634 Returns zero if none are available.
7635 Returns -1 if something is wrong.
7636 See also |clientserver|.
7637 This function is not available in the |sandbox|.
7638 {only available when compiled with the |+clientserver| feature}
7639 Examples: >
7640 :let repl = ""
7641 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
7642
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007643remote_read({serverid}, [{timeout}]) *remote_read()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007644 Return the oldest available reply from {serverid} and consume
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007645 it. Unless a {timeout} in seconds is given, it blocks until a
7646 reply is available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007647 See also |clientserver|.
7648 This function is not available in the |sandbox|.
7649 {only available when compiled with the |+clientserver| feature}
7650 Example: >
7651 :echo remote_read(id)
7652<
7653 *remote_send()* *E241*
7654remote_send({server}, {string} [, {idvar}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007655 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00007656 keys and the function returns immediately. At the Vim server
7657 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007658 If {idvar} is present, it is taken as the name of a variable
7659 and a {serverid} for later use with remote_read() is stored
7660 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007661 See also |clientserver| |RemoteReply|.
7662 This function is not available in the |sandbox|.
7663 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007664
Bram Moolenaar071d4272004-06-13 20:20:40 +00007665 Note: Any errors will be reported in the server and may mess
7666 up the display.
7667 Examples: >
7668 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
7669 \ remote_read(serverid)
7670
7671 :autocmd NONE RemoteReply *
7672 \ echo remote_read(expand("<amatch>"))
7673 :echo remote_send("gvim", ":sleep 10 | echo ".
7674 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007675<
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007676 *remote_startserver()* *E941* *E942*
7677remote_startserver({name})
7678 Become the server {name}. This fails if already running as a
7679 server, when |v:servername| is not empty.
7680 {only available when compiled with the |+clientserver| feature}
7681
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007682remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007683 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007684 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007685 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007686 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007687 item as {end} a list with one item is returned. When {end}
7688 points to an item before {idx} this is an error.
7689 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007690 Example: >
7691 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007692 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007693<
7694 Use |delete()| to remove a file.
7695
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007696remove({blob}, {idx} [, {end}])
7697 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7698 return the byte.
7699 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7700 return a |Blob| with these bytes. When {idx} points to the same
7701 byte as {end} a |Blob| with one byte is returned. When {end}
7702 points to a byte before {idx} this is an error.
7703 Example: >
7704 :echo "last byte: " . remove(myblob, -1)
7705 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007706
Bram Moolenaard8b02732005-01-14 21:48:43 +00007707remove({dict}, {key})
7708 Remove the entry from {dict} with key {key}. Example: >
7709 :echo "removed " . remove(dict, "one")
7710< If there is no {key} in {dict} this is an error.
7711
Bram Moolenaar071d4272004-06-13 20:20:40 +00007712rename({from}, {to}) *rename()*
7713 Rename the file by the name {from} to the name {to}. This
7714 should also work to move files across file systems. The
7715 result is a Number, which is 0 if the file was renamed
7716 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00007717 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007718 This function is not available in the |sandbox|.
7719
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007720repeat({expr}, {count}) *repeat()*
7721 Repeat {expr} {count} times and return the concatenated
7722 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007723 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007724< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007725 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar58b85342016-08-14 19:54:54 +02007726 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007727 :let longlist = repeat(['a', 'b'], 3)
7728< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007729
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007730
Bram Moolenaar071d4272004-06-13 20:20:40 +00007731resolve({filename}) *resolve()* *E655*
7732 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7733 returns the path the shortcut points to in a simplified form.
Bram Moolenaardce1e892019-02-10 23:18:53 +01007734 When {filename} is a symbolic link or junction point, return
7735 the full path to the target. If the target of junction is
7736 removed, return {filename}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007737 On Unix, repeat resolving symbolic links in all path
7738 components of {filename} and return the simplified result.
7739 To cope with link cycles, resolving of symbolic links is
7740 stopped after 100 iterations.
7741 On other systems, return the simplified {filename}.
7742 The simplification step is done as by |simplify()|.
7743 resolve() keeps a leading path component specifying the
7744 current directory (provided the result is still a relative
7745 path name) and also keeps a trailing path separator.
7746
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007747 *reverse()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007748reverse({object})
7749 Reverse the order of items in {object} in-place.
7750 {object} can be a |List| or a |Blob|.
7751 Returns {object}.
7752 If you want an object to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007753 :let revlist = reverse(copy(mylist))
7754
Bram Moolenaar446cb832008-06-24 21:56:24 +00007755round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007756 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00007757 as a |Float|. If {expr} lies halfway between two integral
7758 values, then use the larger one (away from zero).
7759 {expr} must evaluate to a |Float| or a |Number|.
7760 Examples: >
7761 echo round(0.456)
7762< 0.0 >
7763 echo round(4.5)
7764< 5.0 >
7765 echo round(-4.5)
7766< -5.0
7767 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007768
Bram Moolenaare99be0e2019-03-26 22:51:09 +01007769rubyeval({expr}) *rubyeval()*
7770 Evaluate Ruby expression {expr} and return its result
7771 converted to Vim data structures.
7772 Numbers, floats and strings are returned as they are (strings
7773 are copied though).
7774 Arrays are represented as Vim |List| type.
7775 Hashes are represented as Vim |Dictionary| type.
7776 Other objects are represented as strings resulted from their
7777 "Object#to_s" method.
7778 {only available when compiled with the |+ruby| feature}
7779
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007780screenattr({row}, {col}) *screenattr()*
Bram Moolenaar36f44c22016-08-28 18:17:20 +02007781 Like |screenchar()|, but return the attribute. This is a rather
Bram Moolenaar9a773482013-06-11 18:40:13 +02007782 arbitrary number that can only be used to compare to the
7783 attribute at other positions.
7784
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007785screenchar({row}, {col}) *screenchar()*
Bram Moolenaar9a773482013-06-11 18:40:13 +02007786 The result is a Number, which is the character at position
7787 [row, col] on the screen. This works for every possible
7788 screen position, also status lines, window separators and the
7789 command line. The top left position is row one, column one
7790 The character excludes composing characters. For double-byte
7791 encodings it may only be the first byte.
7792 This is mainly to be used for testing.
7793 Returns -1 when row or col is out of range.
7794
Bram Moolenaar2912abb2019-03-29 14:16:42 +01007795screenchars({row}, {col}) *screenchars()*
7796 The result is a List of Numbers. The first number is the same
7797 as what |screenchar()| returns. Further numbers are
7798 composing characters on top of the base character.
7799 This is mainly to be used for testing.
7800 Returns an empty List when row or col is out of range.
7801
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007802screencol() *screencol()*
7803 The result is a Number, which is the current screen column of
7804 the cursor. The leftmost column has number 1.
7805 This function is mainly used for testing.
7806
7807 Note: Always returns the current screen column, thus if used
7808 in a command (e.g. ":echo screencol()") it will return the
7809 column inside the command line, which is 1 when the command is
7810 executed. To get the cursor position in the file use one of
7811 the following mappings: >
7812 nnoremap <expr> GG ":echom ".screencol()."\n"
7813 nnoremap <silent> GG :echom screencol()<CR>
7814<
7815screenrow() *screenrow()*
7816 The result is a Number, which is the current screen row of the
7817 cursor. The top line has number one.
7818 This function is mainly used for testing.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02007819 Alternatively you can use |winline()|.
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007820
7821 Note: Same restrictions as with |screencol()|.
7822
Bram Moolenaar2912abb2019-03-29 14:16:42 +01007823screenstring({row}, {col}) *screenstring()*
7824 The result is a String that contains the base character and
7825 any composing characters at position [row, col] on the screen.
7826 This is like |screenchars()| but returning a String with the
7827 characters.
7828 This is mainly to be used for testing.
7829 Returns an empty String when row or col is out of range.
7830
Bram Moolenaar76929292008-01-06 19:07:36 +00007831search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007832 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00007833 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007834
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007835 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007836 If there is no match a 0 is returned and the cursor doesn't
7837 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007838
Bram Moolenaar071d4272004-06-13 20:20:40 +00007839 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007840 'b' search Backward instead of forward
7841 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007842 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007843 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007844 'p' return number of matching sub-Pattern (see below)
7845 's' Set the ' mark at the previous location of the cursor
7846 'w' Wrap around the end of the file
7847 'W' don't Wrap around the end of the file
7848 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00007849 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7850
Bram Moolenaar02743632005-07-25 20:42:36 +00007851 If the 's' flag is supplied, the ' mark is set, only if the
7852 cursor is moved. The 's' flag cannot be combined with the 'n'
7853 flag.
7854
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007855 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007856
Bram Moolenaar85084ef2016-01-17 22:26:33 +01007857 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007858 column zero and then matches before the cursor are skipped.
7859 When the 'c' flag is present in 'cpo' the next search starts
7860 after the match. Without the 'c' flag the next search starts
7861 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007862
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007863 When the {stopline} argument is given then the search stops
7864 after searching this line. This is useful to restrict the
7865 search to a range of lines. Examples: >
7866 let match = search('(', 'b', line("w0"))
7867 let end = search('END', '', line("w$"))
7868< When {stopline} is used and it is not zero this also implies
7869 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00007870 A zero value is equal to not giving the argument.
7871
7872 When the {timeout} argument is given the search stops when
Bram Moolenaar58b85342016-08-14 19:54:54 +02007873 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00007874 {timeout} is 500 the search stops after half a second.
7875 The value must not be negative. A zero value is like not
7876 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02007877 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007878
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007879 *search()-sub-match*
7880 With the 'p' flag the returned value is one more than the
7881 first sub-match in \(\). One if none of them matched but the
7882 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007883 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007884
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007885 The cursor will be positioned at the match, unless the 'n'
7886 flag is used.
7887
Bram Moolenaar071d4272004-06-13 20:20:40 +00007888 Example (goes over all files in the argument list): >
7889 :let n = 1
7890 :while n <= argc() " loop over all files in arglist
7891 : exe "argument " . n
7892 : " start at the last char in the file and wrap for the
7893 : " first search to find match at start of file
7894 : normal G$
7895 : let flags = "w"
7896 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00007897 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00007898 : let flags = "W"
7899 : endwhile
7900 : update " write the file if modified
7901 : let n = n + 1
7902 :endwhile
7903<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007904 Example for using some flags: >
7905 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7906< This will search for the keywords "if", "else", and "endif"
7907 under or after the cursor. Because of the 'p' flag, it
7908 returns 1, 2, or 3 depending on which keyword is found, or 0
7909 if the search fails. With the cursor on the first word of the
7910 line:
7911 if (foo == 0) | let foo = foo + 1 | endif ~
7912 the function returns 1. Without the 'c' flag, the function
7913 finds the "endif" and returns 3. The same thing happens
7914 without the 'e' flag if the cursor is on the "f" of "if".
7915 The 'n' flag tells the function not to move the cursor.
7916
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007917
Bram Moolenaarf75a9632005-09-13 21:20:47 +00007918searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7919 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007920
Bram Moolenaarf75a9632005-09-13 21:20:47 +00007921 With a non-zero {global} argument it works like |gD|, find
7922 first match in the file. Otherwise it works like |gd|, find
7923 first match in the function.
7924
7925 With a non-zero {thisblock} argument matches in a {} block
7926 that ends before the cursor position are ignored. Avoids
7927 finding variable declarations only valid in another scope.
7928
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007929 Moves the cursor to the found match.
7930 Returns zero for success, non-zero for failure.
7931 Example: >
7932 if searchdecl('myvar') == 0
7933 echo getline('.')
7934 endif
7935<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007936 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00007937searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7938 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00007939 Search for the match of a nested start-end pair. This can be
7940 used to find the "endif" that matches an "if", while other
7941 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007942 The search starts at the cursor. The default is to search
7943 forward, include 'b' in {flags} to search backward.
7944 If a match is found, the cursor is positioned at it and the
7945 line number is returned. If no match is found 0 or -1 is
7946 returned and the cursor doesn't move. No error message is
7947 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007948
7949 {start}, {middle} and {end} are patterns, see |pattern|. They
7950 must not contain \( \) pairs. Use of \%( \) is allowed. When
7951 {middle} is not empty, it is found when searching from either
7952 direction, but only when not in a nested start-end pair. A
7953 typical use is: >
7954 searchpair('\<if\>', '\<else\>', '\<endif\>')
7955< By leaving {middle} empty the "else" is skipped.
7956
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007957 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7958 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00007959 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007960 outer pair. Implies the 'W' flag.
7961 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007962 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007963 Note: it's nearly always a good idea to use the 'W' flag, to
7964 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007965
7966 When a match for {start}, {middle} or {end} is found, the
7967 {skip} expression is evaluated with the cursor positioned on
7968 the start of the match. It should return non-zero if this
7969 match is to be skipped. E.g., because it is inside a comment
7970 or a string.
7971 When {skip} is omitted or empty, every match is accepted.
7972 When evaluating {skip} causes an error the search is aborted
7973 and -1 returned.
Bram Moolenaar48570482017-10-30 21:48:41 +01007974 {skip} can be a string, a lambda, a funcref or a partial.
Bram Moolenaar675e8d62018-06-24 20:42:01 +02007975 Anything else makes the function fail.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007976
Bram Moolenaar76929292008-01-06 19:07:36 +00007977 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007978
Bram Moolenaar071d4272004-06-13 20:20:40 +00007979 The value of 'ignorecase' is used. 'magic' is ignored, the
7980 patterns are used like it's on.
7981
7982 The search starts exactly at the cursor. A match with
7983 {start}, {middle} or {end} at the next character, in the
7984 direction of searching, is the first one found. Example: >
7985 if 1
7986 if 2
7987 endif 2
7988 endif 1
7989< When starting at the "if 2", with the cursor on the "i", and
7990 searching forwards, the "endif 2" is found. When starting on
7991 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar58b85342016-08-14 19:54:54 +02007992 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007993 then this is considered to be a nested if/endif from "if 2" to
7994 "endif 2".
7995 When searching backwards and {end} is more than one character,
7996 it may be useful to put "\zs" at the end of the pattern, so
7997 that when the cursor is inside a match with the end it finds
7998 the matching start.
7999
8000 Example, to find the "endif" command in a Vim script: >
8001
8002 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
8003 \ 'getline(".") =~ "^\\s*\""')
8004
8005< The cursor must be at or after the "if" for which a match is
8006 to be found. Note that single-quote strings are used to avoid
8007 having to double the backslashes. The skip expression only
8008 catches comments at the start of a line, not after a command.
8009 Also, a word "en" or "if" halfway a line is considered a
8010 match.
8011 Another example, to search for the matching "{" of a "}": >
8012
8013 :echo searchpair('{', '', '}', 'bW')
8014
8015< This works when the cursor is at or before the "}" for which a
8016 match is to be found. To reject matches that syntax
8017 highlighting recognized as strings: >
8018
8019 :echo searchpair('{', '', '}', 'bW',
8020 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
8021<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008022 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00008023searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
8024 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008025 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008026 column position of the match. The first element of the |List|
8027 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008028 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008029 returns [0, 0]. >
8030
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008031 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
8032<
8033 See |match-parens| for a bigger and more useful example.
8034
Bram Moolenaar76929292008-01-06 19:07:36 +00008035searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008036 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008037 column position of the match. The first element of the |List|
8038 is the line number and the second element is the byte index of
8039 the column position of the match. If no match is found,
8040 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00008041 Example: >
8042 :let [lnum, col] = searchpos('mypattern', 'n')
8043
8044< When the 'p' flag is given then there is an extra item with
8045 the sub-pattern match number |search()-sub-match|. Example: >
8046 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
8047< In this example "submatch" is 2 when a lowercase letter is
8048 found |/\l|, 3 when an uppercase letter is found |/\u|.
8049
Bram Moolenaar81edd172016-04-14 13:51:37 +02008050server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008051 Send a reply string to {clientid}. The most recent {clientid}
8052 that sent a string can be retrieved with expand("<client>").
8053 {only available when compiled with the |+clientserver| feature}
8054 Note:
8055 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008056 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008057 before calling any commands that waits for input.
8058 See also |clientserver|.
8059 Example: >
8060 :echo server2client(expand("<client>"), "HELLO")
8061<
8062serverlist() *serverlist()*
8063 Return a list of available server names, one per line.
8064 When there are no servers or the information is not available
8065 an empty string is returned. See also |clientserver|.
8066 {only available when compiled with the |+clientserver| feature}
8067 Example: >
8068 :echo serverlist()
8069<
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008070setbufline({expr}, {lnum}, {text}) *setbufline()*
8071 Set line {lnum} to {text} in buffer {expr}. To insert
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008072 lines use |append()|. Any text properties in {lnum} are
8073 cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008074
8075 For the use of {expr}, see |bufname()| above.
8076
8077 {lnum} is used like with |setline()|.
8078 This works like |setline()| for the specified buffer.
8079 On success 0 is returned, on failure 1 is returned.
8080
8081 If {expr} is not a valid buffer or {lnum} is not valid, an
8082 error message is given.
8083
Bram Moolenaar071d4272004-06-13 20:20:40 +00008084setbufvar({expr}, {varname}, {val}) *setbufvar()*
8085 Set option or local variable {varname} in buffer {expr} to
8086 {val}.
8087 This also works for a global or local window option, but it
8088 doesn't work for a global or local window variable.
8089 For a local window option the global value is unchanged.
8090 For the use of {expr}, see |bufname()| above.
8091 Note that the variable name without "b:" must be used.
8092 Examples: >
8093 :call setbufvar(1, "&mod", 1)
8094 :call setbufvar("todo", "myvar", "foobar")
8095< This function is not available in the |sandbox|.
8096
Bram Moolenaar12969c02015-09-08 23:36:10 +02008097setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02008098 Set the current character search information to {dict},
8099 which contains one or more of the following entries:
8100
8101 char character which will be used for a subsequent
8102 |,| or |;| command; an empty string clears the
8103 character search
8104 forward direction of character search; 1 for forward,
8105 0 for backward
8106 until type of character search; 1 for a |t| or |T|
8107 character search, 0 for an |f| or |F|
8108 character search
8109
8110 This can be useful to save/restore a user's character search
8111 from a script: >
8112 :let prevsearch = getcharsearch()
8113 :" Perform a command which clobbers user's search
8114 :call setcharsearch(prevsearch)
8115< Also see |getcharsearch()|.
8116
Bram Moolenaar071d4272004-06-13 20:20:40 +00008117setcmdpos({pos}) *setcmdpos()*
8118 Set the cursor position in the command line to byte position
Bram Moolenaar58b85342016-08-14 19:54:54 +02008119 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008120 Use |getcmdpos()| to obtain the current position.
8121 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00008122 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
8123 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
8124 set after the command line is set to the expression. For
8125 |c_CTRL-R_=| it is set after evaluating the expression but
8126 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008127 When the number is too big the cursor is put at the end of the
8128 line. A number smaller than one has undefined results.
8129 Returns 0 when successful, 1 when not editing the command
8130 line.
8131
Bram Moolenaar691ddee2019-05-09 14:52:41 +02008132setenv({name}, {val}) *setenv()*
8133 Set environment variable {name} to {val}.
8134 When {val} is |v:null| the environment variable is deleted.
8135 See also |expr-env|.
8136
Bram Moolenaar80492532016-03-08 17:08:53 +01008137setfperm({fname}, {mode}) *setfperm()* *chmod*
8138 Set the file permissions for {fname} to {mode}.
8139 {mode} must be a string with 9 characters. It is of the form
8140 "rwxrwxrwx", where each group of "rwx" flags represent, in
8141 turn, the permissions of the owner of the file, the group the
8142 file belongs to, and other users. A '-' character means the
8143 permission is off, any other character means on. Multi-byte
8144 characters are not supported.
8145
8146 For example "rw-r-----" means read-write for the user,
8147 readable by the group, not accessible by others. "xx-x-----"
8148 would do the same thing.
8149
8150 Returns non-zero for success, zero for failure.
8151
8152 To read permissions see |getfperm()|.
8153
8154
Bram Moolenaar446cb832008-06-24 21:56:24 +00008155setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008156 Set line {lnum} of the current buffer to {text}. To insert
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008157 lines use |append()|. To set lines in another buffer use
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008158 |setbufline()|. Any text properties in {lnum} are cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008159
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008160 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008161 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008162 added as a new line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008163
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008164 If this succeeds, 0 is returned. If this fails (most likely
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008165 because {lnum} is invalid) 1 is returned.
8166
8167 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008168 :call setline(5, strftime("%c"))
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008169
Bram Moolenaar446cb832008-06-24 21:56:24 +00008170< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008171 will be set to the items in the list. Example: >
8172 :call setline(5, ['aaa', 'bbb', 'ccc'])
8173< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02008174 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008175 : call setline(n, l)
8176 :endfor
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008177
Bram Moolenaar071d4272004-06-13 20:20:40 +00008178< Note: The '[ and '] marks are not set.
8179
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008180setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00008181 Create or replace or add to the location list for window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008182 {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02008183 When {nr} is zero the current window is used.
8184
8185 For a location list window, the displayed location list is
8186 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00008187 Otherwise, same as |setqflist()|.
8188 Also see |location-list|.
8189
Bram Moolenaard823fa92016-08-12 16:29:27 +02008190 If the optional {what} dictionary argument is supplied, then
8191 only the items listed in {what} are set. Refer to |setqflist()|
8192 for the list of supported keys in {what}.
8193
Bram Moolenaaraff74912019-03-30 18:11:49 +01008194setmatches({list} [, {win}]) *setmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01008195 Restores a list of matches saved by |getmatches() for the
8196 current window|. Returns 0 if successful, otherwise -1. All
8197 current matches are cleared before the list is restored. See
8198 example for |getmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01008199 If {win} is specified, use the window with this number or
8200 window ID instead of the current window.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008201
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008202 *setpos()*
8203setpos({expr}, {list})
8204 Set the position for {expr}. Possible values:
8205 . the cursor
8206 'x mark x
8207
Bram Moolenaar493c1782014-05-28 14:34:46 +02008208 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008209 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02008210 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008211
Bram Moolenaar58b85342016-08-14 19:54:54 +02008212 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarf13e00b2017-01-28 18:23:54 +01008213 current buffer. When setting an uppercase mark "bufnum" is
8214 used for the mark position. For other marks it specifies the
8215 buffer to set the mark in. You can use the |bufnr()| function
8216 to turn a file name into a buffer number.
8217 For setting the cursor and the ' mark "bufnum" is ignored,
8218 since these are associated with a window, not a buffer.
Bram Moolenaardb552d602006-03-23 22:59:57 +00008219 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008220
8221 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008222 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8223 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008224
8225 The "off" number is only used when 'virtualedit' is set. Then
8226 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008227 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008228 character.
8229
Bram Moolenaar493c1782014-05-28 14:34:46 +02008230 The "curswant" number is only used when setting the cursor
8231 position. It sets the preferred column for when moving the
8232 cursor vertically. When the "curswant" number is missing the
8233 preferred column is not set. When it is present and setting a
8234 mark position it is not used.
8235
Bram Moolenaardfb18412013-12-11 18:53:29 +01008236 Note that for '< and '> changing the line number may result in
8237 the marks to be effectively be swapped, so that '< is always
8238 before '>.
8239
Bram Moolenaar08250432008-02-13 11:42:46 +00008240 Returns 0 when the position could be set, -1 otherwise.
8241 An error message is given if {expr} is invalid.
8242
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02008243 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008244
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008245 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02008246 vertically; if you set the cursor position with this, |j| and
8247 |k| motions will jump to previous columns! Use |cursor()| to
8248 also set the preferred column. Also see the "curswant" key in
8249 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008250
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008251setqflist({list} [, {action} [, {what}]]) *setqflist()*
Bram Moolenaarae338332017-08-11 20:25:26 +02008252 Create or replace or add to the quickfix list.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008253
Bram Moolenaarae338332017-08-11 20:25:26 +02008254 When {what} is not present, use the items in {list}. Each
8255 item must be a dictionary. Non-dictionary items in {list} are
8256 ignored. Each dictionary item can contain the following
8257 entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008258
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008259 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00008260 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008261 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00008262 present or it is invalid.
Bram Moolenaard76ce852018-05-01 15:02:04 +02008263 module name of a module; if given it will be used in
8264 quickfix error window instead of the filename.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008265 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008266 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00008267 col column number
8268 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008269 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00008270 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008271 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00008272 type single-character error type, 'E', 'W', etc.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02008273 valid recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008274
Bram Moolenaar582fd852005-03-28 20:58:01 +00008275 The "col", "vcol", "nr", "type" and "text" entries are
8276 optional. Either "lnum" or "pattern" entry can be used to
8277 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008278 If the "filename" and "bufnr" entries are not present or
8279 neither the "lnum" or "pattern" entries are present, then the
8280 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008281 If both "pattern" and "lnum" are present then "pattern" will
8282 be used.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02008283 If the "valid" entry is not supplied, then the valid flag is
8284 set when "bufnr" is a valid buffer or "filename" exists.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008285 If you supply an empty {list}, the quickfix list will be
8286 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008287 Note that the list is not exactly the same as what
8288 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008289
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008290 {action} values: *E927*
8291 'a' The items from {list} are added to the existing
8292 quickfix list. If there is no existing list, then a
8293 new list is created.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008294
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008295 'r' The items from the current quickfix list are replaced
8296 with the items from {list}. This can also be used to
8297 clear the list: >
8298 :call setqflist([], 'r')
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008299<
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008300 'f' All the quickfix lists in the quickfix stack are
8301 freed.
8302
Bram Moolenaar511972d2016-06-04 18:09:59 +02008303 If {action} is not present or is set to ' ', then a new list
Bram Moolenaar55b69262017-08-13 13:42:01 +02008304 is created. The new quickfix list is added after the current
8305 quickfix list in the stack and all the following lists are
8306 freed. To add a new quickfix list at the end of the stack,
Bram Moolenaar36538222017-09-02 19:51:44 +02008307 set "nr" in {what} to "$".
Bram Moolenaar35c54e52005-05-20 21:25:31 +00008308
Bram Moolenaard823fa92016-08-12 16:29:27 +02008309 If the optional {what} dictionary argument is supplied, then
8310 only the items listed in {what} are set. The first {list}
8311 argument is ignored. The following items can be specified in
8312 {what}:
Bram Moolenaar15142e22018-04-30 22:19:58 +02008313 context quickfix list context. See |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02008314 efm errorformat to use when parsing text from
8315 "lines". If this is not present, then the
8316 'errorformat' option value is used.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008317 See |quickfix-parse|
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008318 id quickfix list identifier |quickfix-ID|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008319 idx index of the current entry in the quickfix
8320 list specified by 'id' or 'nr'. If set to '$',
8321 then the last entry in the list is set as the
8322 current entry. See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02008323 items list of quickfix entries. Same as the {list}
8324 argument.
Bram Moolenaar2c809b72017-09-01 18:34:02 +02008325 lines use 'errorformat' to parse a list of lines and
8326 add the resulting entries to the quickfix list
8327 {nr} or {id}. Only a |List| value is supported.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008328 See |quickfix-parse|
Bram Moolenaar875feea2017-06-11 16:07:51 +02008329 nr list number in the quickfix stack; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02008330 means the current quickfix list and "$" means
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008331 the last quickfix list.
8332 title quickfix list title text. See |quickfix-title|
Bram Moolenaard823fa92016-08-12 16:29:27 +02008333 Unsupported keys in {what} are ignored.
8334 If the "nr" item is not present, then the current quickfix list
Bram Moolenaar86f100dc2017-06-28 21:26:27 +02008335 is modified. When creating a new quickfix list, "nr" can be
8336 set to a value one greater than the quickfix stack size.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008337 When modifying a quickfix list, to guarantee that the correct
Bram Moolenaar36538222017-09-02 19:51:44 +02008338 list is modified, "id" should be used instead of "nr" to
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008339 specify the list.
Bram Moolenaard823fa92016-08-12 16:29:27 +02008340
Bram Moolenaar15142e22018-04-30 22:19:58 +02008341 Examples (See also |setqflist-examples|): >
Bram Moolenaar2c809b72017-09-01 18:34:02 +02008342 :call setqflist([], 'r', {'title': 'My search'})
8343 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
Bram Moolenaar15142e22018-04-30 22:19:58 +02008344 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02008345<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008346 Returns zero for success, -1 for failure.
8347
8348 This function can be used to create a quickfix list
8349 independent of the 'errorformat' setting. Use a command like
Bram Moolenaar94237492017-04-23 18:40:21 +02008350 `:cc 1` to jump to the first position.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008351
8352
Bram Moolenaar071d4272004-06-13 20:20:40 +00008353 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01008354setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00008355 Set the register {regname} to {value}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008356 {value} may be any value returned by |getreg()|, including
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008357 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008358 If {options} contains "a" or {regname} is upper case,
8359 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02008360 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008361 "c" or "v" |characterwise| mode
8362 "l" or "V" |linewise| mode
8363 "b" or "<CTRL-V>" |blockwise-visual| mode
8364 If a number immediately follows "b" or "<CTRL-V>" then this is
8365 used as the width of the selection - if it is not specified
8366 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008367 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008368
8369 If {options} contains no register settings, then the default
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008370 is to use character mode unless {value} ends in a <NL> for
8371 string {value} and linewise mode for list {value}. Blockwise
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008372 mode is never selected automatically.
8373 Returns zero for success, non-zero for failure.
8374
8375 *E883*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008376 Note: you may not use |List| containing more than one item to
8377 set search and expression registers. Lists containing no
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008378 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008379
8380 Examples: >
8381 :call setreg(v:register, @*)
8382 :call setreg('*', @%, 'ac')
8383 :call setreg('a', "1\n2\n3", 'b5')
8384
8385< This example shows using the functions to save and restore a
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008386 register: >
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008387 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008388 :let var_amode = getregtype('a')
8389 ....
8390 :call setreg('a', var_a, var_amode)
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008391< Note: you may not reliably restore register value
8392 without using the third argument to |getreg()| as without it
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008393 newlines are represented as newlines AND Nul bytes are
8394 represented as newlines as well, see |NL-used-for-Nul|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008395
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008396 You can also change the type of a register by appending
Bram Moolenaar071d4272004-06-13 20:20:40 +00008397 nothing: >
8398 :call setreg('a', '', 'al')
8399
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008400settabvar({tabnr}, {varname}, {val}) *settabvar()*
8401 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8402 |t:var|
Bram Moolenaarb4230122019-05-30 18:40:53 +02008403 Note that autocommands are blocked, side effects may not be
8404 triggered, e.g. when setting 'filetype'.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008405 Note that the variable name without "t:" must be used.
8406 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008407 This function is not available in the |sandbox|.
8408
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008409settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8410 Set option or local variable {varname} in window {winnr} to
8411 {val}.
8412 Tabs are numbered starting with one. For the current tabpage
8413 use |setwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008414 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008415 When {winnr} is zero the current window is used.
Bram Moolenaarb4230122019-05-30 18:40:53 +02008416 Note that autocommands are blocked, side effects may not be
8417 triggered, e.g. when setting 'filetype' or 'syntax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008418 This also works for a global or local buffer option, but it
8419 doesn't work for a global or local buffer variable.
8420 For a local buffer option the global value is unchanged.
8421 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008422 Examples: >
8423 :call settabwinvar(1, 1, "&list", 0)
8424 :call settabwinvar(3, 2, "myvar", "foobar")
8425< This function is not available in the |sandbox|.
8426
Bram Moolenaarf49cc602018-11-11 15:21:05 +01008427settagstack({nr}, {dict} [, {action}]) *settagstack()*
8428 Modify the tag stack of the window {nr} using {dict}.
8429 {nr} can be the window number or the |window-ID|.
8430
8431 For a list of supported items in {dict}, refer to
8432 |gettagstack()|
8433 *E962*
8434 If {action} is not present or is set to 'r', then the tag
8435 stack is replaced. If {action} is set to 'a', then new entries
8436 from {dict} are pushed onto the tag stack.
8437
8438 Returns zero for success, -1 for failure.
8439
8440 Examples:
8441 Set current index of the tag stack to 4: >
8442 call settagstack(1005, {'curidx' : 4})
8443
8444< Empty the tag stack of window 3: >
8445 call settagstack(3, {'items' : []})
8446
8447< Push a new item onto the tag stack: >
8448 let pos = [bufnr('myfile.txt'), 10, 1, 0]
8449 let newtag = [{'tagname' : 'mytag', 'from' : pos}]
8450 call settagstack(2, {'items' : newtag}, 'a')
8451
8452< Save and restore the tag stack: >
8453 let stack = gettagstack(1003)
8454 " do something else
8455 call settagstack(1003, stack)
8456 unlet stack
8457<
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008458setwinvar({nr}, {varname}, {val}) *setwinvar()*
8459 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008460 Examples: >
8461 :call setwinvar(1, "&list", 0)
8462 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008463
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008464sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01008465 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008466 checksum of {string}.
8467 {only available when compiled with the |+cryptv| feature}
8468
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008469shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008470 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008471 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008472 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008473 quotes within {string}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02008474 Otherwise it will enclose {string} in single quotes and
8475 replace all "'" with "'\''".
Bram Moolenaar875feea2017-06-11 16:07:51 +02008476
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008477 When the {special} argument is present and it's a non-zero
8478 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008479 items such as "!", "%", "#" and "<cword>" will be preceded by
8480 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008481 command.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008482
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008483 The "!" character will be escaped (again with a |non-zero-arg|
8484 {special}) when 'shell' contains "csh" in the tail. That is
8485 because for csh and tcsh "!" is used for history replacement
8486 even when inside single quotes.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008487
8488 With a |non-zero-arg| {special} the <NL> character is also
8489 escaped. When 'shell' containing "csh" in the tail it's
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008490 escaped a second time.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008491
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008492 Example of use with a |:!| command: >
8493 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
8494< This results in a directory listing for the file under the
8495 cursor. Example of use with |system()|: >
8496 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01008497< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008498
8499
Bram Moolenaarf9514162018-11-22 03:08:29 +01008500shiftwidth([{col}]) *shiftwidth()*
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008501 Returns the effective value of 'shiftwidth'. This is the
8502 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01008503 'tabstop' value. This function was introduced with patch
Bram Moolenaarf9514162018-11-22 03:08:29 +01008504 7.3.694 in 2012, everybody should have it by now (however it
8505 did not allow for the optional {col} argument until 8.1.542).
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008506
Bram Moolenaarf9514162018-11-22 03:08:29 +01008507 When there is one argument {col} this is used as column number
8508 for which to return the 'shiftwidth' value. This matters for the
8509 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8510 no {col} argument is given, column 1 will be assumed.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008511
Bram Moolenaar162b7142018-12-21 15:17:36 +01008512sign_define({name} [, {dict}]) *sign_define()*
8513 Define a new sign named {name} or modify the attributes of an
8514 existing sign. This is similar to the |:sign-define| command.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008515
Bram Moolenaar162b7142018-12-21 15:17:36 +01008516 Prefix {name} with a unique text to avoid name collisions.
8517 There is no {group} like with placing signs.
8518
8519 The {name} can be a String or a Number. The optional {dict}
8520 argument specifies the sign attributes. The following values
8521 are supported:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008522 icon full path to the bitmap file for the sign.
8523 linehl highlight group used for the whole line the
Bram Moolenaar162b7142018-12-21 15:17:36 +01008524 sign is placed in.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008525 text text that is displayed when there is no icon
Bram Moolenaar162b7142018-12-21 15:17:36 +01008526 or the GUI is not being used.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008527 texthl highlight group used for the text item
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008528
8529 If the sign named {name} already exists, then the attributes
8530 of the sign are updated.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008531
8532 Returns 0 on success and -1 on failure.
8533
8534 Examples: >
8535 call sign_define("mySign", {"text" : "=>", "texthl" :
8536 \ "Error", "linehl" : "Search"})
8537<
8538sign_getdefined([{name}]) *sign_getdefined()*
8539 Get a list of defined signs and their attributes.
8540 This is similar to the |:sign-list| command.
8541
8542 If the {name} is not supplied, then a list of all the defined
8543 signs is returned. Otherwise the attribute of the specified
8544 sign is returned.
8545
8546 Each list item in the returned value is a dictionary with the
8547 following entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008548 icon full path to the bitmap file of the sign
8549 linehl highlight group used for the whole line the
Bram Moolenaar162b7142018-12-21 15:17:36 +01008550 sign is placed in.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008551 name name of the sign
8552 text text that is displayed when there is no icon
Bram Moolenaar162b7142018-12-21 15:17:36 +01008553 or the GUI is not being used.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008554 texthl highlight group used for the text item
Bram Moolenaar162b7142018-12-21 15:17:36 +01008555
8556 Returns an empty List if there are no signs and when {name} is
8557 not found.
8558
8559 Examples: >
8560 " Get a list of all the defined signs
8561 echo sign_getdefined()
8562
8563 " Get the attribute of the sign named mySign
8564 echo sign_getdefined("mySign")
8565<
8566sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()*
8567 Return a list of signs placed in a buffer or all the buffers.
8568 This is similar to the |:sign-place-list| command.
8569
8570 If the optional buffer name {expr} is specified, then only the
8571 list of signs placed in that buffer is returned. For the use
8572 of {expr}, see |bufname()|. The optional {dict} can contain
8573 the following entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008574 group select only signs in this group
8575 id select sign with this identifier
8576 lnum select signs placed in this line. For the use
Bram Moolenaar162b7142018-12-21 15:17:36 +01008577 of {lnum}, see |line()|.
8578 If {group} is '*', then signs in all the groups including the
Bram Moolenaar6436cd82018-12-27 00:28:33 +01008579 global group are returned. If {group} is not supplied or is an
8580 empty string, then only signs in the global group are
8581 returned. If no arguments are supplied, then signs in the
8582 global group placed in all the buffers are returned.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008583 See |sign-group|.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008584
8585 Each list item in the returned value is a dictionary with the
8586 following entries:
8587 bufnr number of the buffer with the sign
8588 signs list of signs placed in {bufnr}. Each list
8589 item is a dictionary with the below listed
8590 entries
8591
8592 The dictionary for each sign contains the following entries:
8593 group sign group. Set to '' for the global group.
8594 id identifier of the sign
8595 lnum line number where the sign is placed
8596 name name of the defined sign
8597 priority sign priority
8598
Bram Moolenaarb589f952019-01-07 22:10:00 +01008599 The returned signs in a buffer are ordered by their line
Bram Moolenaar58a7f872019-06-04 22:48:15 +02008600 number and priority.
Bram Moolenaarb589f952019-01-07 22:10:00 +01008601
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008602 Returns an empty list on failure or if there are no placed
8603 signs.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008604
8605 Examples: >
8606 " Get a List of signs placed in eval.c in the
8607 " global group
8608 echo sign_getplaced("eval.c")
8609
8610 " Get a List of signs in group 'g1' placed in eval.c
8611 echo sign_getplaced("eval.c", {'group' : 'g1'})
8612
8613 " Get a List of signs placed at line 10 in eval.c
8614 echo sign_getplaced("eval.c", {'lnum' : 10})
8615
8616 " Get sign with identifier 10 placed in a.py
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008617 echo sign_getplaced("a.py", {'id' : 10})
Bram Moolenaar162b7142018-12-21 15:17:36 +01008618
8619 " Get sign with id 20 in group 'g1' placed in a.py
8620 echo sign_getplaced("a.py", {'group' : 'g1',
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008621 \ 'id' : 20})
Bram Moolenaar162b7142018-12-21 15:17:36 +01008622
8623 " Get a List of all the placed signs
8624 echo sign_getplaced()
8625<
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01008626 *sign_jump()*
8627sign_jump({id}, {group}, {expr})
8628 Open the buffer {expr} or jump to the window that contains
8629 {expr} and position the cursor at sign {id} in group {group}.
8630 This is similar to the |:sign-jump| command.
8631
8632 For the use of {expr}, see |bufname()|.
8633
8634 Returns the line number of the sign. Returns -1 if the
8635 arguments are invalid.
8636
8637 Example: >
8638 " Jump to sign 10 in the current buffer
8639 call sign_jump(10, '', '')
8640<
Bram Moolenaar162b7142018-12-21 15:17:36 +01008641 *sign_place()*
8642sign_place({id}, {group}, {name}, {expr} [, {dict}])
8643 Place the sign defined as {name} at line {lnum} in file {expr}
8644 and assign {id} and {group} to sign. This is similar to the
8645 |:sign-place| command.
8646
8647 If the sign identifier {id} is zero, then a new identifier is
8648 allocated. Otherwise the specified number is used. {group} is
8649 the sign group name. To use the global sign group, use an
8650 empty string. {group} functions as a namespace for {id}, thus
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008651 two groups can use the same IDs. Refer to |sign-identifier|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008652 and |sign-group| for more information.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008653
Bram Moolenaar162b7142018-12-21 15:17:36 +01008654 {name} refers to a defined sign.
8655 {expr} refers to a buffer name or number. For the accepted
8656 values, see |bufname()|.
8657
8658 The optional {dict} argument supports the following entries:
8659 lnum line number in the buffer {expr} where
8660 the sign is to be placed. For the
8661 accepted values, see |line()|.
8662 priority priority of the sign. See
8663 |sign-priority| for more information.
8664
8665 If the optional {dict} is not specified, then it modifies the
8666 placed sign {id} in group {group} to use the defined sign
8667 {name}.
8668
8669 Returns the sign identifier on success and -1 on failure.
8670
8671 Examples: >
8672 " Place a sign named sign1 with id 5 at line 20 in
8673 " buffer json.c
8674 call sign_place(5, '', 'sign1', 'json.c',
8675 \ {'lnum' : 20})
8676
8677 " Updates sign 5 in buffer json.c to use sign2
8678 call sign_place(5, '', 'sign2', 'json.c')
8679
8680 " Place a sign named sign3 at line 30 in
8681 " buffer json.c with a new identifier
8682 let id = sign_place(0, '', 'sign3', 'json.c',
8683 \ {'lnum' : 30})
8684
8685 " Place a sign named sign4 with id 10 in group 'g3'
8686 " at line 40 in buffer json.c with priority 90
8687 call sign_place(10, 'g3', 'sign4', 'json.c',
8688 \ {'lnum' : 40, 'priority' : 90})
8689<
8690sign_undefine([{name}]) *sign_undefine()*
8691 Deletes a previously defined sign {name}. This is similar to
8692 the |:sign-undefine| command. If {name} is not supplied, then
8693 deletes all the defined signs.
8694
8695 Returns 0 on success and -1 on failure.
8696
8697 Examples: >
8698 " Delete a sign named mySign
8699 call sign_undefine("mySign")
8700
8701 " Delete all the signs
8702 call sign_undefine()
8703<
8704sign_unplace({group} [, {dict}]) *sign_unplace()*
8705 Remove a previously placed sign in one or more buffers. This
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008706 is similar to the |:sign-unplace| command.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008707
8708 {group} is the sign group name. To use the global sign group,
8709 use an empty string. If {group} is set to '*', then all the
8710 groups including the global group are used.
8711 The signs in {group} are selected based on the entries in
8712 {dict}. The following optional entries in {dict} are
8713 supported:
8714 buffer buffer name or number. See |bufname()|.
8715 id sign identifier
8716 If {dict} is not supplied, then all the signs in {group} are
8717 removed.
8718
8719 Returns 0 on success and -1 on failure.
8720
8721 Examples: >
8722 " Remove sign 10 from buffer a.vim
8723 call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
8724
8725 " Remove sign 20 in group 'g1' from buffer 3
8726 call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
8727
8728 " Remove all the signs in group 'g2' from buffer 10
8729 call sign_unplace('g2', {'buffer' : 10})
8730
8731 " Remove sign 30 in group 'g3' from all the buffers
8732 call sign_unplace('g3', {'id' : 30})
8733
8734 " Remove all the signs placed in buffer 5
8735 call sign_unplace('*', {'buffer' : 5})
8736
8737 " Remove the signs in group 'g4' from all the buffers
8738 call sign_unplace('g4')
8739
8740 " Remove sign 40 from all the buffers
8741 call sign_unplace('*', {'id' : 40})
8742
8743 " Remove all the placed signs from all the buffers
8744 call sign_unplace('*')
8745<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008746simplify({filename}) *simplify()*
8747 Simplify the file name as much as possible without changing
8748 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8749 Unix) are not resolved. If the first path component in
8750 {filename} designates the current directory, this will be
8751 valid for the result as well. A trailing path separator is
8752 not removed either.
8753 Example: >
8754 simplify("./dir/.././/file/") == "./file/"
8755< Note: The combination "dir/.." is only removed if "dir" is
8756 a searchable directory or does not exist. On Unix, it is also
8757 removed when "dir" is a symbolic link within the same
8758 directory. In order to resolve all the involved symbolic
8759 links before simplifying the path name, use |resolve()|.
8760
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008761
Bram Moolenaar446cb832008-06-24 21:56:24 +00008762sin({expr}) *sin()*
8763 Return the sine of {expr}, measured in radians, as a |Float|.
8764 {expr} must evaluate to a |Float| or a |Number|.
8765 Examples: >
8766 :echo sin(100)
8767< -0.506366 >
8768 :echo sin(-4.01)
8769< 0.763301
8770 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008771
Bram Moolenaar446cb832008-06-24 21:56:24 +00008772
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008773sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008774 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008775 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008776 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008777 Examples: >
8778 :echo sinh(0.5)
8779< 0.521095 >
8780 :echo sinh(-0.9)
8781< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02008782 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008783
8784
Bram Moolenaar5f894962011-06-19 02:55:37 +02008785sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01008786 Sort the items in {list} in-place. Returns {list}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008787
Bram Moolenaar327aa022014-03-25 18:24:23 +01008788 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008789 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02008790
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008791< When {func} is omitted, is empty or zero, then sort() uses the
8792 string representation of each item to sort on. Numbers sort
8793 after Strings, |Lists| after Numbers. For sorting text in the
8794 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008795
Bram Moolenaar34401cc2014-08-29 15:12:19 +02008796 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008797 ignored.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008798
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008799 When {func} is given and it is 'n' then all items will be
8800 sorted numerical (Implementation detail: This uses the
8801 strtod() function to parse numbers, Strings, Lists, Dicts and
8802 Funcrefs will be considered as being 0).
8803
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01008804 When {func} is given and it is 'N' then all items will be
8805 sorted numerical. This is like 'n' but a string containing
8806 digits will be used as the number they represent.
8807
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01008808 When {func} is given and it is 'f' then all items will be
8809 sorted numerical. All values must be a Number or a Float.
8810
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008811 When {func} is a |Funcref| or a function name, this function
8812 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008813 items as argument and must return zero if they are equal, 1 or
8814 bigger if the first one sorts after the second one, -1 or
8815 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008816
8817 {dict} is for functions with the "dict" attribute. It will be
8818 used to set the local variable "self". |Dictionary-function|
8819
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008820 The sort is stable, items which compare equal (as number or as
8821 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02008822 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008823 same order as they were originally.
8824
Bram Moolenaar327aa022014-03-25 18:24:23 +01008825 Also see |uniq()|.
8826
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008827 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008828 func MyCompare(i1, i2)
8829 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8830 endfunc
8831 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008832< A shorter compare version for this specific simple case, which
8833 ignores overflow: >
8834 func MyCompare(i1, i2)
8835 return a:i1 - a:i2
8836 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008837<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008838 *soundfold()*
8839soundfold({word})
8840 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00008841 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008842 soundfolding. 'spell' must be set. When no sound folding is
8843 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008844 This can be used for making spelling suggestions. Note that
8845 the method can be quite slow.
8846
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008847 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00008848spellbadword([{sentence}])
8849 Without argument: The result is the badly spelled word under
8850 or after the cursor. The cursor is moved to the start of the
8851 bad word. When no bad word is found in the cursor line the
8852 result is an empty string and the cursor doesn't move.
8853
8854 With argument: The result is the first word in {sentence} that
8855 is badly spelled. If there are no spelling mistakes the
8856 result is an empty string.
8857
8858 The return value is a list with two items:
8859 - The badly spelled word or an empty string.
8860 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008861 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00008862 "rare" rare word
8863 "local" word only valid in another region
8864 "caps" word should start with Capital
8865 Example: >
8866 echo spellbadword("the quik brown fox")
8867< ['quik', 'bad'] ~
8868
8869 The spelling information for the current window is used. The
8870 'spell' option must be set and the value of 'spelllang' is
8871 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008872
8873 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008874spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008875 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008876 When {max} is given up to this number of suggestions are
8877 returned. Otherwise up to 25 suggestions are returned.
8878
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008879 When the {capital} argument is given and it's non-zero only
8880 suggestions with a leading capital will be given. Use this
8881 after a match with 'spellcapcheck'.
8882
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008883 {word} can be a badly spelled word followed by other text.
8884 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00008885 suggestions also include the following text, thus you can
8886 replace a line.
8887
8888 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008889 returned. {word} itself is not included in the suggestions,
8890 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008891
8892 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008893 'spell' option must be set and the values of 'spelllang' and
8894 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008895
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008896
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008897split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008898 Make a |List| out of {expr}. When {pattern} is omitted or
8899 empty each white-separated sequence of characters becomes an
8900 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008901 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01008902 removing the matched characters. 'ignorecase' is not used
8903 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008904 When the first or last item is empty it is omitted, unless the
8905 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008906 Other empty items are kept when {pattern} matches at least one
8907 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008908 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008909 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008910< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008911 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02008912< If you want to keep the separator you can also use '\zs' at
8913 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00008914 :echo split('abc:def:ghi', ':\zs')
8915< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008916 Splitting a table where the first element can be empty: >
8917 :let items = split(line, ':', 1)
8918< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008919
8920
Bram Moolenaar446cb832008-06-24 21:56:24 +00008921sqrt({expr}) *sqrt()*
8922 Return the non-negative square root of Float {expr} as a
8923 |Float|.
8924 {expr} must evaluate to a |Float| or a |Number|. When {expr}
8925 is negative the result is NaN (Not a Number).
8926 Examples: >
8927 :echo sqrt(100)
8928< 10.0 >
8929 :echo sqrt(-4.01)
8930< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00008931 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008932 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008933
Bram Moolenaar446cb832008-06-24 21:56:24 +00008934
Bram Moolenaar81edd172016-04-14 13:51:37 +02008935str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008936 Convert String {expr} to a Float. This mostly works the same
8937 as when using a floating point number in an expression, see
8938 |floating-point-format|. But it's a bit more permissive.
8939 E.g., "1e40" is accepted, while in an expression you need to
Bram Moolenaard47d5222018-12-09 20:43:55 +01008940 write "1.0e40". The hexadecimal form "0x123" is also
8941 accepted, but not others, like binary or octal.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008942 Text after the number is silently ignored.
8943 The decimal point is always '.', no matter what the locale is
8944 set to. A comma ends the number: "12,345.67" is converted to
8945 12.0. You can strip out thousands separators with
8946 |substitute()|: >
8947 let f = str2float(substitute(text, ',', '', 'g'))
8948< {only available when compiled with the |+float| feature}
8949
Bram Moolenaar9d401282019-04-06 13:18:12 +02008950str2list({expr} [, {utf8}]) *str2list()*
8951 Return a list containing the number values which represent
8952 each character in String {expr}. Examples: >
8953 str2list(" ") returns [32]
8954 str2list("ABC") returns [65, 66, 67]
8955< |list2str()| does the opposite.
8956
8957 When {utf8} is omitted or zero, the current 'encoding' is used.
8958 With {utf8} set to 1, always treat the String as utf-8
8959 characters. With utf-8 composing characters are handled
8960 properly: >
8961 str2list("á") returns [97, 769]
Bram Moolenaar446cb832008-06-24 21:56:24 +00008962
Bram Moolenaar81edd172016-04-14 13:51:37 +02008963str2nr({expr} [, {base}]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008964 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01008965 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008966 When {base} is omitted base 10 is used. This also means that
8967 a leading zero doesn't cause octal conversion to be used, as
8968 with the default String to Number conversion.
8969 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01008970 different base the result will be zero. Similarly, when
8971 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
8972 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008973 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008974
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008975
Bram Moolenaar979243b2015-06-26 19:35:49 +02008976strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02008977 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02008978 in String {expr}.
8979 When {skipcc} is omitted or zero, composing characters are
8980 counted separately.
8981 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02008982 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008983
Bram Moolenaar86ae7202015-07-10 19:31:35 +02008984 {skipcc} is only available after 7.4.755. For backward
8985 compatibility, you can define a wrapper function: >
8986 if has("patch-7.4.755")
8987 function s:strchars(str, skipcc)
8988 return strchars(a:str, a:skipcc)
8989 endfunction
8990 else
8991 function s:strchars(str, skipcc)
8992 if a:skipcc
8993 return strlen(substitute(a:str, ".", "x", "g"))
8994 else
8995 return strchars(a:str)
8996 endif
8997 endfunction
8998 endif
8999<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009000strcharpart({src}, {start} [, {len}]) *strcharpart()*
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009001 Like |strpart()| but using character index and length instead
9002 of byte index and length.
9003 When a character index is used where a character does not
Bram Moolenaar369b6f52017-01-17 12:22:32 +01009004 exist it is assumed to be one character. For example: >
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009005 strcharpart('abc', -1, 2)
9006< results in 'a'.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02009007
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009008strdisplaywidth({expr} [, {col}]) *strdisplaywidth()*
Bram Moolenaardc536092010-07-18 15:45:49 +02009009 The result is a Number, which is the number of display cells
Bram Moolenaar4c92e752019-02-17 21:18:32 +01009010 String {expr} occupies on the screen when it starts at {col}
9011 (first column is zero). When {col} is omitted zero is used.
9012 Otherwise it is the screen column where to start. This
9013 matters for Tab characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02009014 The option settings of the current window are used. This
9015 matters for anything that's displayed differently, such as
9016 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02009017 When {expr} contains characters with East Asian Width Class
9018 Ambiguous, this function's return value depends on 'ambiwidth'.
9019 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02009020
Bram Moolenaar071d4272004-06-13 20:20:40 +00009021strftime({format} [, {time}]) *strftime()*
9022 The result is a String, which is a formatted date and time, as
9023 specified by the {format} string. The given {time} is used,
9024 or the current time if no time is given. The accepted
9025 {format} depends on your system, thus this is not portable!
9026 See the manual page of the C function strftime() for the
9027 format. The maximum length of the result is 80 characters.
9028 See also |localtime()| and |getftime()|.
9029 The language can be changed with the |:language| command.
9030 Examples: >
9031 :echo strftime("%c") Sun Apr 27 11:49:23 1997
9032 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
9033 :echo strftime("%y%m%d %T") 970427 11:53:55
9034 :echo strftime("%H:%M") 11:55
9035 :echo strftime("%c", getftime("file.c"))
9036 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009037< Not available on all systems. To check use: >
9038 :if exists("*strftime")
9039
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009040strgetchar({str}, {index}) *strgetchar()*
9041 Get character {index} from {str}. This uses a character
9042 index, not a byte index. Composing characters are considered
9043 separate characters here.
9044 Also see |strcharpart()| and |strchars()|.
9045
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009046stridx({haystack}, {needle} [, {start}]) *stridx()*
9047 The result is a Number, which gives the byte index in
9048 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00009049 If {start} is specified, the search starts at index {start}.
9050 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01009051 :let colon1 = stridx(line, ":")
9052 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00009053< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009054 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009055 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00009056 See also |strridx()|.
9057 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009058 :echo stridx("An Example", "Example") 3
9059 :echo stridx("Starting point", "Start") 0
9060 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009061< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00009062 stridx() works similar to the C function strstr(). When used
9063 with a single character it works similar to strchr().
9064
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009065 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009066string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01009067 Float, String, Blob or a composition of them, then the result
9068 can be parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009069 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01009070 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009071 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00009072 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00009073 Funcref function('name')
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01009074 Blob 0z00112233.44556677.8899
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00009075 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00009076 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01009077
9078 When a List or Dictionary has a recursive reference it is
9079 replaced by "[...]" or "{...}". Using eval() on the result
9080 will then fail.
9081
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009082 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009083
Bram Moolenaar071d4272004-06-13 20:20:40 +00009084 *strlen()*
9085strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00009086 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00009087 If the argument is a Number it is first converted to a String.
9088 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02009089 If you want to count the number of multi-byte characters use
9090 |strchars()|.
9091 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009092
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009093strpart({src}, {start} [, {len}]) *strpart()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009094 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00009095 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009096 To count characters instead of bytes use |strcharpart()|.
9097
9098 When bytes are selected which do not exist, this doesn't
9099 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009100 If {len} is missing, the copy continues from {start} till the
9101 end of the {src}. >
9102 strpart("abcdefg", 3, 2) == "de"
9103 strpart("abcdefg", -2, 4) == "ab"
9104 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00009105 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02009106
Bram Moolenaar071d4272004-06-13 20:20:40 +00009107< Note: To get the first character, {start} must be 0. For
9108 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00009109 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009110<
Bram Moolenaar677ee682005-01-27 14:41:15 +00009111strridx({haystack}, {needle} [, {start}]) *strridx()*
9112 The result is a Number, which gives the byte index in
9113 {haystack} of the last occurrence of the String {needle}.
9114 When {start} is specified, matches beyond this index are
9115 ignored. This can be used to find a match before a previous
9116 match: >
9117 :let lastcomma = strridx(line, ",")
9118 :let comma2 = strridx(line, ",", lastcomma - 1)
9119< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00009120 For pattern searches use |match()|.
9121 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00009122 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00009123 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009124 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009125< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00009126 When used with a single character it works similar to the C
9127 function strrchr().
9128
Bram Moolenaar071d4272004-06-13 20:20:40 +00009129strtrans({expr}) *strtrans()*
9130 The result is a String, which is {expr} with all unprintable
9131 characters translated into printable characters |'isprint'|.
9132 Like they are shown in a window. Example: >
9133 echo strtrans(@a)
9134< This displays a newline in register a as "^@" instead of
9135 starting a new line.
9136
Bram Moolenaar72597a52010-07-18 15:31:08 +02009137strwidth({expr}) *strwidth()*
9138 The result is a Number, which is the number of display cells
9139 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02009140 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02009141 When {expr} contains characters with East Asian Width Class
9142 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02009143 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02009144
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009145submatch({nr} [, {list}]) *submatch()* *E935*
Bram Moolenaar251e1912011-06-19 05:09:16 +02009146 Only for an expression in a |:substitute| command or
9147 substitute() function.
9148 Returns the {nr}'th submatch of the matched text. When {nr}
9149 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02009150 Note that a NL in the string can stand for a line break of a
9151 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009152 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02009153
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009154 If {list} is present and non-zero then submatch() returns
9155 a list of strings, similar to |getline()| with two arguments.
Bram Moolenaar41571762014-04-02 19:00:58 +02009156 NL characters in the text represent NUL characters in the
9157 text.
9158 Only returns more than one item for |:substitute|, inside
9159 |substitute()| this list will always contain one or zero
9160 items, since there are no real line breaks.
9161
Bram Moolenaar6100d022016-10-02 16:51:57 +02009162 When substitute() is used recursively only the submatches in
9163 the current (deepest) call can be obtained.
9164
Bram Moolenaar2f058492017-11-30 20:27:52 +01009165 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009166 :s/\d\+/\=submatch(0) + 1/
Bram Moolenaar2f058492017-11-30 20:27:52 +01009167 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009168< This finds the first number in the line and adds one to it.
9169 A line break is included as a newline character.
9170
9171substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
9172 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02009173 the first match of {pat} is replaced with {sub}.
9174 When {flags} is "g", all matches of {pat} in {expr} are
9175 replaced. Otherwise {flags} should be "".
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009176
Bram Moolenaar251e1912011-06-19 05:09:16 +02009177 This works like the ":substitute" command (without any flags).
9178 But the matching with {pat} is always done like the 'magic'
9179 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01009180 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9181 if you want to ignore or match case and ignore 'ignorecase'.
9182 'smartcase' is not used. See |string-match| for how {pat} is
9183 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009184
9185 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009186 Note that some codes in {sub} have a special meaning
Bram Moolenaar58b85342016-08-14 19:54:54 +02009187 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00009188 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009189
Bram Moolenaar071d4272004-06-13 20:20:40 +00009190 When {pat} does not match in {expr}, {expr} is returned
9191 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009192
Bram Moolenaar071d4272004-06-13 20:20:40 +00009193 Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009194 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009195< This removes the last component of the 'path' option. >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009196 :echo substitute("testing", ".*", "\\U\\0", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009197< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02009198
9199 When {sub} starts with "\=", the remainder is interpreted as
9200 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009201 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02009202 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009203
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009204< When {sub} is a Funcref that function is called, with one
9205 optional argument. Example: >
9206 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9207< The optional argument is a list which contains the whole
Bram Moolenaar58b85342016-08-14 19:54:54 +02009208 matched string and up to nine submatches, like what
9209 |submatch()| returns. Example: >
9210 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009211
Bram Moolenaar20aac6c2018-09-02 21:07:30 +02009212swapinfo({fname}) *swapinfo()*
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009213 The result is a dictionary, which holds information about the
9214 swapfile {fname}. The available fields are:
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009215 version Vim version
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009216 user user name
9217 host host name
9218 fname original file name
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009219 pid PID of the Vim process that created the swap
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009220 file
9221 mtime last modification time in seconds
9222 inode Optional: INODE number of the file
Bram Moolenaar47ad5652018-08-21 21:09:07 +02009223 dirty 1 if file was modified, 0 if not
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02009224 Note that "user" and "host" are truncated to at most 39 bytes.
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009225 In case of failure an "error" item is added with the reason:
9226 Cannot open file: file not found or in accessible
9227 Cannot read file: cannot read first block
Bram Moolenaar47ad5652018-08-21 21:09:07 +02009228 Not a swap file: does not contain correct block ID
9229 Magic number mismatch: Info in first block is invalid
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009230
Bram Moolenaar110bd602018-09-16 18:46:59 +02009231swapname({expr}) *swapname()*
9232 The result is the swap file path of the buffer {expr}.
9233 For the use of {expr}, see |bufname()| above.
9234 If buffer {expr} is the current buffer, the result is equal to
9235 |:swapname| (unless no swap file).
9236 If buffer {expr} has no swap file, returns an empty string.
9237
Bram Moolenaar47136d72004-10-12 20:02:24 +00009238synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009239 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00009240 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009241 The syntax ID can be used with |synIDattr()| and
9242 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009243
Bram Moolenaar47136d72004-10-12 20:02:24 +00009244 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009245 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02009246 Note that when the position is after the last character,
9247 that's where the cursor can be in Insert mode, synID() returns
9248 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009249
Bram Moolenaar79815f12016-07-09 17:07:29 +02009250 When {trans} is |TRUE|, transparent items are reduced to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02009251 item that they reveal. This is useful when wanting to know
Bram Moolenaar79815f12016-07-09 17:07:29 +02009252 the effective color. When {trans} is |FALSE|, the transparent
Bram Moolenaar071d4272004-06-13 20:20:40 +00009253 item is returned. This is useful when wanting to know which
9254 syntax item is effective (e.g. inside parens).
9255 Warning: This function can be very slow. Best speed is
9256 obtained by going through the file in forward direction.
9257
9258 Example (echoes the name of the syntax item under the cursor): >
9259 :echo synIDattr(synID(line("."), col("."), 1), "name")
9260<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02009261
Bram Moolenaar071d4272004-06-13 20:20:40 +00009262synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9263 The result is a String, which is the {what} attribute of
9264 syntax ID {synID}. This can be used to obtain information
9265 about a syntax item.
9266 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar58b85342016-08-14 19:54:54 +02009267 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00009268 used, the attributes for the currently active highlighting are
9269 used (GUI, cterm or term).
9270 Use synIDtrans() to follow linked highlight groups.
9271 {what} result
9272 "name" the name of the syntax item
9273 "fg" foreground color (GUI: color name used to set
9274 the color, cterm: color number as a string,
9275 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009276 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01009277 "font" font name (only available in the GUI)
9278 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009279 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009280 "fg#" like "fg", but for the GUI and the GUI is
9281 running the name in "#RRGGBB" form
9282 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009283 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009284 "bold" "1" if bold
9285 "italic" "1" if italic
9286 "reverse" "1" if reverse
9287 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01009288 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00009289 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009290 "undercurl" "1" if undercurled
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02009291 "strike" "1" if strikethrough
Bram Moolenaar071d4272004-06-13 20:20:40 +00009292
9293 Example (echoes the color of the syntax item under the
9294 cursor): >
9295 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9296<
9297synIDtrans({synID}) *synIDtrans()*
9298 The result is a Number, which is the translated syntax ID of
9299 {synID}. This is the syntax group ID of what is being used to
9300 highlight the character. Highlight links given with
9301 ":highlight link" are followed.
9302
Bram Moolenaar483c5d82010-10-20 18:45:33 +02009303synconcealed({lnum}, {col}) *synconcealed()*
Bram Moolenaar4d785892017-06-22 22:00:50 +02009304 The result is a List with currently three items:
9305 1. The first item in the list is 0 if the character at the
9306 position {lnum} and {col} is not part of a concealable
9307 region, 1 if it is.
9308 2. The second item in the list is a string. If the first item
9309 is 1, the second item contains the text which will be
9310 displayed in place of the concealed text, depending on the
9311 current setting of 'conceallevel' and 'listchars'.
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02009312 3. The third and final item in the list is a number
9313 representing the specific syntax region matched in the
9314 line. When the character is not concealed the value is
9315 zero. This allows detection of the beginning of a new
9316 concealable region if there are two consecutive regions
9317 with the same replacement character. For an example, if
9318 the text is "123456" and both "23" and "45" are concealed
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009319 and replaced by the character "X", then:
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02009320 call returns ~
Bram Moolenaarc572da52017-08-27 16:52:01 +02009321 synconcealed(lnum, 1) [0, '', 0]
9322 synconcealed(lnum, 2) [1, 'X', 1]
9323 synconcealed(lnum, 3) [1, 'X', 1]
9324 synconcealed(lnum, 4) [1, 'X', 2]
9325 synconcealed(lnum, 5) [1, 'X', 2]
9326 synconcealed(lnum, 6) [0, '', 0]
Bram Moolenaar483c5d82010-10-20 18:45:33 +02009327
9328
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009329synstack({lnum}, {col}) *synstack()*
9330 Return a |List|, which is the stack of syntax items at the
9331 position {lnum} and {col} in the current window. Each item in
9332 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009333 The first item in the List is the outer region, following are
9334 items contained in that one. The last one is what |synID()|
9335 returns, unless not the whole item is highlighted or it is a
9336 transparent item.
9337 This function is useful for debugging a syntax file.
9338 Example that shows the syntax stack under the cursor: >
9339 for id in synstack(line("."), col("."))
9340 echo synIDattr(id, "name")
9341 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02009342< When the position specified with {lnum} and {col} is invalid
9343 nothing is returned. The position just after the last
9344 character in a line and the first column in an empty line are
9345 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009346
Bram Moolenaarc0197e22004-09-13 20:26:32 +00009347system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009348 Get the output of the shell command {expr} as a string. See
9349 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009350
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009351 When {input} is given and is a string this string is written
9352 to a file and passed as stdin to the command. The string is
9353 written as-is, you need to take care of using the correct line
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009354 separators yourself.
9355 If {input} is given and is a |List| it is written to the file
9356 in a way |writefile()| does with {binary} set to "b" (i.e.
9357 with a newline between each list item with newlines inside
Bram Moolenaar12c44922017-01-08 13:26:03 +01009358 list items converted to NULs).
9359 When {input} is given and is a number that is a valid id for
9360 an existing buffer then the content of the buffer is written
9361 to the file line by line, each line terminated by a NL and
9362 NULs characters where the text has a NL.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02009363
9364 Pipes are not used, the 'shelltemp' option is not used.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009365
Bram Moolenaar04186092016-08-29 21:55:35 +02009366 When prepended by |:silent| the terminal will not be set to
Bram Moolenaar52a72462014-08-29 15:53:52 +02009367 cooked mode. This is meant to be used for commands that do
9368 not need the user to type. It avoids stray characters showing
9369 up on the screen which require |CTRL-L| to remove. >
9370 :silent let f = system('ls *.vim')
9371<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009372 Note: Use |shellescape()| or |::S| with |expand()| or
9373 |fnamemodify()| to escape special characters in a command
9374 argument. Newlines in {expr} may cause the command to fail.
9375 The characters in 'shellquote' and 'shellxquote' may also
Bram Moolenaar26df0922014-02-23 23:39:13 +01009376 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009377 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009378
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009379 The result is a String. Example: >
9380 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01009381 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00009382
9383< To make the result more system-independent, the shell output
9384 is filtered to replace <CR> with <NL> for Macintosh, and
9385 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02009386 To avoid the string being truncated at a NUL, all NUL
9387 characters are replaced with SOH (0x01).
9388
Bram Moolenaar071d4272004-06-13 20:20:40 +00009389 The command executed is constructed using several options:
9390 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9391 ({tmp} is an automatically generated file name).
9392 For Unix and OS/2 braces are put around {expr} to allow for
9393 concatenated commands.
9394
Bram Moolenaar433f7c82006-03-21 21:29:36 +00009395 The command will be executed in "cooked" mode, so that a
9396 CTRL-C will interrupt the command (on Unix at least).
9397
Bram Moolenaar071d4272004-06-13 20:20:40 +00009398 The resulting error code can be found in |v:shell_error|.
9399 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00009400
9401 Note that any wrong value in the options mentioned above may
9402 make the function fail. It has also been reported to fail
9403 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009404 Unlike ":!cmd" there is no automatic check for changed files.
9405 Use |:checktime| to force a check.
9406
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009407
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009408systemlist({expr} [, {input}]) *systemlist()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009409 Same as |system()|, but returns a |List| with lines (parts of
9410 output separated by NL) with NULs transformed into NLs. Output
9411 is the same as |readfile()| will output with {binary} argument
Bram Moolenaar68563932017-01-10 13:31:15 +01009412 set to "b". Note that on MS-Windows you may get trailing CR
9413 characters.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009414
Bram Moolenaar975b5272016-03-15 23:10:59 +01009415 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009416
9417
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009418tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009419 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009420 buffer associated with each window in the current tab page.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009421 {arg} specifies the number of the tab page to be used. When
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009422 omitted the current tab page is used.
9423 When {arg} is invalid the number zero is returned.
9424 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009425 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009426 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009427 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009428 endfor
9429< Note that a buffer may appear in more than one window.
9430
9431
9432tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00009433 The result is a Number, which is the number of the current
9434 tab page. The first tab page has number 1.
9435 When the optional argument is "$", the number of the last tab
9436 page is returned (the tab page count).
9437 The number can be used with the |:tab| command.
9438
9439
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01009440tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02009441 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009442 {tabarg} specifies the number of tab page to be used.
9443 {arg} is used like with |winnr()|:
9444 - When omitted the current window number is returned. This is
9445 the window which will be used when going to this tab page.
9446 - When "$" the number of windows is returned.
9447 - When "#" the previous window nr is returned.
9448 Useful examples: >
9449 tabpagewinnr(1) " current window of tab page 1
9450 tabpagewinnr(4, '$') " number of windows in tab page 4
9451< When {tabarg} is invalid zero is returned.
9452
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00009453 *tagfiles()*
9454tagfiles() Returns a |List| with the file names used to search for tags
9455 for the current buffer. This is the 'tags' option expanded.
9456
9457
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009458taglist({expr} [, {filename}]) *taglist()*
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009459 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaarc6aafba2017-03-21 17:09:10 +01009460
9461 If {filename} is passed it is used to prioritize the results
9462 in the same way that |:tselect| does. See |tag-priority|.
9463 {filename} should be the full path of the file.
9464
Bram Moolenaard8c00872005-07-22 21:52:15 +00009465 Each list item is a dictionary with at least the following
9466 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00009467 name Name of the tag.
9468 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009469 defined. It is either relative to the
9470 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009471 cmd Ex command used to locate the tag in
9472 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009473 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009474 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009475 kind values. Only available when
9476 using a tags file generated by
9477 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009478 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009479 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009480 More entries may be present, depending on the content of the
9481 tags file: access, implementation, inherits and signature.
9482 Refer to the ctags documentation for information about these
9483 fields. For C code the fields "struct", "class" and "enum"
9484 may appear, they give the name of the entity the tag is
9485 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00009486
Bram Moolenaar214641f2017-03-05 17:04:09 +01009487 The ex-command "cmd" can be either an ex search pattern, a
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00009488 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009489
9490 If there are no matching tags, then an empty list is returned.
9491
9492 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01009493 used in {expr}. This also make the function work faster.
9494 Refer to |tag-regexp| for more information about the tag
9495 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009496
9497 Refer to |'tags'| for information about how the tags file is
9498 located by Vim. Refer to |tags-file-format| for the format of
9499 the tags file generated by the different ctags tools.
9500
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009501tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009502 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009503 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009504 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009505 Examples: >
9506 :echo tan(10)
9507< 0.648361 >
9508 :echo tan(-4.01)
9509< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02009510 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009511
9512
9513tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009514 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009515 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009516 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009517 Examples: >
9518 :echo tanh(0.5)
9519< 0.462117 >
9520 :echo tanh(-1)
9521< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02009522 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009523
9524
Bram Moolenaar574860b2016-05-24 17:33:34 +02009525tempname() *tempname()* *temp-file-name*
9526 The result is a String, which is the name of a file that
Bram Moolenaar58b85342016-08-14 19:54:54 +02009527 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar574860b2016-05-24 17:33:34 +02009528 is different for at least 26 consecutive calls. Example: >
9529 :let tmpfile = tempname()
9530 :exe "redir > " . tmpfile
9531< For Unix, the file will be in a private directory |tempfile|.
9532 For MS-Windows forward slashes are used when the 'shellslash'
9533 option is set or when 'shellcmdflag' starts with '-'.
9534
Bram Moolenaard96ff162018-02-18 22:13:29 +01009535 *term_dumpdiff()*
9536term_dumpdiff({filename}, {filename} [, {options}])
9537 Open a new window displaying the difference between the two
9538 files. The files must have been created with
9539 |term_dumpwrite()|.
9540 Returns the buffer number or zero when the diff fails.
9541 Also see |terminal-diff|.
9542 NOTE: this does not work with double-width characters yet.
9543
9544 The top part of the buffer contains the contents of the first
9545 file, the bottom part of the buffer contains the contents of
9546 the second file. The middle part shows the differences.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009547 The parts are separated by a line of equals.
Bram Moolenaard96ff162018-02-18 22:13:29 +01009548
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009549 If the {options} argument is present, it must be a Dict with
9550 these possible members:
9551 "term_name" name to use for the buffer name, instead
9552 of the first file name.
9553 "term_rows" vertical size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009554 instead of using 'termwinsize'
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009555 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009556 instead of using 'termwinsize'
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009557 "vertical" split the window vertically
9558 "curwin" use the current window, do not split the
9559 window; fails if the current buffer
9560 cannot be |abandon|ed
Bram Moolenaar87abab92019-06-03 21:14:59 +02009561 "bufnr" do not create a new buffer, use the
9562 existing buffer "bufnr". This buffer
9563 must have been previously created with
9564 term_dumpdiff() or term_dumpload() and
9565 visible in a window.
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009566 "norestore" do not add the terminal window to a
9567 session file
Bram Moolenaard96ff162018-02-18 22:13:29 +01009568
9569 Each character in the middle part indicates a difference. If
9570 there are multiple differences only the first in this list is
9571 used:
9572 X different character
9573 w different width
9574 f different foreground color
9575 b different background color
9576 a different attribute
9577 + missing position in first file
9578 - missing position in second file
9579
9580 Using the "s" key the top and bottom parts are swapped. This
9581 makes it easy to spot a difference.
9582
9583 *term_dumpload()*
9584term_dumpload({filename} [, {options}])
9585 Open a new window displaying the contents of {filename}
9586 The file must have been created with |term_dumpwrite()|.
9587 Returns the buffer number or zero when it fails.
9588 Also see |terminal-diff|.
9589
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009590 For {options} see |term_dumpdiff()|.
Bram Moolenaard96ff162018-02-18 22:13:29 +01009591
9592 *term_dumpwrite()*
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01009593term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01009594 Dump the contents of the terminal screen of {buf} in the file
9595 {filename}. This uses a format that can be used with
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01009596 |term_dumpload()| and |term_dumpdiff()|.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02009597 If the job in the terminal already finished an error is given:
9598 *E958*
9599 If {filename} already exists an error is given: *E953*
Bram Moolenaard96ff162018-02-18 22:13:29 +01009600 Also see |terminal-diff|.
9601
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01009602 {options} is a dictionary with these optional entries:
9603 "rows" maximum number of rows to dump
9604 "columns" maximum number of columns to dump
9605
Bram Moolenaare41e3b42017-08-11 16:24:50 +02009606term_getaltscreen({buf}) *term_getaltscreen()*
9607 Returns 1 if the terminal of {buf} is using the alternate
9608 screen.
9609 {buf} is used as with |term_getsize()|.
9610 {only available when compiled with the |+terminal| feature}
9611
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009612term_getansicolors({buf}) *term_getansicolors()*
9613 Get the ANSI color palette in use by terminal {buf}.
9614 Returns a List of length 16 where each element is a String
9615 representing a color in hexadecimal "#rrggbb" format.
9616 Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
9617 If neither was used returns the default colors.
9618
9619 {buf} is used as with |term_getsize()|. If the buffer does not
9620 exist or is not a terminal window, an empty list is returned.
9621 {only available when compiled with the |+terminal| feature and
9622 with GUI enabled and/or the |+termguicolors| feature}
9623
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009624term_getattr({attr}, {what}) *term_getattr()*
9625 Given {attr}, a value returned by term_scrape() in the "attr"
9626 item, return whether {what} is on. {what} can be one of:
9627 bold
9628 italic
9629 underline
9630 strike
9631 reverse
Bram Moolenaar45356542017-08-06 17:53:31 +02009632 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009633
Bram Moolenaar97870002017-07-30 18:28:38 +02009634term_getcursor({buf}) *term_getcursor()*
Bram Moolenaar45356542017-08-06 17:53:31 +02009635 Get the cursor position of terminal {buf}. Returns a list with
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009636 two numbers and a dictionary: [row, col, dict].
Bram Moolenaar45356542017-08-06 17:53:31 +02009637
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009638 "row" and "col" are one based, the first screen cell is row
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009639 1, column 1. This is the cursor position of the terminal
9640 itself, not of the Vim window.
9641
9642 "dict" can have these members:
9643 "visible" one when the cursor is visible, zero when it
9644 is hidden.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009645 "blink" one when the cursor is blinking, zero when it
9646 is not blinking.
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009647 "shape" 1 for a block cursor, 2 for underline and 3
9648 for a vertical bar.
Bram Moolenaar911ead12019-04-21 00:03:35 +02009649 "color" color of the cursor, e.g. "green"
Bram Moolenaar97870002017-07-30 18:28:38 +02009650
9651 {buf} must be the buffer number of a terminal window. If the
9652 buffer does not exist or is not a terminal window, an empty
9653 list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009654 {only available when compiled with the |+terminal| feature}
Bram Moolenaar97870002017-07-30 18:28:38 +02009655
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009656term_getjob({buf}) *term_getjob()*
9657 Get the Job associated with terminal window {buf}.
9658 {buf} is used as with |term_getsize()|.
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009659 Returns |v:null| when there is no job.
Bram Moolenaar45356542017-08-06 17:53:31 +02009660 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009661
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009662term_getline({buf}, {row}) *term_getline()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009663 Get a line of text from the terminal window of {buf}.
9664 {buf} is used as with |term_getsize()|.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009665
Bram Moolenaar45356542017-08-06 17:53:31 +02009666 The first line has {row} one. When {row} is "." the cursor
9667 line is used. When {row} is invalid an empty string is
9668 returned.
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009669
9670 To get attributes of each character use |term_scrape()|.
Bram Moolenaar45356542017-08-06 17:53:31 +02009671 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009672
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02009673term_getscrolled({buf}) *term_getscrolled()*
9674 Return the number of lines that scrolled to above the top of
9675 terminal {buf}. This is the offset between the row number
9676 used for |term_getline()| and |getline()|, so that: >
9677 term_getline(buf, N)
9678< is equal to: >
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009679 getline(N + term_getscrolled(buf))
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02009680< (if that line exists).
9681
9682 {buf} is used as with |term_getsize()|.
9683 {only available when compiled with the |+terminal| feature}
9684
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009685term_getsize({buf}) *term_getsize()*
9686 Get the size of terminal {buf}. Returns a list with two
9687 numbers: [rows, cols]. This is the size of the terminal, not
9688 the window containing the terminal.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009689
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009690 {buf} must be the buffer number of a terminal window. Use an
9691 empty string for the current buffer. If the buffer does not
9692 exist or is not a terminal window, an empty list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009693 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009694
Bram Moolenaarb000e322017-07-30 19:38:21 +02009695term_getstatus({buf}) *term_getstatus()*
9696 Get the status of terminal {buf}. This returns a comma
9697 separated list of these items:
9698 running job is running
9699 finished job has finished
Bram Moolenaar45356542017-08-06 17:53:31 +02009700 normal in Terminal-Normal mode
Bram Moolenaarb000e322017-07-30 19:38:21 +02009701 One of "running" or "finished" is always present.
9702
9703 {buf} must be the buffer number of a terminal window. If the
9704 buffer does not exist or is not a terminal window, an empty
9705 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009706 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02009707
9708term_gettitle({buf}) *term_gettitle()*
9709 Get the title of terminal {buf}. This is the title that the
9710 job in the terminal has set.
9711
9712 {buf} must be the buffer number of a terminal window. If the
9713 buffer does not exist or is not a terminal window, an empty
9714 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009715 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02009716
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009717term_gettty({buf} [, {input}]) *term_gettty()*
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009718 Get the name of the controlling terminal associated with
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009719 terminal window {buf}. {buf} is used as with |term_getsize()|.
9720
9721 When {input} is omitted or 0, return the name for writing
9722 (stdout). When {input} is 1 return the name for reading
9723 (stdin). On UNIX, both return same name.
Bram Moolenaar45356542017-08-06 17:53:31 +02009724 {only available when compiled with the |+terminal| feature}
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009725
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02009726term_list() *term_list()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009727 Return a list with the buffer numbers of all buffers for
9728 terminal windows.
Bram Moolenaar45356542017-08-06 17:53:31 +02009729 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009730
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009731term_scrape({buf}, {row}) *term_scrape()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009732 Get the contents of {row} of terminal screen of {buf}.
9733 For {buf} see |term_getsize()|.
9734
Bram Moolenaar45356542017-08-06 17:53:31 +02009735 The first line has {row} one. When {row} is "." the cursor
9736 line is used. When {row} is invalid an empty string is
9737 returned.
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02009738
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009739 Return a List containing a Dict for each screen cell:
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009740 "chars" character(s) at the cell
9741 "fg" foreground color as #rrggbb
9742 "bg" background color as #rrggbb
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009743 "attr" attributes of the cell, use |term_getattr()|
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009744 to get the individual flags
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009745 "width" cell width: 1 or 2
Bram Moolenaar45356542017-08-06 17:53:31 +02009746 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009747
9748term_sendkeys({buf}, {keys}) *term_sendkeys()*
9749 Send keystrokes {keys} to terminal {buf}.
9750 {buf} is used as with |term_getsize()|.
9751
9752 {keys} are translated as key sequences. For example, "\<c-x>"
9753 means the character CTRL-X.
Bram Moolenaar45356542017-08-06 17:53:31 +02009754 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009755
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009756term_setansicolors({buf}, {colors}) *term_setansicolors()*
9757 Set the ANSI color palette used by terminal {buf}.
9758 {colors} must be a List of 16 valid color names or hexadecimal
9759 color codes, like those accepted by |highlight-guifg|.
9760 Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
9761
Bram Moolenaara42d3632018-04-14 17:05:38 +02009762 The colors normally are:
9763 0 black
9764 1 dark red
9765 2 dark green
9766 3 brown
9767 4 dark blue
9768 5 dark magenta
9769 6 dark cyan
9770 7 light grey
9771 8 dark grey
9772 9 red
9773 10 green
9774 11 yellow
9775 12 blue
9776 13 magenta
9777 14 cyan
9778 15 white
9779
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009780 These colors are used in the GUI and in the terminal when
9781 'termguicolors' is set. When not using GUI colors (GUI mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009782 or 'termguicolors'), the terminal window always uses the 16
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009783 ANSI colors of the underlying terminal.
9784 {only available when compiled with the |+terminal| feature and
9785 with GUI enabled and/or the |+termguicolors| feature}
9786
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009787term_setkill({buf}, {how}) *term_setkill()*
9788 When exiting Vim or trying to close the terminal window in
9789 another way, {how} defines whether the job in the terminal can
9790 be stopped.
9791 When {how} is empty (the default), the job will not be
9792 stopped, trying to exit will result in |E947|.
9793 Otherwise, {how} specifies what signal to send to the job.
9794 See |job_stop()| for the values.
9795
9796 After sending the signal Vim will wait for up to a second to
9797 check that the job actually stopped.
9798
Bram Moolenaarb5b75622018-03-09 22:22:21 +01009799term_setrestore({buf}, {command}) *term_setrestore()*
9800 Set the command to write in a session file to restore the job
9801 in this terminal. The line written in the session file is: >
9802 terminal ++curwin ++cols=%d ++rows=%d {command}
9803< Make sure to escape the command properly.
9804
9805 Use an empty {command} to run 'shell'.
9806 Use "NONE" to not restore this window.
9807 {only available when compiled with the |+terminal| feature}
9808
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009809term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955*
Bram Moolenaara42d3632018-04-14 17:05:38 +02009810 Set the size of terminal {buf}. The size of the window
9811 containing the terminal will also be adjusted, if possible.
9812 If {rows} or {cols} is zero or negative, that dimension is not
9813 changed.
9814
9815 {buf} must be the buffer number of a terminal window. Use an
9816 empty string for the current buffer. If the buffer does not
9817 exist or is not a terminal window, an error is given.
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009818 {only available when compiled with the |+terminal| feature}
9819
Bram Moolenaar911ead12019-04-21 00:03:35 +02009820term_start({cmd} [, {options}]) *term_start()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009821 Open a terminal window and run {cmd} in it.
9822
Bram Moolenaar01164a62017-11-02 22:58:42 +01009823 {cmd} can be a string or a List, like with |job_start()|. The
9824 string "NONE" can be used to open a terminal window without
9825 starting a job, the pty of the terminal can be used by a
9826 command like gdb.
9827
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009828 Returns the buffer number of the terminal window. If {cmd}
9829 cannot be executed the window does open and shows an error
9830 message.
9831 If opening the window fails zero is returned.
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009832
Bram Moolenaar78712a72017-08-05 14:50:12 +02009833 {options} are similar to what is used for |job_start()|, see
9834 |job-options|. However, not all options can be used. These
9835 are supported:
9836 all timeout options
Bram Moolenaard473c8c2018-08-11 18:00:22 +02009837 "stoponexit", "cwd", "env"
9838 "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
Bram Moolenaar78712a72017-08-05 14:50:12 +02009839 "in_io", "in_top", "in_bot", "in_name", "in_buf"
9840 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
9841 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
9842 However, at least one of stdin, stdout or stderr must be
9843 connected to the terminal. When I/O is connected to the
9844 terminal then the callback function for that part is not used.
9845
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009846 There are extra options:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02009847 "term_name" name to use for the buffer name, instead
9848 of the command name.
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009849 "term_rows" vertical size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009850 instead of using 'termwinsize'
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009851 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009852 instead of using 'termwinsize'
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02009853 "vertical" split the window vertically; note that
9854 other window position can be defined with
9855 command modifiers, such as |:belowright|.
Bram Moolenaarda43b612017-08-11 22:27:50 +02009856 "curwin" use the current window, do not split the
9857 window; fails if the current buffer
9858 cannot be |abandon|ed
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009859 "hidden" do not open a window
Bram Moolenaarb5b75622018-03-09 22:22:21 +01009860 "norestore" do not add the terminal window to a
9861 session file
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009862 "term_kill" what to do when trying to close the
9863 terminal window, see |term_setkill()|
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009864 "term_finish" What to do when the job is finished:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02009865 "close": close any windows
9866 "open": open window if needed
9867 Note that "open" can be interruptive.
9868 See |term++close| and |term++open|.
Bram Moolenaar37c45832017-08-12 16:01:04 +02009869 "term_opencmd" command to use for opening the window when
9870 "open" is used for "term_finish"; must
9871 have "%d" where the buffer number goes,
9872 e.g. "10split|buffer %d"; when not
9873 specified "botright sbuf %d" is used
Bram Moolenaaref68e4f2017-09-02 16:28:36 +02009874 "eof_chars" Text to send after all buffer lines were
9875 written to the terminal. When not set
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009876 CTRL-D is used on MS-Windows. For Python
9877 use CTRL-Z or "exit()". For a shell use
9878 "exit". A CR is always added.
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009879 "ansi_colors" A list of 16 color names or hex codes
9880 defining the ANSI palette used in GUI
9881 color modes. See |g:terminal_ansi_colors|.
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01009882 "tty_type" (MS-Windows only): Specify which pty to
9883 use. See 'termwintype' for the values.
Bram Moolenaar37c45832017-08-12 16:01:04 +02009884
Bram Moolenaar45356542017-08-06 17:53:31 +02009885 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009886
Bram Moolenaarf3402b12017-08-06 19:07:08 +02009887term_wait({buf} [, {time}]) *term_wait()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009888 Wait for pending updates of {buf} to be handled.
9889 {buf} is used as with |term_getsize()|.
Bram Moolenaarf3402b12017-08-06 19:07:08 +02009890 {time} is how long to wait for updates to arrive in msec. If
9891 not set then 10 msec will be used.
Bram Moolenaar45356542017-08-06 17:53:31 +02009892 {only available when compiled with the |+terminal| feature}
Bram Moolenaar574860b2016-05-24 17:33:34 +02009893
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009894test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()*
9895 This is for testing: If the memory allocation with {id} is
9896 called, then decrement {countdown}, and when it reaches zero
9897 let memory allocation fail {repeat} times. When {repeat} is
9898 smaller than one it fails one time.
9899
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02009900test_autochdir() *test_autochdir()*
9901 Set a flag to enable the effect of 'autochdir' before Vim
9902 startup has finished.
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009903
Bram Moolenaar5e80de32017-09-03 15:48:12 +02009904test_feedinput({string}) *test_feedinput()*
9905 Characters in {string} are queued for processing as if they
9906 were typed by the user. This uses a low level input buffer.
9907 This function works only when with |+unix| or GUI is running.
9908
Bram Moolenaar574860b2016-05-24 17:33:34 +02009909test_garbagecollect_now() *test_garbagecollect_now()*
9910 Like garbagecollect(), but executed right away. This must
9911 only be called directly to avoid any structure to exist
9912 internally, and |v:testing| must have been set before calling
9913 any function.
9914
Bram Moolenaareda65222019-05-16 20:29:44 +02009915test_getvalue({name}) *test_getvalue()*
9916 Get the value of an internal variable. These values for
9917 {name} are supported:
9918 need_fileinfo
9919
Bram Moolenaare0c31f62017-03-01 15:07:05 +01009920test_ignore_error({expr}) *test_ignore_error()*
9921 Ignore any error containing {expr}. A normal message is given
9922 instead.
9923 This is only meant to be used in tests, where catching the
9924 error with try/catch cannot be used (because it skips over
9925 following code).
9926 {expr} is used literally, not as a pattern.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +01009927 When the {expr} is the string "RESET" then the list of ignored
9928 errors is made empty.
Bram Moolenaare0c31f62017-03-01 15:07:05 +01009929
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009930test_null_blob() *test_null_blob()*
9931 Return a |Blob| that is null. Only useful for testing.
9932
Bram Moolenaar574860b2016-05-24 17:33:34 +02009933test_null_channel() *test_null_channel()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009934 Return a |Channel| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009935 {only available when compiled with the +channel feature}
9936
9937test_null_dict() *test_null_dict()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009938 Return a |Dict| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009939
9940test_null_job() *test_null_job()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009941 Return a |Job| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009942 {only available when compiled with the +job feature}
9943
9944test_null_list() *test_null_list()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009945 Return a |List| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009946
9947test_null_partial() *test_null_partial()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009948 Return a |Partial| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009949
9950test_null_string() *test_null_string()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009951 Return a |String| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009952
Bram Moolenaarfe8ef982018-09-13 20:31:54 +02009953test_option_not_set({name}) *test_option_not_set()*
9954 Reset the flag that indicates option {name} was set. Thus it
9955 looks like it still has the default value. Use like this: >
9956 set ambiwidth=double
9957 call test_option_not_set('ambiwidth')
9958< Now the 'ambiwidth' option behaves like it was never changed,
9959 even though the value is "double".
9960 Only to be used for testing!
9961
Bram Moolenaar036986f2017-03-16 17:41:02 +01009962test_override({name}, {val}) *test_override()*
Bram Moolenaar9d87a372018-12-18 21:41:50 +01009963 Overrides certain parts of Vim's internal processing to be able
Bram Moolenaar036986f2017-03-16 17:41:02 +01009964 to run tests. Only to be used for testing Vim!
9965 The override is enabled when {val} is non-zero and removed
9966 when {val} is zero.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009967 Current supported values for name are:
Bram Moolenaar036986f2017-03-16 17:41:02 +01009968
9969 name effect when {val} is non-zero ~
9970 redraw disable the redrawing() function
Bram Moolenaared5a9d62018-09-06 13:14:43 +02009971 redraw_flag ignore the RedrawingDisabled flag
Bram Moolenaar036986f2017-03-16 17:41:02 +01009972 char_avail disable the char_avail() function
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009973 starting reset the "starting" variable, see below
Bram Moolenaarbcf94422018-06-23 14:21:42 +02009974 nfa_fail makes the NFA regexp engine fail to force a
9975 fallback to the old engine
Bram Moolenaar92fd5992019-05-02 23:00:22 +02009976 no_query_mouse do not query the mouse position for "dec"
9977 terminals
Bram Moolenaar036986f2017-03-16 17:41:02 +01009978 ALL clear all overrides ({val} is not used)
9979
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009980 "starting" is to be used when a test should behave like
9981 startup was done. Since the tests are run by sourcing a
9982 script the "starting" variable is non-zero. This is usually a
9983 good thing (tests run faster), but sometimes changes behavior
9984 in a way that the test doesn't work properly.
9985 When using: >
9986 call test_override('starting', 1)
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009987< The value of "starting" is saved. It is restored by: >
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009988 call test_override('starting', 0)
9989
Bram Moolenaarc3e92c12019-03-23 14:23:07 +01009990test_refcount({expr}) *test_refcount()*
9991 Return the reference count of {expr}. When {expr} is of a
9992 type that does not have a reference count, returns -1. Only
9993 to be used for testing.
9994
Bram Moolenaarab186732018-09-14 21:27:06 +02009995test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()*
9996 Pretend using scrollbar {which} to move it to position
9997 {value}. {which} can be:
9998 left Left scrollbar of the current window
9999 right Right scrollbar of the current window
10000 hor Horizontal scrollbar
10001
10002 For the vertical scrollbars {value} can be 1 to the
10003 line-count of the buffer. For the horizontal scrollbar the
10004 {value} can be between 1 and the maximum line length, assuming
10005 'wrap' is not set.
10006
10007 When {dragging} is non-zero it's like dragging the scrollbar,
10008 otherwise it's like clicking in the scrollbar.
10009 Only works when the {which} scrollbar actually exists,
10010 obviously only when using the GUI.
10011
Bram Moolenaarbb8476b2019-05-04 15:47:48 +020010012test_setmouse({row}, {col}) *test_setmouse()*
10013 Set the mouse position to be used for the next mouse action.
10014 {row} and {col} are one based.
10015 For example: >
10016 call test_setmouse(4, 20)
10017 call feedkeys("\<LeftMouse>", "xt")
10018
Bram Moolenaarc95a3022016-06-12 23:01:46 +020010019test_settime({expr}) *test_settime()*
10020 Set the time Vim uses internally. Currently only used for
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020010021 timestamps in the history, as they are used in viminfo, and
10022 for undo.
Bram Moolenaar3df01732017-02-17 22:47:16 +010010023 Using a value of 1 makes Vim not sleep after a warning or
10024 error message.
Bram Moolenaarc95a3022016-06-12 23:01:46 +020010025 {expr} must evaluate to a number. When the value is zero the
10026 normal behavior is restored.
Bram Moolenaar574860b2016-05-24 17:33:34 +020010027
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020010028 *timer_info()*
10029timer_info([{id}])
10030 Return a list with information about timers.
10031 When {id} is given only information about this timer is
10032 returned. When timer {id} does not exist an empty list is
10033 returned.
10034 When {id} is omitted information about all timers is returned.
10035
10036 For each timer the information is stored in a Dictionary with
10037 these items:
10038 "id" the timer ID
10039 "time" time the timer was started with
10040 "remaining" time until the timer fires
10041 "repeat" number of times the timer will still fire;
Bram Moolenaarb73598e2016-08-07 18:22:53 +020010042 -1 means forever
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020010043 "callback" the callback
Bram Moolenaarb73598e2016-08-07 18:22:53 +020010044 "paused" 1 if the timer is paused, 0 otherwise
10045
10046 {only available when compiled with the |+timers| feature}
10047
10048timer_pause({timer}, {paused}) *timer_pause()*
10049 Pause or unpause a timer. A paused timer does not invoke its
Bram Moolenaardc1f1642016-08-16 18:33:43 +020010050 callback when its time expires. Unpausing a timer may cause
10051 the callback to be invoked almost immediately if enough time
10052 has passed.
Bram Moolenaarb73598e2016-08-07 18:22:53 +020010053
10054 Pausing a timer is useful to avoid the callback to be called
10055 for a short time.
10056
10057 If {paused} evaluates to a non-zero Number or a non-empty
10058 String, then the timer is paused, otherwise it is unpaused.
10059 See |non-zero-arg|.
10060
10061 {only available when compiled with the |+timers| feature}
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020010062
Bram Moolenaardc1f1642016-08-16 18:33:43 +020010063 *timer_start()* *timer* *timers*
Bram Moolenaar975b5272016-03-15 23:10:59 +010010064timer_start({time}, {callback} [, {options}])
10065 Create a timer and return the timer ID.
10066
10067 {time} is the waiting time in milliseconds. This is the
10068 minimum time before invoking the callback. When the system is
10069 busy or Vim is not waiting for input the time will be longer.
10070
10071 {callback} is the function to call. It can be the name of a
Bram Moolenaarf37506f2016-08-31 22:22:10 +020010072 function or a |Funcref|. It is called with one argument, which
Bram Moolenaar975b5272016-03-15 23:10:59 +010010073 is the timer ID. The callback is only invoked when Vim is
10074 waiting for input.
10075
10076 {options} is a dictionary. Supported entries:
10077 "repeat" Number of times to repeat calling the
Bram Moolenaarabd468e2016-09-08 22:22:43 +020010078 callback. -1 means forever. When not present
10079 the callback will be called once.
Bram Moolenaarc577d812017-07-08 22:37:34 +020010080 If the timer causes an error three times in a
10081 row the repeat is cancelled. This avoids that
10082 Vim becomes unusable because of all the error
10083 messages.
Bram Moolenaar975b5272016-03-15 23:10:59 +010010084
10085 Example: >
10086 func MyHandler(timer)
10087 echo 'Handler called'
10088 endfunc
10089 let timer = timer_start(500, 'MyHandler',
10090 \ {'repeat': 3})
10091< This will invoke MyHandler() three times at 500 msec
10092 intervals.
Bram Moolenaarb73598e2016-08-07 18:22:53 +020010093
Bram Moolenaar68e65602019-05-26 21:33:31 +020010094 Not available in the |sandbox|.
Bram Moolenaar975b5272016-03-15 23:10:59 +010010095 {only available when compiled with the |+timers| feature}
10096
Bram Moolenaar03602ec2016-03-20 20:57:45 +010010097timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +020010098 Stop a timer. The timer callback will no longer be invoked.
10099 {timer} is an ID returned by timer_start(), thus it must be a
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020010100 Number. If {timer} does not exist there is no error.
Bram Moolenaar03602ec2016-03-20 20:57:45 +010010101
Bram Moolenaarb73598e2016-08-07 18:22:53 +020010102 {only available when compiled with the |+timers| feature}
10103
10104timer_stopall() *timer_stopall()*
10105 Stop all timers. The timer callbacks will no longer be
10106 invoked. Useful if some timers is misbehaving. If there are
10107 no timers there is no error.
10108
10109 {only available when compiled with the |+timers| feature}
10110
Bram Moolenaar071d4272004-06-13 20:20:40 +000010111tolower({expr}) *tolower()*
10112 The result is a copy of the String given, with all uppercase
10113 characters turned into lowercase (just like applying |gu| to
10114 the string).
10115
10116toupper({expr}) *toupper()*
10117 The result is a copy of the String given, with all lowercase
10118 characters turned into uppercase (just like applying |gU| to
10119 the string).
10120
Bram Moolenaar8299df92004-07-10 09:47:34 +000010121tr({src}, {fromstr}, {tostr}) *tr()*
10122 The result is a copy of the {src} string with all characters
10123 which appear in {fromstr} replaced by the character in that
10124 position in the {tostr} string. Thus the first character in
10125 {fromstr} is translated into the first character in {tostr}
10126 and so on. Exactly like the unix "tr" command.
10127 This code also deals with multibyte characters properly.
10128
10129 Examples: >
10130 echo tr("hello there", "ht", "HT")
10131< returns "Hello THere" >
10132 echo tr("<blob>", "<>", "{}")
10133< returns "{blob}"
10134
Bram Moolenaard473c8c2018-08-11 18:00:22 +020010135trim({text} [, {mask}]) *trim()*
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010010136 Return {text} as a String where any character in {mask} is
10137 removed from the beginning and end of {text}.
10138 If {mask} is not given, {mask} is all characters up to 0x20,
10139 which includes Tab, space, NL and CR, plus the non-breaking
10140 space character 0xa0.
10141 This code deals with multibyte characters properly.
10142
10143 Examples: >
Bram Moolenaarab943432018-03-29 18:27:07 +020010144 echo trim(" some text ")
10145< returns "some text" >
10146 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010010147< returns "RESERVE_TAIL" >
Bram Moolenaarab943432018-03-29 18:27:07 +020010148 echo trim("rm<Xrm<>X>rrm", "rm<>")
10149< returns "Xrm<>X" (characters in the middle are not removed)
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010010150
Bram Moolenaar446cb832008-06-24 21:56:24 +000010151trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +000010152 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +000010153 equal to {expr} as a |Float| (truncate towards zero).
10154 {expr} must evaluate to a |Float| or a |Number|.
10155 Examples: >
10156 echo trunc(1.456)
10157< 1.0 >
10158 echo trunc(-5.456)
10159< -5.0 >
10160 echo trunc(4.0)
10161< 4.0
10162 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010163
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000010164 *type()*
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010165type({expr}) The result is a Number representing the type of {expr}.
10166 Instead of using the number directly, it is better to use the
10167 v:t_ variable that has the value:
10168 Number: 0 |v:t_number|
10169 String: 1 |v:t_string|
10170 Funcref: 2 |v:t_func|
10171 List: 3 |v:t_list|
10172 Dictionary: 4 |v:t_dict|
10173 Float: 5 |v:t_float|
10174 Boolean: 6 |v:t_bool| (v:false and v:true)
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010175 None: 7 |v:t_none| (v:null and v:none)
10176 Job: 8 |v:t_job|
10177 Channel: 9 |v:t_channel|
10178 Blob: 10 |v:t_blob|
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010179 For backward compatibility, this method can be used: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000010180 :if type(myvar) == type(0)
10181 :if type(myvar) == type("")
10182 :if type(myvar) == type(function("tr"))
10183 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +000010184 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +000010185 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +010010186 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +010010187 :if type(myvar) == type(v:none)
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010188< To check if the v:t_ variables exist use this: >
10189 :if exists('v:t_number')
Bram Moolenaar071d4272004-06-13 20:20:40 +000010190
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010191undofile({name}) *undofile()*
10192 Return the name of the undo file that would be used for a file
10193 with name {name} when writing. This uses the 'undodir'
10194 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +020010195 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +020010196 {name} is always expanded to the full path, since that is what
10197 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +020010198 If {name} is empty undofile() returns an empty string, since a
10199 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010200 Useful in combination with |:wundo| and |:rundo|.
Bram Moolenaarb328cca2019-01-06 16:24:01 +010010201 When compiled without the |+persistent_undo| option this always
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010202 returns an empty string.
10203
Bram Moolenaara800b422010-06-27 01:15:55 +020010204undotree() *undotree()*
10205 Return the current state of the undo tree in a dictionary with
10206 the following items:
10207 "seq_last" The highest undo sequence number used.
10208 "seq_cur" The sequence number of the current position in
10209 the undo tree. This differs from "seq_last"
10210 when some changes were undone.
10211 "time_cur" Time last used for |:earlier| and related
10212 commands. Use |strftime()| to convert to
10213 something readable.
10214 "save_last" Number of the last file write. Zero when no
10215 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +020010216 "save_cur" Number of the current position in the undo
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010217 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +020010218 "synced" Non-zero when the last undo block was synced.
10219 This happens when waiting from input from the
10220 user. See |undo-blocks|.
10221 "entries" A list of dictionaries with information about
10222 undo blocks.
10223
10224 The first item in the "entries" list is the oldest undo item.
10225 Each List item is a Dictionary with these items:
10226 "seq" Undo sequence number. Same as what appears in
10227 |:undolist|.
10228 "time" Timestamp when the change happened. Use
10229 |strftime()| to convert to something readable.
10230 "newhead" Only appears in the item that is the last one
10231 that was added. This marks the last change
10232 and where further changes will be added.
10233 "curhead" Only appears in the item that is the last one
10234 that was undone. This marks the current
10235 position in the undo tree, the block that will
10236 be used by a redo command. When nothing was
10237 undone after the last change this item will
10238 not appear anywhere.
10239 "save" Only appears on the last block before a file
10240 write. The number is the write count. The
10241 first write has number 1, the last one the
10242 "save_last" mentioned above.
10243 "alt" Alternate entry. This is again a List of undo
10244 blocks. Each item may again have an "alt"
10245 item.
10246
Bram Moolenaar327aa022014-03-25 18:24:23 +010010247uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
10248 Remove second and succeeding copies of repeated adjacent
10249 {list} items in-place. Returns {list}. If you want a list
10250 to remain unmodified make a copy first: >
10251 :let newlist = uniq(copy(mylist))
10252< The default compare function uses the string representation of
10253 each item. For the use of {func} and {dict} see |sort()|.
10254
Bram Moolenaar677ee682005-01-27 14:41:15 +000010255values({dict}) *values()*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010256 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +010010257 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaar677ee682005-01-27 14:41:15 +000010258
10259
Bram Moolenaar071d4272004-06-13 20:20:40 +000010260virtcol({expr}) *virtcol()*
10261 The result is a Number, which is the screen column of the file
10262 position given with {expr}. That is, the last screen position
10263 occupied by the character at that position, when the screen
10264 would be of unlimited width. When there is a <Tab> at the
10265 position, the returned Number will be the column at the end of
10266 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +020010267 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +000010268 For the byte position use |col()|.
10269 For the use of {expr} see |col()|.
10270 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +000010271 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +000010272 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +020010273 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010274 When Virtual editing is active in the current mode, a position
10275 beyond the end of the line can be returned. |'virtualedit'|
10276 The accepted positions are:
10277 . the cursor position
10278 $ the end of the cursor line (the result is the
10279 number of displayed characters in the cursor line
10280 plus one)
10281 'x position of mark x (if the mark is not set, 0 is
10282 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +010010283 v In Visual mode: the start of the Visual area (the
10284 cursor is the end). When not in Visual mode
10285 returns the cursor position. Differs from |'<| in
10286 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010287 Note that only marks in the current file can be used.
10288 Examples: >
10289 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
10290 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +000010291 virtcol("'t") with text " there", with 't at 'h', returns 6
Bram Moolenaar58b85342016-08-14 19:54:54 +020010292< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010293 A more advanced example that echoes the maximum length of
10294 all lines: >
10295 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10296
Bram Moolenaar071d4272004-06-13 20:20:40 +000010297
10298visualmode([expr]) *visualmode()*
10299 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010300 used in the current buffer. Initially it returns an empty
10301 string, but once Visual mode has been used, it returns "v",
10302 "V", or "<CTRL-V>" (a single CTRL-V character) for
10303 character-wise, line-wise, or block-wise Visual mode
10304 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010305 Example: >
10306 :exe "normal " . visualmode()
10307< This enters the same Visual mode as before. It is also useful
10308 in scripts if you wish to act differently depending on the
10309 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010310 If Visual mode is active, use |mode()| to get the Visual mode
10311 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +000010312 If [expr] is supplied and it evaluates to a non-zero Number or
10313 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaare381d3d2016-07-07 14:50:41 +020010314 the old value is returned. See |non-zero-arg|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010315
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010316wildmenumode() *wildmenumode()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +020010317 Returns |TRUE| when the wildmenu is active and |FALSE|
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010318 otherwise. See 'wildmenu' and 'wildmode'.
10319 This can be used in mappings to handle the 'wildcharm' option
10320 gracefully. (Makes only sense with |mapmode-c| mappings).
10321
10322 For example to make <c-j> work like <down> in wildmode, use: >
10323 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10324<
10325 (Note, this needs the 'wildcharm' option set appropriately).
10326
Bram Moolenaar868b7b62019-05-29 21:44:40 +020010327win_execute({id}, {command} [, {silent}]) *win_execute()*
10328 Like `execute()` but in the context of window {id}.
10329 The window will temporarily be made the current window,
Bram Moolenaarb4230122019-05-30 18:40:53 +020010330 without triggering autocommands. When executing {command}
10331 autocommands will be triggered, this may have unexpected side
10332 effects. Use |:noautocmd| if needed.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020010333 Example: >
Bram Moolenaarb4230122019-05-30 18:40:53 +020010334 call win_execute(winid, 'set syntax=python')
10335< Doing the same with `setwinvar()` would not trigger
10336 autocommands and not actually show syntax highlighting.
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020010337 *E994*
10338 Not all commands are allowed in popup windows.
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010339
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010010340win_findbuf({bufnr}) *win_findbuf()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020010341 Returns a list with |window-ID|s for windows that contain
10342 buffer {bufnr}. When there is none the list is empty.
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010010343
Bram Moolenaar86edef62016-03-13 18:07:30 +010010344win_getid([{win} [, {tab}]]) *win_getid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020010345 Get the |window-ID| for the specified window.
Bram Moolenaar86edef62016-03-13 18:07:30 +010010346 When {win} is missing use the current window.
10347 With {win} this is the window number. The top window has
Bram Moolenaarba3ff532018-11-04 14:45:49 +010010348 number 1.
Bram Moolenaar86edef62016-03-13 18:07:30 +010010349 Without {tab} use the current tab, otherwise the tab with
10350 number {tab}. The first tab has number one.
10351 Return zero if the window cannot be found.
10352
10353win_gotoid({expr}) *win_gotoid()*
10354 Go to window with ID {expr}. This may also change the current
10355 tabpage.
10356 Return 1 if successful, 0 if the window cannot be found.
10357
Bram Moolenaar03413f42016-04-12 21:07:15 +020010358win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +010010359 Return a list with the tab number and window number of window
10360 with ID {expr}: [tabnr, winnr].
10361 Return [0, 0] if the window cannot be found.
10362
10363win_id2win({expr}) *win_id2win()*
10364 Return the window number of window with ID {expr}.
10365 Return 0 if the window cannot be found in the current tabpage.
10366
Bram Moolenaar22044dc2017-12-02 15:43:37 +010010367win_screenpos({nr}) *win_screenpos()*
10368 Return the screen position of window {nr} as a list with two
10369 numbers: [row, col]. The first window always has position
Bram Moolenaar7132ddc2018-07-15 17:01:11 +020010370 [1, 1], unless there is a tabline, then it is [2, 1].
Bram Moolenaar22044dc2017-12-02 15:43:37 +010010371 {nr} can be the window number or the |window-ID|.
10372 Return [0, 0] if the window cannot be found in the current
10373 tabpage.
10374
Bram Moolenaar071d4272004-06-13 20:20:40 +000010375 *winbufnr()*
10376winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +020010377 associated with window {nr}. {nr} can be the window number or
Bram Moolenaar7571d552016-08-18 22:54:46 +020010378 the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +020010379 When {nr} is zero, the number of the buffer in the current
10380 window is returned.
10381 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010382 Example: >
10383 :echo "The file in the current window is " . bufname(winbufnr(0))
10384<
10385 *wincol()*
10386wincol() The result is a Number, which is the virtual column of the
10387 cursor in the window. This is counting screen cells from the
10388 left side of the window. The leftmost column is one.
10389
10390winheight({nr}) *winheight()*
10391 The result is a Number, which is the height of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010392 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010393 When {nr} is zero, the height of the current window is
10394 returned. When window {nr} doesn't exist, -1 is returned.
10395 An existing window always has a height of zero or more.
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010396 This excludes any window toolbar line.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010397 Examples: >
10398 :echo "The current window has " . winheight(0) . " lines."
10399<
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +020010400winlayout([{tabnr}]) *winlayout()*
10401 The result is a nested List containing the layout of windows
10402 in a tabpage.
10403
10404 Without {tabnr} use the current tabpage, otherwise the tabpage
10405 with number {tabnr}. If the tabpage {tabnr} is not found,
10406 returns an empty list.
10407
10408 For a leaf window, it returns:
10409 ['leaf', {winid}]
10410 For horizontally split windows, which form a column, it
10411 returns:
10412 ['col', [{nested list of windows}]]
10413 For vertically split windows, which form a row, it returns:
10414 ['row', [{nested list of windows}]]
10415
10416 Example: >
10417 " Only one window in the tab page
10418 :echo winlayout()
10419 ['leaf', 1000]
10420 " Two horizontally split windows
10421 :echo winlayout()
10422 ['col', [['leaf', 1000], ['leaf', 1001]]]
10423 " Three horizontally split windows, with two
10424 " vertically split windows in the middle window
10425 :echo winlayout(2)
10426 ['col', [['leaf', 1002], ['row', ['leaf', 1003],
10427 ['leaf', 1001]]], ['leaf', 1000]]
10428<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010429 *winline()*
10430winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar58b85342016-08-14 19:54:54 +020010431 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +000010432 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +000010433 If the cursor was moved the view on the file will be updated
10434 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010435
10436 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010437winnr([{arg}]) The result is a Number, which is the number of the current
10438 window. The top window has number 1.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010439
10440 The optional argument {arg} supports the following values:
10441 $ the number of the last window (the window
10442 count).
10443 # the number of the last accessed window (where
10444 |CTRL-W_p| goes to). If there is no previous
10445 window or it is in another tab page 0 is
10446 returned.
10447 {N}j the number of the Nth window below the
10448 current window (where |CTRL-W_j| goes to).
10449 {N}k the number of the Nth window above the current
10450 window (where |CTRL-W_k| goes to).
10451 {N}h the number of the Nth window left of the
10452 current window (where |CTRL-W_h| goes to).
10453 {N}l the number of the Nth window right of the
10454 current window (where |CTRL-W_l| goes to).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010455 The number can be used with |CTRL-W_w| and ":wincmd w"
10456 |:wincmd|.
Bram Moolenaar690afe12017-01-28 18:34:47 +010010457 Also see |tabpagewinnr()| and |win_getid()|.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010458 Examples: >
10459 let window_count = winnr('$')
10460 let prev_window = winnr('#')
10461 let wnum = winnr('3k')
10462<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010463 *winrestcmd()*
10464winrestcmd() Returns a sequence of |:resize| commands that should restore
10465 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010466 are opened or closed and the current window and tab page is
10467 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010468 Example: >
10469 :let cmd = winrestcmd()
10470 :call MessWithWindowSizes()
10471 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010472<
10473 *winrestview()*
10474winrestview({dict})
10475 Uses the |Dictionary| returned by |winsaveview()| to restore
10476 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +020010477 Note: The {dict} does not have to contain all values, that are
10478 returned by |winsaveview()|. If values are missing, those
10479 settings won't be restored. So you can use: >
10480 :call winrestview({'curswant': 4})
10481<
10482 This will only set the curswant value (the column the cursor
10483 wants to move on vertical movements) of the cursor to column 5
10484 (yes, that is 5), while all other settings will remain the
10485 same. This is useful, if you set the cursor position manually.
10486
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010487 If you have changed the values the result is unpredictable.
10488 If the window size changed the result won't be the same.
10489
10490 *winsaveview()*
10491winsaveview() Returns a |Dictionary| that contains information to restore
10492 the view of the current window. Use |winrestview()| to
10493 restore the view.
10494 This is useful if you have a mapping that jumps around in the
10495 buffer and you want to go back to the original view.
10496 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +000010497 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +020010498 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010499 The return value includes:
10500 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +020010501 col cursor column (Note: the first column
10502 zero, as opposed to what getpos()
10503 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010504 coladd cursor column offset for 'virtualedit'
10505 curswant column for vertical movement
10506 topline first line in the window
10507 topfill filler lines, only in diff mode
10508 leftcol first column displayed
10509 skipcol columns skipped
10510 Note that no option values are saved.
10511
Bram Moolenaar071d4272004-06-13 20:20:40 +000010512
10513winwidth({nr}) *winwidth()*
10514 The result is a Number, which is the width of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010515 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010516 When {nr} is zero, the width of the current window is
10517 returned. When window {nr} doesn't exist, -1 is returned.
10518 An existing window always has a width of zero or more.
10519 Examples: >
10520 :echo "The current window has " . winwidth(0) . " columns."
10521 :if winwidth(0) <= 50
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010522 : 50 wincmd |
Bram Moolenaar071d4272004-06-13 20:20:40 +000010523 :endif
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010524< For getting the terminal or screen size, see the 'columns'
10525 option.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010526
10527
Bram Moolenaared767a22016-01-03 22:49:16 +010010528wordcount() *wordcount()*
10529 The result is a dictionary of byte/chars/word statistics for
10530 the current buffer. This is the same info as provided by
10531 |g_CTRL-G|
10532 The return value includes:
10533 bytes Number of bytes in the buffer
10534 chars Number of chars in the buffer
10535 words Number of words in the buffer
10536 cursor_bytes Number of bytes before cursor position
10537 (not in Visual mode)
10538 cursor_chars Number of chars before cursor position
10539 (not in Visual mode)
10540 cursor_words Number of words before cursor position
10541 (not in Visual mode)
10542 visual_bytes Number of bytes visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010543 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010544 visual_chars Number of chars visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010545 (only in Visual mode)
Bram Moolenaarc572da52017-08-27 16:52:01 +020010546 visual_words Number of words visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010547 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010548
10549
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010550 *writefile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010551writefile({object}, {fname} [, {flags}])
10552 When {object} is a |List| write it to file {fname}. Each list
10553 item is separated with a NL. Each list item must be a String
10554 or Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010555 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010556 not be a NL after the last list item. An empty item at the
10557 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010558
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010559 When {object} is a |Blob| write the bytes to file {fname}
10560 unmodified.
10561
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010562 When {flags} contains "a" then append mode is used, lines are
Bram Moolenaar46fceaa2016-10-23 21:21:08 +020010563 appended to the file: >
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010564 :call writefile(["foo"], "event.log", "a")
10565 :call writefile(["bar"], "event.log", "a")
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010566<
10567 When {flags} contains "s" then fsync() is called after writing
10568 the file. This flushes the file to disk, if possible. This
10569 takes more time but avoids losing the file if the system
10570 crashes.
Bram Moolenaar74240d32017-12-10 15:26:15 +010010571 When {flags} does not contain "S" or "s" then fsync() is
10572 called if the 'fsync' option is set.
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010573 When {flags} contains "S" then fsync() is not called, even
10574 when 'fsync' is set.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010575
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010576 All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010577 Inserting CR characters needs to be done before passing {list}
10578 to writefile().
10579 An existing file is overwritten, if possible.
10580 When the write fails -1 is returned, otherwise 0. There is an
10581 error message if the file can't be created or when writing
10582 fails.
10583 Also see |readfile()|.
10584 To copy a file byte for byte: >
10585 :let fl = readfile("foo", "b")
10586 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010587
10588
10589xor({expr}, {expr}) *xor()*
10590 Bitwise XOR on the two arguments. The arguments are converted
10591 to a number. A List, Dict or Float argument causes an error.
10592 Example: >
10593 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +010010594<
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010595
Bram Moolenaar071d4272004-06-13 20:20:40 +000010596
10597 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +020010598There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000105991. Features that are only supported when they have been enabled when Vim
10600 was compiled |+feature-list|. Example: >
10601 :if has("cindent")
106022. Features that are only supported when certain conditions have been met.
10603 Example: >
10604 :if has("gui_running")
10605< *has-patch*
Bram Moolenaar2f018892018-05-18 18:12:06 +0200106063. Beyond a certain version or at a certain version and including a specific
10607 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10608 later, or it is version 7.4 and patch 248 was included. Example: >
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010609 :if has("patch-7.4.248")
Bram Moolenaar2f018892018-05-18 18:12:06 +020010610< Note that it's possible for patch 248 to be omitted even though 249 is
10611 included. Only happens when cherry-picking patches.
10612 Note that this form only works for patch 7.4.237 and later, before that
10613 you need to check for the patch and the v:version. Example (checking
10614 version 6.2.148 or later): >
10615 :if v:version > 602 || (v:version == 602 && has("patch148"))
Bram Moolenaar071d4272004-06-13 20:20:40 +000010616
Bram Moolenaard823fa92016-08-12 16:29:27 +020010617Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10618use: `if exists('+shellslash')`
10619
10620
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010621acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010622all_builtin_terms Compiled with all builtin terminals enabled.
10623amiga Amiga version of Vim.
10624arabic Compiled with Arabic support |Arabic|.
10625arp Compiled with ARP support (Amiga).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010626autocmd Compiled with autocommand support. (always true)
Bram Moolenaar91f84f62018-07-29 15:07:52 +020010627autochdir Compiled with support for 'autochdir'
Bram Moolenaare42a6d22017-11-12 19:21:51 +010010628autoservername Automatically enable |clientserver|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010629balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +000010630balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010631beos BeOS version of Vim.
10632browse Compiled with |:browse| support, and browse() will
10633 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +020010634browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010635bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010636builtin_terms Compiled with some builtin terminals.
10637byte_offset Compiled with support for 'o' in 'statusline'
10638cindent Compiled with 'cindent' support.
10639clientserver Compiled with remote invocation support |clientserver|.
10640clipboard Compiled with 'clipboard' support.
10641cmdline_compl Compiled with |cmdline-completion| support.
10642cmdline_hist Compiled with |cmdline-history| support.
10643cmdline_info Compiled with 'showcmd' and 'ruler' support.
10644comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010645compatible Compiled to be very Vi compatible.
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +010010646conpty Platform where |ConPTY| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010647cryptv Compiled with encryption support |encryption|.
10648cscope Compiled with |cscope| support.
Bram Moolenaar314dd792019-02-03 15:27:20 +010010649cursorbind Compiled with |'cursorbind'| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010650debug Compiled with "DEBUG" defined.
10651dialog_con Compiled with console dialog support.
10652dialog_gui Compiled with GUI dialog support.
10653diff Compiled with |vimdiff| and 'diff' support.
10654digraphs Compiled with support for digraphs.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010655directx Compiled with support for DirectX and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010656dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010657ebcdic Compiled on a machine with ebcdic character set.
10658emacs_tags Compiled with support for Emacs tags.
10659eval Compiled with expression evaluation support. Always
10660 true, of course!
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010661ex_extra |+ex_extra| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010662extra_search Compiled with support for |'incsearch'| and
10663 |'hlsearch'|
10664farsi Compiled with Farsi support |farsi|.
10665file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010666filterpipe When 'shelltemp' is off pipes are used for shell
10667 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000010668find_in_path Compiled with support for include file searches
10669 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010670float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010671fname_case Case in file names matters (for Amiga, MS-DOS, and
10672 Windows this is not present).
10673folding Compiled with |folding| support.
10674footer Compiled with GUI footer support. |gui-footer|
10675fork Compiled to use fork()/exec() instead of system().
10676gettext Compiled with message translation |multi-lang|
10677gui Compiled with GUI enabled.
10678gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010679gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010680gui_gtk Compiled with GTK+ GUI (any version).
10681gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +010010682gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010683gui_mac Compiled with Macintosh GUI.
10684gui_motif Compiled with Motif GUI.
10685gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010686gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010687gui_win32 Compiled with MS Windows Win32 GUI.
10688gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010689hangul_input Compiled with Hangul input support. |hangul|
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010690hpux HP-UX version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010691iconv Can use iconv() for conversion.
10692insert_expand Compiled with support for CTRL-X expansion commands in
10693 Insert mode.
10694jumplist Compiled with |jumplist| support.
10695keymap Compiled with 'keymap' support.
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010696lambda Compiled with |lambda| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010697langmap Compiled with 'langmap' support.
10698libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +020010699linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10700 'breakindent' support.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010701linux Linux version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010702lispindent Compiled with support for lisp indenting.
10703listcmds Compiled with commands for the buffer list |:files|
10704 and the argument list |arglist|.
10705localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +020010706lua Compiled with Lua interface |Lua|.
Bram Moolenaard0573012017-10-28 21:11:06 +020010707mac Any Macintosh version of Vim cf. osx
10708macunix Synonym for osxdarwin
Bram Moolenaar071d4272004-06-13 20:20:40 +000010709menu Compiled with support for |:menu|.
10710mksession Compiled with support for |:mksession|.
10711modify_fname Compiled with file name modifiers. |filename-modifiers|
10712mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010713mouse_dec Compiled with support for Dec terminal mouse.
10714mouse_gpm Compiled with support for gpm (Linux console mouse)
Bram Moolenaar4b8366b2019-05-04 17:34:34 +020010715mouse_gpm_enabled GPM mouse is working
Bram Moolenaar071d4272004-06-13 20:20:40 +000010716mouse_netterm Compiled with support for netterm mouse.
10717mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010718mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +020010719mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +010010720mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010721mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010722mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar4c92e752019-02-17 21:18:32 +010010723multi_byte Compiled with support for 'encoding' (always true)
Bram Moolenaar42022d52008-12-09 09:57:49 +000010724multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010725multi_byte_ime Compiled with support for IME input method.
10726multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000010727mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +020010728netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010729netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010730num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010731ole Compiled with OLE automation support for Win32.
Bram Moolenaard0573012017-10-28 21:11:06 +020010732osx Compiled for macOS cf. mac
10733osxdarwin Compiled for macOS, with |mac-darwin-feature|
Bram Moolenaar91c49372016-05-08 09:50:29 +020010734packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010735path_extra Compiled with up/downwards search in 'path' and 'tags'
10736perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +020010737persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010738postscript Compiled with PostScript file printing.
10739printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +000010740profile Compiled with |:profile| support.
Bram Moolenaar84b242c2018-01-28 17:45:49 +010010741python Python 2.x interface available. |has-python|
10742python_compiled Compiled with Python 2.x interface. |has-python|
10743python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10744python3 Python 3.x interface available. |has-python|
10745python3_compiled Compiled with Python 3.x interface. |has-python|
10746python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +010010747pythonx Compiled with |python_x| interface. |has-pythonx|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010748qnx QNX version of Vim.
10749quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +000010750reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010751rightleft Compiled with 'rightleft' support.
10752ruby Compiled with Ruby interface |ruby|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010753scrollbind Compiled with 'scrollbind' support. (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010754showcmd Compiled with 'showcmd' support.
10755signs Compiled with |:sign| support.
10756smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010757spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +000010758startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010759statusline Compiled with support for 'statusline', 'rulerformat'
10760 and special formats of 'titlestring' and 'iconstring'.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010761sun SunOS version of Vim.
Bram Moolenaard09091d2019-01-17 16:07:22 +010010762sun_workshop Support for Sun |workshop| has been removed.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +000010763syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010764syntax_items There are active syntax highlighting items for the
10765 current buffer.
10766system Compiled to use system() instead of fork()/exec().
10767tag_binary Compiled with binary searching in tags files
10768 |tag-binary-search|.
Bram Moolenaar723dd942019-04-04 13:11:03 +020010769tag_old_static Support for old static tags was removed, see
Bram Moolenaar071d4272004-06-13 20:20:40 +000010770 |tag-old-static|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010771tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +020010772termguicolors Compiled with true color in terminal support.
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +020010773terminal Compiled with |terminal| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010774terminfo Compiled with terminfo instead of termcap.
10775termresponse Compiled with support for |t_RV| and |v:termresponse|.
10776textobjects Compiled with support for |text-objects|.
Bram Moolenaar98aefe72018-12-13 22:20:09 +010010777textprop Compiled with support for |text-properties|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010778tgetent Compiled with tgetent support, able to use a termcap
10779 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +010010780timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010781title Compiled with window title support |'title'|.
10782toolbar Compiled with support for |gui-toolbar|.
Bram Moolenaar2cab0e12016-11-24 15:09:07 +010010783ttyin input is a terminal (tty)
10784ttyout output is a terminal (tty)
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010785unix Unix version of Vim. *+unix*
Bram Moolenaar3df01732017-02-17 22:47:16 +010010786unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
Bram Moolenaarac9fb182019-04-27 13:04:13 +020010787user_commands User-defined commands. (always true)
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010010788vcon Win32: Virtual console support is working, can use
10789 'termguicolors'. Also see |+vtp|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010790vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010791 (always true)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010792vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010793 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010794viminfo Compiled with viminfo support.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020010795vimscript-1 Compiled Vim script version 1 support
10796vimscript-2 Compiled Vim script version 2 support
Bram Moolenaar911ead12019-04-21 00:03:35 +020010797vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010798virtualedit Compiled with 'virtualedit' option. (always true)
Bram Moolenaar5b69c222019-01-11 14:50:06 +010010799visual Compiled with Visual mode. (always true)
10800visualextra Compiled with extra Visual mode commands. (always
10801 true) |blockwise-operators|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010802vms VMS version of Vim.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010803vreplace Compiled with |gR| and |gr| commands. (always true)
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010804vtp Compiled for vcon support |+vtp| (check vcon to find
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +010010805 out if it works in the current console).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010806wildignore Compiled with 'wildignore' option.
10807wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010808win16 old version for MS-Windows 3.1 (always false)
Bram Moolenaard58e9292011-02-09 17:07:58 +010010809win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10810 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010811win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010812win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010813win95 Win32 version for MS-Windows 95/98/ME (always false)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010814winaltkeys Compiled with 'winaltkeys' option.
10815windows Compiled with support for more than one window.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010816 (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010817writebackup Compiled with 'writebackup' default on.
10818xfontset Compiled with X fontset support |xfontset|.
10819xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010820xpm Compiled with pixmap support.
10821xpm_w32 Compiled with pixmap support for Win32. (Only for
10822 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010823xsmp Compiled with X session management support.
10824xsmp_interact Compiled with interactive X session management support.
10825xterm_clipboard Compiled with support for xterm clipboard.
10826xterm_save Compiled with support for saving and restoring the
10827 xterm screen.
10828x11 Compiled with X11 support.
10829
10830 *string-match*
10831Matching a pattern in a String
10832
10833A regexp pattern as explained at |pattern| is normally used to find a match in
10834the buffer lines. When a pattern is used to find a match in a String, almost
10835everything works in the same way. The difference is that a String is handled
10836like it is one line. When it contains a "\n" character, this is not seen as a
10837line break for the pattern. It can be matched with a "\n" in the pattern, or
10838with ".". Example: >
10839 :let a = "aaaa\nxxxx"
10840 :echo matchstr(a, "..\n..")
10841 aa
10842 xx
10843 :echo matchstr(a, "a.x")
10844 a
10845 x
10846
10847Don't forget that "^" will only match at the first character of the String and
10848"$" at the last character of the string. They don't match after or before a
10849"\n".
10850
10851==============================================================================
108525. Defining functions *user-functions*
10853
10854New functions can be defined. These can be called just like builtin
10855functions. The function executes a sequence of Ex commands. Normal mode
10856commands can be executed with the |:normal| command.
10857
10858The function name must start with an uppercase letter, to avoid confusion with
10859builtin functions. To prevent from using the same name in different scripts
10860avoid obvious, short names. A good habit is to start the function name with
10861the name of the script, e.g., "HTMLcolor()".
10862
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010863It's also possible to use curly braces, see |curly-braces-names|. And the
10864|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010865
10866 *local-function*
10867A function local to a script must start with "s:". A local script function
10868can only be called from within the script and from functions, user commands
10869and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +000010870function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +000010871instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010872There are only script-local functions, no buffer-local or window-local
10873functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010874
10875 *:fu* *:function* *E128* *E129* *E123*
10876:fu[nction] List all functions and their arguments.
10877
10878:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010879 {name} can also be a |Dictionary| entry that is a
10880 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010881 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010882
10883:fu[nction] /{pattern} List functions with a name matching {pattern}.
10884 Example that lists all functions ending with "File": >
10885 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010886<
10887 *:function-verbose*
10888When 'verbose' is non-zero, listing a function will also display where it was
10889last defined. Example: >
10890
10891 :verbose function SetFileTypeSH
10892 function SetFileTypeSH(name)
10893 Last set from /usr/share/vim/vim-7.0/filetype.vim
10894<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +000010895See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010896
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010897 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010898:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +010010899 Define a new function by the name {name}. The body of
10900 the function follows in the next lines, until the
10901 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010902
Bram Moolenaar01164a62017-11-02 22:58:42 +010010903 The name must be made of alphanumeric characters and
10904 '_', and must start with a capital or "s:" (see
10905 above). Note that using "b:" or "g:" is not allowed.
10906 (since patch 7.4.260 E884 is given if the function
10907 name has a colon in the name, e.g. for "foo:bar()".
10908 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010909
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010910 {name} can also be a |Dictionary| entry that is a
10911 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010912 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +020010913< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010914 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +020010915 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010916 result is a |Funcref| to a numbered function. The
10917 function can only be used with a |Funcref| and will be
10918 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010919 *E127* *E122*
10920 When a function by this name already exists and [!] is
Bram Moolenaarded5f1b2018-11-10 17:33:29 +010010921 not used an error message is given. There is one
10922 exception: When sourcing a script again, a function
10923 that was previously defined in that script will be
10924 silently replaced.
10925 When [!] is used, an existing function is silently
10926 replaced. Unless it is currently being executed, that
10927 is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010928 NOTE: Use ! wisely. If used without care it can cause
10929 an existing function to be replaced unexpectedly,
10930 which is hard to debug.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010931
10932 For the {arguments} see |function-argument|.
10933
Bram Moolenaar8d043172014-01-23 14:24:41 +010010934 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010935 When the [range] argument is added, the function is
10936 expected to take care of a range itself. The range is
10937 passed as "a:firstline" and "a:lastline". If [range]
10938 is excluded, ":{range}call" will call the function for
10939 each line in the range, with the cursor on the start
10940 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +010010941 The cursor is still moved to the first line of the
10942 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010943 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010944 When the [abort] argument is added, the function will
10945 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010946 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010947 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +020010948 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010949 local variable "self" will then be set to the
10950 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010951 *:func-closure* *E932*
10952 When the [closure] argument is added, the function
10953 can access variables and arguments from the outer
10954 scope. This is usually called a closure. In this
10955 example Bar() uses "x" from the scope of Foo(). It
10956 remains referenced even after Foo() returns: >
10957 :function! Foo()
10958 : let x = 0
10959 : function! Bar() closure
10960 : let x += 1
10961 : return x
10962 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +020010963 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010964 :endfunction
10965
10966 :let F = Foo()
10967 :echo F()
10968< 1 >
10969 :echo F()
10970< 2 >
10971 :echo F()
10972< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +000010973
Bram Moolenaar446cb832008-06-24 21:56:24 +000010974 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +000010975 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +000010976 will not be changed by the function. This also
10977 implies that the effect of |:nohlsearch| is undone
10978 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +000010979
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010980 *:endf* *:endfunction* *E126* *E193* *W22*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010981:endf[unction] [argument]
10982 The end of a function definition. Best is to put it
10983 on a line by its own, without [argument].
10984
10985 [argument] can be:
10986 | command command to execute next
10987 \n command command to execute next
10988 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010989 anything else ignored, warning given when
10990 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +020010991 The support for a following command was added in Vim
10992 8.0.0654, before that any argument was silently
10993 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010994
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010995 To be able to define a function inside an `:execute`
10996 command, use line breaks instead of |:bar|: >
10997 :exe "func Foo()\necho 'foo'\nendfunc"
10998<
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010999 *:delf* *:delfunction* *E130* *E131* *E933*
Bram Moolenaar663bb232017-06-22 19:12:10 +020011000:delf[unction][!] {name}
11001 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011002 {name} can also be a |Dictionary| entry that is a
11003 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011004 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +020011005< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011006 function is deleted if there are no more references to
11007 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +020011008 With the ! there is no error if the function does not
11009 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011010 *:retu* *:return* *E133*
11011:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
11012 evaluated and returned as the result of the function.
11013 If "[expr]" is not given, the number 0 is returned.
11014 When a function ends without an explicit ":return",
11015 the number 0 is returned.
11016 Note that there is no check for unreachable lines,
11017 thus there is no warning if commands follow ":return".
11018
11019 If the ":return" is used after a |:try| but before the
11020 matching |:finally| (if present), the commands
11021 following the ":finally" up to the matching |:endtry|
11022 are executed first. This process applies to all
11023 nested ":try"s inside the function. The function
11024 returns at the outermost ":endtry".
11025
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011026 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +020011027An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011028be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011029 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011030Up to 20 arguments can be given, separated by commas. After the named
11031arguments an argument "..." can be specified, which means that more arguments
11032may optionally be following. In the function the extra arguments can be used
11033as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011034can be 0). "a:000" is set to a |List| that contains these arguments. Note
11035that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011036 *E742*
11037The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +020011038However, if a composite type is used, such as |List| or |Dictionary| , you can
11039change their contents. Thus you can pass a |List| to a function and have the
11040function add an item to it. If you want to make sure the function cannot
11041change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011042
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011043It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +010011044still supply the () then.
11045
Bram Moolenaar98ef2332018-03-18 14:44:37 +010011046It is allowed to define another function inside a function body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011047
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020011048 *optional-function-argument*
11049You can provide default values for positional named arguments. This makes
11050them optional for function calls. When a positional argument is not
11051specified at a call, the default expression is used to initialize it.
Bram Moolenaar68e65602019-05-26 21:33:31 +020011052This only works for functions declared with `:function`, not for lambda
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020011053expressions |expr-lambda|.
11054
11055Example: >
11056 function Something(key, value = 10)
Bram Moolenaar8aad88d2019-05-12 13:53:50 +020011057 echo a:key .. ": " .. a:value
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020011058 endfunction
11059 call Something('empty') "empty: 10"
Bram Moolenaar8aad88d2019-05-12 13:53:50 +020011060 call Something('key', 20) "key: 20"
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020011061
11062The argument default expressions are evaluated at the time of the function
11063call, not definition. Thus it is possible to use an expression which is
Bram Moolenaar68e65602019-05-26 21:33:31 +020011064invalid the moment the function is defined. The expressions are also only
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020011065evaluated when arguments are not specified during a call.
11066
11067You can pass |v:none| to use the default expression. Note that this means you
11068cannot pass v:none as an ordinary value when an argument has a default
11069expression.
11070
11071Example: >
11072 function Something(a = 10, b = 20, c = 30)
11073 endfunction
11074 call Something(1, v:none, 3) " b = 20
11075<
11076 *E989*
11077Optional arguments with default expressions must occur after any mandatory
11078arguments. You can use "..." after all optional named arguments.
11079
11080It is possible for later argument defaults to refer to prior arguments,
11081but not the other way around. They must be prefixed with "a:", as with all
11082arguments.
11083
11084Example that works: >
11085 :function Okay(mandatory, optional = a:mandatory)
11086 :endfunction
11087Example that does NOT work: >
11088 :function NoGood(first = a:second, second = 10)
11089 :endfunction
11090<
11091When not using "...", the number of arguments in a function call must be equal
11092to the number of mandatory named arguments. When using "...", the number of
11093arguments may be larger.
11094
Bram Moolenaar8f999f12005-01-25 22:12:55 +000011095 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +020011096Inside a function local variables can be used. These will disappear when the
11097function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +000011098
11099Example: >
11100 :function Table(title, ...)
11101 : echohl Title
11102 : echo a:title
11103 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +000011104 : echo a:0 . " items:"
11105 : for s in a:000
11106 : echon ' ' . s
11107 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +000011108 :endfunction
11109
11110This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +000011111 call Table("Table", "line1", "line2")
11112 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +000011113
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011114To return more than one value, return a |List|: >
11115 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011116 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011117 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +000011118 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011119 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +000011120 :endfunction
11121
11122This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011123 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011124 :if success == "ok"
11125 : echo div
11126 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011127<
Bram Moolenaar39f05632006-03-19 22:15:26 +000011128 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011129:[range]cal[l] {name}([arguments])
11130 Call a function. The name of the function and its arguments
Bram Moolenaar68e65602019-05-26 21:33:31 +020011131 are as specified with `:function`. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011132 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011133 Without a range and for functions that accept a range, the
11134 function is called once. When a range is given the cursor is
11135 positioned at the start of the first line before executing the
11136 function.
11137 When a range is given and the function doesn't handle it
11138 itself, the function is executed for each line in the range,
11139 with the cursor in the first column of that line. The cursor
11140 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +020011141 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +000011142 this works:
11143 *function-range-example* >
11144 :function Mynumber(arg)
11145 : echo line(".") . " " . a:arg
11146 :endfunction
11147 :1,5call Mynumber(getline("."))
11148<
11149 The "a:firstline" and "a:lastline" are defined anyway, they
11150 can be used to do something different at the start or end of
11151 the range.
11152
11153 Example of a function that handles the range itself: >
11154
11155 :function Cont() range
11156 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
11157 :endfunction
11158 :4,8call Cont()
11159<
11160 This function inserts the continuation character "\" in front
11161 of all the lines in the range, except the first one.
11162
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011163 When the function returns a composite value it can be further
11164 dereferenced, but the range will not be used then. Example: >
11165 :4,8call GetDict().method()
11166< Here GetDict() gets the range but method() does not.
11167
Bram Moolenaar071d4272004-06-13 20:20:40 +000011168 *E132*
11169The recursiveness of user functions is restricted with the |'maxfuncdepth'|
11170option.
11171
Bram Moolenaar7c626922005-02-07 22:01:03 +000011172
11173AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000011174 *autoload-functions*
11175When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +000011176only when they are used. There are two methods: with an autocommand and with
11177the "autoload" directory in 'runtimepath'.
11178
11179
11180Using an autocommand ~
11181
Bram Moolenaar05159a02005-02-26 23:04:13 +000011182This is introduced in the user manual, section |41.14|.
11183
Bram Moolenaar7c626922005-02-07 22:01:03 +000011184The autocommand is useful if you have a plugin that is a long Vim script file.
Bram Moolenaar68e65602019-05-26 21:33:31 +020011185You can define the autocommand and quickly quit the script with `:finish`.
Bram Moolenaar58b85342016-08-14 19:54:54 +020011186That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar68e65602019-05-26 21:33:31 +020011187again, setting a variable to skip the `:finish` command.
Bram Moolenaar7c626922005-02-07 22:01:03 +000011188
11189Use the FuncUndefined autocommand event with a pattern that matches the
11190function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011191
11192 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
11193
11194The file "~/vim/bufnetfuncs.vim" should then define functions that start with
11195"BufNet". Also see |FuncUndefined|.
11196
Bram Moolenaar7c626922005-02-07 22:01:03 +000011197
11198Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011199 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +000011200This is introduced in the user manual, section |41.15|.
11201
Bram Moolenaar7c626922005-02-07 22:01:03 +000011202Using a script in the "autoload" directory is simpler, but requires using
11203exactly the right file name. A function that can be autoloaded has a name
11204like this: >
11205
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011206 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011207
11208When such a function is called, and it is not defined yet, Vim will search the
11209"autoload" directories in 'runtimepath' for a script file called
11210"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
11211then define the function like this: >
11212
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011213 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011214 echo "Done!"
11215 endfunction
11216
Bram Moolenaar60a795a2005-09-16 21:55:43 +000011217The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +000011218exactly, and the defined function must have the name exactly as it will be
11219called.
11220
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011221It is possible to use subdirectories. Every # in the function name works like
11222a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +000011223
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011224 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011225
11226Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
11227
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011228This also works when reading a variable that has not been set yet: >
11229
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011230 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011231
Bram Moolenaara5792f52005-11-23 21:25:05 +000011232However, when the autoload script was already loaded it won't be loaded again
11233for an unknown variable.
11234
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011235When assigning a value to such a variable nothing special happens. This can
11236be used to pass settings to the autoload script before it's loaded: >
11237
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011238 :let foo#bar#toggle = 1
11239 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011240
Bram Moolenaar4399ef42005-02-12 14:29:27 +000011241Note that when you make a mistake and call a function that is supposed to be
11242defined in an autoload script, but the script doesn't actually define the
11243function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011244And you will get an error message every time.
11245
11246Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +000011247other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011248Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +000011249
Bram Moolenaar433f7c82006-03-21 21:29:36 +000011250Hint: If you distribute a bunch of scripts you can pack them together with the
11251|vimball| utility. Also read the user manual |distribute-script|.
11252
Bram Moolenaar071d4272004-06-13 20:20:40 +000011253==============================================================================
112546. Curly braces names *curly-braces-names*
11255
Bram Moolenaar84f72352012-03-11 15:57:40 +010011256In most places where you can use a variable, you can use a "curly braces name"
11257variable. This is a regular variable name with one or more expressions
11258wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011259 my_{adjective}_variable
11260
11261When Vim encounters this, it evaluates the expression inside the braces, puts
11262that in place of the expression, and re-interprets the whole as a variable
11263name. So in the above example, if the variable "adjective" was set to
11264"noisy", then the reference would be to "my_noisy_variable", whereas if
11265"adjective" was set to "quiet", then it would be to "my_quiet_variable".
11266
11267One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +020011268value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011269 echo my_{&background}_message
11270
11271would output the contents of "my_dark_message" or "my_light_message" depending
11272on the current value of 'background'.
11273
11274You can use multiple brace pairs: >
11275 echo my_{adverb}_{adjective}_message
11276..or even nest them: >
11277 echo my_{ad{end_of_word}}_message
11278where "end_of_word" is either "verb" or "jective".
11279
11280However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000011281variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011282 :let foo='a + b'
11283 :echo c{foo}d
11284.. since the result of expansion is "ca + bd", which is not a variable name.
11285
11286 *curly-braces-function-names*
11287You can call and define functions by an evaluated name in a similar way.
11288Example: >
11289 :let func_end='whizz'
11290 :call my_func_{func_end}(parameter)
11291
11292This would call the function "my_func_whizz(parameter)".
11293
Bram Moolenaar84f72352012-03-11 15:57:40 +010011294This does NOT work: >
11295 :let i = 3
11296 :let @{i} = '' " error
11297 :echo @{i} " error
11298
Bram Moolenaar071d4272004-06-13 20:20:40 +000011299==============================================================================
113007. Commands *expression-commands*
11301
11302:let {var-name} = {expr1} *:let* *E18*
11303 Set internal variable {var-name} to the result of the
11304 expression {expr1}. The variable will get the type
11305 from the {expr}. If {var-name} didn't exist yet, it
11306 is created.
11307
Bram Moolenaar13065c42005-01-08 16:08:21 +000011308:let {var-name}[{idx}] = {expr1} *E689*
11309 Set a list item to the result of the expression
11310 {expr1}. {var-name} must refer to a list and {idx}
11311 must be a valid index in that list. For nested list
11312 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011313 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020011314 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +000011315 can do that like this: >
11316 :let var = var[0:2] . 'X' . var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010011317< When {var-name} is a |Blob| then {idx} can be the
11318 length of the blob, in which case one byte is
11319 appended.
11320
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011321 *E711* *E719*
11322:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011323 Set a sequence of items in a |List| to the result of
11324 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011325 correct number of items.
11326 {idx1} can be omitted, zero is used instead.
11327 {idx2} can be omitted, meaning the end of the list.
11328 When the selected range of items is partly past the
11329 end of the list, items will be added.
11330
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011331 *:let+=* *:let-=* *:letstar=*
11332 *:let/=* *:let%=* *:let.=* *:let..=* *E734* *E985*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011333:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
11334:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +010011335:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
11336:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
11337:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011338:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011339:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011340 These fail if {var} was not set yet and when the type
11341 of {var} and {expr1} don't fit the operator.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011342 `.=` is not supported with Vim script version 2 and
11343 later, see |vimscript-version|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011344
11345
Bram Moolenaar071d4272004-06-13 20:20:40 +000011346:let ${env-name} = {expr1} *:let-environment* *:let-$*
11347 Set environment variable {env-name} to the result of
11348 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011349:let ${env-name} .= {expr1}
11350 Append {expr1} to the environment variable {env-name}.
11351 If the environment variable didn't exist yet this
11352 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +000011353
11354:let @{reg-name} = {expr1} *:let-register* *:let-@*
11355 Write the result of the expression {expr1} in register
11356 {reg-name}. {reg-name} must be a single letter, and
11357 must be the name of a writable register (see
11358 |registers|). "@@" can be used for the unnamed
11359 register, "@/" for the search pattern.
11360 If the result of {expr1} ends in a <CR> or <NL>, the
11361 register will be linewise, otherwise it will be set to
11362 characterwise.
11363 This can be used to clear the last search pattern: >
11364 :let @/ = ""
11365< This is different from searching for an empty string,
11366 that would match everywhere.
11367
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011368:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +020011369 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011370 register was empty it's like setting it to {expr1}.
11371
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011372:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011373 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011374 expression {expr1}. A String or Number value is
11375 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011376 For an option local to a window or buffer the effect
11377 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +000011378 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011379 Example: >
11380 :let &path = &path . ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +010011381< This also works for terminal codes in the form t_xx.
11382 But only for alphanumerical names. Example: >
11383 :let &t_k1 = "\<Esc>[234;"
11384< When the code does not exist yet it will be created as
11385 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011386
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011387:let &{option-name} .= {expr1}
11388 For a string option: Append {expr1} to the value.
11389 Does not insert a comma like |:set+=|.
11390
11391:let &{option-name} += {expr1}
11392:let &{option-name} -= {expr1}
11393 For a number or boolean option: Add or subtract
11394 {expr1}.
11395
Bram Moolenaar071d4272004-06-13 20:20:40 +000011396:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011397:let &l:{option-name} .= {expr1}
11398:let &l:{option-name} += {expr1}
11399:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000011400 Like above, but only set the local value of an option
11401 (if there is one). Works like |:setlocal|.
11402
11403:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011404:let &g:{option-name} .= {expr1}
11405:let &g:{option-name} += {expr1}
11406:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000011407 Like above, but only set the global value of an option
11408 (if there is one). Works like |:setglobal|.
11409
Bram Moolenaar13065c42005-01-08 16:08:21 +000011410:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011411 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011412 the list is assigned to {name1}, the second item to
11413 {name2}, etc.
11414 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011415 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011416 Each name can be one of the items of the ":let"
11417 command as mentioned above.
11418 Example: >
11419 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011420< Detail: {expr1} is evaluated first, then the
11421 assignments are done in sequence. This matters if
11422 {name2} depends on {name1}. Example: >
11423 :let x = [0, 1]
11424 :let i = 0
11425 :let [i, x[i]] = [1, 2]
11426 :echo x
11427< The result is [0, 2].
11428
11429:let [{name1}, {name2}, ...] .= {expr1}
11430:let [{name1}, {name2}, ...] += {expr1}
11431:let [{name1}, {name2}, ...] -= {expr1}
11432 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011433 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011434
11435:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011436 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011437 items than there are names. A list of the remaining
11438 items is assigned to {lastname}. If there are no
11439 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011440 Example: >
11441 :let [a, b; rest] = ["aval", "bval", 3, 4]
11442<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011443:let [{name}, ..., ; {lastname}] .= {expr1}
11444:let [{name}, ..., ; {lastname}] += {expr1}
11445:let [{name}, ..., ; {lastname}] -= {expr1}
11446 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011447 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +020011448
Bram Moolenaarf5842c52019-05-19 18:41:26 +020011449 *:let=<<* *:let-heredoc* *E990* *E991*
11450:let {var-name} =<< [trim] {marker}
11451text...
11452text...
11453{marker}
11454 Set internal variable {var-name} to a List containing
11455 the lines of text bounded by the string {marker}.
11456 {marker} must not contain white space.
11457 The last line should end only with the {marker} string
11458 without any other character. Watch out for white
11459 space after {marker}!
11460 If {marker} is not supplied, then "." is used as the
11461 default marker.
11462
11463 Any white space characters in the lines of text are
11464 preserved. If "trim" is specified before {marker},
11465 then all the leading indentation exactly matching the
11466 leading indentation before `let` is stripped from the
11467 input lines and the line containing {marker}. Note
11468 that the difference between space and tab matters
11469 here.
11470
11471 If {var-name} didn't exist yet, it is created.
11472 Cannot be followed by another command, but can be
11473 followed by a comment.
11474
11475 Examples: >
11476 let var1 =<< END
11477 Sample text 1
11478 Sample text 2
11479 Sample text 3
11480 END
11481
11482 let data =<< trim DATA
11483 1 2 3 4
11484 5 6 7 8
11485 DATA
11486<
Bram Moolenaar4a748032010-09-30 21:47:56 +020011487 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +020011488:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000011489 variable names may be given. Special names recognized
11490 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +000011491 g: global variables
11492 b: local buffer variables
11493 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011494 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +000011495 s: script-local variables
11496 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000011497 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011498
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000011499:let List the values of all variables. The type of the
11500 variable is indicated before the value:
11501 <nothing> String
11502 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000011503 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +000011504
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011505
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011506:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011507 Remove the internal variable {name}. Several variable
11508 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011509 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011510 With [!] no error message is given for non-existing
11511 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011512 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000011513 :unlet list[3] " remove fourth item
11514 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011515< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000011516 :unlet dict['two']
11517 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +000011518< This is especially useful to clean up used global
11519 variables and script-local variables (these are not
11520 deleted when the script ends). Function-local
11521 variables are automatically deleted when the function
11522 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011523
Bram Moolenaar137374f2018-05-13 15:59:50 +020011524:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
11525 Remove environment variable {env-name}.
11526 Can mix {name} and ${env-name} in one :unlet command.
11527 No error message is given for a non-existing
11528 variable, also without !.
11529 If the system does not support deleting an environment
11530 variable, it is made emtpy.
11531
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011532:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
11533 Lock the internal variable {name}. Locking means that
11534 it can no longer be changed (until it is unlocked).
11535 A locked variable can be deleted: >
11536 :lockvar v
11537 :let v = 'asdf' " fails!
11538 :unlet v
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011539< *E741* *E940*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011540 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011541 error message: "E741: Value is locked: {name}".
11542 If you try to lock or unlock a built-in variable you
11543 get an error message: "E940: Cannot lock or unlock
11544 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011545
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011546 [depth] is relevant when locking a |List| or
11547 |Dictionary|. It specifies how deep the locking goes:
11548 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011549 cannot add or remove items, but can
11550 still change their values.
11551 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011552 the items. If an item is a |List| or
11553 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011554 items, but can still change the
11555 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011556 3 Like 2 but for the |List| /
11557 |Dictionary| in the |List| /
11558 |Dictionary|, one level deeper.
11559 The default [depth] is 2, thus when {name} is a |List|
11560 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011561 *E743*
11562 For unlimited depth use [!] and omit [depth].
11563 However, there is a maximum depth of 100 to catch
11564 loops.
11565
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011566 Note that when two variables refer to the same |List|
11567 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011568 locked when used through the other variable.
11569 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011570 :let l = [0, 1, 2, 3]
11571 :let cl = l
11572 :lockvar l
11573 :let cl[1] = 99 " won't work!
11574< You may want to make a copy of a list to avoid this.
11575 See |deepcopy()|.
11576
11577
11578:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
11579 Unlock the internal variable {name}. Does the
11580 opposite of |:lockvar|.
11581
11582
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020011583:if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011584:en[dif] Execute the commands until the next matching ":else"
11585 or ":endif" if {expr1} evaluates to non-zero.
11586
11587 From Vim version 4.5 until 5.0, every Ex command in
11588 between the ":if" and ":endif" is ignored. These two
11589 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +010011590 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +000011591 that any ":else" or ":elseif" was ignored, the "else"
11592 part was not executed either.
11593
11594 You can use this to remain compatible with older
11595 versions: >
11596 :if version >= 500
11597 : version-5-specific-commands
11598 :endif
11599< The commands still need to be parsed to find the
11600 "endif". Sometimes an older Vim has a problem with a
11601 new command. For example, ":silent" is recognized as
11602 a ":substitute" command. In that case ":execute" can
11603 avoid problems: >
11604 :if version >= 600
11605 : execute "silent 1,$delete"
11606 :endif
11607<
11608 NOTE: The ":append" and ":insert" commands don't work
11609 properly in between ":if" and ":endif".
11610
11611 *:else* *:el* *E581* *E583*
11612:el[se] Execute the commands until the next matching ":else"
11613 or ":endif" if they previously were not being
11614 executed.
11615
11616 *:elseif* *:elsei* *E582* *E584*
11617:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
11618 is no extra ":endif".
11619
11620:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011621 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011622:endw[hile] Repeat the commands between ":while" and ":endwhile",
11623 as long as {expr1} evaluates to non-zero.
11624 When an error is detected from a command inside the
11625 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +000011626 Example: >
11627 :let lnum = 1
11628 :while lnum <= line("$")
11629 :call FixLine(lnum)
11630 :let lnum = lnum + 1
11631 :endwhile
11632<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011633 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +000011634 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011635
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011636:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +000011637:endfo[r] *:endfo* *:endfor*
11638 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011639 each item in {object}. {object} can be a |List| or
11640 a |Blob|. Variable {var} is set to the value of each
11641 item. When an error is detected for a command inside
11642 the loop, execution continues after the "endfor".
11643 Changing {object} inside the loop affects what items
11644 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +000011645 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011646<
11647 When {object} is a |List| and not making a copy, Vim
11648 stores a reference to the next item in the |List|
11649 before executing the commands with the current item.
11650 Thus the current item can be removed without effect.
11651 Removing any later item means it will not be found.
11652 Thus the following example works (an inefficient way
11653 to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011654 for item in mylist
11655 call remove(mylist, 0)
11656 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011657< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011658 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +000011659
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011660 When {object} is a |Blob|, Vim always makes a copy to
11661 iterate over. Unlike with |List|, modifying the
11662 |Blob| does not affect the iteration.
11663
Bram Moolenaar12805862005-01-05 22:16:17 +000011664:for [{var1}, {var2}, ...] in {listlist}
11665:endfo[r]
11666 Like ":for" above, but each item in {listlist} must be
11667 a list, of which each item is assigned to {var1},
11668 {var2}, etc. Example: >
11669 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
11670 :echo getline(lnum)[col]
11671 :endfor
11672<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011673 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +000011674:con[tinue] When used inside a ":while" or ":for" loop, jumps back
11675 to the start of the loop.
11676 If it is used after a |:try| inside the loop but
11677 before the matching |:finally| (if present), the
11678 commands following the ":finally" up to the matching
11679 |:endtry| are executed first. This process applies to
11680 all nested ":try"s inside the loop. The outermost
11681 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011682
11683 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +000011684:brea[k] When used inside a ":while" or ":for" loop, skips to
11685 the command after the matching ":endwhile" or
11686 ":endfor".
11687 If it is used after a |:try| inside the loop but
11688 before the matching |:finally| (if present), the
11689 commands following the ":finally" up to the matching
11690 |:endtry| are executed first. This process applies to
11691 all nested ":try"s inside the loop. The outermost
11692 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011693
11694:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
11695:endt[ry] Change the error handling for the commands between
11696 ":try" and ":endtry" including everything being
11697 executed across ":source" commands, function calls,
11698 or autocommand invocations.
11699
11700 When an error or interrupt is detected and there is
11701 a |:finally| command following, execution continues
11702 after the ":finally". Otherwise, or when the
11703 ":endtry" is reached thereafter, the next
11704 (dynamically) surrounding ":try" is checked for
11705 a corresponding ":finally" etc. Then the script
11706 processing is terminated. (Whether a function
11707 definition has an "abort" argument does not matter.)
11708 Example: >
11709 :try | edit too much | finally | echo "cleanup" | endtry
11710 :echo "impossible" " not reached, script terminated above
11711<
11712 Moreover, an error or interrupt (dynamically) inside
11713 ":try" and ":endtry" is converted to an exception. It
11714 can be caught as if it were thrown by a |:throw|
11715 command (see |:catch|). In this case, the script
11716 processing is not terminated.
11717
11718 The value "Vim:Interrupt" is used for an interrupt
11719 exception. An error in a Vim command is converted
11720 to a value of the form "Vim({command}):{errmsg}",
11721 other errors are converted to a value of the form
11722 "Vim:{errmsg}". {command} is the full command name,
11723 and {errmsg} is the message that is displayed if the
11724 error exception is not caught, always beginning with
11725 the error number.
11726 Examples: >
11727 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
11728 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
11729<
11730 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011731:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011732 |:finally|, or |:endtry| that belongs to the same
11733 |:try| as the ":catch" are executed when an exception
11734 matching {pattern} is being thrown and has not yet
11735 been caught by a previous ":catch". Otherwise, these
11736 commands are skipped.
11737 When {pattern} is omitted all errors are caught.
11738 Examples: >
Bram Moolenaar647e24b2019-03-17 16:39:46 +010011739 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
11740 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
11741 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
11742 :catch /^Vim(write):/ " catch all errors in :write
11743 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
11744 :catch /my-exception/ " catch user exception
11745 :catch /.*/ " catch everything
11746 :catch " same as /.*/
Bram Moolenaar071d4272004-06-13 20:20:40 +000011747<
11748 Another character can be used instead of / around the
11749 {pattern}, so long as it does not have a special
11750 meaning (e.g., '|' or '"') and doesn't occur inside
11751 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020011752 Information about the exception is available in
11753 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011754 NOTE: It is not reliable to ":catch" the TEXT of
11755 an error message because it may vary in different
11756 locales.
11757
11758 *:fina* *:finally* *E606* *E607*
11759:fina[lly] The following commands until the matching |:endtry|
11760 are executed whenever the part between the matching
11761 |:try| and the ":finally" is left: either by falling
11762 through to the ":finally" or by a |:continue|,
11763 |:break|, |:finish|, or |:return|, or by an error or
11764 interrupt or exception (see |:throw|).
11765
11766 *:th* *:throw* *E608*
11767:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
11768 If the ":throw" is used after a |:try| but before the
11769 first corresponding |:catch|, commands are skipped
11770 until the first ":catch" matching {expr1} is reached.
11771 If there is no such ":catch" or if the ":throw" is
11772 used after a ":catch" but before the |:finally|, the
11773 commands following the ":finally" (if present) up to
11774 the matching |:endtry| are executed. If the ":throw"
11775 is after the ":finally", commands up to the ":endtry"
11776 are skipped. At the ":endtry", this process applies
11777 again for the next dynamically surrounding ":try"
11778 (which may be found in a calling function or sourcing
11779 script), until a matching ":catch" has been found.
11780 If the exception is not caught, the command processing
11781 is terminated.
11782 Example: >
11783 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +010011784< Note that "catch" may need to be on a separate line
11785 for when an error causes the parsing to skip the whole
11786 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011787
11788 *:ec* *:echo*
11789:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
11790 first {expr1} starts on a new line.
11791 Also see |:comment|.
11792 Use "\n" to start a new line. Use "\r" to move the
11793 cursor to the first column.
11794 Uses the highlighting set by the |:echohl| command.
11795 Cannot be followed by a comment.
11796 Example: >
11797 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011798< *:echo-redraw*
11799 A later redraw may make the message disappear again.
11800 And since Vim mostly postpones redrawing until it's
11801 finished with a sequence of commands this happens
11802 quite often. To avoid that a command from before the
11803 ":echo" causes a redraw afterwards (redraws are often
11804 postponed until you type something), force a redraw
11805 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011806 :new | redraw | echo "there is a new window"
11807<
11808 *:echon*
11809:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
11810 |:comment|.
11811 Uses the highlighting set by the |:echohl| command.
11812 Cannot be followed by a comment.
11813 Example: >
11814 :echon "the value of 'shell' is " &shell
11815<
11816 Note the difference between using ":echo", which is a
11817 Vim command, and ":!echo", which is an external shell
11818 command: >
11819 :!echo % --> filename
11820< The arguments of ":!" are expanded, see |:_%|. >
11821 :!echo "%" --> filename or "filename"
11822< Like the previous example. Whether you see the double
11823 quotes or not depends on your 'shell'. >
11824 :echo % --> nothing
11825< The '%' is an illegal character in an expression. >
11826 :echo "%" --> %
11827< This just echoes the '%' character. >
11828 :echo expand("%") --> filename
11829< This calls the expand() function to expand the '%'.
11830
11831 *:echoh* *:echohl*
11832:echoh[l] {name} Use the highlight group {name} for the following
11833 |:echo|, |:echon| and |:echomsg| commands. Also used
11834 for the |input()| prompt. Example: >
11835 :echohl WarningMsg | echo "Don't panic!" | echohl None
11836< Don't forget to set the group back to "None",
11837 otherwise all following echo's will be highlighted.
11838
11839 *:echom* *:echomsg*
11840:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
11841 message in the |message-history|.
11842 Spaces are placed between the arguments as with the
11843 |:echo| command. But unprintable characters are
11844 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011845 The parsing works slightly different from |:echo|,
11846 more like |:execute|. All the expressions are first
11847 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011848 If expressions does not evaluate to a Number or
11849 String, string() is used to turn it into a string.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011850 Uses the highlighting set by the |:echohl| command.
11851 Example: >
11852 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011853< See |:echo-redraw| to avoid the message disappearing
11854 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011855 *:echoe* *:echoerr*
11856:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
11857 message in the |message-history|. When used in a
11858 script or function the line number will be added.
11859 Spaces are placed between the arguments as with the
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011860 |:echomsg| command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011861 the message is raised as an error exception instead
11862 (see |try-echoerr|).
11863 Example: >
11864 :echoerr "This script just failed!"
11865< If you just want a highlighted message use |:echohl|.
11866 And to get a beep: >
11867 :exe "normal \<Esc>"
11868<
11869 *:exe* *:execute*
11870:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011871 of {expr1} as an Ex command.
11872 Multiple arguments are concatenated, with a space in
11873 between. To avoid the extra space use the "."
11874 operator to concatenate strings into one argument.
11875 {expr1} is used as the processed command, command line
11876 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011877 Cannot be followed by a comment.
11878 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011879 :execute "buffer" nextbuf
11880 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +000011881<
11882 ":execute" can be used to append a command to commands
11883 that don't accept a '|'. Example: >
11884 :execute '!ls' | echo "theend"
11885
11886< ":execute" is also a nice way to avoid having to type
11887 control characters in a Vim script for a ":normal"
11888 command: >
11889 :execute "normal ixxx\<Esc>"
11890< This has an <Esc> character, see |expr-string|.
11891
Bram Moolenaar446cb832008-06-24 21:56:24 +000011892 Be careful to correctly escape special characters in
11893 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +000011894 for Vim commands, |shellescape()| for |:!| commands.
11895 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +000011896 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +010011897 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +000011898<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011899 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010011900 starting or ending "if", "while" and "for" does not
11901 always work, because when commands are skipped the
11902 ":execute" is not evaluated and Vim loses track of
11903 where blocks start and end. Also "break" and
11904 "continue" should not be inside ":execute".
11905 This example does not work, because the ":execute" is
11906 not evaluated and Vim does not see the "while", and
11907 gives an error for finding an ":endwhile": >
11908 :if 0
11909 : execute 'while i > 5'
11910 : echo "test"
11911 : endwhile
11912 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +000011913<
11914 It is allowed to have a "while" or "if" command
11915 completely in the executed string: >
11916 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
11917<
11918
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011919 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011920 ":execute", ":echo" and ":echon" cannot be followed by
11921 a comment directly, because they see the '"' as the
11922 start of a string. But, you can use '|' followed by a
11923 comment. Example: >
11924 :echo "foo" | "this is a comment
11925
11926==============================================================================
119278. Exception handling *exception-handling*
11928
11929The Vim script language comprises an exception handling feature. This section
11930explains how it can be used in a Vim script.
11931
11932Exceptions may be raised by Vim on an error or on interrupt, see
11933|catch-errors| and |catch-interrupt|. You can also explicitly throw an
11934exception by using the ":throw" command, see |throw-catch|.
11935
11936
11937TRY CONDITIONALS *try-conditionals*
11938
11939Exceptions can be caught or can cause cleanup code to be executed. You can
11940use a try conditional to specify catch clauses (that catch exceptions) and/or
11941a finally clause (to be executed for cleanup).
11942 A try conditional begins with a |:try| command and ends at the matching
11943|:endtry| command. In between, you can use a |:catch| command to start
11944a catch clause, or a |:finally| command to start a finally clause. There may
11945be none or multiple catch clauses, but there is at most one finally clause,
11946which must not be followed by any catch clauses. The lines before the catch
11947clauses and the finally clause is called a try block. >
11948
11949 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +000011950 : ...
11951 : ... TRY BLOCK
11952 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011953 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011954 : ...
11955 : ... CATCH CLAUSE
11956 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011957 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011958 : ...
11959 : ... CATCH CLAUSE
11960 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011961 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +000011962 : ...
11963 : ... FINALLY CLAUSE
11964 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011965 :endtry
11966
11967The try conditional allows to watch code for exceptions and to take the
11968appropriate actions. Exceptions from the try block may be caught. Exceptions
11969from the try block and also the catch clauses may cause cleanup actions.
11970 When no exception is thrown during execution of the try block, the control
11971is transferred to the finally clause, if present. After its execution, the
11972script continues with the line following the ":endtry".
11973 When an exception occurs during execution of the try block, the remaining
11974lines in the try block are skipped. The exception is matched against the
11975patterns specified as arguments to the ":catch" commands. The catch clause
11976after the first matching ":catch" is taken, other catch clauses are not
11977executed. The catch clause ends when the next ":catch", ":finally", or
11978":endtry" command is reached - whatever is first. Then, the finally clause
11979(if present) is executed. When the ":endtry" is reached, the script execution
11980continues in the following line as usual.
11981 When an exception that does not match any of the patterns specified by the
11982":catch" commands is thrown in the try block, the exception is not caught by
11983that try conditional and none of the catch clauses is executed. Only the
11984finally clause, if present, is taken. The exception pends during execution of
11985the finally clause. It is resumed at the ":endtry", so that commands after
11986the ":endtry" are not executed and the exception might be caught elsewhere,
11987see |try-nesting|.
11988 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +020011989remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +000011990not matched against the patterns in any of the ":catch" commands of the same
11991try conditional and none of its catch clauses is taken. If there is, however,
11992a finally clause, it is executed, and the exception pends during its
11993execution. The commands following the ":endtry" are not executed. The new
11994exception might, however, be caught elsewhere, see |try-nesting|.
11995 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +020011996thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000011997clause has been taken because of an exception from the try block or one of the
11998catch clauses, the original (pending) exception is discarded. The commands
11999following the ":endtry" are not executed, and the exception from the finally
12000clause is propagated and can be caught elsewhere, see |try-nesting|.
12001
12002The finally clause is also executed, when a ":break" or ":continue" for
12003a ":while" loop enclosing the complete try conditional is executed from the
12004try block or a catch clause. Or when a ":return" or ":finish" is executed
12005from the try block or a catch clause of a try conditional in a function or
12006sourced script, respectively. The ":break", ":continue", ":return", or
12007":finish" pends during execution of the finally clause and is resumed when the
12008":endtry" is reached. It is, however, discarded when an exception is thrown
12009from the finally clause.
12010 When a ":break" or ":continue" for a ":while" loop enclosing the complete
12011try conditional or when a ":return" or ":finish" is encountered in the finally
12012clause, the rest of the finally clause is skipped, and the ":break",
12013":continue", ":return" or ":finish" is executed as usual. If the finally
12014clause has been taken because of an exception or an earlier ":break",
12015":continue", ":return", or ":finish" from the try block or a catch clause,
12016this pending exception or command is discarded.
12017
12018For examples see |throw-catch| and |try-finally|.
12019
12020
12021NESTING OF TRY CONDITIONALS *try-nesting*
12022
12023Try conditionals can be nested arbitrarily. That is, a complete try
12024conditional can be put into the try block, a catch clause, or the finally
12025clause of another try conditional. If the inner try conditional does not
12026catch an exception thrown in its try block or throws a new exception from one
12027of its catch clauses or its finally clause, the outer try conditional is
12028checked according to the rules above. If the inner try conditional is in the
12029try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +020012030otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +000012031nesting, whether the inner try conditional is directly contained in the outer
12032one, or whether the outer one sources a script or calls a function containing
12033the inner try conditional.
12034
12035When none of the active try conditionals catches an exception, just their
12036finally clauses are executed. Thereafter, the script processing terminates.
12037An error message is displayed in case of an uncaught exception explicitly
12038thrown by a ":throw" command. For uncaught error and interrupt exceptions
12039implicitly raised by Vim, the error message(s) or interrupt message are shown
12040as usual.
12041
12042For examples see |throw-catch|.
12043
12044
12045EXAMINING EXCEPTION HANDLING CODE *except-examine*
12046
12047Exception handling code can get tricky. If you are in doubt what happens, set
12048'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
12049script file. Then you see when an exception is thrown, discarded, caught, or
12050finished. When using a verbosity level of at least 14, things pending in
12051a finally clause are also shown. This information is also given in debug mode
12052(see |debug-scripts|).
12053
12054
12055THROWING AND CATCHING EXCEPTIONS *throw-catch*
12056
12057You can throw any number or string as an exception. Use the |:throw| command
12058and pass the value to be thrown as argument: >
12059 :throw 4711
12060 :throw "string"
12061< *throw-expression*
12062You can also specify an expression argument. The expression is then evaluated
12063first, and the result is thrown: >
12064 :throw 4705 + strlen("string")
12065 :throw strpart("strings", 0, 6)
12066
12067An exception might be thrown during evaluation of the argument of the ":throw"
12068command. Unless it is caught there, the expression evaluation is abandoned.
12069The ":throw" command then does not throw a new exception.
12070 Example: >
12071
12072 :function! Foo(arg)
12073 : try
12074 : throw a:arg
12075 : catch /foo/
12076 : endtry
12077 : return 1
12078 :endfunction
12079 :
12080 :function! Bar()
12081 : echo "in Bar"
12082 : return 4710
12083 :endfunction
12084 :
12085 :throw Foo("arrgh") + Bar()
12086
12087This throws "arrgh", and "in Bar" is not displayed since Bar() is not
12088executed. >
12089 :throw Foo("foo") + Bar()
12090however displays "in Bar" and throws 4711.
12091
12092Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +020012093abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000012094exception is then propagated to the caller of the command.
12095 Example: >
12096
12097 :if Foo("arrgh")
12098 : echo "then"
12099 :else
12100 : echo "else"
12101 :endif
12102
12103Here neither of "then" or "else" is displayed.
12104
12105 *catch-order*
12106Exceptions can be caught by a try conditional with one or more |:catch|
12107commands, see |try-conditionals|. The values to be caught by each ":catch"
12108command can be specified as a pattern argument. The subsequent catch clause
12109gets executed when a matching exception is caught.
12110 Example: >
12111
12112 :function! Foo(value)
12113 : try
12114 : throw a:value
12115 : catch /^\d\+$/
12116 : echo "Number thrown"
12117 : catch /.*/
12118 : echo "String thrown"
12119 : endtry
12120 :endfunction
12121 :
12122 :call Foo(0x1267)
12123 :call Foo('string')
12124
12125The first call to Foo() displays "Number thrown", the second "String thrown".
12126An exception is matched against the ":catch" commands in the order they are
12127specified. Only the first match counts. So you should place the more
12128specific ":catch" first. The following order does not make sense: >
12129
12130 : catch /.*/
12131 : echo "String thrown"
12132 : catch /^\d\+$/
12133 : echo "Number thrown"
12134
12135The first ":catch" here matches always, so that the second catch clause is
12136never taken.
12137
12138 *throw-variables*
12139If you catch an exception by a general pattern, you may access the exact value
12140in the variable |v:exception|: >
12141
12142 : catch /^\d\+$/
12143 : echo "Number thrown. Value is" v:exception
12144
12145You may also be interested where an exception was thrown. This is stored in
12146|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
12147exception most recently caught as long it is not finished.
12148 Example: >
12149
12150 :function! Caught()
12151 : if v:exception != ""
12152 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
12153 : else
12154 : echo 'Nothing caught'
12155 : endif
12156 :endfunction
12157 :
12158 :function! Foo()
12159 : try
12160 : try
12161 : try
12162 : throw 4711
12163 : finally
12164 : call Caught()
12165 : endtry
12166 : catch /.*/
12167 : call Caught()
12168 : throw "oops"
12169 : endtry
12170 : catch /.*/
12171 : call Caught()
12172 : finally
12173 : call Caught()
12174 : endtry
12175 :endfunction
12176 :
12177 :call Foo()
12178
12179This displays >
12180
12181 Nothing caught
12182 Caught "4711" in function Foo, line 4
12183 Caught "oops" in function Foo, line 10
12184 Nothing caught
12185
12186A practical example: The following command ":LineNumber" displays the line
12187number in the script or function where it has been used: >
12188
12189 :function! LineNumber()
12190 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
12191 :endfunction
12192 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
12193<
12194 *try-nested*
12195An exception that is not caught by a try conditional can be caught by
12196a surrounding try conditional: >
12197
12198 :try
12199 : try
12200 : throw "foo"
12201 : catch /foobar/
12202 : echo "foobar"
12203 : finally
12204 : echo "inner finally"
12205 : endtry
12206 :catch /foo/
12207 : echo "foo"
12208 :endtry
12209
12210The inner try conditional does not catch the exception, just its finally
12211clause is executed. The exception is then caught by the outer try
12212conditional. The example displays "inner finally" and then "foo".
12213
12214 *throw-from-catch*
12215You can catch an exception and throw a new one to be caught elsewhere from the
12216catch clause: >
12217
12218 :function! Foo()
12219 : throw "foo"
12220 :endfunction
12221 :
12222 :function! Bar()
12223 : try
12224 : call Foo()
12225 : catch /foo/
12226 : echo "Caught foo, throw bar"
12227 : throw "bar"
12228 : endtry
12229 :endfunction
12230 :
12231 :try
12232 : call Bar()
12233 :catch /.*/
12234 : echo "Caught" v:exception
12235 :endtry
12236
12237This displays "Caught foo, throw bar" and then "Caught bar".
12238
12239 *rethrow*
12240There is no real rethrow in the Vim script language, but you may throw
12241"v:exception" instead: >
12242
12243 :function! Bar()
12244 : try
12245 : call Foo()
12246 : catch /.*/
12247 : echo "Rethrow" v:exception
12248 : throw v:exception
12249 : endtry
12250 :endfunction
12251< *try-echoerr*
12252Note that this method cannot be used to "rethrow" Vim error or interrupt
12253exceptions, because it is not possible to fake Vim internal exceptions.
12254Trying so causes an error exception. You should throw your own exception
12255denoting the situation. If you want to cause a Vim error exception containing
12256the original error exception value, you can use the |:echoerr| command: >
12257
12258 :try
12259 : try
12260 : asdf
12261 : catch /.*/
12262 : echoerr v:exception
12263 : endtry
12264 :catch /.*/
12265 : echo v:exception
12266 :endtry
12267
12268This code displays
12269
Bram Moolenaar446cb832008-06-24 21:56:24 +000012270 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012271
12272
12273CLEANUP CODE *try-finally*
12274
12275Scripts often change global settings and restore them at their end. If the
12276user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +020012277an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +000012278a script when an error occurs or you explicitly throw an exception without
12279catching it. You can solve these problems by using a try conditional with
12280a finally clause for restoring the settings. Its execution is guaranteed on
12281normal control flow, on error, on an explicit ":throw", and on interrupt.
12282(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +020012283to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000012284clause has been executed.)
12285Example: >
12286
12287 :try
12288 : let s:saved_ts = &ts
12289 : set ts=17
12290 :
12291 : " Do the hard work here.
12292 :
12293 :finally
12294 : let &ts = s:saved_ts
12295 : unlet s:saved_ts
12296 :endtry
12297
12298This method should be used locally whenever a function or part of a script
12299changes global settings which need to be restored on failure or normal exit of
12300that function or script part.
12301
12302 *break-finally*
12303Cleanup code works also when the try block or a catch clause is left by
12304a ":continue", ":break", ":return", or ":finish".
12305 Example: >
12306
12307 :let first = 1
12308 :while 1
12309 : try
12310 : if first
12311 : echo "first"
12312 : let first = 0
12313 : continue
12314 : else
12315 : throw "second"
12316 : endif
12317 : catch /.*/
12318 : echo v:exception
12319 : break
12320 : finally
12321 : echo "cleanup"
12322 : endtry
12323 : echo "still in while"
12324 :endwhile
12325 :echo "end"
12326
12327This displays "first", "cleanup", "second", "cleanup", and "end". >
12328
12329 :function! Foo()
12330 : try
12331 : return 4711
12332 : finally
12333 : echo "cleanup\n"
12334 : endtry
12335 : echo "Foo still active"
12336 :endfunction
12337 :
12338 :echo Foo() "returned by Foo"
12339
12340This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +020012341extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +000012342return value.)
12343
12344 *except-from-finally*
12345Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
12346a finally clause is possible, but not recommended since it abandons the
12347cleanup actions for the try conditional. But, of course, interrupt and error
12348exceptions might get raised from a finally clause.
12349 Example where an error in the finally clause stops an interrupt from
12350working correctly: >
12351
12352 :try
12353 : try
12354 : echo "Press CTRL-C for interrupt"
12355 : while 1
12356 : endwhile
12357 : finally
12358 : unlet novar
12359 : endtry
12360 :catch /novar/
12361 :endtry
12362 :echo "Script still running"
12363 :sleep 1
12364
12365If you need to put commands that could fail into a finally clause, you should
12366think about catching or ignoring the errors in these commands, see
12367|catch-errors| and |ignore-errors|.
12368
12369
12370CATCHING ERRORS *catch-errors*
12371
12372If you want to catch specific errors, you just have to put the code to be
12373watched in a try block and add a catch clause for the error message. The
12374presence of the try conditional causes all errors to be converted to an
12375exception. No message is displayed and |v:errmsg| is not set then. To find
12376the right pattern for the ":catch" command, you have to know how the format of
12377the error exception is.
12378 Error exceptions have the following format: >
12379
12380 Vim({cmdname}):{errmsg}
12381or >
12382 Vim:{errmsg}
12383
12384{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +020012385the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +000012386when the error occurs outside try conditionals. It always begins with
12387a capital "E", followed by a two or three-digit error number, a colon, and
12388a space.
12389
12390Examples:
12391
12392The command >
12393 :unlet novar
12394normally produces the error message >
12395 E108: No such variable: "novar"
12396which is converted inside try conditionals to an exception >
12397 Vim(unlet):E108: No such variable: "novar"
12398
12399The command >
12400 :dwim
12401normally produces the error message >
12402 E492: Not an editor command: dwim
12403which is converted inside try conditionals to an exception >
12404 Vim:E492: Not an editor command: dwim
12405
12406You can catch all ":unlet" errors by a >
12407 :catch /^Vim(unlet):/
12408or all errors for misspelled command names by a >
12409 :catch /^Vim:E492:/
12410
12411Some error messages may be produced by different commands: >
12412 :function nofunc
12413and >
12414 :delfunction nofunc
12415both produce the error message >
12416 E128: Function name must start with a capital: nofunc
12417which is converted inside try conditionals to an exception >
12418 Vim(function):E128: Function name must start with a capital: nofunc
12419or >
12420 Vim(delfunction):E128: Function name must start with a capital: nofunc
12421respectively. You can catch the error by its number independently on the
12422command that caused it if you use the following pattern: >
12423 :catch /^Vim(\a\+):E128:/
12424
12425Some commands like >
12426 :let x = novar
12427produce multiple error messages, here: >
12428 E121: Undefined variable: novar
12429 E15: Invalid expression: novar
12430Only the first is used for the exception value, since it is the most specific
12431one (see |except-several-errors|). So you can catch it by >
12432 :catch /^Vim(\a\+):E121:/
12433
12434You can catch all errors related to the name "nofunc" by >
12435 :catch /\<nofunc\>/
12436
12437You can catch all Vim errors in the ":write" and ":read" commands by >
12438 :catch /^Vim(\(write\|read\)):E\d\+:/
12439
12440You can catch all Vim errors by the pattern >
12441 :catch /^Vim\((\a\+)\)\=:E\d\+:/
12442<
12443 *catch-text*
12444NOTE: You should never catch the error message text itself: >
12445 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +010012446only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +000012447a different language by the |:language| command. It is however helpful to
12448cite the message text in a comment: >
12449 :catch /^Vim(\a\+):E108:/ " No such variable
12450
12451
12452IGNORING ERRORS *ignore-errors*
12453
12454You can ignore errors in a specific Vim command by catching them locally: >
12455
12456 :try
12457 : write
12458 :catch
12459 :endtry
12460
12461But you are strongly recommended NOT to use this simple form, since it could
12462catch more than you want. With the ":write" command, some autocommands could
12463be executed and cause errors not related to writing, for instance: >
12464
12465 :au BufWritePre * unlet novar
12466
12467There could even be such errors you are not responsible for as a script
12468writer: a user of your script might have defined such autocommands. You would
12469then hide the error from the user.
12470 It is much better to use >
12471
12472 :try
12473 : write
12474 :catch /^Vim(write):/
12475 :endtry
12476
12477which only catches real write errors. So catch only what you'd like to ignore
12478intentionally.
12479
12480For a single command that does not cause execution of autocommands, you could
12481even suppress the conversion of errors to exceptions by the ":silent!"
12482command: >
12483 :silent! nunmap k
12484This works also when a try conditional is active.
12485
12486
12487CATCHING INTERRUPTS *catch-interrupt*
12488
12489When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +020012490the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000012491script is not terminated, then.
12492 Example: >
12493
12494 :function! TASK1()
12495 : sleep 10
12496 :endfunction
12497
12498 :function! TASK2()
12499 : sleep 20
12500 :endfunction
12501
12502 :while 1
12503 : let command = input("Type a command: ")
12504 : try
12505 : if command == ""
12506 : continue
12507 : elseif command == "END"
12508 : break
12509 : elseif command == "TASK1"
12510 : call TASK1()
12511 : elseif command == "TASK2"
12512 : call TASK2()
12513 : else
12514 : echo "\nIllegal command:" command
12515 : continue
12516 : endif
12517 : catch /^Vim:Interrupt$/
12518 : echo "\nCommand interrupted"
12519 : " Caught the interrupt. Continue with next prompt.
12520 : endtry
12521 :endwhile
12522
12523You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +020012524a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012525
12526For testing what happens when CTRL-C would be pressed on a specific line in
12527your script, use the debug mode and execute the |>quit| or |>interrupt|
12528command on that line. See |debug-scripts|.
12529
12530
12531CATCHING ALL *catch-all*
12532
12533The commands >
12534
12535 :catch /.*/
12536 :catch //
12537 :catch
12538
12539catch everything, error exceptions, interrupt exceptions and exceptions
12540explicitly thrown by the |:throw| command. This is useful at the top level of
12541a script in order to catch unexpected things.
12542 Example: >
12543
12544 :try
12545 :
12546 : " do the hard work here
12547 :
12548 :catch /MyException/
12549 :
12550 : " handle known problem
12551 :
12552 :catch /^Vim:Interrupt$/
12553 : echo "Script interrupted"
12554 :catch /.*/
12555 : echo "Internal error (" . v:exception . ")"
12556 : echo " - occurred at " . v:throwpoint
12557 :endtry
12558 :" end of script
12559
12560Note: Catching all might catch more things than you want. Thus, you are
12561strongly encouraged to catch only for problems that you can really handle by
12562specifying a pattern argument to the ":catch".
12563 Example: Catching all could make it nearly impossible to interrupt a script
12564by pressing CTRL-C: >
12565
12566 :while 1
12567 : try
12568 : sleep 1
12569 : catch
12570 : endtry
12571 :endwhile
12572
12573
12574EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
12575
12576Exceptions may be used during execution of autocommands. Example: >
12577
12578 :autocmd User x try
12579 :autocmd User x throw "Oops!"
12580 :autocmd User x catch
12581 :autocmd User x echo v:exception
12582 :autocmd User x endtry
12583 :autocmd User x throw "Arrgh!"
12584 :autocmd User x echo "Should not be displayed"
12585 :
12586 :try
12587 : doautocmd User x
12588 :catch
12589 : echo v:exception
12590 :endtry
12591
12592This displays "Oops!" and "Arrgh!".
12593
12594 *except-autocmd-Pre*
12595For some commands, autocommands get executed before the main action of the
12596command takes place. If an exception is thrown and not caught in the sequence
12597of autocommands, the sequence and the command that caused its execution are
12598abandoned and the exception is propagated to the caller of the command.
12599 Example: >
12600
12601 :autocmd BufWritePre * throw "FAIL"
12602 :autocmd BufWritePre * echo "Should not be displayed"
12603 :
12604 :try
12605 : write
12606 :catch
12607 : echo "Caught:" v:exception "from" v:throwpoint
12608 :endtry
12609
12610Here, the ":write" command does not write the file currently being edited (as
12611you can see by checking 'modified'), since the exception from the BufWritePre
12612autocommand abandons the ":write". The exception is then caught and the
12613script displays: >
12614
12615 Caught: FAIL from BufWrite Auto commands for "*"
12616<
12617 *except-autocmd-Post*
12618For some commands, autocommands get executed after the main action of the
12619command has taken place. If this main action fails and the command is inside
12620an active try conditional, the autocommands are skipped and an error exception
12621is thrown that can be caught by the caller of the command.
12622 Example: >
12623
12624 :autocmd BufWritePost * echo "File successfully written!"
12625 :
12626 :try
12627 : write /i/m/p/o/s/s/i/b/l/e
12628 :catch
12629 : echo v:exception
12630 :endtry
12631
12632This just displays: >
12633
12634 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
12635
12636If you really need to execute the autocommands even when the main action
12637fails, trigger the event from the catch clause.
12638 Example: >
12639
12640 :autocmd BufWritePre * set noreadonly
12641 :autocmd BufWritePost * set readonly
12642 :
12643 :try
12644 : write /i/m/p/o/s/s/i/b/l/e
12645 :catch
12646 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
12647 :endtry
12648<
12649You can also use ":silent!": >
12650
12651 :let x = "ok"
12652 :let v:errmsg = ""
12653 :autocmd BufWritePost * if v:errmsg != ""
12654 :autocmd BufWritePost * let x = "after fail"
12655 :autocmd BufWritePost * endif
12656 :try
12657 : silent! write /i/m/p/o/s/s/i/b/l/e
12658 :catch
12659 :endtry
12660 :echo x
12661
12662This displays "after fail".
12663
12664If the main action of the command does not fail, exceptions from the
12665autocommands will be catchable by the caller of the command: >
12666
12667 :autocmd BufWritePost * throw ":-("
12668 :autocmd BufWritePost * echo "Should not be displayed"
12669 :
12670 :try
12671 : write
12672 :catch
12673 : echo v:exception
12674 :endtry
12675<
12676 *except-autocmd-Cmd*
12677For some commands, the normal action can be replaced by a sequence of
12678autocommands. Exceptions from that sequence will be catchable by the caller
12679of the command.
12680 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +020012681had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +000012682some way. >
12683
12684 :if !exists("cnt")
12685 : let cnt = 0
12686 :
12687 : autocmd BufWriteCmd * if &modified
12688 : autocmd BufWriteCmd * let cnt = cnt + 1
12689 : autocmd BufWriteCmd * if cnt % 3 == 2
12690 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12691 : autocmd BufWriteCmd * endif
12692 : autocmd BufWriteCmd * write | set nomodified
12693 : autocmd BufWriteCmd * if cnt % 3 == 0
12694 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12695 : autocmd BufWriteCmd * endif
12696 : autocmd BufWriteCmd * echo "File successfully written!"
12697 : autocmd BufWriteCmd * endif
12698 :endif
12699 :
12700 :try
12701 : write
12702 :catch /^BufWriteCmdError$/
12703 : if &modified
12704 : echo "Error on writing (file contents not changed)"
12705 : else
12706 : echo "Error after writing"
12707 : endif
12708 :catch /^Vim(write):/
12709 : echo "Error on writing"
12710 :endtry
12711
12712When this script is sourced several times after making changes, it displays
12713first >
12714 File successfully written!
12715then >
12716 Error on writing (file contents not changed)
12717then >
12718 Error after writing
12719etc.
12720
12721 *except-autocmd-ill*
12722You cannot spread a try conditional over autocommands for different events.
12723The following code is ill-formed: >
12724
12725 :autocmd BufWritePre * try
12726 :
12727 :autocmd BufWritePost * catch
12728 :autocmd BufWritePost * echo v:exception
12729 :autocmd BufWritePost * endtry
12730 :
12731 :write
12732
12733
12734EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
12735
12736Some programming languages allow to use hierarchies of exception classes or to
12737pass additional information with the object of an exception class. You can do
12738similar things in Vim.
12739 In order to throw an exception from a hierarchy, just throw the complete
12740class name with the components separated by a colon, for instance throw the
12741string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
12742 When you want to pass additional information with your exception class, add
12743it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
12744for an error when writing "myfile".
12745 With the appropriate patterns in the ":catch" command, you can catch for
12746base classes or derived classes of your hierarchy. Additional information in
12747parentheses can be cut out from |v:exception| with the ":substitute" command.
12748 Example: >
12749
12750 :function! CheckRange(a, func)
12751 : if a:a < 0
12752 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
12753 : endif
12754 :endfunction
12755 :
12756 :function! Add(a, b)
12757 : call CheckRange(a:a, "Add")
12758 : call CheckRange(a:b, "Add")
12759 : let c = a:a + a:b
12760 : if c < 0
12761 : throw "EXCEPT:MATHERR:OVERFLOW"
12762 : endif
12763 : return c
12764 :endfunction
12765 :
12766 :function! Div(a, b)
12767 : call CheckRange(a:a, "Div")
12768 : call CheckRange(a:b, "Div")
12769 : if (a:b == 0)
12770 : throw "EXCEPT:MATHERR:ZERODIV"
12771 : endif
12772 : return a:a / a:b
12773 :endfunction
12774 :
12775 :function! Write(file)
12776 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +000012777 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012778 : catch /^Vim(write):/
12779 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
12780 : endtry
12781 :endfunction
12782 :
12783 :try
12784 :
12785 : " something with arithmetics and I/O
12786 :
12787 :catch /^EXCEPT:MATHERR:RANGE/
12788 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
12789 : echo "Range error in" function
12790 :
12791 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
12792 : echo "Math error"
12793 :
12794 :catch /^EXCEPT:IO/
12795 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
12796 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
12797 : if file !~ '^/'
12798 : let file = dir . "/" . file
12799 : endif
12800 : echo 'I/O error for "' . file . '"'
12801 :
12802 :catch /^EXCEPT/
12803 : echo "Unspecified error"
12804 :
12805 :endtry
12806
12807The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
12808a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
12809exceptions with the "Vim" prefix; they are reserved for Vim.
12810 Vim error exceptions are parameterized with the name of the command that
12811failed, if known. See |catch-errors|.
12812
12813
12814PECULIARITIES
12815 *except-compat*
12816The exception handling concept requires that the command sequence causing the
12817exception is aborted immediately and control is transferred to finally clauses
12818and/or a catch clause.
12819
12820In the Vim script language there are cases where scripts and functions
12821continue after an error: in functions without the "abort" flag or in a command
12822after ":silent!", control flow goes to the following line, and outside
12823functions, control flow goes to the line following the outermost ":endwhile"
12824or ":endif". On the other hand, errors should be catchable as exceptions
12825(thus, requiring the immediate abortion).
12826
12827This problem has been solved by converting errors to exceptions and using
12828immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +020012829conditional is active. This is no restriction since an (error) exception can
12830be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +000012831termination without catching the error, just use a try conditional without
12832catch clause. (You can cause cleanup code being executed before termination
12833by specifying a finally clause.)
12834
12835When no try conditional is active, the usual abortion and continuation
12836behavior is used instead of immediate abortion. This ensures compatibility of
12837scripts written for Vim 6.1 and earlier.
12838
12839However, when sourcing an existing script that does not use exception handling
12840commands (or when calling one of its functions) from inside an active try
12841conditional of a new script, you might change the control flow of the existing
12842script on error. You get the immediate abortion on error and can catch the
12843error in the new script. If however the sourced script suppresses error
12844messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +020012845|v:errmsg| if appropriate), its execution path is not changed. The error is
12846not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +000012847where this happens is for scripts that don't care about errors and produce
12848error messages. You probably won't want to use such code from your new
12849scripts.
12850
12851 *except-syntax-err*
12852Syntax errors in the exception handling commands are never caught by any of
12853the ":catch" commands of the try conditional they belong to. Its finally
12854clauses, however, is executed.
12855 Example: >
12856
12857 :try
12858 : try
12859 : throw 4711
12860 : catch /\(/
12861 : echo "in catch with syntax error"
12862 : catch
12863 : echo "inner catch-all"
12864 : finally
12865 : echo "inner finally"
12866 : endtry
12867 :catch
12868 : echo 'outer catch-all caught "' . v:exception . '"'
12869 : finally
12870 : echo "outer finally"
12871 :endtry
12872
12873This displays: >
12874 inner finally
12875 outer catch-all caught "Vim(catch):E54: Unmatched \("
12876 outer finally
12877The original exception is discarded and an error exception is raised, instead.
12878
12879 *except-single-line*
12880The ":try", ":catch", ":finally", and ":endtry" commands can be put on
12881a single line, but then syntax errors may make it difficult to recognize the
12882"catch" line, thus you better avoid this.
12883 Example: >
12884 :try | unlet! foo # | catch | endtry
12885raises an error exception for the trailing characters after the ":unlet!"
12886argument, but does not see the ":catch" and ":endtry" commands, so that the
12887error exception is discarded and the "E488: Trailing characters" message gets
12888displayed.
12889
12890 *except-several-errors*
12891When several errors appear in a single command, the first error message is
12892usually the most specific one and therefor converted to the error exception.
12893 Example: >
12894 echo novar
12895causes >
12896 E121: Undefined variable: novar
12897 E15: Invalid expression: novar
12898The value of the error exception inside try conditionals is: >
12899 Vim(echo):E121: Undefined variable: novar
12900< *except-syntax-error*
12901But when a syntax error is detected after a normal error in the same command,
12902the syntax error is used for the exception being thrown.
12903 Example: >
12904 unlet novar #
12905causes >
12906 E108: No such variable: "novar"
12907 E488: Trailing characters
12908The value of the error exception inside try conditionals is: >
12909 Vim(unlet):E488: Trailing characters
12910This is done because the syntax error might change the execution path in a way
12911not intended by the user. Example: >
12912 try
12913 try | unlet novar # | catch | echo v:exception | endtry
12914 catch /.*/
12915 echo "outer catch:" v:exception
12916 endtry
12917This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
12918a "E600: Missing :endtry" error message is given, see |except-single-line|.
12919
12920==============================================================================
129219. Examples *eval-examples*
12922
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012923Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012924>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010012925 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012926 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012927 : let n = a:nr
12928 : let r = ""
12929 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012930 : let r = '01'[n % 2] . r
12931 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +000012932 : endwhile
12933 : return r
12934 :endfunc
12935
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012936 :" The function String2Bin() converts each character in a string to a
12937 :" binary string, separated with dashes.
12938 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012939 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012940 : for ix in range(strlen(a:str))
12941 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
12942 : endfor
12943 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +000012944 :endfunc
12945
12946Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012947 :echo Nr2Bin(32)
12948result: "100000" >
12949 :echo String2Bin("32")
12950result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +000012951
12952
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012953Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012954
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012955This example sorts lines with a specific compare function. >
12956
12957 :func SortBuffer()
12958 : let lines = getline(1, '$')
12959 : call sort(lines, function("Strcmp"))
12960 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012961 :endfunction
12962
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012963As a one-liner: >
12964 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +000012965
Bram Moolenaar071d4272004-06-13 20:20:40 +000012966
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012967scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012968 *sscanf*
12969There is no sscanf() function in Vim. If you need to extract parts from a
12970line, you can use matchstr() and substitute() to do it. This example shows
12971how to get the file name, line number and column number out of a line like
12972"foobar.txt, 123, 45". >
12973 :" Set up the match bit
12974 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
12975 :"get the part matching the whole expression
12976 :let l = matchstr(line, mx)
12977 :"get each item out of the match
12978 :let file = substitute(l, mx, '\1', '')
12979 :let lnum = substitute(l, mx, '\2', '')
12980 :let col = substitute(l, mx, '\3', '')
12981
12982The input is in the variable "line", the results in the variables "file",
12983"lnum" and "col". (idea from Michael Geddes)
12984
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012985
12986getting the scriptnames in a Dictionary ~
12987 *scriptnames-dictionary*
12988The |:scriptnames| command can be used to get a list of all script files that
12989have been sourced. There is no equivalent function or variable for this
12990(because it's rarely needed). In case you need to manipulate the list this
12991code can be used: >
12992 " Get the output of ":scriptnames" in the scriptnames_output variable.
12993 let scriptnames_output = ''
12994 redir => scriptnames_output
12995 silent scriptnames
12996 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010012997
Bram Moolenaar446cb832008-06-24 21:56:24 +000012998 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012999 " "scripts" dictionary.
13000 let scripts = {}
13001 for line in split(scriptnames_output, "\n")
13002 " Only do non-blank lines.
13003 if line =~ '\S'
13004 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +000013005 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013006 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +000013007 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013008 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +000013009 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013010 endif
13011 endfor
13012 unlet scriptnames_output
13013
Bram Moolenaar071d4272004-06-13 20:20:40 +000013014==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001301510. Vim script versions *vimscript-version* *vimscript-versions*
Bram Moolenaar911ead12019-04-21 00:03:35 +020013016 *scriptversion*
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013017Over time many features have been added to Vim script. This includes Ex
13018commands, functions, variable types, etc. Each individual feature can be
13019checked with the |has()| and |exists()| functions.
13020
13021Sometimes old syntax of functionality gets in the way of making Vim better.
13022When support is taken away this will break older Vim scripts. To make this
13023explicit the |:scriptversion| command can be used. When a Vim script is not
13024compatible with older versions of Vim this will give an explicit error,
13025instead of failing in mysterious ways. >
13026
13027 :scriptversion 1
13028< This is the original Vim script, same as not using a |:scriptversion|
13029 command. Can be used to go back to old syntax for a range of lines.
13030 Test for support with: >
13031 has('vimscript-1')
13032
13033 :scriptversion 2
Bram Moolenaar68e65602019-05-26 21:33:31 +020013034< String concatenation with "." is not supported, use ".." instead.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013035 This avoids the ambiguity using "." for Dict member access and
13036 floating point numbers. Now ".5" means the number 0.5.
Bram Moolenaar911ead12019-04-21 00:03:35 +020013037>
13038 :scriptversion 3
13039< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't
13040 work as |v:version| anymore, it can be used as a normal variable.
13041 Same for some obvious names as "count" and others.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013042
Bram Moolenaar911ead12019-04-21 00:03:35 +020013043 Test for support with: >
13044 has('vimscript-3')
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020013045
13046==============================================================================
1304711. No +eval feature *no-eval-feature*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013048
13049When the |+eval| feature was disabled at compile time, none of the expression
13050evaluation commands are available. To prevent this from causing Vim scripts
13051to generate all kinds of errors, the ":if" and ":endif" commands are still
13052recognized, though the argument of the ":if" and everything between the ":if"
13053and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
13054only if the commands are at the start of the line. The ":else" command is not
13055recognized.
13056
13057Example of how to avoid executing commands when the |+eval| feature is
13058missing: >
13059
13060 :if 1
13061 : echo "Expression evaluation is compiled in"
13062 :else
13063 : echo "You will _never_ see this message"
13064 :endif
13065
Bram Moolenaar773a97c2019-06-06 20:39:55 +020013066To execute a command only when the |+eval| feature is disabled can be done in
13067two ways. The simplest is to exit the script (or Vim) prematurely: >
13068 if 1
13069 echo "commands executed with +eval"
13070 finish
13071 endif
13072 args " command executed without +eval
13073
13074If you do not want to abort loading the script you can use a trick, as this
13075example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +020013076
13077 silent! while 0
13078 set history=111
13079 silent! endwhile
13080
13081When the |+eval| feature is available the command is skipped because of the
13082"while 0". Without the |+eval| feature the "while 0" is an error, which is
13083silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020013084
Bram Moolenaar071d4272004-06-13 20:20:40 +000013085==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001308612. The sandbox *eval-sandbox* *sandbox* *E48*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013087
Bram Moolenaar368373e2010-07-19 20:46:22 +020013088The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
13089'foldtext' options may be evaluated in a sandbox. This means that you are
13090protected from these expressions having nasty side effects. This gives some
13091safety for when these options are set from a modeline. It is also used when
13092the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000013093The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013094
13095These items are not allowed in the sandbox:
13096 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +020013097 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000013098 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013099 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013100 - executing a shell command
13101 - reading or writing a file
13102 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000013103 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000013104This is not guaranteed 100% secure, but it should block most attacks.
13105
13106 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000013107:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000013108 option that may have been set from a modeline, e.g.
13109 'foldexpr'.
13110
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013111 *sandbox-option*
13112A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000013113have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013114restrictive, thus this only happens when the option was set from an insecure
13115location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000013116- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013117- while executing in the sandbox
13118- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +020013119- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013120
13121Note that when in the sandbox and saving an option value and restoring it, the
13122option will still be marked as it was set in the sandbox.
13123
13124==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001312513. Textlock *textlock*
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013126
13127In a few situations it is not allowed to change the text in the buffer, jump
13128to another window and some other things that might confuse or break what Vim
13129is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +020013130actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000013131happen any moment the mouse cursor is resting at some position.
13132
13133This is not allowed when the textlock is active:
13134 - changing the buffer text
13135 - jumping to another buffer or window
13136 - editing another file
13137 - closing a window or quitting Vim
13138 - etc.
13139
Bram Moolenaardc1f1642016-08-16 18:33:43 +020013140==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001314114. Testing *testing*
Bram Moolenaardc1f1642016-08-16 18:33:43 +020013142
13143Vim can be tested after building it, usually with "make test".
13144The tests are located in the directory "src/testdir".
13145
13146There are several types of tests added over time:
13147 test33.in oldest, don't add any more
13148 test_something.in old style tests
13149 test_something.vim new style tests
13150
13151 *new-style-testing*
13152New tests should be added as new style tests. These use functions such as
13153|assert_equal()| to keep the test commands and the expected result in one
13154place.
13155 *old-style-testing*
13156In some cases an old style test needs to be used. E.g. when testing Vim
13157without the |+eval| feature.
13158
13159Find more information in the file src/testdir/README.txt.
13160
Bram Moolenaar071d4272004-06-13 20:20:40 +000013161
Bram Moolenaar91f84f62018-07-29 15:07:52 +020013162 vim:tw=78:ts=8:noet:ft=help:norl: