blob: e1ce00fa638b98ebb49507f2af6a901ee66257f4 [file] [log] [blame]
Bram Moolenaarac9fb182019-04-27 13:04:13 +02001*eval.txt* For Vim version 8.1. Last change: 2019 Apr 27
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
36{Vi does not have any of these commands}
37
38==============================================================================
391. Variables *variables*
40
Bram Moolenaar13065c42005-01-08 16:08:21 +0000411.1 Variable types ~
Bram Moolenaarbf821bc2019-01-23 21:15:02 +010042 *E712* *E896* *E897* *E899*
Bram Moolenaar38a55632016-02-15 22:07:32 +010043There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000044
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020045Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020046 64-bit Numbers are available only when compiled with the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020047 |+num64| feature.
Bram Moolenaar7571d552016-08-18 22:54:46 +020048 Examples: -123 0x10 0177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000049
Bram Moolenaar446cb832008-06-24 21:56:24 +000050Float A floating point number. |floating-point-format| *Float*
51 {only when compiled with the |+float| feature}
52 Examples: 123.456 1.15e-6 -1.1e3
53
Bram Moolenaar06481422016-04-30 15:13:38 +020054 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000055String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000056 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000057
Bram Moolenaard8968242019-01-15 22:51:57 +010058List An ordered sequence of items, see |List| for details.
Bram Moolenaard8b02732005-01-14 21:48:43 +000059 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000061Dictionary An associative, unordered array: Each entry has a key and a
62 value. |Dictionary|
63 Example: {'blue': "#0000ff", 'red': "#ff0000"}
64
Bram Moolenaar835dc632016-02-07 14:27:38 +010065Funcref A reference to a function |Funcref|.
66 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020067 It can be bound to a dictionary and arguments, it then works
68 like a Partial.
69 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010070
Bram Moolenaar02e83b42016-02-21 20:10:26 +010071Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010072
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020073Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010074
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020075Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010076
Bram Moolenaard8968242019-01-15 22:51:57 +010077Blob Binary Large Object. Stores any sequence of bytes. See |Blob|
78 for details
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010079 Example: 0zFF00ED015DAF
80 0z is an empty Blob.
81
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000082The Number and String types are converted automatically, depending on how they
83are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000084
85Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020086the Number. Examples:
87 Number 123 --> String "123" ~
88 Number 0 --> String "0" ~
89 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020090 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010091Conversion from a String to a Number is done by converting the first digits to
92a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
93recognized. If the String doesn't start with digits, the result is zero.
94Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020095 String "456" --> Number 456 ~
96 String "6bar" --> Number 6 ~
97 String "foo" --> Number 0 ~
98 String "0xf1" --> Number 241 ~
99 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +0100100 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200101 String "-8" --> Number -8 ~
102 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000103
104To force conversion from String to Number, add zero to it: >
105 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000106< 64 ~
107
108To avoid a leading zero to cause octal conversion, or for using a different
109base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000110
Bram Moolenaard09091d2019-01-17 16:07:22 +0100111 *TRUE* *FALSE* *Boolean*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000112For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200113You can also use |v:false| and |v:true|. When TRUE is returned from a
114function it is the Number one, FALSE is the number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000115
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200116Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000117 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200118 :" NOT executed
119"foo" is converted to 0, which means FALSE. If the string starts with a
120non-zero number it means TRUE: >
121 :if "8foo"
122 :" executed
123To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200124 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100125<
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200126 *non-zero-arg*
127Function arguments often behave slightly different from |TRUE|: If the
128argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200129non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100130Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
131A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200132
Bram Moolenaar38a55632016-02-15 22:07:32 +0100133 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +0100134 *E974* *E975* *E976*
Bram Moolenaard09091d2019-01-17 16:07:22 +0100135|List|, |Dictionary|, |Funcref|, |Job|, |Channel| and |Blob| types are not
136automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000137
Bram Moolenaar446cb832008-06-24 21:56:24 +0000138 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200139When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000140there is no automatic conversion of Float. You can use str2float() for String
141to Float, printf() for Float to String and float2nr() for Float to Number.
142
Bram Moolenaar38a55632016-02-15 22:07:32 +0100143 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100144When expecting a Float a Number can also be used, but nothing else.
145
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100146 *no-type-checking*
147You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000148
Bram Moolenaar13065c42005-01-08 16:08:21 +0000149
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001501.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000151 *Funcref* *E695* *E718*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200152A Funcref variable is obtained with the |function()| function, the |funcref()|
153function or created with the lambda expression |expr-lambda|. It can be used
154in an expression in the place of a function name, before the parenthesis
155around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000156
157 :let Fn = function("MyFunc")
158 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000159< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000160A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200161can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000162cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000163
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000164A special case is defining a function and directly assigning its Funcref to a
165Dictionary entry. Example: >
166 :function dict.init() dict
167 : let self.val = 0
168 :endfunction
169
170The key of the Dictionary can start with a lower case letter. The actual
171function name is not used here. Also see |numbered-function|.
172
173A Funcref can also be used with the |:call| command: >
174 :call Fn()
175 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000176
177The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000178 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000179
180You can use |call()| to invoke a Funcref and use a list variable for the
181arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000182 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200183<
184 *Partial*
185A Funcref optionally binds a Dictionary and/or arguments. This is also called
186a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200187function() or funcref(). When calling the function the Dictionary and/or
188arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200189
190 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100191 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200192
193This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100194 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200195
196This is very useful when passing a function around, e.g. in the arguments of
197|ch_open()|.
198
199Note that binding a function to a Dictionary also happens when the function is
200a member of the Dictionary: >
201
202 let myDict.myFunction = MyFunction
203 call myDict.myFunction()
204
205Here MyFunction() will get myDict passed as "self". This happens when the
206"myFunction" member is accessed. When making assigning "myFunction" to
207otherDict and calling it, it will be bound to otherDict: >
208
209 let otherDict.myFunction = myDict.myFunction
210 call otherDict.myFunction()
211
212Now "self" will be "otherDict". But when the dictionary was bound explicitly
213this won't happen: >
214
215 let myDict.myFunction = function(MyFunction, myDict)
216 let otherDict.myFunction = myDict.myFunction
217 call otherDict.myFunction()
218
Bram Moolenaard823fa92016-08-12 16:29:27 +0200219Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000220
221
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002221.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200223 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000224A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200225can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000226position in the sequence.
227
Bram Moolenaar13065c42005-01-08 16:08:21 +0000228
229List creation ~
230 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000231A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000232Examples: >
233 :let mylist = [1, two, 3, "four"]
234 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000235
Bram Moolenaar58b85342016-08-14 19:54:54 +0200236An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000237List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000238 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000239
240An extra comma after the last item is ignored.
241
Bram Moolenaar13065c42005-01-08 16:08:21 +0000242
243List index ~
244 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000245An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000246after the List. Indexes are zero-based, thus the first item has index zero. >
247 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000248 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000249
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000250When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000251 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000252<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000253A negative index is counted from the end. Index -1 refers to the last item in
254the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000255 :let last = mylist[-1] " get the last item: "four"
256
Bram Moolenaar13065c42005-01-08 16:08:21 +0000257To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000258is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000259 :echo get(mylist, idx)
260 :echo get(mylist, idx, "NONE")
261
262
263List concatenation ~
264
265Two lists can be concatenated with the "+" operator: >
266 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000267 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000268
269To prepend or append an item turn the item into a list by putting [] around
270it. To change a list in-place see |list-modification| below.
271
272
273Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200274 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000275A part of the List can be obtained by specifying the first and last index,
276separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000277 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000278
279Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000280similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000281 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
282 :let shortlist = mylist[2:2] " List with one item: [3]
283 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000284
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000285If the first index is beyond the last item of the List or the second item is
286before the first item, the result is an empty list. There is no error
287message.
288
289If the second index is equal to or greater than the length of the list the
290length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000291 :let mylist = [0, 1, 2, 3]
292 :echo mylist[2:8] " result: [2, 3]
293
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000294NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200295using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000296mylist[s : e].
297
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000298
Bram Moolenaar13065c42005-01-08 16:08:21 +0000299List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000300 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000301When variable "aa" is a list and you assign it to another variable "bb", both
302variables refer to the same list. Thus changing the list "aa" will also
303change "bb": >
304 :let aa = [1, 2, 3]
305 :let bb = aa
306 :call add(aa, 4)
307 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000308< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000309
310Making a copy of a list is done with the |copy()| function. Using [:] also
311works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000312a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000313 :let aa = [[1, 'a'], 2, 3]
314 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000315 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000316 :let aa[0][1] = 'aaa'
317 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000318< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000319 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000320< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000321
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000322To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000323copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000324
325The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000326List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000327the same value. >
328 :let alist = [1, 2, 3]
329 :let blist = [1, 2, 3]
330 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000331< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000332 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000333< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000334
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000335Note about comparing lists: Two lists are considered equal if they have the
336same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000337exception: When comparing a number with a string they are considered
338different. There is no automatic type conversion, as with using "==" on
339variables. Example: >
340 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000341< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000342 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000343< 0
344
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000345Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000346can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000347
348 :let a = 5
349 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000350 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000351< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000352 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000353< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000354
Bram Moolenaar13065c42005-01-08 16:08:21 +0000355
356List unpack ~
357
358To unpack the items in a list to individual variables, put the variables in
359square brackets, like list items: >
360 :let [var1, var2] = mylist
361
362When the number of variables does not match the number of items in the list
363this produces an error. To handle any extra items from the list append ";"
364and a variable name: >
365 :let [var1, var2; rest] = mylist
366
367This works like: >
368 :let var1 = mylist[0]
369 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000370 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000371
372Except that there is no error if there are only two items. "rest" will be an
373empty list then.
374
375
376List modification ~
377 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000378To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000379 :let list[4] = "four"
380 :let listlist[0][3] = item
381
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000382To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000383modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000384 :let list[3:5] = [3, 4, 5]
385
Bram Moolenaar13065c42005-01-08 16:08:21 +0000386Adding and removing items from a list is done with functions. Here are a few
387examples: >
388 :call insert(list, 'a') " prepend item 'a'
389 :call insert(list, 'a', 3) " insert item 'a' before list[3]
390 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000391 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000392 :call extend(list, [1, 2]) " extend the list with two more items
393 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000394 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000395 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000396 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000397 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000398
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000400 :call sort(list) " sort a list alphabetically
401 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100402 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000403
Bram Moolenaar13065c42005-01-08 16:08:21 +0000404
405For loop ~
406
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000407The |:for| loop executes commands for each item in a list. A variable is set
408to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000409 :for item in mylist
410 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000411 :endfor
412
413This works like: >
414 :let index = 0
415 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000416 : let item = mylist[index]
417 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000418 : let index = index + 1
419 :endwhile
420
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000421If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000422function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000423
Bram Moolenaar58b85342016-08-14 19:54:54 +0200424Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000425requires the argument to be a list of lists. >
426 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
427 : call Doit(lnum, col)
428 :endfor
429
430This works like a |:let| command is done for each list item. Again, the types
431must remain the same to avoid an error.
432
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000433It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000434 :for [i, j; rest] in listlist
435 : call Doit(i, j)
436 : if !empty(rest)
437 : echo "remainder: " . string(rest)
438 : endif
439 :endfor
440
441
442List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000443 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000444Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000445 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000446 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000447 :let l = len(list) " number of items in list
448 :let big = max(list) " maximum value in list
449 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000450 :let xs = count(list, 'x') " count nr of times 'x' appears in list
451 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000452 :let lines = getline(1, 10) " get ten text lines from buffer
453 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000454 :let list = split("a b c") " create list from items in a string
455 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000456 :let s = string(list) " String representation of list
457 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000458
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000459Don't forget that a combination of features can make things simple. For
460example, to add up all the numbers in a list: >
461 :exe 'let sum = ' . join(nrlist, '+')
462
Bram Moolenaar13065c42005-01-08 16:08:21 +0000463
Bram Moolenaard8b02732005-01-14 21:48:43 +00004641.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100465 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000466A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000467entry can be located with the key. The entries are stored without a specific
468ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000469
470
471Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000472 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000473A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000474braces. Each entry has a key and a value, separated by a colon. Each key can
475only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000476 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
477 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000478< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000479A key is always a String. You can use a Number, it will be converted to a
480String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200481entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar03413f42016-04-12 21:07:15 +0200482Number will be converted to the String '4'. The empty string can be used as a
483key.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000484
Bram Moolenaar58b85342016-08-14 19:54:54 +0200485A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000486nested Dictionary: >
487 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
488
489An extra comma after the last entry is ignored.
490
491
492Accessing entries ~
493
494The normal way to access an entry is by putting the key in square brackets: >
495 :let val = mydict["one"]
496 :let mydict["four"] = 4
497
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000498You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000499
500For keys that consist entirely of letters, digits and underscore the following
501form can be used |expr-entry|: >
502 :let val = mydict.one
503 :let mydict.four = 4
504
505Since an entry can be any type, also a List and a Dictionary, the indexing and
506key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000507 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000508
509
510Dictionary to List conversion ~
511
Bram Moolenaar58b85342016-08-14 19:54:54 +0200512You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000513turn the Dictionary into a List and pass it to |:for|.
514
515Most often you want to loop over the keys, using the |keys()| function: >
516 :for key in keys(mydict)
517 : echo key . ': ' . mydict[key]
518 :endfor
519
520The List of keys is unsorted. You may want to sort them first: >
521 :for key in sort(keys(mydict))
522
523To loop over the values use the |values()| function: >
524 :for v in values(mydict)
525 : echo "value: " . v
526 :endfor
527
528If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100529a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000530 :for [key, value] in items(mydict)
531 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000532 :endfor
533
534
535Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000536 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000537Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
538Dictionary. Otherwise, assignment results in referring to the same
539Dictionary: >
540 :let onedict = {'a': 1, 'b': 2}
541 :let adict = onedict
542 :let adict['a'] = 11
543 :echo onedict['a']
544 11
545
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000546Two Dictionaries compare equal if all the key-value pairs compare equal. For
547more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000548
549
550Dictionary modification ~
551 *dict-modification*
552To change an already existing entry of a Dictionary, or to add a new entry,
553use |:let| this way: >
554 :let dict[4] = "four"
555 :let dict['one'] = item
556
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000557Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
558Three ways to remove the entry with key "aaa" from dict: >
559 :let i = remove(dict, 'aaa')
560 :unlet dict.aaa
561 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000562
563Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000564 :call extend(adict, bdict)
565This extends adict with all entries from bdict. Duplicate keys cause entries
566in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000567Note that the order of entries in a Dictionary is irrelevant, thus don't
568expect ":echo adict" to show the items from bdict after the older entries in
569adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000570
571Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000572 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000573This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000574
575
576Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100577 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000578When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200579special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000580 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000581 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000582 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000583 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
584 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000585
586This is like a method in object oriented programming. The entry in the
587Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
588the function was invoked from.
589
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000590It is also possible to add a function without the "dict" attribute as a
591Funcref to a Dictionary, but the "self" variable is not available then.
592
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000593 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000594To avoid the extra name for the function it can be defined and directly
595assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000596 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200597 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000598 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000599 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000600 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000601
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000602The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200603that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000604|Funcref|. It will automatically be deleted when there is no |Funcref|
605remaining that refers to it.
606
607It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000608
Bram Moolenaar1affd722010-08-04 17:49:30 +0200609If you get an error for a numbered function, you can find out what it is with
610a trick. Assuming the function is 42, the command is: >
611 :function {42}
612
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000613
614Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000615 *E715*
616Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000617 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
618 :if empty(dict) " TRUE if dict is empty
619 :let l = len(dict) " number of items in dict
620 :let big = max(dict) " maximum value in dict
621 :let small = min(dict) " minimum value in dict
622 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
623 :let s = string(dict) " String representation of dict
624 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000625
626
Bram Moolenaard8968242019-01-15 22:51:57 +01006271.5 Blobs ~
628 *blob* *Blob* *Blobs* *E978*
Bram Moolenaaraff74912019-03-30 18:11:49 +0100629A Blob is a binary object. It can be used to read an image from a file and
630send it over a channel, for example.
631
632A Blob mostly behaves like a |List| of numbers, where each number has the
633value of an 8-bit byte, from 0 to 255.
Bram Moolenaard8968242019-01-15 22:51:57 +0100634
635
636Blob creation ~
637
638A Blob can be created with a |blob-literal|: >
639 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100640Dots can be inserted between bytes (pair of hex characters) for readability,
641they don't change the value: >
642 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100643
644A blob can be read from a file with |readfile()| passing the {type} argument
645set to "B", for example: >
646 :let b = readfile('image.png', 'B')
647
648A blob can be read from a channel with the |ch_readblob()| function.
649
650
651Blob index ~
652 *blob-index* *E979*
653A byte in the Blob can be accessed by putting the index in square brackets
654after the Blob. Indexes are zero-based, thus the first byte has index zero. >
655 :let myblob = 0z00112233
656 :let byte = myblob[0] " get the first byte: 0x00
657 :let byte = myblob[2] " get the third byte: 0x22
658
659A negative index is counted from the end. Index -1 refers to the last byte in
660the Blob, -2 to the last but one byte, etc. >
661 :let last = myblob[-1] " get the last byte: 0x33
662
663To avoid an error for an invalid index use the |get()| function. When an item
664is not available it returns -1 or the default value you specify: >
665 :echo get(myblob, idx)
666 :echo get(myblob, idx, 999)
667
668
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100669Blob iteration ~
670
671The |:for| loop executes commands for each byte of a Blob. The loop variable is
672set to each byte in the Blob. Example: >
673 :for byte in 0z112233
674 : call Doit(byte)
675 :endfor
676This calls Doit() with 0x11, 0x22 and 0x33.
677
678
Bram Moolenaard8968242019-01-15 22:51:57 +0100679Blob concatenation ~
680
681Two blobs can be concatenated with the "+" operator: >
682 :let longblob = myblob + 0z4455
683 :let myblob += 0z6677
684
685To change a blob in-place see |blob-modification| below.
686
687
688Part of a blob ~
689
690A part of the Blob can be obtained by specifying the first and last index,
691separated by a colon in square brackets: >
692 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100693 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100694 :let shortblob = myblob[2:-1] " get 0z2233
695
696Omitting the first index is similar to zero. Omitting the last index is
697similar to -1. >
698 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
699 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
700 :let otherblob = myblob[:] " make a copy of the Blob
701
Bram Moolenaard09091d2019-01-17 16:07:22 +0100702If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100703before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100704message.
705
706If the second index is equal to or greater than the length of the list the
707length minus one is used: >
708 :echo myblob[2:8] " result: 0z2233
709
710
711Blob modification ~
712 *blob-modification*
713To change a specific byte of a blob use |:let| this way: >
714 :let blob[4] = 0x44
715
716When the index is just one beyond the end of the Blob, it is appended. Any
717higher index is an error.
718
719To change a sequence of bytes the [:] notation can be used: >
720 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100721The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100722provided. *E972*
723
724To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100725modified. The value must have the same number of bytes in the range: >
726 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100727
728You can also use the functions |add()|, |remove()| and |insert()|.
729
730
731Blob identity ~
732
733Blobs can be compared for equality: >
734 if blob == 0z001122
735And for equal identity: >
736 if blob is otherblob
737< *blob-identity* *E977*
738When variable "aa" is a Blob and you assign it to another variable "bb", both
739variables refer to the same Blob. Then the "is" operator returns true.
740
741When making a copy using [:] or |copy()| the values are the same, but the
742identity is different: >
743 :let blob = 0z112233
744 :let blob2 = blob
745 :echo blob == blob2
746< 1 >
747 :echo blob is blob2
748< 1 >
749 :let blob3 = blob[:]
750 :echo blob == blob3
751< 1 >
752 :echo blob is blob3
753< 0
754
Bram Moolenaard09091d2019-01-17 16:07:22 +0100755Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100756works, as explained above.
757
758
7591.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000760 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000761If you need to know the type of a variable or expression, use the |type()|
762function.
763
764When the '!' flag is included in the 'viminfo' option, global variables that
765start with an uppercase letter, and don't contain a lowercase letter, are
766stored in the viminfo file |viminfo-file|.
767
768When the 'sessionoptions' option contains "global", global variables that
769start with an uppercase letter and contain at least one lowercase letter are
770stored in the session file |session-file|.
771
772variable name can be stored where ~
773my_var_6 not
774My_Var_6 session file
775MY_VAR_6 viminfo file
776
777
778It's possible to form a variable name with curly braces, see
779|curly-braces-names|.
780
781==============================================================================
7822. Expression syntax *expression-syntax*
783
784Expression syntax summary, from least to most significant:
785
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200786|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200787 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000788
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200789|expr2| expr3
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200790 expr3 || expr3 ... logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000791
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200792|expr3| expr4
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200793 expr4 && expr4 ... logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000794
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200795|expr4| expr5
796 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797 expr5 != expr5 not equal
798 expr5 > expr5 greater than
799 expr5 >= expr5 greater than or equal
800 expr5 < expr5 smaller than
801 expr5 <= expr5 smaller than or equal
802 expr5 =~ expr5 regexp matches
803 expr5 !~ expr5 regexp doesn't match
804
805 expr5 ==? expr5 equal, ignoring case
806 expr5 ==# expr5 equal, match case
807 etc. As above, append ? for ignoring case, # for
808 matching case
809
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100810 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
811 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
812 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000813
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200814|expr5| expr6
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200815 expr6 + expr6 ... number addition, list or blob concatenation
816 expr6 - expr6 ... number subtraction
817 expr6 . expr6 ... string concatenation
818 expr6 .. expr6 ... string concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000819
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200820|expr6| expr7
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200821 expr7 * expr7 ... number multiplication
822 expr7 / expr7 ... number division
823 expr7 % expr7 ... number modulo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200825|expr7| expr8
826 ! expr7 logical NOT
Bram Moolenaar071d4272004-06-13 20:20:40 +0000827 - expr7 unary minus
828 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000829
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200830|expr8| expr9
831 expr8[expr1] byte of a String or item of a |List|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000832 expr8[expr1 : expr1] substring of a String or sublist of a |List|
833 expr8.name entry in a |Dictionary|
834 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000835
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200836|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000837 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000838 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000839 [expr1, ...] |List|
840 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000841 &option option value
842 (expr1) nested expression
843 variable internal variable
844 va{ria}ble internal variable with curly braces
845 $VAR environment variable
846 @r contents of register 'r'
847 function(expr1, ...) function call
848 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar069c1e72016-07-15 21:25:08 +0200849 {args -> expr1} lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850
851
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200852"..." indicates that the operations in this level can be concatenated.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000853Example: >
854 &nu || &list && &shell == "csh"
855
856All expressions within one level are parsed from left to right.
857
858
859expr1 *expr1* *E109*
860-----
861
862expr2 ? expr1 : expr1
863
864The expression before the '?' is evaluated to a number. If it evaluates to
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200865|TRUE|, the result is the value of the expression between the '?' and ':',
Bram Moolenaar071d4272004-06-13 20:20:40 +0000866otherwise the result is the value of the expression after the ':'.
867Example: >
868 :echo lnum == 1 ? "top" : lnum
869
870Since the first expression is an "expr2", it cannot contain another ?:. The
871other two expressions can, thus allow for recursive use of ?:.
872Example: >
873 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
874
875To keep this readable, using |line-continuation| is suggested: >
876 :echo lnum == 1
877 :\ ? "top"
878 :\ : lnum == 1000
879 :\ ? "last"
880 :\ : lnum
881
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000882You should always put a space before the ':', otherwise it can be mistaken for
883use in a variable such as "a:1".
884
Bram Moolenaar071d4272004-06-13 20:20:40 +0000885
886expr2 and expr3 *expr2* *expr3*
887---------------
888
Bram Moolenaar04186092016-08-29 21:55:35 +0200889expr3 || expr3 .. logical OR *expr-barbar*
890expr4 && expr4 .. logical AND *expr-&&*
891
Bram Moolenaar071d4272004-06-13 20:20:40 +0000892The "||" and "&&" operators take one argument on each side. The arguments
893are (converted to) Numbers. The result is:
894
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200895 input output ~
896n1 n2 n1 || n2 n1 && n2 ~
897|FALSE| |FALSE| |FALSE| |FALSE|
898|FALSE| |TRUE| |TRUE| |FALSE|
899|TRUE| |FALSE| |TRUE| |FALSE|
900|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000901
902The operators can be concatenated, for example: >
903
904 &nu || &list && &shell == "csh"
905
906Note that "&&" takes precedence over "||", so this has the meaning of: >
907
908 &nu || (&list && &shell == "csh")
909
910Once the result is known, the expression "short-circuits", that is, further
911arguments are not evaluated. This is like what happens in C. For example: >
912
913 let a = 1
914 echo a || b
915
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200916This is valid even if there is no variable called "b" because "a" is |TRUE|,
917so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000918
919 echo exists("b") && b == "yes"
920
921This is valid whether "b" has been defined or not. The second clause will
922only be evaluated if "b" has been defined.
923
924
925expr4 *expr4*
926-----
927
928expr5 {cmp} expr5
929
930Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
931if it evaluates to true.
932
Bram Moolenaar446cb832008-06-24 21:56:24 +0000933 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000934 *expr-<* *expr-<=* *expr-=~* *expr-!~*
935 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
936 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
937 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
938 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200939 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
940 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000941 use 'ignorecase' match case ignore case ~
942equal == ==# ==?
943not equal != !=# !=?
944greater than > ># >?
945greater than or equal >= >=# >=?
946smaller than < <# <?
947smaller than or equal <= <=# <=?
948regexp matches =~ =~# =~?
949regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200950same instance is is# is?
951different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000952
953Examples:
954"abc" ==# "Abc" evaluates to 0
955"abc" ==? "Abc" evaluates to 1
956"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
957
Bram Moolenaar13065c42005-01-08 16:08:21 +0000958 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +0100959A |List| can only be compared with a |List| and only "equal", "not equal",
960"is" and "isnot" can be used. This compares the values of the list,
961recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000962
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000963 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000964A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +0100965equal", "is" and "isnot" can be used. This compares the key/values of the
966|Dictionary| recursively. Ignoring case means case is ignored when comparing
967item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000968
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200969 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +0200970A |Funcref| can only be compared with a |Funcref| and only "equal", "not
971equal", "is" and "isnot" can be used. Case is never ignored. Whether
972arguments or a Dictionary are bound (with a partial) matters. The
973Dictionaries must also be equal (or the same, in case of "is") and the
974arguments must be equal (or the same).
975
976To compare Funcrefs to see if they refer to the same function, ignoring bound
977Dictionary and arguments, use |get()| to get the function name: >
978 if get(Part1, 'name') == get(Part2, 'name')
979 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000980
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100981Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
982the expressions are referring to the same |List|, |Dictionary| or |Blob|
983instance. A copy of a |List| is different from the original |List|. When
984using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
985using "equal", using "isnot" equivalent to using "not equal". Except that
986a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100987 echo 4 == '4'
988 1
989 echo 4 is '4'
990 0
991 echo 0 is []
992 0
993"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000994
Bram Moolenaar071d4272004-06-13 20:20:40 +0000995When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar58b85342016-08-14 19:54:54 +0200996and the comparison is done on Numbers. This means that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100997 echo 0 == 'x'
998 1
999because 'x' converted to a Number is zero. However: >
1000 echo [0] == ['x']
1001 0
1002Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001003
1004When comparing two Strings, this is done with strcmp() or stricmp(). This
1005results in the mathematical difference (comparing byte values), not
1006necessarily the alphabetical difference in the local language.
1007
Bram Moolenaar446cb832008-06-24 21:56:24 +00001008When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001009'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001010
1011When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001012'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1013
1014'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001015
1016The "=~" and "!~" operators match the lefthand argument with the righthand
1017argument, which is used as a pattern. See |pattern| for what a pattern is.
1018This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1019matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1020portable. To avoid backslashes in the regexp pattern to be doubled, use a
1021single-quote string, see |literal-string|.
1022Since a string is considered to be a single line, a multi-line pattern
1023(containing \n, backslash-n) will not match. However, a literal NL character
1024can be matched like an ordinary character. Examples:
1025 "foo\nbar" =~ "\n" evaluates to 1
1026 "foo\nbar" =~ "\\n" evaluates to 0
1027
1028
1029expr5 and expr6 *expr5* *expr6*
1030---------------
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001031expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+*
1032expr6 - expr6 Number subtraction *expr--*
1033expr6 . expr6 String concatenation *expr-.*
1034expr6 .. expr6 String concatenation *expr-..*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001035
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001036For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001037result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001038
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001039For String concatenation ".." is preferred, since "." is ambiguous, it is also
1040used for |Dict| member access and floating point numbers.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001041When |vimscript-version| is 2 or higher, using "." is not allowed.
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001042
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001043expr7 * expr7 Number multiplication *expr-star*
1044expr7 / expr7 Number division *expr-/*
1045expr7 % expr7 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001046
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02001047For all, except "." and "..", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001048For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001049
1050Note the difference between "+" and ".":
1051 "123" + "456" = 579
1052 "123" . "456" = "123456"
1053
Bram Moolenaar446cb832008-06-24 21:56:24 +00001054Since '.' has the same precedence as '+' and '-', you need to read: >
1055 1 . 90 + 90.0
1056As: >
1057 (1 . 90) + 90.0
1058That works, since the String "190" is automatically converted to the Number
1059190, which can be added to the Float 90.0. However: >
1060 1 . 90 * 90.0
1061Should be read as: >
1062 1 . (90 * 90.0)
1063Since '.' has lower precedence than '*'. This does NOT work, since this
1064attempts to concatenate a Float and a String.
1065
1066When dividing a Number by zero the result depends on the value:
1067 0 / 0 = -0x80000000 (like NaN for Float)
1068 >0 / 0 = 0x7fffffff (like positive infinity)
1069 <0 / 0 = -0x7fffffff (like negative infinity)
1070 (before Vim 7.2 it was always 0x7fffffff)
1071
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001072When 64-bit Number support is enabled:
1073 0 / 0 = -0x8000000000000000 (like NaN for Float)
1074 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1075 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1076
Bram Moolenaar071d4272004-06-13 20:20:40 +00001077When the righthand side of '%' is zero, the result is 0.
1078
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001079None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001080
Bram Moolenaar446cb832008-06-24 21:56:24 +00001081. and % do not work for Float. *E804*
1082
Bram Moolenaar071d4272004-06-13 20:20:40 +00001083
1084expr7 *expr7*
1085-----
1086! expr7 logical NOT *expr-!*
1087- expr7 unary minus *expr-unary--*
1088+ expr7 unary plus *expr-unary-+*
1089
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001090For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001091For '-' the sign of the number is changed.
1092For '+' the number is unchanged.
1093
1094A String will be converted to a Number first.
1095
Bram Moolenaar58b85342016-08-14 19:54:54 +02001096These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001097 !-1 == 0
1098 !!8 == 1
1099 --9 == 9
1100
1101
1102expr8 *expr8*
1103-----
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001104This expression is either |expr9| or a sequence of the alternatives below,
1105in any order. E.g., these are all possible:
1106 expr9[expr1].name
1107 expr9.name[expr1]
1108 expr9(expr1, ...)[expr1].name
1109
1110
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001111expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +02001112 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001113If expr8 is a Number or String this results in a String that contains the
1114expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001115Number. This doesn't recognize multi-byte encodings, see `byteidx()` for
Bram Moolenaar03413f42016-04-12 21:07:15 +02001116an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001117
Bram Moolenaar256972a2015-12-29 19:10:25 +01001118Index zero gives the first byte. This is like it works in C. Careful:
1119text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001120cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001121 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001122
1123If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001124String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001125compatibility). Use [-1:] to get the last byte.
1126
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001127If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001128for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001129error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001130 :let item = mylist[-1] " get last item
1131
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001132Generally, if a |List| index is equal to or higher than the length of the
1133|List|, or more negative than the length of the |List|, this results in an
1134error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001135
Bram Moolenaard8b02732005-01-14 21:48:43 +00001136
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001137expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001138
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001139If expr8 is a Number or String this results in the substring with the bytes
1140from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001141expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
1142|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001143
1144If expr1a is omitted zero is used. If expr1b is omitted the length of the
1145string minus one is used.
1146
1147A negative number can be used to measure from the end of the string. -1 is
1148the last character, -2 the last but one, etc.
1149
1150If an index goes out of range for the string characters are omitted. If
1151expr1b is smaller than expr1a the result is an empty string.
1152
1153Examples: >
1154 :let c = name[-1:] " last byte of a string
1155 :let c = name[-2:-2] " last but one byte of a string
1156 :let s = line(".")[4:] " from the fifth byte to the end
1157 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001158<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001159 *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001160If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001161the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001162just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001163 :let l = mylist[:3] " first four items
1164 :let l = mylist[4:4] " List with one item
1165 :let l = mylist[:] " shallow copy of a List
1166
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001167If expr8 is a |Blob| this results in a new |Blob| with the bytes in the
1168indexes expr1a and expr1b, inclusive. Examples: >
1169 :let b = 0zDEADBEEF
1170 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001171 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001172
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001173Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
1174error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175
Bram Moolenaarda440d22016-01-16 21:27:23 +01001176Watch out for confusion between a namespace and a variable followed by a colon
1177for a sublist: >
1178 mylist[n:] " uses variable n
1179 mylist[s:] " uses namespace s:, error!
1180
Bram Moolenaard8b02732005-01-14 21:48:43 +00001181
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001182expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +00001183
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001184If expr8 is a |Dictionary| and it is followed by a dot, then the following
1185name will be used as a key in the |Dictionary|. This is just like:
1186expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001187
1188The name must consist of alphanumeric characters, just like a variable name,
1189but it may start with a number. Curly braces cannot be used.
1190
1191There must not be white space before or after the dot.
1192
1193Examples: >
1194 :let dict = {"one": 1, 2: "two"}
1195 :echo dict.one
1196 :echo dict .2
1197
1198Note that the dot is also used for String concatenation. To avoid confusion
1199always put spaces around the dot for String concatenation.
1200
1201
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001202expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001203
1204When expr8 is a |Funcref| type variable, invoke the function it refers to.
1205
1206
1207
1208 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001209number
1210------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001211number number constant *expr-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001212 *hex-number* *octal-number* *binary-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001213
Bram Moolenaar7571d552016-08-18 22:54:46 +02001214Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
1215and Octal (starting with 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001216
Bram Moolenaar446cb832008-06-24 21:56:24 +00001217 *floating-point-format*
1218Floating point numbers can be written in two forms:
1219
1220 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001221 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001222
1223{N} and {M} are numbers. Both {N} and {M} must be present and can only
1224contain digits.
1225[-+] means there is an optional plus or minus sign.
1226{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001227Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001228locale is.
1229{only when compiled with the |+float| feature}
1230
1231Examples:
1232 123.456
1233 +0.0001
1234 55.0
1235 -0.123
1236 1.234e03
1237 1.0E-6
1238 -3.1416e+88
1239
1240These are INVALID:
1241 3. empty {M}
1242 1e40 missing .{M}
1243
1244Rationale:
1245Before floating point was introduced, the text "123.456" was interpreted as
1246the two numbers "123" and "456", both converted to a string and concatenated,
1247resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001248could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001249incompatibility was accepted in favor of being able to use the normal notation
1250for floating point numbers.
1251
Bram Moolenaard47d5222018-12-09 20:43:55 +01001252 *float-pi* *float-e*
1253A few useful values to copy&paste: >
1254 :let pi = 3.14159265359
1255 :let e = 2.71828182846
1256Or, if you don't want to write them in as floating-point literals, you can
1257also use functions, like the following: >
1258 :let pi = acos(-1.0)
1259 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001260<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001261 *floating-point-precision*
1262The precision and range of floating points numbers depends on what "double"
1263means in the library Vim was compiled with. There is no way to change this at
1264runtime.
1265
1266The default for displaying a |Float| is to use 6 decimal places, like using
1267printf("%g", f). You can select something else when using the |printf()|
1268function. Example: >
1269 :echo printf('%.15e', atan(1))
1270< 7.853981633974483e-01
1271
1272
Bram Moolenaar071d4272004-06-13 20:20:40 +00001273
Bram Moolenaar979243b2015-06-26 19:35:49 +02001274string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001275------
1276"string" string constant *expr-quote*
1277
1278Note that double quotes are used.
1279
1280A string constant accepts these special characters:
1281\... three-digit octal number (e.g., "\316")
1282\.. two-digit octal number (must be followed by non-digit)
1283\. one-digit octal number (must be followed by non-digit)
1284\x.. byte specified with two hex numbers (e.g., "\x1f")
1285\x. byte specified with one hex number (must be followed by non-hex char)
1286\X.. same as \x..
1287\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001288\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001289 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001290\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001291\b backspace <BS>
1292\e escape <Esc>
1293\f formfeed <FF>
1294\n newline <NL>
1295\r return <CR>
1296\t tab <Tab>
1297\\ backslash
1298\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001299\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001300 in mappings, the 0x80 byte is escaped.
1301 To use the double quote character it must be escaped: "<M-\">".
1302 Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as
1303 mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001304
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001305Note that "\xff" is stored as the byte 255, which may be invalid in some
1306encodings. Use "\u00ff" to store character 255 according to the current value
1307of 'encoding'.
1308
Bram Moolenaar071d4272004-06-13 20:20:40 +00001309Note that "\000" and "\x00" force the end of the string.
1310
1311
Bram Moolenaard8968242019-01-15 22:51:57 +01001312blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001313------------
1314
1315Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1316The sequence must be an even number of hex characters. Example: >
1317 :let b = 0zFF00ED015DAF
1318
1319
Bram Moolenaar071d4272004-06-13 20:20:40 +00001320literal-string *literal-string* *E115*
1321---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001322'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001323
1324Note that single quotes are used.
1325
Bram Moolenaar58b85342016-08-14 19:54:54 +02001326This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001327meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001328
1329Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001330to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001331 if a =~ "\\s*"
1332 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001333
1334
1335option *expr-option* *E112* *E113*
1336------
1337&option option value, local value if possible
1338&g:option global option value
1339&l:option local option value
1340
1341Examples: >
1342 echo "tabstop is " . &tabstop
1343 if &insertmode
1344
1345Any option name can be used here. See |options|. When using the local value
1346and there is no buffer-local or window-local value, the global value is used
1347anyway.
1348
1349
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001350register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001351--------
1352@r contents of register 'r'
1353
1354The result is the contents of the named register, as a single string.
1355Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001356register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001357registers.
1358
1359When using the '=' register you get the expression itself, not what it
1360evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001361
1362
1363nesting *expr-nesting* *E110*
1364-------
1365(expr1) nested expression
1366
1367
1368environment variable *expr-env*
1369--------------------
1370$VAR environment variable
1371
1372The String value of any environment variable. When it is not defined, the
1373result is an empty string.
1374 *expr-env-expand*
1375Note that there is a difference between using $VAR directly and using
1376expand("$VAR"). Using it directly will only expand environment variables that
1377are known inside the current Vim session. Using expand() will first try using
1378the environment variables known inside the current Vim session. If that
1379fails, a shell will be used to expand the variable. This can be slow, but it
1380does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001381 :echo $shell
1382 :echo expand("$shell")
1383The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001384variable (if your shell supports it).
1385
1386
1387internal variable *expr-variable*
1388-----------------
1389variable internal variable
1390See below |internal-variables|.
1391
1392
Bram Moolenaar05159a02005-02-26 23:04:13 +00001393function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001394-------------
1395function(expr1, ...) function call
1396See below |functions|.
1397
1398
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001399lambda expression *expr-lambda* *lambda*
1400-----------------
1401{args -> expr1} lambda expression
1402
1403A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001404evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001405the following ways:
1406
14071. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1408 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020014092. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001410 :let F = {arg1, arg2 -> arg1 - arg2}
1411 :echo F(5, 2)
1412< 3
1413
1414The arguments are optional. Example: >
1415 :let F = {-> 'error function'}
1416 :echo F()
1417< error function
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001418 *closure*
1419Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001420often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001421while they already exist in the function scope. They remain valid even after
1422the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001423 :function Foo(arg)
1424 : let i = 3
1425 : return {x -> x + i - a:arg}
1426 :endfunction
1427 :let Bar = Foo(4)
1428 :echo Bar(6)
1429< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001430
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001431Note that the variables must exist in the outer scope before the lamba is
1432defined for this to work. See also |:func-closure|.
1433
1434Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001435 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001436
1437Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1438 :echo map([1, 2, 3], {idx, val -> val + 1})
1439< [2, 3, 4] >
1440 :echo sort([3,7,2,1,4], {a, b -> a - b})
1441< [1, 2, 3, 4, 7]
1442
1443The lambda expression is also useful for Channel, Job and timer: >
1444 :let timer = timer_start(500,
1445 \ {-> execute("echo 'Handler called'", "")},
1446 \ {'repeat': 3})
1447< Handler called
1448 Handler called
1449 Handler called
1450
1451Note how execute() is used to execute an Ex command. That's ugly though.
1452
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001453
1454Lambda expressions have internal names like '<lambda>42'. If you get an error
1455for a lambda expression, you can find what it is with the following command: >
1456 :function {'<lambda>42'}
1457See also: |numbered-function|
1458
Bram Moolenaar071d4272004-06-13 20:20:40 +00001459==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020014603. Internal variable *internal-variables* *E461*
1461
Bram Moolenaar071d4272004-06-13 20:20:40 +00001462An internal variable name can be made up of letters, digits and '_'. But it
1463cannot start with a digit. It's also possible to use curly braces, see
1464|curly-braces-names|.
1465
1466An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001467An internal variable is explicitly destroyed with the ":unlet" command
1468|:unlet|.
1469Using a name that is not an internal variable or refers to a variable that has
1470been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001471
1472There are several name spaces for variables. Which one is to be used is
1473specified by what is prepended:
1474
1475 (nothing) In a function: local to a function; otherwise: global
1476|buffer-variable| b: Local to the current buffer.
1477|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001478|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001479|global-variable| g: Global.
1480|local-variable| l: Local to a function.
1481|script-variable| s: Local to a |:source|'ed Vim script.
1482|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001483|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001484
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001485The scope name by itself can be used as a |Dictionary|. For example, to
1486delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001487 :for k in keys(s:)
1488 : unlet s:[k]
1489 :endfor
1490<
Bram Moolenaar531da592013-05-06 05:58:55 +02001491 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001492A variable name that is preceded with "b:" is local to the current buffer.
1493Thus you can have several "b:foo" variables, one for each buffer.
1494This kind of variable is deleted when the buffer is wiped out or deleted with
1495|:bdelete|.
1496
1497One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001498 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001499b:changedtick The total number of changes to the current buffer. It is
1500 incremented for each change. An undo command is also a change
1501 in this case. This can be used to perform an action only when
1502 the buffer has changed. Example: >
1503 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001504 : let my_changedtick = b:changedtick
1505 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001506 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001507< You cannot change or delete the b:changedtick variable.
1508
Bram Moolenaar531da592013-05-06 05:58:55 +02001509 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001510A variable name that is preceded with "w:" is local to the current window. It
1511is deleted when the window is closed.
1512
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001513 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001514A variable name that is preceded with "t:" is local to the current tab page,
1515It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001516without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001517
Bram Moolenaar531da592013-05-06 05:58:55 +02001518 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar58b85342016-08-14 19:54:54 +02001520access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001521place if you like.
1522
Bram Moolenaar531da592013-05-06 05:58:55 +02001523 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001524Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001525But you can also prepend "l:" if you like. However, without prepending "l:"
1526you may run into reserved variable names. For example "count". By itself it
1527refers to "v:count". Using "l:count" you can have a local variable with the
1528same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001529
1530 *script-variable* *s:var*
1531In a Vim script variables starting with "s:" can be used. They cannot be
1532accessed from outside of the scripts, thus are local to the script.
1533
1534They can be used in:
1535- commands executed while the script is sourced
1536- functions defined in the script
1537- autocommands defined in the script
1538- functions and autocommands defined in functions and autocommands which were
1539 defined in the script (recursively)
1540- user defined commands defined in the script
1541Thus not in:
1542- other scripts sourced from this one
1543- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001544- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001545- etc.
1546
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001547Script variables can be used to avoid conflicts with global variable names.
1548Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001549
1550 let s:counter = 0
1551 function MyCounter()
1552 let s:counter = s:counter + 1
1553 echo s:counter
1554 endfunction
1555 command Tick call MyCounter()
1556
1557You can now invoke "Tick" from any script, and the "s:counter" variable in
1558that script will not be changed, only the "s:counter" in the script where
1559"Tick" was defined is used.
1560
1561Another example that does the same: >
1562
1563 let s:counter = 0
1564 command Tick let s:counter = s:counter + 1 | echo s:counter
1565
1566When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001567script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001568defined.
1569
1570The script variables are also available when a function is defined inside a
1571function that is defined in a script. Example: >
1572
1573 let s:counter = 0
1574 function StartCounting(incr)
1575 if a:incr
1576 function MyCounter()
1577 let s:counter = s:counter + 1
1578 endfunction
1579 else
1580 function MyCounter()
1581 let s:counter = s:counter - 1
1582 endfunction
1583 endif
1584 endfunction
1585
1586This defines the MyCounter() function either for counting up or counting down
1587when calling StartCounting(). It doesn't matter from where StartCounting() is
1588called, the s:counter variable will be accessible in MyCounter().
1589
1590When the same script is sourced again it will use the same script variables.
1591They will remain valid as long as Vim is running. This can be used to
1592maintain a counter: >
1593
1594 if !exists("s:counter")
1595 let s:counter = 1
1596 echo "script executed for the first time"
1597 else
1598 let s:counter = s:counter + 1
1599 echo "script executed " . s:counter . " times now"
1600 endif
1601
1602Note that this means that filetype plugins don't get a different set of script
1603variables for each buffer. Use local buffer variables instead |b:var|.
1604
1605
Bram Moolenaard47d5222018-12-09 20:43:55 +01001606PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
1607 *E963*
1608Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001609
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001610 *v:beval_col* *beval_col-variable*
1611v:beval_col The number of the column, over which the mouse pointer is.
1612 This is the byte index in the |v:beval_lnum| line.
1613 Only valid while evaluating the 'balloonexpr' option.
1614
1615 *v:beval_bufnr* *beval_bufnr-variable*
1616v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1617 valid while evaluating the 'balloonexpr' option.
1618
1619 *v:beval_lnum* *beval_lnum-variable*
1620v:beval_lnum The number of the line, over which the mouse pointer is. Only
1621 valid while evaluating the 'balloonexpr' option.
1622
1623 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001624v:beval_text The text under or after the mouse pointer. Usually a word as
1625 it is useful for debugging a C program. 'iskeyword' applies,
1626 but a dot and "->" before the position is included. When on a
1627 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001628 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001629 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001630 Only valid while evaluating the 'balloonexpr' option.
1631
1632 *v:beval_winnr* *beval_winnr-variable*
1633v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001634 valid while evaluating the 'balloonexpr' option. The first
1635 window has number zero (unlike most other places where a
1636 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001637
Bram Moolenaar511972d2016-06-04 18:09:59 +02001638 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001639v:beval_winid The |window-ID| of the window, over which the mouse pointer
1640 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001641
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001642 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001643v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001644 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001645 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001646
Bram Moolenaar071d4272004-06-13 20:20:40 +00001647 *v:charconvert_from* *charconvert_from-variable*
1648v:charconvert_from
1649 The name of the character encoding of a file to be converted.
1650 Only valid while evaluating the 'charconvert' option.
1651
1652 *v:charconvert_to* *charconvert_to-variable*
1653v:charconvert_to
1654 The name of the character encoding of a file after conversion.
1655 Only valid while evaluating the 'charconvert' option.
1656
1657 *v:cmdarg* *cmdarg-variable*
1658v:cmdarg This variable is used for two purposes:
1659 1. The extra arguments given to a file read/write command.
1660 Currently these are "++enc=" and "++ff=". This variable is
1661 set before an autocommand event for a file read/write
1662 command is triggered. There is a leading space to make it
1663 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001664 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001665 included here, because it will be executed anyway.
1666 2. When printing a PostScript file with ":hardcopy" this is
1667 the argument for the ":hardcopy" command. This can be used
1668 in 'printexpr'.
1669
1670 *v:cmdbang* *cmdbang-variable*
1671v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1672 was used the value is 1, otherwise it is 0. Note that this
1673 can only be used in autocommands. For user commands |<bang>|
1674 can be used.
1675
Bram Moolenaar42a45122015-07-10 17:56:23 +02001676 *v:completed_item* *completed_item-variable*
1677v:completed_item
1678 |Dictionary| containing the |complete-items| for the most
1679 recently completed word after |CompleteDone|. The
1680 |Dictionary| is empty if the completion failed.
1681
Bram Moolenaar071d4272004-06-13 20:20:40 +00001682 *v:count* *count-variable*
1683v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001684 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001685 :map _x :<C-U>echo "the count is " . v:count<CR>
1686< Note: The <C-U> is required to remove the line range that you
1687 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001688 When there are two counts, as in "3d2w", they are multiplied,
1689 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001690 Also used for evaluating the 'formatexpr' option.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001691 "count" also works, for backwards compatibility, unless
1692 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001693
1694 *v:count1* *count1-variable*
1695v:count1 Just like "v:count", but defaults to one when no count is
1696 used.
1697
1698 *v:ctype* *ctype-variable*
1699v:ctype The current locale setting for characters of the runtime
1700 environment. This allows Vim scripts to be aware of the
1701 current locale encoding. Technical: it's the value of
1702 LC_CTYPE. When not using a locale the value is "C".
1703 This variable can not be set directly, use the |:language|
1704 command.
1705 See |multi-lang|.
1706
1707 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001708v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001709 one. When multiple signals are caught the number increases.
1710 Can be used in an autocommand to check if Vim didn't
1711 terminate normally. {only works on Unix}
1712 Example: >
1713 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001714< Note: if another deadly signal is caught when v:dying is one,
1715 VimLeave autocommands will not be executed.
1716
Bram Moolenaar071d4272004-06-13 20:20:40 +00001717 *v:errmsg* *errmsg-variable*
1718v:errmsg Last given error message. It's allowed to set this variable.
1719 Example: >
1720 :let v:errmsg = ""
1721 :silent! next
1722 :if v:errmsg != ""
1723 : ... handle error
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001724< "errmsg" also works, for backwards compatibility, unless
1725 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001726
Bram Moolenaar65a54642018-04-28 16:56:53 +02001727 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001728v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001729 This is a list of strings.
1730 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02001731 The return value indicates this: a one is returned if an item
1732 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01001733 To remove old results make it empty: >
1734 :let v:errors = []
1735< If v:errors is set to anything but a list it is made an empty
1736 list by the assert function.
1737
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001738 *v:event* *event-variable*
1739v:event Dictionary containing information about the current
1740 |autocommand|. The dictionary is emptied when the |autocommand|
1741 finishes, please refer to |dict-identity| for how to get an
1742 independent copy of it.
1743
Bram Moolenaar071d4272004-06-13 20:20:40 +00001744 *v:exception* *exception-variable*
1745v:exception The value of the exception most recently caught and not
1746 finished. See also |v:throwpoint| and |throw-variables|.
1747 Example: >
1748 :try
1749 : throw "oops"
1750 :catch /.*/
1751 : echo "caught" v:exception
1752 :endtry
1753< Output: "caught oops".
1754
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001755 *v:false* *false-variable*
1756v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001757 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001758 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001759 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001760< v:false ~
1761 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001762 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001763
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001764 *v:fcs_reason* *fcs_reason-variable*
1765v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1766 Can be used in an autocommand to decide what to do and/or what
1767 to set v:fcs_choice to. Possible values:
1768 deleted file no longer exists
1769 conflict file contents, mode or timestamp was
1770 changed and buffer is modified
1771 changed file contents has changed
1772 mode mode of file changed
1773 time only file timestamp changed
1774
1775 *v:fcs_choice* *fcs_choice-variable*
1776v:fcs_choice What should happen after a |FileChangedShell| event was
1777 triggered. Can be used in an autocommand to tell Vim what to
1778 do with the affected buffer:
1779 reload Reload the buffer (does not work if
1780 the file was deleted).
1781 ask Ask the user what to do, as if there
1782 was no autocommand. Except that when
1783 only the timestamp changed nothing
1784 will happen.
1785 <empty> Nothing, the autocommand should do
1786 everything that needs to be done.
1787 The default is empty. If another (invalid) value is used then
1788 Vim behaves like it is empty, there is no warning message.
1789
Bram Moolenaar071d4272004-06-13 20:20:40 +00001790 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001791v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001792 option used for ~
1793 'charconvert' file to be converted
1794 'diffexpr' original file
1795 'patchexpr' original file
1796 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001797 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001798
1799 *v:fname_out* *fname_out-variable*
1800v:fname_out The name of the output file. Only valid while
1801 evaluating:
1802 option used for ~
1803 'charconvert' resulting converted file (*)
1804 'diffexpr' output of diff
1805 'patchexpr' resulting patched file
1806 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02001807 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001808 for a read command (e.g., ":e file") it will be a temporary
1809 file and different from v:fname_in.
1810
1811 *v:fname_new* *fname_new-variable*
1812v:fname_new The name of the new version of the file. Only valid while
1813 evaluating 'diffexpr'.
1814
1815 *v:fname_diff* *fname_diff-variable*
1816v:fname_diff The name of the diff (patch) file. Only valid while
1817 evaluating 'patchexpr'.
1818
1819 *v:folddashes* *folddashes-variable*
1820v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1821 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001822 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001823
1824 *v:foldlevel* *foldlevel-variable*
1825v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001826 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001827
1828 *v:foldend* *foldend-variable*
1829v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001830 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001831
1832 *v:foldstart* *foldstart-variable*
1833v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001834 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001835
Bram Moolenaar817a8802013-11-09 01:44:43 +01001836 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001837v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01001838 Setting it makes sense only if 'hlsearch' is enabled which
1839 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001840 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001841 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001842< Note that the value is restored when returning from a
1843 function. |function-search-undo|.
1844
Bram Moolenaar843ee412004-06-30 16:16:41 +00001845 *v:insertmode* *insertmode-variable*
1846v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1847 events. Values:
1848 i Insert mode
1849 r Replace mode
1850 v Virtual Replace mode
1851
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001852 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001853v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001854 evaluating the expression used with |map()| and |filter()|.
1855 Read-only.
1856
Bram Moolenaar071d4272004-06-13 20:20:40 +00001857 *v:lang* *lang-variable*
1858v:lang The current locale setting for messages of the runtime
1859 environment. This allows Vim scripts to be aware of the
1860 current language. Technical: it's the value of LC_MESSAGES.
1861 The value is system dependent.
1862 This variable can not be set directly, use the |:language|
1863 command.
1864 It can be different from |v:ctype| when messages are desired
1865 in a different language than what is used for character
1866 encoding. See |multi-lang|.
1867
1868 *v:lc_time* *lc_time-variable*
1869v:lc_time The current locale setting for time messages of the runtime
1870 environment. This allows Vim scripts to be aware of the
1871 current language. Technical: it's the value of LC_TIME.
1872 This variable can not be set directly, use the |:language|
1873 command. See |multi-lang|.
1874
1875 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001876v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1877 'indentexpr' expressions, tab page number for 'guitablabel'
1878 and 'guitabtooltip'. Only valid while one of these
1879 expressions is being evaluated. Read-only when in the
1880 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001881
Bram Moolenaar219b8702006-11-01 14:32:36 +00001882 *v:mouse_win* *mouse_win-variable*
1883v:mouse_win Window number for a mouse click obtained with |getchar()|.
1884 First window has number 1, like with |winnr()|. The value is
1885 zero when there was no mouse button click.
1886
Bram Moolenaar511972d2016-06-04 18:09:59 +02001887 *v:mouse_winid* *mouse_winid-variable*
1888v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
1889 The value is zero when there was no mouse button click.
1890
Bram Moolenaar219b8702006-11-01 14:32:36 +00001891 *v:mouse_lnum* *mouse_lnum-variable*
1892v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1893 This is the text line number, not the screen line number. The
1894 value is zero when there was no mouse button click.
1895
1896 *v:mouse_col* *mouse_col-variable*
1897v:mouse_col Column number for a mouse click obtained with |getchar()|.
1898 This is the screen column number, like with |virtcol()|. The
1899 value is zero when there was no mouse button click.
1900
Bram Moolenaard09091d2019-01-17 16:07:22 +01001901 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001902v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001903 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001904 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001905 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001906 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001907< v:none ~
1908 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001909 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001910
1911 *v:null* *null-variable*
1912v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001913 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001914 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001915 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001916 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001917< v:null ~
1918 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001919 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001920
Bram Moolenaard812df62008-11-09 12:46:09 +00001921 *v:oldfiles* *oldfiles-variable*
1922v:oldfiles List of file names that is loaded from the |viminfo| file on
1923 startup. These are the files that Vim remembers marks for.
1924 The length of the List is limited by the ' argument of the
1925 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001926 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001927 Also see |:oldfiles| and |c_#<|.
1928 The List can be modified, but this has no effect on what is
1929 stored in the |viminfo| file later. If you use values other
1930 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001931 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001932
Bram Moolenaar53744302015-07-17 17:38:22 +02001933 *v:option_new*
1934v:option_new New value of the option. Valid while executing an |OptionSet|
1935 autocommand.
1936 *v:option_old*
1937v:option_old Old value of the option. Valid while executing an |OptionSet|
1938 autocommand.
1939 *v:option_type*
1940v:option_type Scope of the set command. Valid while executing an
1941 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001942 *v:operator* *operator-variable*
1943v:operator The last operator given in Normal mode. This is a single
1944 character except for commands starting with <g> or <z>,
1945 in which case it is two characters. Best used alongside
1946 |v:prevcount| and |v:register|. Useful if you want to cancel
1947 Operator-pending mode and then use the operator, e.g.: >
1948 :omap O <Esc>:call MyMotion(v:operator)<CR>
1949< The value remains set until another operator is entered, thus
1950 don't expect it to be empty.
1951 v:operator is not set for |:delete|, |:yank| or other Ex
1952 commands.
1953 Read-only.
1954
Bram Moolenaar071d4272004-06-13 20:20:40 +00001955 *v:prevcount* *prevcount-variable*
1956v:prevcount The count given for the last but one Normal mode command.
1957 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001958 you want to cancel Visual or Operator-pending mode and then
1959 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001960 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1961< Read-only.
1962
Bram Moolenaar05159a02005-02-26 23:04:13 +00001963 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001964v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001965 See |profiling|.
1966
Bram Moolenaar071d4272004-06-13 20:20:40 +00001967 *v:progname* *progname-variable*
1968v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001969 invoked. Allows you to do special initialisations for |view|,
1970 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001971 Read-only.
1972
Bram Moolenaara1706c92014-04-01 19:55:49 +02001973 *v:progpath* *progpath-variable*
1974v:progpath Contains the command with which Vim was invoked, including the
1975 path. Useful if you want to message a Vim server using a
1976 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001977 To get the full path use: >
1978 echo exepath(v:progpath)
Bram Moolenaar08cab962017-03-04 14:37:18 +01001979< If the path is relative it will be expanded to the full path,
1980 so that it still works after `:cd`. Thus starting "./vim"
1981 results in "/home/user/path/to/vim/src/vim".
1982 On MS-Windows the executable may be called "vim.exe", but the
1983 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001984 Read-only.
1985
Bram Moolenaar071d4272004-06-13 20:20:40 +00001986 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001987v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001988 command (regardless of whether that command actually used a
1989 register). Or for the currently executing normal mode mapping
1990 (use this in custom commands that take a register).
1991 If none is supplied it is the default register '"', unless
1992 'clipboard' contains "unnamed" or "unnamedplus", then it is
1993 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001994 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001995
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001996 *v:scrollstart* *scrollstart-variable*
1997v:scrollstart String describing the script or function that caused the
1998 screen to scroll up. It's only set when it is empty, thus the
1999 first reason is remembered. It is set to "Unknown" for a
2000 typed command.
2001 This can be used to find out why your script causes the
2002 hit-enter prompt.
2003
Bram Moolenaar071d4272004-06-13 20:20:40 +00002004 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002005v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002006 Read-only.
2007
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002008
Bram Moolenaar446cb832008-06-24 21:56:24 +00002009v:searchforward *v:searchforward* *searchforward-variable*
2010 Search direction: 1 after a forward search, 0 after a
2011 backward search. It is reset to forward when directly setting
2012 the last search pattern, see |quote/|.
2013 Note that the value is restored when returning from a
2014 function. |function-search-undo|.
2015 Read-write.
2016
Bram Moolenaar071d4272004-06-13 20:20:40 +00002017 *v:shell_error* *shell_error-variable*
2018v:shell_error Result of the last shell command. When non-zero, the last
2019 shell command had an error. When zero, there was no problem.
2020 This only works when the shell returns the error code to Vim.
2021 The value -1 is often used when the command could not be
2022 executed. Read-only.
2023 Example: >
2024 :!mv foo bar
2025 :if v:shell_error
2026 : echo 'could not rename "foo" to "bar"!'
2027 :endif
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002028< "shell_error" also works, for backwards compatibility, unless
2029 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002030
2031 *v:statusmsg* *statusmsg-variable*
2032v:statusmsg Last given status message. It's allowed to set this variable.
2033
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002034 *v:swapname* *swapname-variable*
2035v:swapname Only valid when executing |SwapExists| autocommands: Name of
2036 the swap file found. Read-only.
2037
2038 *v:swapchoice* *swapchoice-variable*
2039v:swapchoice |SwapExists| autocommands can set this to the selected choice
2040 for handling an existing swap file:
2041 'o' Open read-only
2042 'e' Edit anyway
2043 'r' Recover
2044 'd' Delete swapfile
2045 'q' Quit
2046 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002047 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002048 results in the user being asked, as would happen when there is
2049 no SwapExists autocommand. The default is empty.
2050
Bram Moolenaarb3480382005-12-11 21:33:32 +00002051 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002052v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002053 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002054 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002055 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002056 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002057
Bram Moolenaard823fa92016-08-12 16:29:27 +02002058 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002059v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002060 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002061v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002062 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002063v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002064 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002065v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002066 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002067v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002068 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002069v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002070 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002071v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002072 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002073v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002074 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002075v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002076 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002077v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002078 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002079v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002080
Bram Moolenaar071d4272004-06-13 20:20:40 +00002081 *v:termresponse* *termresponse-variable*
2082v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002083 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00002084 that starts with ESC [ or CSI and ends in a 'c', with only
2085 digits, ';' and '.' in between.
2086 When this option is set, the TermResponse autocommand event is
2087 fired, so that you can react to the response from the
2088 terminal.
2089 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
2090 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2091 patch level (since this was introduced in patch 95, it's
2092 always 95 or bigger). Pc is always zero.
2093 {only when compiled with |+termresponse| feature}
2094
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002095 *v:termblinkresp*
2096v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2097 termcap entry. This is used to find out whether the terminal
2098 cursor is blinking. This is used by |term_getcursor()|.
2099
2100 *v:termstyleresp*
2101v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2102 termcap entry. This is used to find out what the shape of the
2103 cursor is. This is used by |term_getcursor()|.
2104
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002105 *v:termrbgresp*
2106v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002107 termcap entry. This is used to find out what the terminal
2108 background color is, see 'background'.
2109
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002110 *v:termrfgresp*
2111v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2112 termcap entry. This is used to find out what the terminal
2113 foreground color is.
2114
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002115 *v:termu7resp*
2116v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2117 termcap entry. This is used to find out what the terminal
2118 does with ambiguous width characters, see 'ambiwidth'.
2119
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002120 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002121v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002122 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002123 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002124
Bram Moolenaar071d4272004-06-13 20:20:40 +00002125 *v:this_session* *this_session-variable*
2126v:this_session Full filename of the last loaded or saved session file. See
2127 |:mksession|. It is allowed to set this variable. When no
2128 session file has been saved, this variable is empty.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002129 "this_session" also works, for backwards compatibility, unless
2130 |scriptversion| is 3 or higher
Bram Moolenaar071d4272004-06-13 20:20:40 +00002131
2132 *v:throwpoint* *throwpoint-variable*
2133v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002134 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002135 also |v:exception| and |throw-variables|.
2136 Example: >
2137 :try
2138 : throw "oops"
2139 :catch /.*/
2140 : echo "Exception from" v:throwpoint
2141 :endtry
2142< Output: "Exception from test.vim, line 2"
2143
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002144 *v:true* *true-variable*
2145v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002146 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002147 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002148 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002149< v:true ~
2150 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002151 value. Read-only.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002152 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002153v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002154 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002155 |filter()|. Read-only.
2156
Bram Moolenaar071d4272004-06-13 20:20:40 +00002157 *v:version* *version-variable*
2158v:version Version number of Vim: Major version number times 100 plus
2159 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
2160 is 501. Read-only. "version" also works, for backwards
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002161 compatibility, unless |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002162 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002163 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002164< Note that patch numbers are specific to the version, thus both
2165 version 5.0 and 5.1 may have a patch 123, but these are
2166 completely different.
2167
Bram Moolenaar14735512016-03-26 21:00:08 +01002168 *v:vim_did_enter* *vim_did_enter-variable*
2169v:vim_did_enter Zero until most of startup is done. It is set to one just
2170 before |VimEnter| autocommands are triggered.
2171
Bram Moolenaar071d4272004-06-13 20:20:40 +00002172 *v:warningmsg* *warningmsg-variable*
2173v:warningmsg Last given warning message. It's allowed to set this variable.
2174
Bram Moolenaar727c8762010-10-20 19:17:48 +02002175 *v:windowid* *windowid-variable*
2176v:windowid When any X11 based GUI is running or when running in a
2177 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002178 set to the window ID.
2179 When an MS-Windows GUI is running this will be set to the
2180 window handle.
2181 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002182 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2183 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002184
Bram Moolenaar071d4272004-06-13 20:20:40 +00002185==============================================================================
21864. Builtin Functions *functions*
2187
2188See |function-list| for a list grouped by what the function is used for.
2189
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002190(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002191
2192USAGE RESULT DESCRIPTION ~
2193
Bram Moolenaar81edd172016-04-14 13:51:37 +02002194abs({expr}) Float or Number absolute value of {expr}
2195acos({expr}) Float arc cosine of {expr}
Bram Moolenaard8968242019-01-15 22:51:57 +01002196add({object}, {item}) List/Blob append {item} to {object}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002197and({expr}, {expr}) Number bitwise AND
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002198append({lnum}, {text}) Number append {text} below line {lnum}
2199appendbufline({expr}, {lnum}, {text})
2200 Number append {text} below line {lnum}
2201 in buffer {expr}
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002202argc([{winid}]) Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002203argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002204arglistid([{winnr} [, {tabnr}]]) Number argument list id
Bram Moolenaare6e39892018-10-25 12:32:11 +02002205argv({nr} [, {winid}]) String {nr} entry of the argument list
2206argv([-1, {winid}]) List the argument list
Bram Moolenaar65a54642018-04-28 16:56:53 +02002207assert_beeps({cmd}) Number assert {cmd} causes a beep
Bram Moolenaar42205552017-03-18 19:42:22 +01002208assert_equal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002209 Number assert {exp} is equal to {act}
Bram Moolenaard96ff162018-02-18 22:13:29 +01002210assert_equalfile({fname-one}, {fname-two})
Bram Moolenaar65a54642018-04-28 16:56:53 +02002211 Number assert file contents is equal
Bram Moolenaar42205552017-03-18 19:42:22 +01002212assert_exception({error} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002213 Number assert {error} is in v:exception
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002214assert_fails({cmd} [, {error} [, {msg}]])
2215 Number assert {cmd} fails
Bram Moolenaar42205552017-03-18 19:42:22 +01002216assert_false({actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002217 Number assert {actual} is false
Bram Moolenaar61c04492016-07-23 15:35:35 +02002218assert_inrange({lower}, {upper}, {actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002219 Number assert {actual} is inside the range
Bram Moolenaar42205552017-03-18 19:42:22 +01002220assert_match({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002221 Number assert {pat} matches {text}
Bram Moolenaar42205552017-03-18 19:42:22 +01002222assert_notequal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002223 Number assert {exp} is not equal {act}
Bram Moolenaar42205552017-03-18 19:42:22 +01002224assert_notmatch({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002225 Number assert {pat} not matches {text}
2226assert_report({msg}) Number report a test failure
2227assert_true({actual} [, {msg}]) Number assert {actual} is true
Bram Moolenaar81edd172016-04-14 13:51:37 +02002228asin({expr}) Float arc sine of {expr}
2229atan({expr}) Float arc tangent of {expr}
Bram Moolenaar04186092016-08-29 21:55:35 +02002230atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar74240d32017-12-10 15:26:15 +01002231balloon_show({expr}) none show {expr} inside the balloon
Bram Moolenaar246fe032017-11-19 19:56:27 +01002232balloon_split({msg}) List split {msg} as used for a balloon
Bram Moolenaar81edd172016-04-14 13:51:37 +02002233browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002234 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02002235browsedir({title}, {initdir}) String put up a directory requester
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002236bufexists({expr}) Number |TRUE| if buffer {expr} exists
2237buflisted({expr}) Number |TRUE| if buffer {expr} is listed
2238bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded
Bram Moolenaar81edd172016-04-14 13:51:37 +02002239bufname({expr}) String Name of the buffer {expr}
2240bufnr({expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002241bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002242bufwinnr({expr}) Number window number of buffer {expr}
2243byte2line({byte}) Number line number at byte count {byte}
2244byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2245byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2246call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002247 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002248ceil({expr}) Float round {expr} up
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002249ch_canread({handle}) Number check if there is something to read
Bram Moolenaar81edd172016-04-14 13:51:37 +02002250ch_close({handle}) none close {handle}
Bram Moolenaar0874a832016-09-01 15:11:51 +02002251ch_close_in({handle}) none close in part of {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002252ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002253 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002254ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002255 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002256ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2257ch_getjob({channel}) Job get the Job of {channel}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002258ch_info({handle}) String info about channel {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002259ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2260ch_logfile({fname} [, {mode}]) none start logging channel activity
2261ch_open({address} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002262 Channel open a channel to {address}
2263ch_read({handle} [, {options}]) String read from {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002264ch_readblob({handle} [, {options}])
2265 Blob read Blob from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002266ch_readraw({handle} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002267 String read raw from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002268ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002269 any send {expr} over JSON {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002270ch_sendraw({handle}, {expr} [, {options}])
2271 any send {expr} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002272ch_setoptions({handle}, {options})
2273 none set options for {handle}
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002274ch_status({handle} [, {options}])
2275 String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002276changenr() Number current change number
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002277char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002278cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002279clearmatches([{win}]) none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002280col({expr}) Number column nr of cursor or mark
2281complete({startcol}, {matches}) none set Insert mode completion
2282complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002283complete_check() Number check for key typed during completion
Bram Moolenaarfd133322019-03-29 12:20:27 +01002284complete_info([{what}]) Dict get current completion information
Bram Moolenaar81edd172016-04-14 13:51:37 +02002285confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002286 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002287copy({expr}) any make a shallow copy of {expr}
2288cos({expr}) Float cosine of {expr}
2289cosh({expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002290count({comp}, {expr} [, {ic} [, {start}]])
2291 Number count how many {expr} are in {comp}
Bram Moolenaardc1f1642016-08-16 18:33:43 +02002292cscope_connection([{num}, {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002293 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02002294cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002295 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002296cursor({list}) Number move cursor to position in {list}
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02002297debugbreak({pid}) Number interrupt process being debugged
Bram Moolenaar81edd172016-04-14 13:51:37 +02002298deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2299delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002300deletebufline({expr}, {first} [, {last}])
Bram Moolenaard79a2622018-06-07 18:17:46 +02002301 Number delete lines from buffer {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002302did_filetype() Number |TRUE| if FileType autocmd event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002303diff_filler({lnum}) Number diff filler lines about {lnum}
2304diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002305empty({expr}) Number |TRUE| if {expr} is empty
Bram Moolenaar81edd172016-04-14 13:51:37 +02002306escape({string}, {chars}) String escape {chars} in {string} with '\'
2307eval({string}) any evaluate {string} into its value
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002308eventhandler() Number |TRUE| if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02002309executable({expr}) Number 1 if executable {expr} exists
Bram Moolenaar79815f12016-07-09 17:07:29 +02002310execute({command}) String execute {command} and get the output
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002311exepath({expr}) String full path of the command {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002312exists({expr}) Number |TRUE| if {expr} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002313extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002314 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002315exp({expr}) Float exponential of {expr}
2316expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002317 any expand special keywords in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002318feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002319filereadable({file}) Number |TRUE| if {file} is a readable file
2320filewritable({file}) Number |TRUE| if {file} is a writable file
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002321filter({expr1}, {expr2}) List/Dict remove items from {expr1} where
2322 {expr2} is 0
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002323finddir({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002324 String find directory {name} in {path}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002325findfile({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002326 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002327float2nr({expr}) Number convert Float {expr} to a Number
2328floor({expr}) Float round {expr} down
2329fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2330fnameescape({fname}) String escape special characters in {fname}
2331fnamemodify({fname}, {mods}) String modify file name
2332foldclosed({lnum}) Number first line of fold at {lnum} if closed
2333foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2334foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002335foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02002336foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002337foreground() Number bring the Vim window to the foreground
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002338funcref({name} [, {arglist}] [, {dict}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002339 Funcref reference to function {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002340function({name} [, {arglist}] [, {dict}])
2341 Funcref named reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002342garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02002343get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2344get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02002345get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002346getbufinfo([{expr}]) List information about buffers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002347getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00002348 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002349getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002350 any variable {varname} in buffer {expr}
Bram Moolenaar07ad8162018-02-13 13:59:59 +01002351getchangelist({expr}) List list of change list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002352getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002353getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02002354getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002355getcmdline() String return the current command-line
2356getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02002357getcmdtype() String return current command-line type
2358getcmdwintype() String return current command-line window type
Bram Moolenaare9d58a62016-08-13 15:07:41 +02002359getcompletion({pat}, {type} [, {filtered}])
2360 List list of cmdline completion matches
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002361getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002362getcwd([{winnr} [, {tabnr}]]) String get the current working directory
2363getfontname([{name}]) String name of font being used
2364getfperm({fname}) String file permissions of file {fname}
2365getfsize({fname}) Number size in bytes of file {fname}
2366getftime({fname}) Number last modification time of file
2367getftype({fname}) String description of type of file {fname}
Bram Moolenaar4f505882018-02-10 21:06:32 +01002368getjumplist([{winnr} [, {tabnr}]])
2369 List list of jump list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002370getline({lnum}) String line {lnum} of current buffer
2371getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002372getloclist({nr} [, {what}]) List list of location list items
Bram Moolenaaraff74912019-03-30 18:11:49 +01002373getmatches([{win}]) List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00002374getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002375getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaard823fa92016-08-12 16:29:27 +02002376getqflist([{what}]) List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002377getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02002378 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02002379getregtype([{regname}]) String type of register
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002380gettabinfo([{expr}]) List list of tab pages
Bram Moolenaar81edd172016-04-14 13:51:37 +02002381gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002382 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002383gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002384 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002385gettagstack([{nr}]) Dict get the tag stack of window {nr}
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02002386getwininfo([{winid}]) List list of info about each window
Bram Moolenaar98ef2332018-03-18 14:44:37 +01002387getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01002388getwinposx() Number X coord in pixels of the Vim window
2389getwinposy() Number Y coord in pixels of the Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002390getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002391 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002392glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002393 any expand file wildcards in {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002394glob2regpat({expr}) String convert a glob pat into a search pat
Bram Moolenaar81edd172016-04-14 13:51:37 +02002395globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002396 String do glob({expr}) for all dirs in {path}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002397has({feature}) Number |TRUE| if feature {feature} supported
2398has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002399haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002400 Number |TRUE| if the window executed |:lcd|
Bram Moolenaar00aa0692019-04-27 20:37:57 +02002401 or |:tcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002402hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002403 Number |TRUE| if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002404histadd({history}, {item}) String add an item to a history
2405histdel({history} [, {item}]) String remove an item from a history
2406histget({history} [, {index}]) String get the item {index} from a history
2407histnr({history}) Number highest index of a history
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002408hlexists({name}) Number |TRUE| if highlight group {name} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002409hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002410hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002411iconv({expr}, {from}, {to}) String convert encoding of {expr}
2412indent({lnum}) Number indent of line {lnum}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002413index({object}, {expr} [, {start} [, {ic}]])
2414 Number index in {object} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002415input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002416 String get input from the user
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02002417inputdialog({prompt} [, {text} [, {completion}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002418 String like input() but in a GUI dialog
Bram Moolenaar81edd172016-04-14 13:51:37 +02002419inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002420inputrestore() Number restore typeahead
2421inputsave() Number save and clear typeahead
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002422inputsecret({prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002423insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002424invert({expr}) Number bitwise invert
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002425isdirectory({directory}) Number |TRUE| if {directory} is a directory
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02002426isinf({expr}) Number determine if {expr} is infinity value
2427 (positive or negative)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002428islocked({expr}) Number |TRUE| if {expr} is locked
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002429isnan({expr}) Number |TRUE| if {expr} is NaN
Bram Moolenaar81edd172016-04-14 13:51:37 +02002430items({dict}) List key-value pairs in {dict}
2431job_getchannel({job}) Channel get the channel handle for {job}
Bram Moolenaare1fc5152018-04-21 19:49:08 +02002432job_info([{job}]) Dict get information about {job}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002433job_setoptions({job}, {options}) none set options for {job}
2434job_start({command} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002435 Job start a job
Bram Moolenaar81edd172016-04-14 13:51:37 +02002436job_status({job}) String get the status of {job}
2437job_stop({job} [, {how}]) Number stop {job}
2438join({list} [, {sep}]) String join {list} items into one String
2439js_decode({string}) any decode JS style JSON
2440js_encode({expr}) String encode JS style JSON
2441json_decode({string}) any decode JSON
2442json_encode({expr}) String encode JSON
2443keys({dict}) List keys in {dict}
2444len({expr}) Number the length of {expr}
2445libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002446libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002447line({expr}) Number line nr of cursor, last line or mark
2448line2byte({lnum}) Number byte count of line {lnum}
2449lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar9d401282019-04-06 13:18:12 +02002450list2str({list} [, {utf8}]) String turn numbers in {list} into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00002451localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002452log({expr}) Float natural logarithm (base e) of {expr}
2453log10({expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002454luaeval({expr} [, {expr}]) any evaluate |Lua| expression
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002455map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002456maparg({name} [, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002457 String or Dict
2458 rhs of mapping {name} in mode {mode}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002459mapcheck({name} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002460 String check for mappings matching {name}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002461match({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002462 Number position where {pat} matches in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002463matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002464 Number highlight {pattern} with {group}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002465matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002466 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002467matcharg({nr}) List arguments of |:match|
Bram Moolenaaraff74912019-03-30 18:11:49 +01002468matchdelete({id} [, {win}]) Number delete match identified by {id}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002469matchend({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002470 Number position where {pat} ends in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002471matchlist({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002472 List match and submatches of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002473matchstr({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002474 String {count}'th match of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002475matchstrpos({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002476 List {count}'th match of {pat} in {expr}
Bram Moolenaar690afe12017-01-28 18:34:47 +01002477max({expr}) Number maximum value of items in {expr}
2478min({expr}) Number minimum value of items in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002479mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002480 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002481mode([expr]) String current editing mode
2482mzeval({expr}) any evaluate |MzScheme| expression
2483nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002484nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002485or({expr}, {expr}) Number bitwise OR
Bram Moolenaar81edd172016-04-14 13:51:37 +02002486pathshorten({expr}) String shorten directory names in a path
2487perleval({expr}) any evaluate |Perl| expression
2488pow({x}, {y}) Float {x} to the power of {y}
2489prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2490printf({fmt}, {expr1}...) String format text
Bram Moolenaarf2732452018-06-03 14:47:35 +02002491prompt_setcallback({buf}, {expr}) none set prompt callback function
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02002492prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
2493prompt_setprompt({buf}, {text}) none set prompt text
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002494prop_add({lnum}, {col}, {props}) none add a text property
Bram Moolenaare3d31b02018-12-24 23:07:04 +01002495prop_clear({lnum} [, {lnum-end} [, {props}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002496 none remove all text properties
2497prop_find({props} [, {direction}])
2498 Dict search for a text property
Bram Moolenaar5b69c222019-01-11 14:50:06 +01002499prop_list({lnum} [, {props}) List text properties in {lnum}
Bram Moolenaarc8c88492018-12-27 23:59:26 +01002500prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002501 Number remove a text property
2502prop_type_add({name}, {props}) none define a new property type
2503prop_type_change({name}, {props})
2504 none change an existing property type
2505prop_type_delete({name} [, {props}])
2506 none delete a property type
2507prop_type_get([{name} [, {props}])
2508 Dict get property type values
2509prop_type_list([{props}]) List get list of property types
Bram Moolenaar446cb832008-06-24 21:56:24 +00002510pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002511pyeval({expr}) any evaluate |Python| expression
2512py3eval({expr}) any evaluate |python3| expression
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01002513pyxeval({expr}) any evaluate |python_x| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002514range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002515 List items from {expr} to {max}
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02002516readdir({dir} [, {expr}]) List file names in {dir} selected by {expr}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002517readfile({fname} [, {type} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002518 List get list of lines from file {fname}
Bram Moolenaarf2732452018-06-03 14:47:35 +02002519reg_executing() String get the executing register name
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02002520reg_recording() String get the recording register name
Bram Moolenaar81edd172016-04-14 13:51:37 +02002521reltime([{start} [, {end}]]) List get time value
2522reltimefloat({time}) Float turn the time value into a Float
2523reltimestr({time}) String turn time value into a String
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002524remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002525 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002526remote_foreground({server}) Number bring Vim server to the foreground
2527remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002528 Number check for reply string
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002529remote_read({serverid} [, {timeout}])
2530 String read reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002531remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002532 String send key sequence
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01002533remote_startserver({name}) none become server {name}
Bram Moolenaar39536dd2019-01-29 22:58:21 +01002534remove({list}, {idx} [, {end}]) any/List
2535 remove items {idx}-{end} from {list}
2536remove({blob}, {idx} [, {end}]) Number/Blob
2537 remove bytes {idx}-{end} from {blob}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002538remove({dict}, {key}) any remove entry {key} from {dict}
2539rename({from}, {to}) Number rename (move) file from {from} to {to}
2540repeat({expr}, {count}) String repeat {expr} {count} times
2541resolve({filename}) String get filename a shortcut points to
2542reverse({list}) List reverse {list} in-place
2543round({expr}) Float round off {expr}
Bram Moolenaare99be0e2019-03-26 22:51:09 +01002544rubyeval({expr}) any evaluate |Ruby| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002545screenattr({row}, {col}) Number attribute at screen position
2546screenchar({row}, {col}) Number character at screen position
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002547screenchars({row}, {col}) List List of characters at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002548screencol() Number current cursor column
2549screenrow() Number current cursor row
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002550screenstring({row}, {col}) String characters at screen position
Bram Moolenaar81edd172016-04-14 13:51:37 +02002551search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002552 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002553searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002554 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002555searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002556 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002557searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002558 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002559searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002560 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002561server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002562 Number send reply string
2563serverlist() String get a list of available servers
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002564setbufline({expr}, {lnum}, {text})
2565 Number set line {lnum} to {text} in buffer
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02002566 {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002567setbufvar({expr}, {varname}, {val})
2568 none set {varname} in buffer {expr} to {val}
2569setcharsearch({dict}) Dict set character search from {dict}
2570setcmdpos({pos}) Number set cursor position in command-line
2571setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2572setline({lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002573setloclist({nr}, {list} [, {action} [, {what}]])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002574 Number modify location list using {list}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002575setmatches({list} [, {win}]) Number restore a list of matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002576setpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002577setqflist({list} [, {action} [, {what}]])
Bram Moolenaard823fa92016-08-12 16:29:27 +02002578 Number modify quickfix list using {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002579setreg({n}, {v} [, {opt}]) Number set register to value and type
Bram Moolenaar81edd172016-04-14 13:51:37 +02002580settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2581settabwinvar({tabnr}, {winnr}, {varname}, {val})
2582 none set {varname} in window {winnr} in tab
2583 page {tabnr} to {val}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002584settagstack({nr}, {dict} [, {action}])
2585 Number modify tag stack using {dict}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002586setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2587sha256({string}) String SHA256 checksum of {string}
2588shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002589 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002590 command argument
Bram Moolenaarf9514162018-11-22 03:08:29 +01002591shiftwidth([{col}]) Number effective value of 'shiftwidth'
Bram Moolenaar162b7142018-12-21 15:17:36 +01002592sign_define({name} [, {dict}]) Number define or update a sign
2593sign_getdefined([{name}]) List get a list of defined signs
2594sign_getplaced([{expr} [, {dict}]])
2595 List get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01002596sign_jump({id}, {group}, {expr})
2597 Number jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01002598sign_place({id}, {group}, {name}, {expr} [, {dict}])
2599 Number place a sign
2600sign_undefine([{name}]) Number undefine a sign
2601sign_unplace({group} [, {dict}])
2602 Number unplace a sign
Bram Moolenaar81edd172016-04-14 13:51:37 +02002603simplify({filename}) String simplify filename as much as possible
2604sin({expr}) Float sine of {expr}
2605sinh({expr}) Float hyperbolic sine of {expr}
2606sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002607 List sort {list}, using {func} to compare
Bram Moolenaar81edd172016-04-14 13:51:37 +02002608soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002609spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002610spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002611 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002612split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002613 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002614sqrt({expr}) Float square root of {expr}
2615str2float({expr}) Float convert String to Float
Bram Moolenaar9d401282019-04-06 13:18:12 +02002616str2list({expr} [, {utf8}]) List convert each character of {expr} to
2617 ASCII/UTF8 value
Bram Moolenaar81edd172016-04-14 13:51:37 +02002618str2nr({expr} [, {base}]) Number convert String to Number
2619strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002620strcharpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002621 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002622strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002623strftime({format} [, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002624strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002625stridx({haystack}, {needle} [, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002626 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002627string({expr}) String String representation of {expr} value
2628strlen({expr}) Number length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002629strpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002630 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002631strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002632 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002633strtrans({expr}) String translate string to make it printable
2634strwidth({expr}) Number display cell length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002635submatch({nr} [, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002636 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002637substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002638 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar00f123a2018-08-21 20:28:54 +02002639swapinfo({fname}) Dict information about swap file {fname}
Bram Moolenaar110bd602018-09-16 18:46:59 +02002640swapname({expr}) String swap file of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002641synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2642synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002643 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002644synIDtrans({synID}) Number translated syntax ID of {synID}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002645synconcealed({lnum}, {col}) List info about concealing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002646synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2647system({expr} [, {input}]) String output of shell command/filter {expr}
2648systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002649tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002650tabpagenr([{arg}]) Number number of current or last tab page
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002651tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
2652taglist({expr} [, {filename}]) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002653tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002654tan({expr}) Float tangent of {expr}
2655tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002656tempname() String name for a temporary file
Bram Moolenaard96ff162018-02-18 22:13:29 +01002657term_dumpdiff({filename}, {filename} [, {options}])
2658 Number display difference between two dumps
2659term_dumpload({filename} [, {options}])
2660 Number displaying a screen dump
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01002661term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01002662 none dump terminal window contents
Bram Moolenaare41e3b42017-08-11 16:24:50 +02002663term_getaltscreen({buf}) Number get the alternate screen flag
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002664term_getansicolors({buf}) List get ANSI palette in GUI color mode
Bram Moolenaar45356542017-08-06 17:53:31 +02002665term_getattr({attr}, {what}) Number get the value of attribute {what}
Bram Moolenaar97870002017-07-30 18:28:38 +02002666term_getcursor({buf}) List get the cursor position of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002667term_getjob({buf}) Job get the job associated with a terminal
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002668term_getline({buf}, {row}) String get a line of text from a terminal
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02002669term_getscrolled({buf}) Number get the scroll count of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002670term_getsize({buf}) List get the size of a terminal
Bram Moolenaarb000e322017-07-30 19:38:21 +02002671term_getstatus({buf}) String get the status of a terminal
2672term_gettitle({buf}) String get the title of a terminal
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002673term_gettty({buf}, [{input}]) String get the tty name of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002674term_list() List get the list of terminal buffers
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002675term_scrape({buf}, {row}) List get row of a terminal screen
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002676term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002677term_setansicolors({buf}, {colors})
2678 none set ANSI palette in GUI color mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002679term_setkill({buf}, {how}) none set signal to stop job in terminal
Bram Moolenaarb5b75622018-03-09 22:22:21 +01002680term_setrestore({buf}, {command}) none set command to restore terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002681term_setsize({buf}, {rows}, {cols})
2682 none set the size of a terminal
Bram Moolenaar911ead12019-04-21 00:03:35 +02002683term_start({cmd} [, {options}]) Number open a terminal window and run a job
Bram Moolenaarf3402b12017-08-06 19:07:08 +02002684term_wait({buf} [, {time}]) Number wait for screen to be updated
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002685test_alloc_fail({id}, {countdown}, {repeat})
2686 none make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02002687test_autochdir() none enable 'autochdir' during startup
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002688test_feedinput({string}) none add key sequence to input buffer
Bram Moolenaar574860b2016-05-24 17:33:34 +02002689test_garbagecollect_now() none free memory right now for testing
Bram Moolenaare0c31f62017-03-01 15:07:05 +01002690test_ignore_error({expr}) none ignore a specific error
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01002691test_null_blob() Blob null value for testing
Bram Moolenaar574860b2016-05-24 17:33:34 +02002692test_null_channel() Channel null value for testing
2693test_null_dict() Dict null value for testing
2694test_null_job() Job null value for testing
2695test_null_list() List null value for testing
2696test_null_partial() Funcref null value for testing
2697test_null_string() String null value for testing
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002698test_option_not_set({name}) none reset flag indicating option was set
2699test_override({expr}, {val}) none test with Vim internal overrides
Bram Moolenaarc3e92c12019-03-23 14:23:07 +01002700test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaarab186732018-09-14 21:27:06 +02002701test_scrollbar({which}, {value}, {dragging})
2702 none scroll in the GUI for testing
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02002703test_setmouse({row}, {col}) none set the mouse position for testing
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002704test_settime({expr}) none set current time for testing
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02002705timer_info([{id}]) List information about timers
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002706timer_pause({id}, {pause}) none pause or unpause a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002707timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002708 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002709timer_stop({timer}) none stop a timer
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002710timer_stopall() none stop all timers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002711tolower({expr}) String the String {expr} switched to lowercase
2712toupper({expr}) String the String {expr} switched to uppercase
2713tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002714 to chars in {tostr}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002715trim({text} [, {mask}]) String trim characters in {mask} from {text}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002716trunc({expr}) Float truncate Float {expr}
2717type({name}) Number type of variable {name}
2718undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002719undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002720uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002721 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002722values({dict}) List values in {dict}
2723virtcol({expr}) Number screen column of cursor or mark
2724visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002725wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar81edd172016-04-14 13:51:37 +02002726win_findbuf({bufnr}) List find windows containing {bufnr}
2727win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2728win_gotoid({expr}) Number go to window with ID {expr}
2729win_id2tabwin({expr}) List get tab and window nr from window ID
2730win_id2win({expr}) Number get window nr from window ID
Bram Moolenaar22044dc2017-12-02 15:43:37 +01002731win_screenpos({nr}) List get screen position of window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002732winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002733wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002734winheight({nr}) Number height of window {nr}
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +02002735winlayout([{tabnr}]) List layout of windows in tab {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002736winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002737winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002738winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002739winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002740winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002741winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002742wordcount() Dict get byte/char/word statistics
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002743writefile({object}, {fname} [, {flags}])
2744 Number write |Blob| or |List| of lines to file
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002745xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002746
Bram Moolenaar03413f42016-04-12 21:07:15 +02002747
Bram Moolenaar446cb832008-06-24 21:56:24 +00002748abs({expr}) *abs()*
2749 Return the absolute value of {expr}. When {expr} evaluates to
2750 a |Float| abs() returns a |Float|. When {expr} can be
2751 converted to a |Number| abs() returns a |Number|. Otherwise
2752 abs() gives an error message and returns -1.
2753 Examples: >
2754 echo abs(1.456)
2755< 1.456 >
2756 echo abs(-5.456)
2757< 5.456 >
2758 echo abs(-4)
2759< 4
2760 {only available when compiled with the |+float| feature}
2761
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002762
2763acos({expr}) *acos()*
2764 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002765 |Float| in the range of [0, pi].
2766 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002767 [-1, 1].
2768 Examples: >
2769 :echo acos(0)
2770< 1.570796 >
2771 :echo acos(-0.5)
2772< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002773 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002774
2775
Bram Moolenaard8968242019-01-15 22:51:57 +01002776add({object}, {expr}) *add()*
2777 Append the item {expr} to |List| or |Blob| {object}. Returns
2778 the resulting |List| or |Blob|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002779 :let alist = add([1, 2, 3], item)
2780 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002781< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002782 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard8968242019-01-15 22:51:57 +01002783 When {object} is a |Blob| then {expr} must be a number.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002784 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002785
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002786
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002787and({expr}, {expr}) *and()*
2788 Bitwise AND on the two arguments. The arguments are converted
2789 to a number. A List, Dict or Float argument causes an error.
2790 Example: >
2791 :let flag = and(bits, 0x80)
2792
2793
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002794append({lnum}, {text}) *append()*
2795 When {text} is a |List|: Append each item of the |List| as a
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002796 text line below line {lnum} in the current buffer.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002797 Otherwise append {text} as one text line below line {lnum} in
Bram Moolenaar748bf032005-02-02 23:04:36 +00002798 the current buffer.
2799 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002800 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar58b85342016-08-14 19:54:54 +02002801 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002802 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002803 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaarca851592018-06-06 21:04:07 +02002804
2805appendbufline({expr}, {lnum}, {text}) *appendbufline()*
2806 Like |append()| but append the text in buffer {expr}.
2807
2808 For the use of {expr}, see |bufname()|.
2809
2810 {lnum} is used like with |append()|. Note that using |line()|
2811 would use the current buffer, not the one appending to.
2812 Use "$" to append at the end of the buffer.
2813
2814 On success 0 is returned, on failure 1 is returned.
2815
2816 If {expr} is not a valid buffer or {lnum} is not valid, an
2817 error message is given. Example: >
2818 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002819<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002820 *argc()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002821argc([{winid}])
2822 The result is the number of files in the argument list. See
2823 |arglist|.
2824 If {winid} is not supplied, the argument list of the current
2825 window is used.
2826 If {winid} is -1, the global argument list is used.
2827 Otherwise {winid} specifies the window of which the argument
2828 list is used: either the window number or the window ID.
2829 Returns -1 if the {winid} argument is invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002830
2831 *argidx()*
2832argidx() The result is the current index in the argument list. 0 is
2833 the first file. argc() - 1 is the last one. See |arglist|.
2834
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002835 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002836arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002837 Return the argument list ID. This is a number which
2838 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002839 global argument list. See |arglist|.
Bram Moolenaare6e39892018-10-25 12:32:11 +02002840 Returns -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002841
2842 Without arguments use the current window.
2843 With {winnr} only use this window in the current tab page.
2844 With {winnr} and {tabnr} use the window in the specified tab
2845 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002846 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002847
Bram Moolenaar071d4272004-06-13 20:20:40 +00002848 *argv()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002849argv([{nr} [, {winid}])
2850 The result is the {nr}th file in the argument list. See
2851 |arglist|. "argv(0)" is the first one. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002852 :let i = 0
2853 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002854 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002855 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2856 : let i = i + 1
2857 :endwhile
Bram Moolenaare6e39892018-10-25 12:32:11 +02002858< Without the {nr} argument, or when {nr} is -1, a |List| with
2859 the whole |arglist| is returned.
2860
2861 The {winid} argument specifies the window ID, see |argc()|.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002862
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002863assert_beeps({cmd}) *assert_beeps()*
2864 Run {cmd} and add an error message to |v:errors| if it does
2865 NOT produce a beep or visual bell.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002866 Also see |assert_fails()| and |assert-return|.
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002867
Bram Moolenaar683fa182015-11-30 21:38:24 +01002868 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002869assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002870 When {expected} and {actual} are not equal an error message is
Bram Moolenaar65a54642018-04-28 16:56:53 +02002871 added to |v:errors| and 1 is returned. Otherwise zero is
2872 returned |assert-return|.
Bram Moolenaar43345542015-11-29 17:35:35 +01002873 There is no automatic conversion, the String "4" is different
2874 from the Number 4. And the number 4 is different from the
2875 Float 4.0. The value of 'ignorecase' is not used here, case
2876 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002877 When {msg} is omitted an error in the form "Expected
2878 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002879 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002880 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002881< Will result in a string to be added to |v:errors|:
2882 test.vim line 12: Expected 'foo' but got 'bar' ~
2883
Bram Moolenaard96ff162018-02-18 22:13:29 +01002884 *assert_equalfile()*
2885assert_equalfile({fname-one}, {fname-two})
2886 When the files {fname-one} and {fname-two} do not contain
2887 exactly the same text an error message is added to |v:errors|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002888 Also see |assert-return|.
Bram Moolenaard96ff162018-02-18 22:13:29 +01002889 When {fname-one} or {fname-two} does not exist the error will
2890 mention that.
2891 Mainly useful with |terminal-diff|.
2892
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002893assert_exception({error} [, {msg}]) *assert_exception()*
2894 When v:exception does not contain the string {error} an error
Bram Moolenaar65a54642018-04-28 16:56:53 +02002895 message is added to |v:errors|. Also see |assert-return|.
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002896 This can be used to assert that a command throws an exception.
2897 Using the error number, followed by a colon, avoids problems
2898 with translations: >
2899 try
2900 commandthatfails
2901 call assert_false(1, 'command should have failed')
2902 catch
2903 call assert_exception('E492:')
2904 endtry
2905
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002906assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()*
Bram Moolenaara260b872016-01-15 20:48:22 +01002907 Run {cmd} and add an error message to |v:errors| if it does
Bram Moolenaar65a54642018-04-28 16:56:53 +02002908 NOT produce an error. Also see |assert-return|.
Bram Moolenaar25de4c22016-11-06 14:48:06 +01002909 When {error} is given it must match in |v:errmsg|.
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002910 Note that beeping is not considered an error, and some failing
2911 commands only beep. Use |assert_beeps()| for those.
Bram Moolenaara260b872016-01-15 20:48:22 +01002912
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002913assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002914 When {actual} is not false an error message is added to
Bram Moolenaar9d87a372018-12-18 21:41:50 +01002915 |v:errors|, like with |assert_equal()|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002916 Also see |assert-return|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002917 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002918 number the assert fails.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002919 When {msg} is omitted an error in the form
2920 "Expected False but got {actual}" is produced.
2921
2922assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()*
Bram Moolenaarf6b40102019-02-22 15:24:03 +01002923 This asserts number and |Float| values. When {actual} is lower
2924 than {lower} or higher than {upper} an error message is added
2925 to |v:errors|. Also see |assert-return|.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002926 When {msg} is omitted an error in the form
2927 "Expected range {lower} - {upper}, but got {actual}" is
2928 produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002929
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002930 *assert_match()*
2931assert_match({pattern}, {actual} [, {msg}])
2932 When {pattern} does not match {actual} an error message is
Bram Moolenaar65a54642018-04-28 16:56:53 +02002933 added to |v:errors|. Also see |assert-return|.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002934
2935 {pattern} is used as with |=~|: The matching is always done
2936 like 'magic' was set and 'cpoptions' is empty, no matter what
2937 the actual value of 'magic' or 'cpoptions' is.
2938
2939 {actual} is used as a string, automatic conversion applies.
2940 Use "^" and "$" to match with the start and end of the text.
2941 Use both to match the whole text.
2942
Bram Moolenaar61c04492016-07-23 15:35:35 +02002943 When {msg} is omitted an error in the form
2944 "Pattern {pattern} does not match {actual}" is produced.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002945 Example: >
2946 assert_match('^f.*o$', 'foobar')
2947< Will result in a string to be added to |v:errors|:
2948 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
2949
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002950 *assert_notequal()*
2951assert_notequal({expected}, {actual} [, {msg}])
2952 The opposite of `assert_equal()`: add an error message to
2953 |v:errors| when {expected} and {actual} are equal.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002954 Also see |assert-return|.
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002955
2956 *assert_notmatch()*
2957assert_notmatch({pattern}, {actual} [, {msg}])
2958 The opposite of `assert_match()`: add an error message to
2959 |v:errors| when {pattern} matches {actual}.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002960 Also see |assert-return|.
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002961
Bram Moolenaar42205552017-03-18 19:42:22 +01002962assert_report({msg}) *assert_report()*
2963 Report a test failure directly, using {msg}.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002964 Always returns one.
Bram Moolenaar42205552017-03-18 19:42:22 +01002965
2966assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002967 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002968 |v:errors|, like with |assert_equal()|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002969 Also see |assert-return|.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002970 A value is TRUE when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002971 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002972 When {msg} is omitted an error in the form "Expected True but
2973 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002974
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002975asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002976 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002977 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002978 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002979 [-1, 1].
2980 Examples: >
2981 :echo asin(0.8)
2982< 0.927295 >
2983 :echo asin(-0.5)
2984< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002985 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002986
2987
Bram Moolenaar446cb832008-06-24 21:56:24 +00002988atan({expr}) *atan()*
2989 Return the principal value of the arc tangent of {expr}, in
2990 the range [-pi/2, +pi/2] radians, as a |Float|.
2991 {expr} must evaluate to a |Float| or a |Number|.
2992 Examples: >
2993 :echo atan(100)
2994< 1.560797 >
2995 :echo atan(-4.01)
2996< -1.326405
2997 {only available when compiled with the |+float| feature}
2998
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002999
3000atan2({expr1}, {expr2}) *atan2()*
3001 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003002 radians, as a |Float| in the range [-pi, pi].
3003 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003004 Examples: >
3005 :echo atan2(-1, 1)
3006< -0.785398 >
3007 :echo atan2(1, -1)
3008< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02003009 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003010
Bram Moolenaar246fe032017-11-19 19:56:27 +01003011balloon_show({expr}) *balloon_show()*
3012 Show {expr} inside the balloon. For the GUI {expr} is used as
3013 a string. For a terminal {expr} can be a list, which contains
3014 the lines of the balloon. If {expr} is not a list it will be
3015 split with |balloon_split()|.
3016
Bram Moolenaar214641f2017-03-05 17:04:09 +01003017 Example: >
Bram Moolenaar59716a22017-03-01 20:32:44 +01003018 func GetBalloonContent()
3019 " initiate getting the content
3020 return ''
3021 endfunc
3022 set balloonexpr=GetBalloonContent()
3023
3024 func BalloonCallback(result)
Bram Moolenaar214641f2017-03-05 17:04:09 +01003025 call balloon_show(a:result)
Bram Moolenaar59716a22017-03-01 20:32:44 +01003026 endfunc
3027<
3028 The intended use is that fetching the content of the balloon
3029 is initiated from 'balloonexpr'. It will invoke an
3030 asynchronous method, in which a callback invokes
3031 balloon_show(). The 'balloonexpr' itself can return an
3032 empty string or a placeholder.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003033
3034 When showing a balloon is not possible nothing happens, no
3035 error message.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003036 {only available when compiled with the |+balloon_eval| or
3037 |+balloon_eval_term| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003038
Bram Moolenaar246fe032017-11-19 19:56:27 +01003039balloon_split({msg}) *balloon_split()*
3040 Split {msg} into lines to be displayed in a balloon. The
3041 splits are made for the current window size and optimize to
3042 show debugger output.
3043 Returns a |List| with the split lines.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003044 {only available when compiled with the |+balloon_eval_term|
Bram Moolenaar669a8282017-11-19 20:13:05 +01003045 feature}
Bram Moolenaar246fe032017-11-19 19:56:27 +01003046
Bram Moolenaar071d4272004-06-13 20:20:40 +00003047 *browse()*
3048browse({save}, {title}, {initdir}, {default})
3049 Put up a file requester. This only works when "has("browse")"
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003050 returns |TRUE| (only in some GUI versions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003051 The input fields are:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003052 {save} when |TRUE|, select file to write
Bram Moolenaar071d4272004-06-13 20:20:40 +00003053 {title} title for the requester
3054 {initdir} directory to start browsing in
3055 {default} default file name
3056 When the "Cancel" button is hit, something went wrong, or
3057 browsing is not possible, an empty string is returned.
3058
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003059 *browsedir()*
3060browsedir({title}, {initdir})
3061 Put up a directory requester. This only works when
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003062 "has("browse")" returns |TRUE| (only in some GUI versions).
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003063 On systems where a directory browser is not supported a file
3064 browser is used. In that case: select a file in the directory
3065 to be used.
3066 The input fields are:
3067 {title} title for the requester
3068 {initdir} directory to start browsing in
3069 When the "Cancel" button is hit, something went wrong, or
3070 browsing is not possible, an empty string is returned.
3071
Bram Moolenaar071d4272004-06-13 20:20:40 +00003072bufexists({expr}) *bufexists()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003073 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003074 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003075 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaara2a80162017-11-21 23:09:50 +01003076 Number zero is the alternate buffer for the current window.
3077
Bram Moolenaar071d4272004-06-13 20:20:40 +00003078 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003079 exactly. The name can be:
3080 - Relative to the current directory.
3081 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003082 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003083 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003084 Unlisted buffers will be found.
3085 Note that help files are listed by their short name in the
3086 output of |:buffers|, but bufexists() requires using their
3087 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003088 bufexists() may report a buffer exists, but to use the name
3089 with a |:buffer| command you may need to use |expand()|. Esp
3090 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003091 Use "bufexists(0)" to test for the existence of an alternate
3092 file name.
3093 *buffer_exists()*
3094 Obsolete name: buffer_exists().
3095
3096buflisted({expr}) *buflisted()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003097 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003098 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003099 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003100
3101bufloaded({expr}) *bufloaded()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003102 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003103 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003104 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003105
3106bufname({expr}) *bufname()*
3107 The result is the name of a buffer, as it is displayed by the
3108 ":ls" command.
3109 If {expr} is a Number, that buffer number's name is given.
3110 Number zero is the alternate buffer for the current window.
3111 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar58b85342016-08-14 19:54:54 +02003112 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003113 set and 'cpoptions' is empty. When there is more than one
3114 match an empty string is returned.
3115 "" or "%" can be used for the current buffer, "#" for the
3116 alternate buffer.
3117 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003118 or middle of the buffer name is accepted. If you only want a
3119 full match then put "^" at the start and "$" at the end of the
3120 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003121 Listed buffers are found first. If there is a single match
3122 with a listed buffer, that one is returned. Next unlisted
3123 buffers are searched for.
3124 If the {expr} is a String, but you want to use it as a buffer
3125 number, force it to be a Number by adding zero to it: >
3126 :echo bufname("3" + 0)
3127< If the buffer doesn't exist, or doesn't have a name, an empty
3128 string is returned. >
3129 bufname("#") alternate buffer name
3130 bufname(3) name of buffer 3
3131 bufname("%") name of current buffer
3132 bufname("file2") name of buffer where "file2" matches.
3133< *buffer_name()*
3134 Obsolete name: buffer_name().
3135
3136 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003137bufnr({expr} [, {create}])
3138 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00003139 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003140 above.
3141 If the buffer doesn't exist, -1 is returned. Or, if the
3142 {create} argument is present and not zero, a new, unlisted,
3143 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003144 bufnr("$") is the last buffer: >
3145 :let last_buffer = bufnr("$")
3146< The result is a Number, which is the highest buffer number
3147 of existing buffers. Note that not all buffers with a smaller
3148 number necessarily exist, because ":bwipeout" may have removed
3149 them. Use bufexists() to test for the existence of a buffer.
3150 *buffer_number()*
3151 Obsolete name: buffer_number().
3152 *last_buffer_nr()*
3153 Obsolete name for bufnr("$"): last_buffer_nr().
3154
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003155bufwinid({expr}) *bufwinid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02003156 The result is a Number, which is the |window-ID| of the first
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003157 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003158 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003159 there is no such window, -1 is returned. Example: >
3160
3161 echo "A window containing buffer 1 is " . (bufwinid(1))
3162<
3163 Only deals with the current tab page.
3164
Bram Moolenaar071d4272004-06-13 20:20:40 +00003165bufwinnr({expr}) *bufwinnr()*
3166 The result is a Number, which is the number of the first
3167 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003168 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00003169 there is no such window, -1 is returned. Example: >
3170
3171 echo "A window containing buffer 1 is " . (bufwinnr(1))
3172
3173< The number can be used with |CTRL-W_w| and ":wincmd w"
3174 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003175 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003176
Bram Moolenaar071d4272004-06-13 20:20:40 +00003177byte2line({byte}) *byte2line()*
3178 Return the line number that contains the character at byte
3179 count {byte} in the current buffer. This includes the
3180 end-of-line character, depending on the 'fileformat' option
3181 for the current buffer. The first character has byte count
3182 one.
3183 Also see |line2byte()|, |go| and |:goto|.
3184 {not available when compiled without the |+byte_offset|
3185 feature}
3186
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003187byteidx({expr}, {nr}) *byteidx()*
3188 Return byte index of the {nr}'th character in the string
3189 {expr}. Use zero for the first character, it returns zero.
3190 This function is only useful when there are multibyte
3191 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003192 Composing characters are not counted separately, their byte
3193 length is added to the preceding base character. See
3194 |byteidxcomp()| below for counting composing characters
3195 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003196 Example : >
3197 echo matchstr(str, ".", byteidx(str, 3))
3198< will display the fourth character. Another way to do the
3199 same: >
3200 let s = strpart(str, byteidx(str, 3))
3201 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003202< Also see |strgetchar()| and |strcharpart()|.
3203
3204 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003205 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003206 in bytes is returned.
3207
3208byteidxcomp({expr}, {nr}) *byteidxcomp()*
3209 Like byteidx(), except that a composing character is counted
3210 as a separate character. Example: >
3211 let s = 'e' . nr2char(0x301)
3212 echo byteidx(s, 1)
3213 echo byteidxcomp(s, 1)
3214 echo byteidxcomp(s, 2)
3215< The first and third echo result in 3 ('e' plus composing
3216 character is 3 bytes), the second echo results in 1 ('e' is
3217 one byte).
3218 Only works different from byteidx() when 'encoding' is set to
3219 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003220
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003221call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003222 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003223 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003224 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003225 a:firstline and a:lastline are set to the cursor line.
3226 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003227 {dict} is for functions with the "dict" attribute. It will be
3228 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003229
Bram Moolenaar446cb832008-06-24 21:56:24 +00003230ceil({expr}) *ceil()*
3231 Return the smallest integral value greater than or equal to
3232 {expr} as a |Float| (round up).
3233 {expr} must evaluate to a |Float| or a |Number|.
3234 Examples: >
3235 echo ceil(1.456)
3236< 2.0 >
3237 echo ceil(-5.456)
3238< -5.0 >
3239 echo ceil(4.0)
3240< 4.0
3241 {only available when compiled with the |+float| feature}
3242
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003243ch_canread({handle}) *ch_canread()*
3244 Return non-zero when there is something to read from {handle}.
3245 {handle} can be a Channel or a Job that has a Channel.
3246
3247 This is useful to read from a channel at a convenient time,
3248 e.g. from a timer.
3249
3250 Note that messages are dropped when the channel does not have
3251 a callback. Add a close callback to avoid that.
3252
3253 {only available when compiled with the |+channel| feature}
3254
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003255ch_close({handle}) *ch_close()*
3256 Close {handle}. See |channel-close|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003257 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02003258 A close callback is not invoked.
3259
3260 {only available when compiled with the |+channel| feature}
3261
3262ch_close_in({handle}) *ch_close_in()*
3263 Close the "in" part of {handle}. See |channel-close-in|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003264 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02003265 A close callback is not invoked.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003266
Bram Moolenaar835dc632016-02-07 14:27:38 +01003267 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003268
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003269ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
3270 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003271 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01003272 with a raw channel. See |channel-use|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003273 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003274 *E917*
3275 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003276 entry. It can have a "timeout" entry to specify the timeout
3277 for this specific request.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003278
3279 ch_evalexpr() waits for a response and returns the decoded
3280 expression. When there is an error or timeout it returns an
3281 empty string.
3282
3283 {only available when compiled with the |+channel| feature}
3284
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003285ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
3286 Send {string} over {handle}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003287 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003288
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003289 Works like |ch_evalexpr()|, but does not encode the request or
3290 decode the response. The caller is responsible for the
3291 correct contents. Also does not add a newline for a channel
3292 in NL mode, the caller must do that. The NL in the response
3293 is removed.
Bram Moolenaar01164a62017-11-02 22:58:42 +01003294 Note that Vim does not know when the text received on a raw
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003295 channel is complete, it may only return the first part and you
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01003296 need to use |ch_readraw()| to fetch the rest.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003297 See |channel-use|.
3298
3299 {only available when compiled with the |+channel| feature}
3300
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003301ch_getbufnr({handle}, {what}) *ch_getbufnr()*
3302 Get the buffer number that {handle} is using for {what}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003303 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01003304 {what} can be "err" for stderr, "out" for stdout or empty for
3305 socket output.
3306 Returns -1 when there is no buffer.
3307 {only available when compiled with the |+channel| feature}
3308
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003309ch_getjob({channel}) *ch_getjob()*
3310 Get the Job associated with {channel}.
3311 If there is no job calling |job_status()| on the returned Job
3312 will result in "fail".
3313
3314 {only available when compiled with the |+channel| and
3315 |+job| features}
3316
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003317ch_info({handle}) *ch_info()*
3318 Returns a Dictionary with information about {handle}. The
3319 items are:
3320 "id" number of the channel
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003321 "status" "open", "buffered" or "closed", like
3322 ch_status()
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003323 When opened with ch_open():
3324 "hostname" the hostname of the address
3325 "port" the port of the address
3326 "sock_status" "open" or "closed"
3327 "sock_mode" "NL", "RAW", "JSON" or "JS"
3328 "sock_io" "socket"
3329 "sock_timeout" timeout in msec
3330 When opened with job_start():
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003331 "out_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003332 "out_mode" "NL", "RAW", "JSON" or "JS"
3333 "out_io" "null", "pipe", "file" or "buffer"
3334 "out_timeout" timeout in msec
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003335 "err_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003336 "err_mode" "NL", "RAW", "JSON" or "JS"
3337 "err_io" "out", "null", "pipe", "file" or "buffer"
3338 "err_timeout" timeout in msec
3339 "in_status" "open" or "closed"
3340 "in_mode" "NL", "RAW", "JSON" or "JS"
3341 "in_io" "null", "pipe", "file" or "buffer"
3342 "in_timeout" timeout in msec
3343
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003344ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003345 Write {msg} in the channel log file, if it was opened with
3346 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003347 When {handle} is passed the channel number is used for the
3348 message.
Bram Moolenaar51628222016-12-01 23:03:28 +01003349 {handle} can be a Channel or a Job that has a Channel. The
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02003350 Channel must be open for the channel number to be used.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003351
3352ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003353 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003354 When {fname} is an empty string: stop logging.
3355
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003356 When {mode} is omitted or "a" append to the file.
3357 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003358
Bram Moolenaar98aefe72018-12-13 22:20:09 +01003359 Use |ch_log()| to write log messages. The file is flushed
3360 after every message, on Unix you can use "tail -f" to see what
3361 is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003362
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02003363 This function is not available in the |sandbox|.
3364 NOTE: the channel communication is stored in the file, be
3365 aware that this may contain confidential and privacy sensitive
3366 information, e.g. a password you type in a terminal window.
3367
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003368
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003369ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003370 Open a channel to {address}. See |channel|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003371 Returns a Channel. Use |ch_status()| to check for failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003372
3373 {address} has the form "hostname:port", e.g.,
3374 "localhost:8765".
3375
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003376 If {options} is given it must be a |Dictionary|.
3377 See |channel-open-options|.
3378
Bram Moolenaar835dc632016-02-07 14:27:38 +01003379 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003380
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003381ch_read({handle} [, {options}]) *ch_read()*
3382 Read from {handle} and return the received message.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003383 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar74240d32017-12-10 15:26:15 +01003384 For a NL channel this waits for a NL to arrive, except when
3385 there is nothing more to read (channel was closed).
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003386 See |channel-more|.
3387 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003388
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003389ch_readblob({handle} [, {options}]) *ch_readblob()*
Bram Moolenaard09091d2019-01-17 16:07:22 +01003390 Like ch_read() but reads binary data and returns a |Blob|.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003391 See |channel-more|.
3392 {only available when compiled with the |+channel| feature}
3393
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003394ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003395 Like ch_read() but for a JS and JSON channel does not decode
Bram Moolenaar74240d32017-12-10 15:26:15 +01003396 the message. For a NL channel it does not block waiting for
3397 the NL to arrive, but otherwise works like ch_read().
3398 See |channel-more|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003399 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003400
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003401ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
3402 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003403 according to the type of channel. The function cannot be used
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003404 with a raw channel.
3405 See |channel-use|. *E912*
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003406 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003407
Bram Moolenaar835dc632016-02-07 14:27:38 +01003408 {only available when compiled with the |+channel| feature}
3409
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003410ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
Bram Moolenaard09091d2019-01-17 16:07:22 +01003411 Send |String| or |Blob| {expr} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003412 Works like |ch_sendexpr()|, but does not encode the request or
3413 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01003414 correct contents. Also does not add a newline for a channel
3415 in NL mode, the caller must do that. The NL in the response
3416 is removed.
3417 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003418
Bram Moolenaar835dc632016-02-07 14:27:38 +01003419 {only available when compiled with the |+channel| feature}
3420
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003421ch_setoptions({handle}, {options}) *ch_setoptions()*
3422 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003423 "callback" the channel callback
3424 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003425 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003426 See |ch_open()| for more explanation.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003427 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003428
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003429 Note that changing the mode may cause queued messages to be
3430 lost.
3431
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003432 These options cannot be changed:
Bram Moolenaar7571d552016-08-18 22:54:46 +02003433 "waittime" only applies to |ch_open()|
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003434
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003435ch_status({handle} [, {options}]) *ch_status()*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003436 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01003437 "fail" failed to open the channel
3438 "open" channel can be used
Bram Moolenaar06481422016-04-30 15:13:38 +02003439 "buffered" channel can be read, not written to
Bram Moolenaar38a55632016-02-15 22:07:32 +01003440 "closed" channel can not be used
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003441 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar06481422016-04-30 15:13:38 +02003442 "buffered" is used when the channel was closed but there is
3443 still data that can be obtained with |ch_read()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003444
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003445 If {options} is given it can contain a "part" entry to specify
3446 the part of the channel to return the status for: "out" or
3447 "err". For example, to get the error status: >
3448 ch_status(job, {"part": "err"})
3449<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003450changenr() *changenr()*
3451 Return the number of the most recent change. This is the same
3452 number as what is displayed with |:undolist| and can be used
3453 with the |:undo| command.
3454 When a change was made it is the number of that change. After
3455 redo it is the number of the redone change. After undo it is
3456 one less than the number of the undone change.
3457
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003458char2nr({expr} [, {utf8}]) *char2nr()*
Bram Moolenaar214641f2017-03-05 17:04:09 +01003459 Return number value of the first char in {expr}. Examples: >
3460 char2nr(" ") returns 32
3461 char2nr("ABC") returns 65
3462< When {utf8} is omitted or zero, the current 'encoding' is used.
3463 Example for "utf-8": >
Bram Moolenaar98ef2332018-03-18 14:44:37 +01003464 char2nr("á") returns 225
3465 char2nr("á"[0]) returns 195
Bram Moolenaar214641f2017-03-05 17:04:09 +01003466< With {utf8} set to 1, always treat as utf-8 characters.
3467 A combining character is a separate character.
3468 |nr2char()| does the opposite.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003469 To turn a string into a list of character numbers: >
3470 let str = "ABC"
3471 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
3472< Result: [65, 66, 67]
Bram Moolenaar214641f2017-03-05 17:04:09 +01003473
3474cindent({lnum}) *cindent()*
3475 Get the amount of indent for line {lnum} according the C
3476 indenting rules, as with 'cindent'.
3477 The indent is counted in spaces, the value of 'tabstop' is
3478 relevant. {lnum} is used just like in |getline()|.
3479 When {lnum} is invalid or Vim was not compiled the |+cindent|
3480 feature, -1 is returned.
3481 See |C-indenting|.
3482
Bram Moolenaaraff74912019-03-30 18:11:49 +01003483clearmatches([{win}]) *clearmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01003484 Clears all matches previously defined for the current window
3485 by |matchadd()| and the |:match| commands.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003486 If {win} is specified, use the window with this number or
3487 window ID instead of the current window.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003488
3489 *col()*
3490col({expr}) The result is a Number, which is the byte index of the column
3491 position given with {expr}. The accepted positions are:
3492 . the cursor position
3493 $ the end of the cursor line (the result is the
3494 number of bytes in the cursor line plus one)
3495 'x position of mark x (if the mark is not set, 0 is
3496 returned)
3497 v In Visual mode: the start of the Visual area (the
3498 cursor is the end). When not in Visual mode
3499 returns the cursor position. Differs from |'<| in
3500 that it's updated right away.
3501 Additionally {expr} can be [lnum, col]: a |List| with the line
3502 and column number. Most useful when the column is "$", to get
3503 the last column of a specific line. When "lnum" or "col" is
3504 out of range then col() returns zero.
3505 To get the line number use |line()|. To get both use
3506 |getpos()|.
3507 For the screen column position use |virtcol()|.
3508 Note that only marks in the current file can be used.
3509 Examples: >
3510 col(".") column of cursor
3511 col("$") length of cursor line plus one
3512 col("'t") column of mark t
3513 col("'" . markname) column of mark markname
3514< The first column is 1. 0 is returned for an error.
3515 For an uppercase mark the column may actually be in another
3516 buffer.
3517 For the cursor position, when 'virtualedit' is active, the
3518 column is one higher if the cursor is after the end of the
3519 line. This can be used to obtain the column in Insert mode: >
3520 :imap <F2> <C-O>:let save_ve = &ve<CR>
3521 \<C-O>:set ve=all<CR>
3522 \<C-O>:echo col(".") . "\n" <Bar>
3523 \let &ve = save_ve<CR>
3524<
3525
3526complete({startcol}, {matches}) *complete()* *E785*
3527 Set the matches for Insert mode completion.
3528 Can only be used in Insert mode. You need to use a mapping
3529 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3530 or with an expression mapping.
3531 {startcol} is the byte offset in the line where the completed
3532 text start. The text up to the cursor is the original text
3533 that will be replaced by the matches. Use col('.') for an
3534 empty string. "col('.') - 1" will replace one character by a
3535 match.
3536 {matches} must be a |List|. Each |List| item is one match.
3537 See |complete-items| for the kind of items that are possible.
3538 Note that the after calling this function you need to avoid
3539 inserting anything that would cause completion to stop.
3540 The match can be selected with CTRL-N and CTRL-P as usual with
3541 Insert mode completion. The popup menu will appear if
3542 specified, see |ins-completion-menu|.
3543 Example: >
3544 inoremap <F5> <C-R>=ListMonths()<CR>
3545
3546 func! ListMonths()
3547 call complete(col('.'), ['January', 'February', 'March',
3548 \ 'April', 'May', 'June', 'July', 'August', 'September',
3549 \ 'October', 'November', 'December'])
3550 return ''
3551 endfunc
3552< This isn't very useful, but it shows how it works. Note that
3553 an empty string is returned to avoid a zero being inserted.
3554
3555complete_add({expr}) *complete_add()*
3556 Add {expr} to the list of matches. Only to be used by the
3557 function specified with the 'completefunc' option.
3558 Returns 0 for failure (empty string or out of memory),
3559 1 when the match was added, 2 when the match was already in
3560 the list.
3561 See |complete-functions| for an explanation of {expr}. It is
3562 the same as one item in the list that 'omnifunc' would return.
3563
3564complete_check() *complete_check()*
3565 Check for a key typed while looking for completion matches.
3566 This is to be used when looking for matches takes some time.
3567 Returns |TRUE| when searching for matches is to be aborted,
3568 zero otherwise.
3569 Only to be used by the function specified with the
3570 'completefunc' option.
3571
Bram Moolenaarfd133322019-03-29 12:20:27 +01003572 *complete_info()*
3573complete_info([{what}])
3574 Returns a Dictionary with information about Insert mode
3575 completion. See |ins-completion|.
3576 The items are:
3577 mode Current completion mode name string.
Bram Moolenaar723dd942019-04-04 13:11:03 +02003578 See |complete_info_mode| for the values.
Bram Moolenaarfd133322019-03-29 12:20:27 +01003579 pum_visible |TRUE| if popup menu is visible.
3580 See |pumvisible()|.
3581 items List of completion matches. Each item is a
3582 dictionary containing the entries "word",
3583 "abbr", "menu", "kind", "info" and "user_data".
3584 See |complete-items|.
3585 selected Selected item index. First index is zero.
3586 Index is -1 if no item is selected (showing
3587 typed text only)
3588 inserted Inserted string. [NOT IMPLEMENT YET]
3589
3590 *complete_info_mode*
3591 mode values are:
3592 "" Not in completion mode
3593 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
3594 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
3595 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
3596 "files" File names |i_CTRL-X_CTRL-F|
3597 "tags" Tags |i_CTRL-X_CTRL-]|
3598 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
3599 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
3600 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
3601 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
3602 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
3603 "function" User defined completion |i_CTRL-X_CTRL-U|
3604 "omni" Omni completion |i_CTRL-X_CTRL-O|
3605 "spell" Spelling suggestions |i_CTRL-X_s|
3606 "eval" |complete()| completion
3607 "unknown" Other internal modes
3608
3609 If the optional {what} list argument is supplied, then only
3610 the items listed in {what} are returned. Unsupported items in
3611 {what} are silently ignored.
3612
3613 Examples: >
3614 " Get all items
3615 call complete_info()
3616 " Get only 'mode'
3617 call complete_info(['mode'])
3618 " Get only 'mode' and 'pum_visible'
3619 call complete_info(['mode', 'pum_visible'])
3620<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003621 *confirm()*
3622confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar647e24b2019-03-17 16:39:46 +01003623 confirm() offers the user a dialog, from which a choice can be
Bram Moolenaar214641f2017-03-05 17:04:09 +01003624 made. It returns the number of the choice. For the first
3625 choice this is 1.
3626 Note: confirm() is only supported when compiled with dialog
3627 support, see |+dialog_con| and |+dialog_gui|.
3628
3629 {msg} is displayed in a |dialog| with {choices} as the
3630 alternatives. When {choices} is missing or empty, "&OK" is
3631 used (and translated).
3632 {msg} is a String, use '\n' to include a newline. Only on
3633 some systems the string is wrapped when it doesn't fit.
3634
3635 {choices} is a String, with the individual choices separated
3636 by '\n', e.g. >
3637 confirm("Save changes?", "&Yes\n&No\n&Cancel")
3638< The letter after the '&' is the shortcut key for that choice.
3639 Thus you can type 'c' to select "Cancel". The shortcut does
3640 not need to be the first letter: >
3641 confirm("file has been modified", "&Save\nSave &All")
3642< For the console, the first letter of each choice is used as
3643 the default shortcut key.
3644
3645 The optional {default} argument is the number of the choice
3646 that is made if the user hits <CR>. Use 1 to make the first
3647 choice the default one. Use 0 to not set a default. If
3648 {default} is omitted, 1 is used.
3649
3650 The optional {type} argument gives the type of dialog. This
3651 is only used for the icon of the GTK, Mac, Motif and Win32
3652 GUI. It can be one of these values: "Error", "Question",
3653 "Info", "Warning" or "Generic". Only the first character is
3654 relevant. When {type} is omitted, "Generic" is used.
3655
3656 If the user aborts the dialog by pressing <Esc>, CTRL-C,
3657 or another valid interrupt key, confirm() returns 0.
3658
3659 An example: >
3660 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
3661 :if choice == 0
3662 : echo "make up your mind!"
3663 :elseif choice == 3
3664 : echo "tasteful"
3665 :else
3666 : echo "I prefer bananas myself."
3667 :endif
3668< In a GUI dialog, buttons are used. The layout of the buttons
3669 depends on the 'v' flag in 'guioptions'. If it is included,
3670 the buttons are always put vertically. Otherwise, confirm()
3671 tries to put the buttons in one horizontal line. If they
3672 don't fit, a vertical layout is used anyway. For some systems
3673 the horizontal layout is always used.
3674
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003675 *copy()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003676copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003677 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003678 When {expr} is a |List| a shallow copy is created. This means
3679 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003680 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003681 changing an item changes the contents of both |Lists|.
3682 A |Dictionary| is copied in a similar way as a |List|.
3683 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003684
Bram Moolenaar446cb832008-06-24 21:56:24 +00003685cos({expr}) *cos()*
3686 Return the cosine of {expr}, measured in radians, as a |Float|.
3687 {expr} must evaluate to a |Float| or a |Number|.
3688 Examples: >
3689 :echo cos(100)
3690< 0.862319 >
3691 :echo cos(-4.01)
3692< -0.646043
3693 {only available when compiled with the |+float| feature}
3694
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003695
3696cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003697 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003698 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003699 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003700 Examples: >
3701 :echo cosh(0.5)
3702< 1.127626 >
3703 :echo cosh(-0.5)
3704< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02003705 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003706
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003707
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003708count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003709 Return the number of times an item with value {expr} appears
Bram Moolenaar9966b212017-07-28 16:46:57 +02003710 in |String|, |List| or |Dictionary| {comp}.
3711
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003712 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003713 {start} can only be used with a |List|.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003714
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003715 When {ic} is given and it's |TRUE| then case is ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003716
Bram Moolenaar9966b212017-07-28 16:46:57 +02003717 When {comp} is a string then the number of not overlapping
Bram Moolenaar338e47f2017-12-19 11:55:26 +01003718 occurrences of {expr} is returned. Zero is returned when
3719 {expr} is an empty string.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003720
Bram Moolenaar071d4272004-06-13 20:20:40 +00003721 *cscope_connection()*
3722cscope_connection([{num} , {dbpath} [, {prepend}]])
3723 Checks for the existence of a |cscope| connection. If no
3724 parameters are specified, then the function returns:
3725 0, if cscope was not available (not compiled in), or
3726 if there are no cscope connections;
3727 1, if there is at least one cscope connection.
3728
3729 If parameters are specified, then the value of {num}
3730 determines how existence of a cscope connection is checked:
3731
3732 {num} Description of existence check
3733 ----- ------------------------------
3734 0 Same as no parameters (e.g., "cscope_connection()").
3735 1 Ignore {prepend}, and use partial string matches for
3736 {dbpath}.
3737 2 Ignore {prepend}, and use exact string matches for
3738 {dbpath}.
3739 3 Use {prepend}, use partial string matches for both
3740 {dbpath} and {prepend}.
3741 4 Use {prepend}, use exact string matches for both
3742 {dbpath} and {prepend}.
3743
3744 Note: All string comparisons are case sensitive!
3745
3746 Examples. Suppose we had the following (from ":cs show"): >
3747
3748 # pid database name prepend path
3749 0 27664 cscope.out /usr/local
3750<
3751 Invocation Return Val ~
3752 ---------- ---------- >
3753 cscope_connection() 1
3754 cscope_connection(1, "out") 1
3755 cscope_connection(2, "out") 0
3756 cscope_connection(3, "out") 0
3757 cscope_connection(3, "out", "local") 1
3758 cscope_connection(4, "out") 0
3759 cscope_connection(4, "out", "local") 0
3760 cscope_connection(4, "cscope.out", "/usr/local") 1
3761<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003762cursor({lnum}, {col} [, {off}]) *cursor()*
3763cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003764 Positions the cursor at the column (byte count) {col} in the
3765 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003766
Bram Moolenaar0b238792006-03-02 22:49:12 +00003767 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003768 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003769 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003770 [{lnum}, {col}, {off}]
3771 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003772 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003773 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003774
Bram Moolenaar071d4272004-06-13 20:20:40 +00003775 Does not change the jumplist.
3776 If {lnum} is greater than the number of lines in the buffer,
3777 the cursor will be positioned at the last line in the buffer.
3778 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003779 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003780 the cursor will be positioned at the last character in the
3781 line.
3782 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003783 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003784 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003785
Bram Moolenaar0b238792006-03-02 22:49:12 +00003786 When 'virtualedit' is used {off} specifies the offset in
3787 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003788 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003789 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003790
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02003791debugbreak({pid}) *debugbreak()*
3792 Specifically used to interrupt a program being debugged. It
3793 will cause process {pid} to get a SIGTRAP. Behavior for other
3794 processes is undefined. See |terminal-debugger|.
3795 {only available on MS-Windows}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003796
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003797deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003798 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003799 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003800 When {expr} is a |List| a full copy is created. This means
3801 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003802 copy, and vice versa. When an item is a |List| or
3803 |Dictionary|, a copy for it is made, recursively. Thus
3804 changing an item in the copy does not change the contents of
3805 the original |List|.
3806 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003807 When {noref} is omitted or zero a contained |List| or
3808 |Dictionary| is only copied once. All references point to
3809 this single copy. With {noref} set to 1 every occurrence of a
3810 |List| or |Dictionary| results in a new copy. This also means
3811 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003812 *E724*
3813 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003814 that refers back to a higher level making a deep copy with
3815 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003816 Also see |copy()|.
3817
Bram Moolenaarda440d22016-01-16 21:27:23 +01003818delete({fname} [, {flags}]) *delete()*
3819 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003820 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003821
3822 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003823 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003824
Bram Moolenaarda440d22016-01-16 21:27:23 +01003825 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003826 {fname} and everything in it, recursively. BE CAREFUL!
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003827 Note: on MS-Windows it is not possible to delete a directory
3828 that is being used.
Bram Moolenaar818078d2016-08-27 21:58:42 +02003829
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003830 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003831
Bram Moolenaarda440d22016-01-16 21:27:23 +01003832 The result is a Number, which is 0 if the delete operation was
3833 successful and -1 when the deletion failed or partly failed.
3834
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003835 Use |remove()| to delete an item from a |List|.
Bram Moolenaard79a2622018-06-07 18:17:46 +02003836 To delete a line from the buffer use |:delete| or
3837 |deletebufline()|.
3838
Bram Moolenaard473c8c2018-08-11 18:00:22 +02003839deletebufline({expr}, {first} [, {last}]) *deletebufline()*
Bram Moolenaard79a2622018-06-07 18:17:46 +02003840 Delete lines {first} to {last} (inclusive) from buffer {expr}.
3841 If {last} is omitted then delete line {first} only.
3842 On success 0 is returned, on failure 1 is returned.
3843
3844 For the use of {expr}, see |bufname()| above.
3845
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003846 {first} and {last} are used like with |getline()|. Note that
Bram Moolenaard79a2622018-06-07 18:17:46 +02003847 when using |line()| this refers to the current buffer. Use "$"
3848 to refer to the last line in buffer {expr}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003849
3850 *did_filetype()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003851did_filetype() Returns |TRUE| when autocommands are being executed and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003852 FileType event has been triggered at least once. Can be used
3853 to avoid triggering the FileType event again in the scripts
3854 that detect the file type. |FileType|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02003855 Returns |FALSE| when `:setf FALLBACK` was used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003856 When editing another file, the counter is reset, thus this
3857 really checks if the FileType event has been triggered for the
3858 current buffer. This allows an autocommand that starts
3859 editing another buffer to set 'filetype' and load a syntax
3860 file.
3861
Bram Moolenaar47136d72004-10-12 20:02:24 +00003862diff_filler({lnum}) *diff_filler()*
3863 Returns the number of filler lines above line {lnum}.
3864 These are the lines that were inserted at this point in
3865 another diff'ed window. These filler lines are shown in the
3866 display but don't exist in the buffer.
3867 {lnum} is used like with |getline()|. Thus "." is the current
3868 line, "'m" mark m, etc.
3869 Returns 0 if the current window is not in diff mode.
3870
3871diff_hlID({lnum}, {col}) *diff_hlID()*
3872 Returns the highlight ID for diff mode at line {lnum} column
3873 {col} (byte index). When the current line does not have a
3874 diff change zero is returned.
3875 {lnum} is used like with |getline()|. Thus "." is the current
3876 line, "'m" mark m, etc.
3877 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3878 line.
3879 The highlight ID can be used with |synIDattr()| to obtain
3880 syntax information about the highlighting.
3881
Bram Moolenaar13065c42005-01-08 16:08:21 +00003882empty({expr}) *empty()*
3883 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003884 - A |List| or |Dictionary| is empty when it does not have any
3885 items.
Bram Moolenaard8968242019-01-15 22:51:57 +01003886 - A |String| is empty when its length is zero.
3887 - A |Number| and |Float| are empty when their value is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003888 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
Bram Moolenaard8968242019-01-15 22:51:57 +01003889 - A |Job| is empty when it failed to start.
3890 - A |Channel| is empty when it is closed.
Bram Moolenaard09091d2019-01-17 16:07:22 +01003891 - A |Blob| is empty when its length is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003892
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003893 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003894 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003895
Bram Moolenaar071d4272004-06-13 20:20:40 +00003896escape({string}, {chars}) *escape()*
3897 Escape the characters in {chars} that occur in {string} with a
3898 backslash. Example: >
3899 :echo escape('c:\program files\vim', ' \')
3900< results in: >
3901 c:\\program\ files\\vim
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003902< Also see |shellescape()| and |fnameescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003903
Bram Moolenaar446cb832008-06-24 21:56:24 +00003904 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003905eval({string}) Evaluate {string} and return the result. Especially useful to
3906 turn the result of |string()| back into the original value.
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01003907 This works for Numbers, Floats, Strings, Blobs and composites
3908 of them. Also works for |Funcref|s that refer to existing
Bram Moolenaar446cb832008-06-24 21:56:24 +00003909 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003910
Bram Moolenaar071d4272004-06-13 20:20:40 +00003911eventhandler() *eventhandler()*
3912 Returns 1 when inside an event handler. That is that Vim got
3913 interrupted while waiting for the user to type a character,
3914 e.g., when dropping a file on Vim. This means interactive
3915 commands cannot be used. Otherwise zero is returned.
3916
3917executable({expr}) *executable()*
3918 This function checks if an executable with the name {expr}
3919 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003920 arguments.
3921 executable() uses the value of $PATH and/or the normal
3922 searchpath for programs. *PATHEXT*
3923 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3924 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar58b85342016-08-14 19:54:54 +02003925 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3926 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003927 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar58b85342016-08-14 19:54:54 +02003928 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003929 Unix shell, then the name is also tried without adding an
3930 extension.
3931 On MS-DOS and MS-Windows it only checks if the file exists and
3932 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003933 On MS-Windows an executable in the same directory as Vim is
3934 always found. Since this directory is added to $PATH it
3935 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003936 The result is a Number:
3937 1 exists
3938 0 does not exist
3939 -1 not implemented on this system
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02003940 |exepath()| can be used to get the full path of an executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003941
Bram Moolenaar79815f12016-07-09 17:07:29 +02003942execute({command} [, {silent}]) *execute()*
3943 Execute an Ex command or commands and return the output as a
3944 string.
3945 {command} can be a string or a List. In case of a List the
3946 lines are executed one by one.
3947 This is equivalent to: >
3948 redir => var
3949 {command}
3950 redir END
3951<
3952 The optional {silent} argument can have these values:
3953 "" no `:silent` used
3954 "silent" `:silent` used
3955 "silent!" `:silent!` used
Bram Moolenaar214641f2017-03-05 17:04:09 +01003956 The default is "silent". Note that with "silent!", unlike
Bram Moolenaar069c1e72016-07-15 21:25:08 +02003957 `:redir`, error messages are dropped. When using an external
3958 command the screen may be messed up, use `system()` instead.
Bram Moolenaar79815f12016-07-09 17:07:29 +02003959 *E930*
3960 It is not possible to use `:redir` anywhere in {command}.
3961
3962 To get a list of lines use |split()| on the result: >
Bram Moolenaar063b9d12016-07-09 20:21:48 +02003963 split(execute('args'), "\n")
Bram Moolenaar79815f12016-07-09 17:07:29 +02003964
3965< When used recursively the output of the recursive call is not
3966 included in the output of the higher level call.
3967
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003968exepath({expr}) *exepath()*
3969 If {expr} is an executable and is either an absolute path, a
3970 relative path or found in $PATH, return the full path.
3971 Note that the current directory is used when {expr} starts
3972 with "./", which may be a problem for Vim: >
3973 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003974< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003975 an empty string is returned.
3976
Bram Moolenaar071d4272004-06-13 20:20:40 +00003977 *exists()*
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02003978exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
3979 zero otherwise.
3980
3981 For checking for a supported feature use |has()|.
3982 For checking if a file exists use |filereadable()|.
3983
3984 The {expr} argument is a string, which contains one of these:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003985 &option-name Vim option (only checks if it exists,
3986 not if it really works)
3987 +option-name Vim option that works.
3988 $ENVNAME environment variable (could also be
3989 done by comparing with an empty
3990 string)
3991 *funcname built-in function (see |functions|)
3992 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02003993 |user-functions|). Also works for a
3994 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003995 varname internal variable (see
Bram Moolenaar58b85342016-08-14 19:54:54 +02003996 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003997 for |curly-braces-names|, |Dictionary|
3998 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00003999 that evaluating an index may cause an
4000 error message for an invalid
4001 expression. E.g.: >
4002 :let l = [1, 2, 3]
4003 :echo exists("l[5]")
4004< 0 >
4005 :echo exists("l[xx]")
4006< E121: Undefined variable: xx
4007 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00004008 :cmdname Ex command: built-in command, user
4009 command or command modifier |:command|.
4010 Returns:
4011 1 for match with start of a command
4012 2 full match with a command
4013 3 matches several user commands
4014 To check for a supported command
4015 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00004016 :2match The |:2match| command.
4017 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004018 #event autocommand defined for this event
4019 #event#pattern autocommand defined for this event and
4020 pattern (the pattern is taken
4021 literally and compared to the
4022 autocommand patterns character by
4023 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004024 #group autocommand group exists
4025 #group#event autocommand defined for this group and
4026 event.
4027 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004028 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004029 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004030 ##event autocommand for this event is
4031 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004032
4033 Examples: >
4034 exists("&shortname")
4035 exists("$HOSTNAME")
4036 exists("*strftime")
4037 exists("*s:MyFunc")
4038 exists("bufcount")
4039 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004040 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004041 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004042 exists("#filetypeindent")
4043 exists("#filetypeindent#FileType")
4044 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004045 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004046< There must be no space between the symbol (&/$/*/#) and the
4047 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004048 There must be no extra characters after the name, although in
4049 a few cases this is ignored. That may become more strict in
4050 the future, thus don't count on it!
4051 Working example: >
4052 exists(":make")
4053< NOT working example: >
4054 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00004055
4056< Note that the argument must be a string, not the name of the
4057 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004058 exists(bufcount)
4059< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00004060 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004061
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004062exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004063 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004064 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004065 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004066 Examples: >
4067 :echo exp(2)
4068< 7.389056 >
4069 :echo exp(-1)
4070< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02004071 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004072
4073
Bram Moolenaar84f72352012-03-11 15:57:40 +01004074expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004075 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004076 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004077
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004078 If {list} is given and it is |TRUE|, a List will be returned.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004079 Otherwise the result is a String and when there are several
4080 matches, they are separated by <NL> characters. [Note: in
4081 version 5.0 a space was used, which caused problems when a
4082 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004083
Bram Moolenaar58b85342016-08-14 19:54:54 +02004084 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02004085 for a non-existing file is not included, unless {expr} does
4086 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004087
4088 When {expr} starts with '%', '#' or '<', the expansion is done
4089 like for the |cmdline-special| variables with their associated
4090 modifiers. Here is a short overview:
4091
4092 % current file name
4093 # alternate file name
4094 #n alternate file name n
4095 <cfile> file name under the cursor
4096 <afile> autocmd file name
4097 <abuf> autocmd buffer number (as a String!)
4098 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01004099 <sfile> sourced script file or function name
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02004100 <slnum> sourced script line number or function
4101 line number
4102 <sflnum> script file line number, also when in
4103 a function
Bram Moolenaar071d4272004-06-13 20:20:40 +00004104 <cword> word under the cursor
4105 <cWORD> WORD under the cursor
4106 <client> the {clientid} of the last received
4107 message |server2client()|
4108 Modifiers:
4109 :p expand to full path
4110 :h head (last path component removed)
4111 :t tail (last path component only)
4112 :r root (one extension removed)
4113 :e extension only
4114
4115 Example: >
4116 :let &tags = expand("%:p:h") . "/tags"
4117< Note that when expanding a string that starts with '%', '#' or
4118 '<', any following text is ignored. This does NOT work: >
4119 :let doesntwork = expand("%:h.bak")
4120< Use this: >
4121 :let doeswork = expand("%:h") . ".bak"
4122< Also note that expanding "<cfile>" and others only returns the
4123 referenced file name without further expansion. If "<cfile>"
4124 is "~/.cshrc", you need to do another expand() to have the
4125 "~/" expanded into the path of the home directory: >
4126 :echo expand(expand("<cfile>"))
4127<
4128 There cannot be white space between the variables and the
4129 following modifier. The |fnamemodify()| function can be used
4130 to modify normal file names.
4131
4132 When using '%' or '#', and the current or alternate file name
4133 is not defined, an empty string is used. Using "%:p" in a
4134 buffer with no name, results in the current directory, with a
4135 '/' added.
4136
4137 When {expr} does not start with '%', '#' or '<', it is
4138 expanded like a file name is expanded on the command line.
4139 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004140 {nosuf} argument is given and it is |TRUE|.
Bram Moolenaar146e9c32012-03-07 19:18:23 +01004141 Names for non-existing files are included. The "**" item can
4142 be used to search in a directory tree. For example, to find
4143 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00004144 :echo expand("**/README")
4145<
Bram Moolenaar647e24b2019-03-17 16:39:46 +01004146 expand() can also be used to expand variables and environment
Bram Moolenaar071d4272004-06-13 20:20:40 +00004147 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02004148 slow, because a shell may be used to do the expansion. See
4149 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004150 The expanded variable is still handled like a list of file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004151 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004152 left unchanged. Thus ":echo expand('$FOOBAR')" results in
4153 "$FOOBAR".
4154
4155 See |glob()| for finding existing files. See |system()| for
4156 getting the raw output of an external command.
4157
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004158extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004159 {expr1} and {expr2} must be both |Lists| or both
4160 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004161
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004162 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004163 If {expr3} is given insert the items of {expr2} before item
4164 {expr3} in {expr1}. When {expr3} is zero insert before the
4165 first item. When {expr3} is equal to len({expr1}) then
4166 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004167 Examples: >
4168 :echo sort(extend(mylist, [7, 5]))
4169 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00004170< When {expr1} is the same List as {expr2} then the number of
4171 items copied is equal to the original length of the List.
4172 E.g., when {expr3} is 1 you get N new copies of the first item
4173 (where N is the original length of the List).
Bram Moolenaar58b85342016-08-14 19:54:54 +02004174 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004175 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004176 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004177<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004178 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004179 Add all entries from {expr2} to {expr1}.
4180 If a key exists in both {expr1} and {expr2} then {expr3} is
4181 used to decide what to do:
4182 {expr3} = "keep": keep the value of {expr1}
4183 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004184 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004185 When {expr3} is omitted then "force" is assumed.
4186
4187 {expr1} is changed when {expr2} is not empty. If necessary
4188 make a copy of {expr1} first.
4189 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02004190 When {expr1} is locked and {expr2} is not empty the operation
4191 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004192 Returns {expr1}.
4193
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004194
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004195feedkeys({string} [, {mode}]) *feedkeys()*
4196 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004197 come from a mapping or were typed by the user.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004198
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004199 By default the string is added to the end of the typeahead
4200 buffer, thus if a mapping is still being executed the
4201 characters come after them. Use the 'i' flag to insert before
4202 other characters, they will be executed next, before any
4203 characters from a mapping.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004204
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004205 The function does not wait for processing of keys contained in
4206 {string}.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004207
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004208 To include special keys into {string}, use double-quotes
4209 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00004210 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004211 feedkeys('\<CR>') pushes 5 characters.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004212
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004213 {mode} is a String, which can contain these character flags:
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004214 'm' Remap keys. This is default. If {mode} is absent,
4215 keys are remapped.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004216 'n' Do not remap keys.
4217 't' Handle keys as if typed; otherwise they are handled as
4218 if coming from a mapping. This matters for undo,
4219 opening folds, etc.
Bram Moolenaar5e66b422019-01-24 21:58:10 +01004220 'L' Lowlevel input. Only works for Unix or when using the
4221 GUI. Keys are used as if they were coming from the
4222 terminal. Other flags are not used. *E980*
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004223 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01004224 'x' Execute commands until typeahead is empty. This is
4225 similar to using ":normal!". You can call feedkeys()
4226 several times without 'x' and then one time with 'x'
4227 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02004228 typeahead. Note that when Vim ends in Insert mode it
4229 will behave as if <Esc> is typed, to avoid getting
4230 stuck, waiting for a character to be typed before the
4231 script continues.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004232 Note that if you manage to call feedkeys() while
Bram Moolenaar5b69c222019-01-11 14:50:06 +01004233 executing commands, thus calling it recursively, then
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004234 all typehead will be consumed by the last call.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004235 '!' When used with 'x' will not end Insert mode. Can be
4236 used in a test when a timer is set to exit Insert mode
4237 a little later. Useful for testing CursorHoldI.
4238
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004239 Return value is always 0.
4240
Bram Moolenaar071d4272004-06-13 20:20:40 +00004241filereadable({file}) *filereadable()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004242 The result is a Number, which is |TRUE| when a file with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004243 name {file} exists, and can be read. If {file} doesn't exist,
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004244 or is a directory, the result is |FALSE|. {file} is any
Bram Moolenaar071d4272004-06-13 20:20:40 +00004245 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004246 If you don't care about the file being readable you can use
4247 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004248 *file_readable()*
4249 Obsolete name: file_readable().
4250
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004251
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004252filewritable({file}) *filewritable()*
4253 The result is a Number, which is 1 when a file with the
4254 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00004255 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004256 directory, and we can write to it, the result is 2.
4257
4258
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004259filter({expr1}, {expr2}) *filter()*
4260 {expr1} must be a |List| or a |Dictionary|.
4261 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004262 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004263 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004264
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004265 If {expr2} is a |string|, inside {expr2} |v:val| has the value
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004266 of the current item. For a |Dictionary| |v:key| has the key
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004267 of the current item and for a |List| |v:key| has the index of
4268 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004269 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004270 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004271< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004272 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004273< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004274 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004275< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004276
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004277 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004278 used as an expression again. Often it is good to use a
4279 |literal-string| to avoid having to double backslashes.
4280
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004281 If {expr2} is a |Funcref| it must take two arguments:
4282 1. the key or the index of the current item.
4283 2. the value of the current item.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004284 The function must return |TRUE| if the item should be kept.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004285 Example that keeps the odd items of a list: >
4286 func Odd(idx, val)
4287 return a:idx % 2 == 1
4288 endfunc
4289 call filter(mylist, function('Odd'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004290< It is shorter when using a |lambda|: >
4291 call filter(myList, {idx, val -> idx * val <= 42})
4292< If you do not use "val" you can leave it out: >
4293 call filter(myList, {idx -> idx % 2 == 1})
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004294<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004295 The operation is done in-place. If you want a |List| or
4296 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00004297 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004298
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004299< Returns {expr1}, the |List| or |Dictionary| that was filtered.
4300 When an error is encountered while evaluating {expr2} no
4301 further items in {expr1} are processed. When {expr2} is a
4302 Funcref errors inside a function are ignored, unless it was
4303 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004304
4305
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004306finddir({name} [, {path} [, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00004307 Find directory {name} in {path}. Supports both downwards and
4308 upwards recursive directory searches. See |file-searching|
4309 for the syntax of {path}.
4310 Returns the path of the first found match. When the found
4311 directory is below the current directory a relative path is
4312 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004313 If {path} is omitted or empty then 'path' is used.
4314 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004315 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00004316 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004317 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004318 {only available when compiled with the |+file_in_path|
4319 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004320
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004321findfile({name} [, {path} [, {count}]]) *findfile()*
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004322 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004323 Uses 'suffixesadd'.
4324 Example: >
4325 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004326< Searches from the directory of the current file upwards until
4327 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004328
Bram Moolenaar446cb832008-06-24 21:56:24 +00004329float2nr({expr}) *float2nr()*
4330 Convert {expr} to a Number by omitting the part after the
4331 decimal point.
4332 {expr} must evaluate to a |Float| or a Number.
4333 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004334 result is truncated to 0x7fffffff or -0x7fffffff (or when
4335 64-bit Number support is enabled, 0x7fffffffffffffff or
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004336 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004337 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00004338 Examples: >
4339 echo float2nr(3.95)
4340< 3 >
4341 echo float2nr(-23.45)
4342< -23 >
4343 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004344< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004345 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004346< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004347 echo float2nr(1.0e-100)
4348< 0
4349 {only available when compiled with the |+float| feature}
4350
4351
4352floor({expr}) *floor()*
4353 Return the largest integral value less than or equal to
4354 {expr} as a |Float| (round down).
4355 {expr} must evaluate to a |Float| or a |Number|.
4356 Examples: >
4357 echo floor(1.856)
4358< 1.0 >
4359 echo floor(-5.456)
4360< -6.0 >
4361 echo floor(4.0)
4362< 4.0
4363 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004364
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004365
4366fmod({expr1}, {expr2}) *fmod()*
4367 Return the remainder of {expr1} / {expr2}, even if the
4368 division is not representable. Returns {expr1} - i * {expr2}
4369 for some integer i such that if {expr2} is non-zero, the
4370 result has the same sign as {expr1} and magnitude less than
4371 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004372 returned is zero. The value returned is a |Float|.
4373 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004374 Examples: >
4375 :echo fmod(12.33, 1.22)
4376< 0.13 >
4377 :echo fmod(-12.33, 1.22)
4378< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02004379 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004380
4381
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004382fnameescape({string}) *fnameescape()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004383 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004384 characters that have a special meaning, such as '%' and '|'
4385 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004386 For most systems the characters escaped are
4387 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
4388 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004389 A leading '+' and '>' is also escaped (special after |:edit|
4390 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004391 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004392 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004393 :exe "edit " . fnameescape(fname)
4394< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004395 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004396
Bram Moolenaar071d4272004-06-13 20:20:40 +00004397fnamemodify({fname}, {mods}) *fnamemodify()*
4398 Modify file name {fname} according to {mods}. {mods} is a
4399 string of characters like it is used for file names on the
4400 command line. See |filename-modifiers|.
4401 Example: >
4402 :echo fnamemodify("main.c", ":p:h")
4403< results in: >
4404 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00004405< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00004406 |expand()| first then.
4407
4408foldclosed({lnum}) *foldclosed()*
4409 The result is a Number. If the line {lnum} is in a closed
4410 fold, the result is the number of the first line in that fold.
4411 If the line {lnum} is not in a closed fold, -1 is returned.
4412
4413foldclosedend({lnum}) *foldclosedend()*
4414 The result is a Number. If the line {lnum} is in a closed
4415 fold, the result is the number of the last line in that fold.
4416 If the line {lnum} is not in a closed fold, -1 is returned.
4417
4418foldlevel({lnum}) *foldlevel()*
4419 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar58b85342016-08-14 19:54:54 +02004420 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004421 returned. If there is no fold at line {lnum}, zero is
4422 returned. It doesn't matter if the folds are open or closed.
4423 When used while updating folds (from 'foldexpr') -1 is
4424 returned for lines where folds are still to be updated and the
4425 foldlevel is unknown. As a special case the level of the
4426 previous line is usually available.
4427
4428 *foldtext()*
4429foldtext() Returns a String, to be displayed for a closed fold. This is
4430 the default function used for the 'foldtext' option and should
4431 only be called from evaluating 'foldtext'. It uses the
4432 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
4433 The returned string looks like this: >
4434 +-- 45 lines: abcdef
Bram Moolenaar42205552017-03-18 19:42:22 +01004435< The number of leading dashes depends on the foldlevel. The
4436 "45" is the number of lines in the fold. "abcdef" is the text
4437 in the first non-blank line of the fold. Leading white space,
4438 "//" or "/*" and the text from the 'foldmarker' and
4439 'commentstring' options is removed.
4440 When used to draw the actual foldtext, the rest of the line
4441 will be filled with the fold char from the 'fillchars'
4442 setting.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004443 {not available when compiled without the |+folding| feature}
4444
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004445foldtextresult({lnum}) *foldtextresult()*
4446 Returns the text that is displayed for the closed fold at line
4447 {lnum}. Evaluates 'foldtext' in the appropriate context.
4448 When there is no closed fold at {lnum} an empty string is
4449 returned.
4450 {lnum} is used like with |getline()|. Thus "." is the current
4451 line, "'m" mark m, etc.
4452 Useful when exporting folded text, e.g., to HTML.
4453 {not available when compiled without the |+folding| feature}
4454
Bram Moolenaar071d4272004-06-13 20:20:40 +00004455 *foreground()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004456foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00004457 a client to a Vim server. |remote_send()|
4458 On Win32 systems this might not work, the OS does not always
4459 allow a window to bring itself to the foreground. Use
4460 |remote_foreground()| instead.
4461 {only in the Win32, Athena, Motif and GTK GUI versions and the
4462 Win32 console version}
4463
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004464 *funcref()*
4465funcref({name} [, {arglist}] [, {dict}])
4466 Just like |function()|, but the returned Funcref will lookup
4467 the function by reference, not by name. This matters when the
4468 function {name} is redefined later.
4469
4470 Unlike |function()|, {name} must be an existing user function.
4471 Also for autoloaded functions. {name} cannot be a builtin
4472 function.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004473
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004474 *function()* *E700* *E922* *E923*
4475function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004476 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01004477 {name} can be the name of a user defined function or an
4478 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004479
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004480 {name} can also be a Funcref or a partial. When it is a
Bram Moolenaar975b5272016-03-15 23:10:59 +01004481 partial the dict stored in it will be used and the {dict}
4482 argument is not allowed. E.g.: >
4483 let FuncWithArg = function(dict.Func, [arg])
4484 let Broken = function(dict.Func, [arg], dict)
4485<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004486 When using the Funcref the function will be found by {name},
4487 also when it was redefined later. Use |funcref()| to keep the
4488 same function.
4489
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004490 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02004491 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004492 the Funcref and will be used when the Funcref is called.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004493
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004494 The arguments are passed to the function in front of other
4495 arguments. Example: >
4496 func Callback(arg1, arg2, name)
4497 ...
4498 let Func = function('Callback', ['one', 'two'])
4499 ...
4500 call Func('name')
4501< Invokes the function as with: >
4502 call Callback('one', 'two', 'name')
4503
Bram Moolenaar03602ec2016-03-20 20:57:45 +01004504< The function() call can be nested to add more arguments to the
4505 Funcref. The extra arguments are appended to the list of
4506 arguments. Example: >
4507 func Callback(arg1, arg2, name)
4508 ...
4509 let Func = function('Callback', ['one'])
4510 let Func2 = function(Func, ['two'])
4511 ...
4512 call Func2('name')
4513< Invokes the function as with: >
4514 call Callback('one', 'two', 'name')
4515
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004516< The Dictionary is only useful when calling a "dict" function.
4517 In that case the {dict} is passed in as "self". Example: >
4518 function Callback() dict
4519 echo "called for " . self.name
4520 endfunction
4521 ...
4522 let context = {"name": "example"}
4523 let Func = function('Callback', context)
4524 ...
4525 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01004526< The use of function() is not needed when there are no extra
4527 arguments, these two are equivalent: >
4528 let Func = function('Callback', context)
4529 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004530
4531< The argument list and the Dictionary can be combined: >
4532 function Callback(arg1, count) dict
4533 ...
4534 let context = {"name": "example"}
4535 let Func = function('Callback', ['one'], context)
4536 ...
4537 call Func(500)
4538< Invokes the function as with: >
4539 call context.Callback('one', 500)
4540
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004541
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004542garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004543 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
4544 that have circular references.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004545
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004546 There is hardly ever a need to invoke this function, as it is
4547 automatically done when Vim runs out of memory or is waiting
4548 for the user to press a key after 'updatetime'. Items without
4549 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004550 This is useful if you have deleted a very big |List| and/or
4551 |Dictionary| with circular references in a script that runs
4552 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004553
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004554 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00004555 collection will also be done when exiting Vim, if it wasn't
4556 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00004557
Bram Moolenaar574860b2016-05-24 17:33:34 +02004558 The garbage collection is not done immediately but only when
4559 it's safe to perform. This is when waiting for the user to
4560 type a character. To force garbage collection immediately use
4561 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004562
Bram Moolenaar677ee682005-01-27 14:41:15 +00004563get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004564 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004565 available return {default}. Return zero when {default} is
4566 omitted.
Bram Moolenaard8968242019-01-15 22:51:57 +01004567get({blob}, {idx} [, {default}])
4568 Get byte {idx} from |Blob| {blob}. When this byte is not
4569 available return {default}. Return -1 when {default} is
4570 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004571get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004572 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004573 item is not available return {default}. Return zero when
4574 {default} is omitted.
Bram Moolenaar03e19a02016-05-24 22:29:49 +02004575get({func}, {what})
4576 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02004577 {what} are:
Bram Moolenaar214641f2017-03-05 17:04:09 +01004578 "name" The function name
4579 "func" The function
4580 "dict" The dictionary
4581 "args" The list with arguments
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004582
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004583 *getbufinfo()*
4584getbufinfo([{expr}])
4585getbufinfo([{dict}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02004586 Get information about buffers as a List of Dictionaries.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004587
4588 Without an argument information about all the buffers is
4589 returned.
4590
4591 When the argument is a Dictionary only the buffers matching
4592 the specified criteria are returned. The following keys can
4593 be specified in {dict}:
4594 buflisted include only listed buffers.
4595 bufloaded include only loaded buffers.
Bram Moolenaar8e6a31d2017-12-10 21:06:22 +01004596 bufmodified include only modified buffers.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004597
4598 Otherwise, {expr} specifies a particular buffer to return
4599 information for. For the use of {expr}, see |bufname()|
4600 above. If the buffer is found the returned List has one item.
4601 Otherwise the result is an empty list.
4602
4603 Each returned List item is a dictionary with the following
4604 entries:
Bram Moolenaar33928832016-08-18 21:22:04 +02004605 bufnr buffer number.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004606 changed TRUE if the buffer is modified.
4607 changedtick number of changes made to the buffer.
4608 hidden TRUE if the buffer is hidden.
4609 listed TRUE if the buffer is listed.
4610 lnum current line number in buffer.
4611 loaded TRUE if the buffer is loaded.
4612 name full path to the file in the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004613 signs list of signs placed in the buffer.
4614 Each list item is a dictionary with
4615 the following fields:
4616 id sign identifier
4617 lnum line number
4618 name sign name
Bram Moolenaar30567352016-08-27 21:25:44 +02004619 variables a reference to the dictionary with
4620 buffer-local variables.
4621 windows list of |window-ID|s that display this
4622 buffer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004623
4624 Examples: >
4625 for buf in getbufinfo()
4626 echo buf.name
4627 endfor
4628 for buf in getbufinfo({'buflisted':1})
Bram Moolenaar30567352016-08-27 21:25:44 +02004629 if buf.changed
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004630 ....
4631 endif
4632 endfor
4633<
Bram Moolenaar30567352016-08-27 21:25:44 +02004634 To get buffer-local options use: >
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004635 getbufvar({bufnr}, '&option_name')
Bram Moolenaar30567352016-08-27 21:25:44 +02004636
4637<
Bram Moolenaar45360022005-07-21 21:08:21 +00004638 *getbufline()*
4639getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004640 Return a |List| with the lines starting from {lnum} to {end}
4641 (inclusive) in the buffer {expr}. If {end} is omitted, a
4642 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004643
4644 For the use of {expr}, see |bufname()| above.
4645
Bram Moolenaar661b1822005-07-28 22:36:45 +00004646 For {lnum} and {end} "$" can be used for the last line of the
4647 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00004648
4649 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004650 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004651
4652 When {end} is greater than the number of lines in the buffer,
4653 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004654 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00004655 returned.
4656
Bram Moolenaar661b1822005-07-28 22:36:45 +00004657 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004658 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004659
4660 Example: >
4661 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004662
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004663getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004664 The result is the value of option or local buffer variable
4665 {varname} in buffer {expr}. Note that the name without "b:"
4666 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004667 When {varname} is empty returns a dictionary with all the
4668 buffer-local variables.
Bram Moolenaar30567352016-08-27 21:25:44 +02004669 When {varname} is equal to "&" returns a dictionary with all
4670 the buffer-local options.
4671 Otherwise, when {varname} starts with "&" returns the value of
4672 a buffer-local option.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004673 This also works for a global or buffer-local option, but it
4674 doesn't work for a global variable, window-local variable or
4675 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004676 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004677 When the buffer or variable doesn't exist {def} or an empty
4678 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004679 Examples: >
4680 :let bufmodified = getbufvar(1, "&mod")
4681 :echo "todo myvar = " . getbufvar("todo", "myvar")
4682<
Bram Moolenaar07ad8162018-02-13 13:59:59 +01004683getchangelist({expr}) *getchangelist()*
4684 Returns the |changelist| for the buffer {expr}. For the use
4685 of {expr}, see |bufname()| above. If buffer {expr} doesn't
4686 exist, an empty list is returned.
4687
4688 The returned list contains two entries: a list with the change
4689 locations and the current position in the list. Each
4690 entry in the change list is a dictionary with the following
4691 entries:
4692 col column number
4693 coladd column offset for 'virtualedit'
4694 lnum line number
4695 If buffer {expr} is the current buffer, then the current
4696 position refers to the position in the list. For other
4697 buffers, it is set to the length of the list.
4698
Bram Moolenaar071d4272004-06-13 20:20:40 +00004699getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00004700 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004701 If [expr] is omitted, wait until a character is available.
4702 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004703 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004704 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00004705 not consumed. Return zero if no character available.
4706
Bram Moolenaardfb18412013-12-11 18:53:29 +01004707 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaarc577d812017-07-08 22:37:34 +02004708 special key is returned. If it is a single character, the
Bram Moolenaar91170f82006-05-05 21:15:17 +00004709 result is a number. Use nr2char() to convert it to a String.
4710 Otherwise a String is returned with the encoded character.
Bram Moolenaarc577d812017-07-08 22:37:34 +02004711 For a special key it's a String with a sequence of bytes
4712 starting with 0x80 (decimal: 128). This is the same value as
4713 the String "\<Key>", e.g., "\<Left>". The returned value is
4714 also a String when a modifier (shift, control, alt) was used
4715 that is not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004716
Bram Moolenaar822ff862014-06-12 21:46:14 +02004717 When [expr] is 0 and Esc is typed, there will be a short delay
4718 while Vim waits to see if this is the start of an escape
4719 sequence.
4720
Bram Moolenaardfb18412013-12-11 18:53:29 +01004721 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00004722 one-byte character it is the character itself as a number.
4723 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004724
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004725 Use getcharmod() to obtain any additional modifiers.
4726
Bram Moolenaar219b8702006-11-01 14:32:36 +00004727 When the user clicks a mouse button, the mouse event will be
4728 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaar511972d2016-06-04 18:09:59 +02004729 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This
4730 example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00004731 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00004732 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00004733 exe v:mouse_win . "wincmd w"
4734 exe v:mouse_lnum
4735 exe "normal " . v:mouse_col . "|"
4736 endif
4737<
Bram Moolenaar690afe12017-01-28 18:34:47 +01004738 When using bracketed paste only the first character is
4739 returned, the rest of the pasted text is dropped.
4740 |xterm-bracketed-paste|.
4741
Bram Moolenaar071d4272004-06-13 20:20:40 +00004742 There is no prompt, you will somehow have to make clear to the
4743 user that a character has to be typed.
4744 There is no mapping for the character.
4745 Key codes are replaced, thus when the user presses the <Del>
4746 key you get the code for the <Del> key, not the raw character
4747 sequence. Examples: >
4748 getchar() == "\<Del>"
4749 getchar() == "\<S-Left>"
4750< This example redefines "f" to ignore case: >
4751 :nmap f :call FindChar()<CR>
4752 :function FindChar()
4753 : let c = nr2char(getchar())
4754 : while col('.') < col('$') - 1
4755 : normal l
4756 : if getline('.')[col('.') - 1] ==? c
4757 : break
4758 : endif
4759 : endwhile
4760 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01004761<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004762 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01004763 |<CursorHold>|. Often you will want to ignore this and get
4764 another character: >
4765 :function GetKey()
4766 : let c = getchar()
4767 : while c == "\<CursorHold>"
4768 : let c = getchar()
4769 : endwhile
4770 : return c
4771 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00004772
4773getcharmod() *getcharmod()*
4774 The result is a Number which is the state of the modifiers for
4775 the last obtained character with getchar() or in another way.
4776 These values are added together:
4777 2 shift
4778 4 control
4779 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004780 16 meta (when it's different from ALT)
4781 32 mouse double click
4782 64 mouse triple click
4783 96 mouse quadruple click (== 32 + 64)
4784 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004785 Only the modifiers that have not been included in the
Bram Moolenaar58b85342016-08-14 19:54:54 +02004786 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004787 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004788
Bram Moolenaardbd24b52015-08-11 14:26:19 +02004789getcharsearch() *getcharsearch()*
4790 Return the current character search information as a {dict}
4791 with the following entries:
4792
4793 char character previously used for a character
4794 search (|t|, |f|, |T|, or |F|); empty string
4795 if no character search has been performed
4796 forward direction of character search; 1 for forward,
4797 0 for backward
4798 until type of character search; 1 for a |t| or |T|
4799 character search, 0 for an |f| or |F|
4800 character search
4801
4802 This can be useful to always have |;| and |,| search
4803 forward/backward regardless of the direction of the previous
4804 character search: >
4805 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4806 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4807< Also see |setcharsearch()|.
4808
Bram Moolenaar071d4272004-06-13 20:20:40 +00004809getcmdline() *getcmdline()*
4810 Return the current command-line. Only works when the command
4811 line is being edited, thus requires use of |c_CTRL-\_e| or
4812 |c_CTRL-R_=|.
4813 Example: >
4814 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004815< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004816 Returns an empty string when entering a password or using
4817 |inputsecret()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004818
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004819getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004820 Return the position of the cursor in the command line as a
4821 byte count. The first column is 1.
4822 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004823 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4824 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004825 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
4826
4827getcmdtype() *getcmdtype()*
4828 Return the current command-line type. Possible return values
4829 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00004830 : normal Ex command
4831 > debug mode command |debug-mode|
4832 / forward search command
4833 ? backward search command
4834 @ |input()| command
4835 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02004836 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004837 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004838 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4839 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004840 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004841
Bram Moolenaarfb539272014-08-22 19:21:47 +02004842getcmdwintype() *getcmdwintype()*
4843 Return the current |command-line-window| type. Possible return
4844 values are the same as |getcmdtype()|. Returns an empty string
4845 when not in the command-line window.
4846
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004847getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004848 Return a list of command-line completion matches. {type}
4849 specifies what for. The following completion types are
4850 supported:
4851
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02004852 arglist file names in argument list
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004853 augroup autocmd groups
4854 buffer buffer names
4855 behave :behave suboptions
4856 color color schemes
4857 command Ex command (and arguments)
4858 compiler compilers
4859 cscope |:cscope| suboptions
4860 dir directory names
4861 environment environment variable names
4862 event autocommand events
4863 expression Vim expression
4864 file file and directory names
4865 file_in_path file and directory names in |'path'|
4866 filetype filetype names |'filetype'|
4867 function function name
4868 help help subjects
4869 highlight highlight groups
4870 history :history suboptions
4871 locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02004872 mapclear buffer argument
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004873 mapping mapping name
4874 menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004875 messages |:messages| suboptions
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004876 option options
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004877 packadd optional package |pack-add| names
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004878 shellcmd Shell command
4879 sign |:sign| suboptions
4880 syntax syntax file names |'syntax'|
4881 syntime |:syntime| suboptions
4882 tag tags
4883 tag_listfiles tags, file names
4884 user user names
4885 var user variables
4886
4887 If {pat} is an empty string, then all the matches are returned.
4888 Otherwise only items matching {pat} are returned. See
4889 |wildcards| for the use of special characters in {pat}.
4890
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004891 If the optional {filtered} flag is set to 1, then 'wildignore'
4892 is applied to filter the results. Otherwise all the matches
4893 are returned. The 'wildignorecase' option always applies.
4894
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004895 If there are no matches, an empty list is returned. An
4896 invalid value for {type} produces an error.
4897
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004898 *getcurpos()*
4899getcurpos() Get the position of the cursor. This is like getpos('.'), but
4900 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01004901 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004902 The "curswant" number is the preferred column when moving the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004903 cursor vertically. Also see |getpos()|.
4904
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004905 This can be used to save and restore the cursor position: >
4906 let save_cursor = getcurpos()
4907 MoveTheCursorAround
4908 call setpos('.', save_cursor)
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004909< Note that this only works within the window. See
4910 |winrestview()| for restoring more state.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004911 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01004912getcwd([{winnr} [, {tabnr}]])
4913 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00004914 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004915
4916 With {winnr} return the local current directory of this window
Bram Moolenaar54591292018-02-09 20:53:59 +01004917 in the current tab page. {winnr} can be the window number or
4918 the |window-ID|.
4919 If {winnr} is -1 return the name of the global working
4920 directory. See also |haslocaldir()|.
4921
Bram Moolenaarc9703302016-01-17 21:49:33 +01004922 With {winnr} and {tabnr} return the local current directory of
Bram Moolenaar00aa0692019-04-27 20:37:57 +02004923 the window in the specified tab page. If {winnr} is -1 return
4924 the working directory of the tabpage.
4925 If {winnr} is zero use the current window, if {tabnr} is zero
4926 use the current tabpage.
4927 Without any arguments, return the working directory of the
4928 current window.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004929 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004930
Bram Moolenaar00aa0692019-04-27 20:37:57 +02004931 Examples: >
4932 " Get the working directory of the current window
4933 :echo getcwd()
4934 :echo getcwd(0)
4935 :echo getcwd(0, 0)
4936 " Get the working directory of window 3 in tabpage 2
4937 :echo getcwd(3, 2)
4938 " Get the global working directory
4939 :echo getcwd(-1)
4940 " Get the working directory of tabpage 3
4941 :echo getcwd(-1, 3)
4942 " Get the working directory of current tabpage
4943 :echo getcwd(-1, 0)
4944<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004945getfsize({fname}) *getfsize()*
4946 The result is a Number, which is the size in bytes of the
4947 given file {fname}.
4948 If {fname} is a directory, 0 is returned.
4949 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00004950 If the size of {fname} is too big to fit in a Number then -2
4951 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004952
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004953getfontname([{name}]) *getfontname()*
4954 Without an argument returns the name of the normal font being
4955 used. Like what is used for the Normal highlight group
4956 |hl-Normal|.
4957 With an argument a check is done whether {name} is a valid
4958 font name. If not then an empty string is returned.
4959 Otherwise the actual font name is returned, or {name} if the
4960 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00004961 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004962 gvimrc file. Use the |GUIEnter| autocommand to use this
4963 function just after the GUI has started.
Bram Moolenaar3df01732017-02-17 22:47:16 +01004964 Note that the GTK GUI accepts any font name, thus checking for
4965 a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004966
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004967getfperm({fname}) *getfperm()*
4968 The result is a String, which is the read, write, and execute
4969 permissions of the given file {fname}.
4970 If {fname} does not exist or its directory cannot be read, an
4971 empty string is returned.
4972 The result is of the form "rwxrwxrwx", where each group of
4973 "rwx" flags represent, in turn, the permissions of the owner
4974 of the file, the group the file belongs to, and other users.
4975 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02004976 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004977 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02004978 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004979< This will hopefully (from a security point of view) display
4980 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004981
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004982 For setting permissions use |setfperm()|.
Bram Moolenaar80492532016-03-08 17:08:53 +01004983
Bram Moolenaar071d4272004-06-13 20:20:40 +00004984getftime({fname}) *getftime()*
4985 The result is a Number, which is the last modification time of
4986 the given file {fname}. The value is measured as seconds
4987 since 1st Jan 1970, and may be passed to strftime(). See also
4988 |localtime()| and |strftime()|.
4989 If the file {fname} can't be found -1 is returned.
4990
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004991getftype({fname}) *getftype()*
4992 The result is a String, which is a description of the kind of
4993 file of the given file {fname}.
4994 If {fname} does not exist an empty string is returned.
4995 Here is a table over different kinds of files and their
4996 results:
4997 Normal file "file"
4998 Directory "dir"
4999 Symbolic link "link"
5000 Block device "bdev"
5001 Character device "cdev"
5002 Socket "socket"
5003 FIFO "fifo"
5004 All other "other"
5005 Example: >
5006 getftype("/home")
5007< Note that a type such as "link" will only be returned on
5008 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01005009 "file" are returned. On MS-Windows a symbolic link to a
5010 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005011
Bram Moolenaard96ff162018-02-18 22:13:29 +01005012getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
Bram Moolenaar4f505882018-02-10 21:06:32 +01005013 Returns the |jumplist| for the specified window.
5014
5015 Without arguments use the current window.
5016 With {winnr} only use this window in the current tab page.
5017 {winnr} can also be a |window-ID|.
5018 With {winnr} and {tabnr} use the window in the specified tab
5019 page.
5020
5021 The returned list contains two entries: a list with the jump
5022 locations and the last used jump position number in the list.
5023 Each entry in the jump location list is a dictionary with
5024 the following entries:
5025 bufnr buffer number
5026 col column number
5027 coladd column offset for 'virtualedit'
5028 filename filename if available
5029 lnum line number
5030
Bram Moolenaar071d4272004-06-13 20:20:40 +00005031 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005032getline({lnum} [, {end}])
5033 Without {end} the result is a String, which is line {lnum}
5034 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005035 getline(1)
5036< When {lnum} is a String that doesn't start with a
Bram Moolenaarf2732452018-06-03 14:47:35 +02005037 digit, |line()| is called to translate the String into a Number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005038 To get the line under the cursor: >
5039 getline(".")
5040< When {lnum} is smaller than 1 or bigger than the number of
5041 lines in the buffer, an empty string is returned.
5042
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005043 When {end} is given the result is a |List| where each item is
5044 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005045 including line {end}.
5046 {end} is used in the same way as {lnum}.
5047 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005048 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005049 Example: >
5050 :let start = line('.')
5051 :let end = search("^$") - 1
5052 :let lines = getline(start, end)
5053
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005054< To get lines from another buffer see |getbufline()|
5055
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005056getloclist({nr} [, {what}]) *getloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005057 Returns a list with all the entries in the location list for
Bram Moolenaar7571d552016-08-18 22:54:46 +02005058 window {nr}. {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02005059 When {nr} is zero the current window is used.
5060
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005061 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00005062 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005063 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005064
Bram Moolenaard823fa92016-08-12 16:29:27 +02005065 If the optional {what} dictionary argument is supplied, then
5066 returns the items listed in {what} as a dictionary. Refer to
5067 |getqflist()| for the supported items in {what}.
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005068
5069 In addition to the items supported by |getqflist()| in {what},
5070 the following item is supported by |getloclist()|:
5071
5072 filewinid id of the window used to display files
5073 from the location list. This field is
5074 applicable only when called from a
5075 location list window. See
5076 |location-list-file-window| for more
5077 details.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005078
Bram Moolenaaraff74912019-03-30 18:11:49 +01005079getmatches([{win}]) *getmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01005080 Returns a |List| with all matches previously defined for the
5081 current window by |matchadd()| and the |:match| commands.
5082 |getmatches()| is useful in combination with |setmatches()|,
5083 as |setmatches()| can restore a list of matches saved by
5084 |getmatches()|.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005085 Example: >
5086 :echo getmatches()
5087< [{'group': 'MyGroup1', 'pattern': 'TODO',
5088 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5089 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5090 :let m = getmatches()
5091 :call clearmatches()
5092 :echo getmatches()
5093< [] >
5094 :call setmatches(m)
5095 :echo getmatches()
5096< [{'group': 'MyGroup1', 'pattern': 'TODO',
5097 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5098 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5099 :unlet m
5100<
Bram Moolenaar822ff862014-06-12 21:46:14 +02005101 *getpid()*
5102getpid() Return a Number which is the process ID of the Vim process.
5103 On Unix and MS-Windows this is a unique number, until Vim
Bram Moolenaar58b85342016-08-14 19:54:54 +02005104 exits. On MS-DOS it's always zero.
Bram Moolenaar822ff862014-06-12 21:46:14 +02005105
5106 *getpos()*
5107getpos({expr}) Get the position for {expr}. For possible values of {expr}
5108 see |line()|. For getting the cursor position see
5109 |getcurpos()|.
5110 The result is a |List| with four numbers:
5111 [bufnum, lnum, col, off]
5112 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
5113 is the buffer number of the mark.
5114 "lnum" and "col" are the position in the buffer. The first
5115 column is 1.
5116 The "off" number is zero, unless 'virtualedit' is used. Then
5117 it is the offset in screen columns from the start of the
5118 character. E.g., a position within a <Tab> or after the last
5119 character.
5120 Note that for '< and '> Visual mode matters: when it is "V"
5121 (visual line mode) the column of '< is zero and the column of
5122 '> is a large number.
5123 This can be used to save and restore the position of a mark: >
5124 let save_a_mark = getpos("'a")
5125 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01005126 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02005127< Also see |getcurpos()| and |setpos()|.
5128
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005129
Bram Moolenaard823fa92016-08-12 16:29:27 +02005130getqflist([{what}]) *getqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005131 Returns a list with all the current quickfix errors. Each
5132 list item is a dictionary with these entries:
5133 bufnr number of buffer that has the file name, use
5134 bufname() to get the name
Bram Moolenaard76ce852018-05-01 15:02:04 +02005135 module module name
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005136 lnum line number in the buffer (first line is 1)
5137 col column number (first column is 1)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005138 vcol |TRUE|: "col" is visual column
5139 |FALSE|: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005140 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005141 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005142 text description of the error
5143 type type of the error, 'E', '1', etc.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005144 valid |TRUE|: recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005145
Bram Moolenaar7571d552016-08-18 22:54:46 +02005146 When there is no error list or it's empty, an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005147 returned. Quickfix list entries with non-existing buffer
5148 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00005149
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005150 Useful application: Find pattern matches in multiple files and
5151 do something with them: >
5152 :vimgrep /theword/jg *.c
5153 :for d in getqflist()
5154 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
5155 :endfor
Bram Moolenaard823fa92016-08-12 16:29:27 +02005156<
5157 If the optional {what} dictionary argument is supplied, then
5158 returns only the items listed in {what} as a dictionary. The
5159 following string items are supported in {what}:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005160 changedtick get the total number of changes made
Bram Moolenaar15142e22018-04-30 22:19:58 +02005161 to the list |quickfix-changedtick|
5162 context get the |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02005163 efm errorformat to use when parsing "lines". If
Bram Moolenaar2f058492017-11-30 20:27:52 +01005164 not present, then the 'errorformat' option
Bram Moolenaar36538222017-09-02 19:51:44 +02005165 value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005166 id get information for the quickfix list with
5167 |quickfix-ID|; zero means the id for the
Bram Moolenaar2f058492017-11-30 20:27:52 +01005168 current list or the list specified by "nr"
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005169 idx index of the current entry in the quickfix
5170 list specified by 'id' or 'nr'.
5171 See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02005172 items quickfix list entries
Bram Moolenaar15142e22018-04-30 22:19:58 +02005173 lines parse a list of lines using 'efm' and return
5174 the resulting entries. Only a |List| type is
5175 accepted. The current quickfix list is not
5176 modified. See |quickfix-parse|.
Bram Moolenaar890680c2016-09-27 21:28:56 +02005177 nr get information for this quickfix list; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02005178 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02005179 the last quickfix list
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005180 qfbufnr number of the buffer displayed in the quickfix
5181 window. Returns 0 if the quickfix buffer is
5182 not present. See |quickfix-buffer|.
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02005183 size number of entries in the quickfix list
Bram Moolenaar15142e22018-04-30 22:19:58 +02005184 title get the list title |quickfix-title|
Bram Moolenaar74240d32017-12-10 15:26:15 +01005185 winid get the quickfix |window-ID|
Bram Moolenaard823fa92016-08-12 16:29:27 +02005186 all all of the above quickfix properties
Bram Moolenaar74240d32017-12-10 15:26:15 +01005187 Non-string items in {what} are ignored. To get the value of a
Bram Moolenaara6d48492017-12-12 22:45:31 +01005188 particular item, set it to zero.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005189 If "nr" is not present then the current quickfix list is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005190 If both "nr" and a non-zero "id" are specified, then the list
5191 specified by "id" is used.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005192 To get the number of lists in the quickfix stack, set "nr" to
5193 "$" in {what}. The "nr" value in the returned dictionary
Bram Moolenaar875feea2017-06-11 16:07:51 +02005194 contains the quickfix stack size.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005195 When "lines" is specified, all the other items except "efm"
5196 are ignored. The returned dictionary contains the entry
5197 "items" with the list of entries.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005198
Bram Moolenaard823fa92016-08-12 16:29:27 +02005199 The returned dictionary contains the following entries:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005200 changedtick total number of changes made to the
5201 list |quickfix-changedtick|
Bram Moolenaar15142e22018-04-30 22:19:58 +02005202 context quickfix list context. See |quickfix-context|
Bram Moolenaara6d48492017-12-12 22:45:31 +01005203 If not present, set to "".
5204 id quickfix list ID |quickfix-ID|. If not
5205 present, set to 0.
5206 idx index of the current entry in the list. If not
5207 present, set to 0.
5208 items quickfix list entries. If not present, set to
5209 an empty list.
5210 nr quickfix list number. If not present, set to 0
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005211 qfbufnr number of the buffer displayed in the quickfix
5212 window. If not present, set to 0.
Bram Moolenaara6d48492017-12-12 22:45:31 +01005213 size number of entries in the quickfix list. If not
5214 present, set to 0.
5215 title quickfix list title text. If not present, set
5216 to "".
Bram Moolenaar74240d32017-12-10 15:26:15 +01005217 winid quickfix |window-ID|. If not present, set to 0
Bram Moolenaard823fa92016-08-12 16:29:27 +02005218
Bram Moolenaar15142e22018-04-30 22:19:58 +02005219 Examples (See also |getqflist-examples|): >
Bram Moolenaard823fa92016-08-12 16:29:27 +02005220 :echo getqflist({'all': 1})
5221 :echo getqflist({'nr': 2, 'title': 1})
Bram Moolenaar2c809b72017-09-01 18:34:02 +02005222 :echo getqflist({'lines' : ["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02005223<
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005224getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005225 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005226 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005227 :let cliptext = getreg('*')
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005228< When {regname} was not set the result is an empty string.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005229
5230 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005231 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005232 getreg('=', 1) returns the expression itself, so that it can
5233 be restored with |setreg()|. For other registers the extra
5234 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005235
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005236 If {list} is present and |TRUE|, the result type is changed
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005237 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005238 about zero bytes possibly present inside register: without
5239 third argument both NLs and zero bytes are represented as NLs
5240 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005241 When the register was not set an empty list is returned.
5242
Bram Moolenaar071d4272004-06-13 20:20:40 +00005243 If {regname} is not specified, |v:register| is used.
5244
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005245
Bram Moolenaar071d4272004-06-13 20:20:40 +00005246getregtype([{regname}]) *getregtype()*
5247 The result is a String, which is type of register {regname}.
5248 The value will be one of:
5249 "v" for |characterwise| text
5250 "V" for |linewise| text
5251 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01005252 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00005253 <CTRL-V> is one character with value 0x16.
5254 If {regname} is not specified, |v:register| is used.
5255
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005256gettabinfo([{arg}]) *gettabinfo()*
5257 If {arg} is not specified, then information about all the tab
5258 pages is returned as a List. Each List item is a Dictionary.
5259 Otherwise, {arg} specifies the tab page number and information
5260 about that one is returned. If the tab page does not exist an
5261 empty List is returned.
5262
5263 Each List item is a Dictionary with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02005264 tabnr tab page number.
Bram Moolenaar30567352016-08-27 21:25:44 +02005265 variables a reference to the dictionary with
5266 tabpage-local variables
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005267 windows List of |window-ID|s in the tab page.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005268
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005269gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005270 Get the value of a tab-local variable {varname} in tab page
5271 {tabnr}. |t:var|
5272 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02005273 When {varname} is empty a dictionary with all tab-local
5274 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005275 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005276 When the tab or variable doesn't exist {def} or an empty
5277 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005278
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005279gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005280 Get the value of window-local variable {varname} in window
5281 {winnr} in tab page {tabnr}.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005282 When {varname} is empty a dictionary with all window-local
5283 variables is returned.
Bram Moolenaar30567352016-08-27 21:25:44 +02005284 When {varname} is equal to "&" get the values of all
5285 window-local options in a Dictionary.
5286 Otherwise, when {varname} starts with "&" get the value of a
5287 window-local option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005288 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005289 Tabs are numbered starting with one. For the current tabpage
5290 use |getwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005291 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005292 When {winnr} is zero the current window is used.
5293 This also works for a global option, buffer-local option and
5294 window-local option, but it doesn't work for a global variable
5295 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005296 When the tab, window or variable doesn't exist {def} or an
5297 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005298 Examples: >
5299 :let list_is_on = gettabwinvar(1, 2, '&list')
5300 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005301<
Bram Moolenaarb477af22018-07-15 20:20:18 +02005302 To obtain all window-local variables use: >
5303 gettabwinvar({tabnr}, {winnr}, '&')
5304
Bram Moolenaarf49cc602018-11-11 15:21:05 +01005305gettagstack([{nr}]) *gettagstack()*
5306 The result is a Dict, which is the tag stack of window {nr}.
5307 {nr} can be the window number or the |window-ID|.
5308 When {nr} is not specified, the current window is used.
5309 When window {nr} doesn't exist, an empty Dict is returned.
5310
5311 The returned dictionary contains the following entries:
5312 curidx Current index in the stack. When at
5313 top of the stack, set to (length + 1).
5314 Index of bottom of the stack is 1.
5315 items List of items in the stack. Each item
5316 is a dictionary containing the
5317 entries described below.
5318 length Number of entries in the stack.
5319
5320 Each item in the stack is a dictionary with the following
5321 entries:
5322 bufnr buffer number of the current jump
5323 from cursor position before the tag jump.
5324 See |getpos()| for the format of the
5325 returned list.
5326 matchnr current matching tag number. Used when
5327 multiple matching tags are found for a
5328 name.
5329 tagname name of the tag
5330
5331 See |tagstack| for more information about the tag stack.
5332
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005333getwininfo([{winid}]) *getwininfo()*
5334 Returns information about windows as a List with Dictionaries.
5335
5336 If {winid} is given Information about the window with that ID
5337 is returned. If the window does not exist the result is an
5338 empty list.
5339
5340 Without {winid} information about all the windows in all the
5341 tab pages is returned.
5342
5343 Each List item is a Dictionary with the following entries:
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01005344 botline last displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005345 bufnr number of buffer in the window
5346 height window height (excluding winbar)
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005347 loclist 1 if showing a location list
5348 {only with the +quickfix feature}
5349 quickfix 1 if quickfix or location list window
5350 {only with the +quickfix feature}
5351 terminal 1 if a terminal window
5352 {only with the +terminal feature}
5353 tabnr tab page number
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01005354 topline first displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005355 variables a reference to the dictionary with
5356 window-local variables
5357 width window width
Bram Moolenaarb477af22018-07-15 20:20:18 +02005358 winbar 1 if the window has a toolbar, 0
5359 otherwise
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005360 wincol leftmost screen column of the window,
5361 col from |win_screenpos()|
5362 winid |window-ID|
5363 winnr window number
5364 winrow topmost screen column of the window,
5365 row from |win_screenpos()|
5366
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005367getwinpos([{timeout}]) *getwinpos()*
5368 The result is a list with two numbers, the result of
Bram Moolenaar9d87a372018-12-18 21:41:50 +01005369 getwinposx() and getwinposy() combined:
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005370 [x-pos, y-pos]
5371 {timeout} can be used to specify how long to wait in msec for
5372 a response from the terminal. When omitted 100 msec is used.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005373 Use a longer time for a remote terminal.
5374 When using a value less than 10 and no response is received
5375 within that time, a previously reported position is returned,
5376 if available. This can be used to poll for the position and
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005377 do some work in the meantime: >
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005378 while 1
5379 let res = getwinpos(1)
5380 if res[0] >= 0
5381 break
5382 endif
5383 " Do some work here
5384 endwhile
5385<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005386 *getwinposx()*
5387getwinposx() The result is a Number, which is the X coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005388 the left hand side of the GUI Vim window. Also works for an
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005389 xterm (uses a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005390 The result will be -1 if the information is not available.
5391 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005392
5393 *getwinposy()*
5394getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005395 the top of the GUI Vim window. Also works for an xterm (uses
5396 a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005397 The result will be -1 if the information is not available.
5398 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005399
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005400getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005401 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005402 Examples: >
5403 :let list_is_on = getwinvar(2, '&list')
5404 :echo "myvar = " . getwinvar(1, 'myvar')
5405<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005406glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005407 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005408 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005409
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005410 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005411 the 'suffixes' and 'wildignore' options apply: Names matching
5412 one of the patterns in 'wildignore' will be skipped and
5413 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01005414 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005415
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005416 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar84f72352012-03-11 15:57:40 +01005417 with all matching files. The advantage of using a List is,
5418 you also get filenames containing newlines correctly.
5419 Otherwise the result is a String and when there are several
5420 matches, they are separated by <NL> characters.
5421
5422 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005423
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02005424 You can also use |readdir()| if you need to do complicated
5425 things, such as limiting the number of matches.
5426
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005427 A name for a non-existing file is not included. A symbolic
5428 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005429 However, when the {alllinks} argument is present and it is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005430 |TRUE| then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005431
5432 For most systems backticks can be used to get files names from
5433 any external command. Example: >
5434 :let tagfiles = glob("`find . -name tags -print`")
5435 :let &tags = substitute(tagfiles, "\n", ",", "g")
5436< The result of the program inside the backticks should be one
Bram Moolenaar58b85342016-08-14 19:54:54 +02005437 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005438
5439 See |expand()| for expanding special Vim variables. See
5440 |system()| for getting the raw output of an external command.
5441
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01005442glob2regpat({expr}) *glob2regpat()*
5443 Convert a file pattern, as used by glob(), into a search
5444 pattern. The result can be used to match with a string that
5445 is a file name. E.g. >
5446 if filename =~ glob2regpat('Make*.mak')
5447< This is equivalent to: >
5448 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005449< When {expr} is an empty string the result is "^$", match an
5450 empty string.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005451 Note that the result depends on the system. On MS-Windows
Bram Moolenaar58b85342016-08-14 19:54:54 +02005452 a backslash usually means a path separator.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005453
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005454 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005455globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00005456 Perform glob() on all directories in {path} and concatenate
5457 the results. Example: >
5458 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005459<
5460 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00005461 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005462 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005463 To add a comma inside a directory name escape it with a
5464 backslash. Note that on MS-Windows a directory may have a
5465 trailing backslash, remove it if you put a comma after it.
5466 If the expansion fails for one of the directories, there is no
5467 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005468
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005469 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005470 the 'suffixes' and 'wildignore' options apply: Names matching
5471 one of the patterns in 'wildignore' will be skipped and
5472 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005473
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005474 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005475 with all matching files. The advantage of using a List is, you
5476 also get filenames containing newlines correctly. Otherwise
5477 the result is a String and when there are several matches,
5478 they are separated by <NL> characters. Example: >
5479 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5480<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005481 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005482
Bram Moolenaar02743632005-07-25 20:42:36 +00005483 The "**" item can be used to search in a directory tree.
5484 For example, to find all "README.txt" files in the directories
5485 in 'runtimepath' and below: >
5486 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00005487< Upwards search and limiting the depth of "**" is not
5488 supported, thus using 'path' will not always work properly.
5489
Bram Moolenaar071d4272004-06-13 20:20:40 +00005490 *has()*
5491has({feature}) The result is a Number, which is 1 if the feature {feature} is
5492 supported, zero otherwise. The {feature} argument is a
5493 string. See |feature-list| below.
5494 Also see |exists()|.
5495
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005496
5497has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005498 The result is a Number, which is 1 if |Dictionary| {dict} has
5499 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005500
Bram Moolenaarc9703302016-01-17 21:49:33 +01005501haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005502 The result is a Number:
5503 1 when the window has set a local directory via |:lcd|
5504 2 when the tab-page has set a local directory via |:tcd|
5505 0 otherwise.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005506
5507 Without arguments use the current window.
5508 With {winnr} use this window in the current tab page.
5509 With {winnr} and {tabnr} use the window in the specified tab
5510 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005511 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005512 If {winnr} is -1 it is ignored and only the tabpage is used.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005513 Return 0 if the arguments are invalid.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005514 Examples: >
5515 if haslocaldir() == 1
5516 " window local directory case
5517 elseif haslocaldir() == 2
5518 " tab-local directory case
5519 else
5520 " global directory case
5521 endif
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005522
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005523 " current window
5524 :echo haslocaldir()
5525 :echo haslocaldir(0)
5526 :echo haslocaldir(0, 0)
5527 " window n in current tab page
5528 :echo haslocaldir(n)
5529 :echo haslocaldir(n, 0)
5530 " window n in tab page m
5531 :echo haslocaldir(n, m)
5532 " tab page m
5533 :echo haslocaldir(-1, m)
5534<
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005535hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005536 The result is a Number, which is 1 if there is a mapping that
5537 contains {what} in somewhere in the rhs (what it is mapped to)
5538 and this mapping exists in one of the modes indicated by
5539 {mode}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005540 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00005541 instead of mappings. Don't forget to specify Insert and/or
5542 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005543 Both the global mappings and the mappings local to the current
5544 buffer are checked for a match.
5545 If no matching mapping is found 0 is returned.
5546 The following characters are recognized in {mode}:
5547 n Normal mode
5548 v Visual mode
5549 o Operator-pending mode
5550 i Insert mode
5551 l Language-Argument ("r", "f", "t", etc.)
5552 c Command-line mode
5553 When {mode} is omitted, "nvo" is used.
5554
5555 This function is useful to check if a mapping already exists
Bram Moolenaar58b85342016-08-14 19:54:54 +02005556 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005557 :if !hasmapto('\ABCdoit')
5558 : map <Leader>d \ABCdoit
5559 :endif
5560< This installs the mapping to "\ABCdoit" only if there isn't
5561 already a mapping to "\ABCdoit".
5562
5563histadd({history}, {item}) *histadd()*
5564 Add the String {item} to the history {history} which can be
5565 one of: *hist-names*
5566 "cmd" or ":" command line history
5567 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00005568 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00005569 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005570 "debug" or ">" debug command history
Bram Moolenaar3e496b02016-09-25 22:11:48 +02005571 empty the current or last used history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005572 The {history} string does not need to be the whole name, one
5573 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005574 If {item} does already exist in the history, it will be
5575 shifted to become the newest entry.
5576 The result is a Number: 1 if the operation was successful,
5577 otherwise 0 is returned.
5578
5579 Example: >
5580 :call histadd("input", strftime("%Y %b %d"))
5581 :let date=input("Enter date: ")
5582< This function is not available in the |sandbox|.
5583
5584histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005585 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005586 for the possible values of {history}.
5587
Bram Moolenaarc236c162008-07-13 17:41:49 +00005588 If the parameter {item} evaluates to a String, it is used as a
5589 regular expression. All entries matching that expression will
5590 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005591 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00005592 If {item} evaluates to a Number, it will be interpreted as
5593 an index, see |:history-indexing|. The respective entry will
5594 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005595
5596 The result is a Number: 1 for a successful operation,
5597 otherwise 0 is returned.
5598
5599 Examples:
5600 Clear expression register history: >
5601 :call histdel("expr")
5602<
5603 Remove all entries starting with "*" from the search history: >
5604 :call histdel("/", '^\*')
5605<
5606 The following three are equivalent: >
5607 :call histdel("search", histnr("search"))
5608 :call histdel("search", -1)
5609 :call histdel("search", '^'.histget("search", -1).'$')
5610<
5611 To delete the last search pattern and use the last-but-one for
5612 the "n" command and 'hlsearch': >
5613 :call histdel("search", -1)
5614 :let @/ = histget("search", -1)
5615
5616histget({history} [, {index}]) *histget()*
5617 The result is a String, the entry with Number {index} from
5618 {history}. See |hist-names| for the possible values of
5619 {history}, and |:history-indexing| for {index}. If there is
5620 no such entry, an empty String is returned. When {index} is
5621 omitted, the most recent item from the history is used.
5622
5623 Examples:
5624 Redo the second last search from history. >
5625 :execute '/' . histget("search", -2)
5626
5627< Define an Ex command ":H {num}" that supports re-execution of
5628 the {num}th entry from the output of |:history|. >
5629 :command -nargs=1 H execute histget("cmd", 0+<args>)
5630<
5631histnr({history}) *histnr()*
5632 The result is the Number of the current entry in {history}.
5633 See |hist-names| for the possible values of {history}.
5634 If an error occurred, -1 is returned.
5635
5636 Example: >
5637 :let inp_index = histnr("expr")
5638<
5639hlexists({name}) *hlexists()*
5640 The result is a Number, which is non-zero if a highlight group
5641 called {name} exists. This is when the group has been
5642 defined in some way. Not necessarily when highlighting has
5643 been defined for it, it may also have been used for a syntax
5644 item.
5645 *highlight_exists()*
5646 Obsolete name: highlight_exists().
5647
5648 *hlID()*
5649hlID({name}) The result is a Number, which is the ID of the highlight group
5650 with name {name}. When the highlight group doesn't exist,
5651 zero is returned.
5652 This can be used to retrieve information about the highlight
Bram Moolenaar58b85342016-08-14 19:54:54 +02005653 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005654 "Comment" group: >
5655 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5656< *highlightID()*
5657 Obsolete name: highlightID().
5658
5659hostname() *hostname()*
5660 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005661 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00005662 256 characters long are truncated.
5663
5664iconv({expr}, {from}, {to}) *iconv()*
5665 The result is a String, which is the text {expr} converted
5666 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005667 When the conversion completely fails an empty string is
5668 returned. When some characters could not be converted they
5669 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005670 The encoding names are whatever the iconv() library function
5671 can accept, see ":!man 3 iconv".
5672 Most conversions require Vim to be compiled with the |+iconv|
5673 feature. Otherwise only UTF-8 to latin1 conversion and back
5674 can be done.
5675 This can be used to display messages with special characters,
5676 no matter what 'encoding' is set to. Write the message in
5677 UTF-8 and use: >
5678 echo iconv(utf8_str, "utf-8", &enc)
5679< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5680 from/to UCS-2 is automatically changed to use UTF-8. You
5681 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005682
5683 *indent()*
5684indent({lnum}) The result is a Number, which is indent of line {lnum} in the
5685 current buffer. The indent is counted in spaces, the value
5686 of 'tabstop' is relevant. {lnum} is used just like in
5687 |getline()|.
5688 When {lnum} is invalid -1 is returned.
5689
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005690
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005691index({object}, {expr} [, {start} [, {ic}]]) *index()*
5692 If {object} is a |List| return the lowest index where the item
5693 has a value equal to {expr}. There is no automatic
5694 conversion, so the String "4" is different from the Number 4.
5695 And the number 4 is different from the Float 4.0. The value
5696 of 'ignorecase' is not used here, case always matters.
5697
5698 If {object} is |Blob| return the lowest index where the byte
5699 value is equal to {expr}.
5700
Bram Moolenaar748bf032005-02-02 23:04:36 +00005701 If {start} is given then start looking at the item with index
5702 {start} (may be negative for an item relative to the end).
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005703 When {ic} is given and it is |TRUE|, ignore case. Otherwise
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005704 case must match.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005705 -1 is returned when {expr} is not found in {object}.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005706 Example: >
5707 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005708 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005709
5710
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005711input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005712 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005713 the command-line. The {prompt} argument is either a prompt
5714 string, or a blank string (for no prompt). A '\n' can be used
5715 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005716 The highlighting set with |:echohl| is used for the prompt.
5717 The input is entered just like a command-line, with the same
Bram Moolenaar58b85342016-08-14 19:54:54 +02005718 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005719 for lines typed for input().
5720 Example: >
5721 :if input("Coffee or beer? ") == "beer"
5722 : echo "Cheers!"
5723 :endif
5724<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005725 If the optional {text} argument is present and not empty, this
5726 is used for the default reply, as if the user typed this.
5727 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005728 :let color = input("Color? ", "white")
5729
5730< The optional {completion} argument specifies the type of
5731 completion supported for the input. Without it completion is
Bram Moolenaar58b85342016-08-14 19:54:54 +02005732 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005733 that can be supplied to a user-defined command using the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005734 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005735 more information. Example: >
5736 let fname = input("File: ", "", "file")
5737<
5738 NOTE: This function must not be used in a startup file, for
5739 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005740 Note: When input() is called from within a mapping it will
5741 consume remaining characters from that mapping, because a
5742 mapping is handled like the characters were typed.
5743 Use |inputsave()| before input() and |inputrestore()|
5744 after input() to avoid that. Another solution is to avoid
5745 that further characters follow in the mapping, e.g., by using
5746 |:execute| or |:normal|.
5747
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005748 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005749 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
5750 :function GetFoo()
5751 : call inputsave()
5752 : let g:Foo = input("enter search pattern: ")
5753 : call inputrestore()
5754 :endfunction
5755
5756inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005757 Like |input()|, but when the GUI is running and text dialogs
5758 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005759 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02005760 :let n = inputdialog("value for shiftwidth", shiftwidth())
5761 :if n != ""
5762 : let &sw = n
5763 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00005764< When the dialog is cancelled {cancelreturn} is returned. When
5765 omitted an empty string is returned.
5766 Hitting <Enter> works like pressing the OK button. Hitting
5767 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005768 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005769
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005770inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005771 {textlist} must be a |List| of strings. This |List| is
5772 displayed, one string per line. The user will be prompted to
5773 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005774 The user can also select an item by clicking on it with the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005775 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005776 above the first item a negative number is returned. When
5777 clicking on the prompt one more than the length of {textlist}
5778 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005779 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar58b85342016-08-14 19:54:54 +02005780 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005781 the start of the string. And put a prompt in the first item.
5782 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005783 let color = inputlist(['Select color:', '1. red',
5784 \ '2. green', '3. blue'])
5785
Bram Moolenaar071d4272004-06-13 20:20:40 +00005786inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005787 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005788 Should be called the same number of times inputsave() is
5789 called. Calling it more often is harmless though.
5790 Returns 1 when there is nothing to restore, 0 otherwise.
5791
5792inputsave() *inputsave()*
5793 Preserve typeahead (also from mappings) and clear it, so that
5794 a following prompt gets input from the user. Should be
5795 followed by a matching inputrestore() after the prompt. Can
5796 be used several times, in which case there must be just as
5797 many inputrestore() calls.
5798 Returns 1 when out of memory, 0 otherwise.
5799
5800inputsecret({prompt} [, {text}]) *inputsecret()*
5801 This function acts much like the |input()| function with but
5802 two exceptions:
5803 a) the user's response will be displayed as a sequence of
5804 asterisks ("*") thereby keeping the entry secret, and
5805 b) the user's response will not be recorded on the input
5806 |history| stack.
5807 The result is a String, which is whatever the user actually
5808 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005809 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005810
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005811insert({object}, {item} [, {idx}]) *insert()*
5812 When {object} is a |List| or a |Blob| insert {item} at the start
5813 of it.
5814
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005815 If {idx} is specified insert {item} before the item with index
Bram Moolenaar58b85342016-08-14 19:54:54 +02005816 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005817 like omitting {idx}. A negative {idx} is also possible, see
5818 |list-index|. -1 inserts just before the last item.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005819
5820 Returns the resulting |List| or |Blob|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005821 :let mylist = insert([2, 3, 5], 1)
5822 :call insert(mylist, 4, -1)
5823 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005824< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005825 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005826 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005827
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005828invert({expr}) *invert()*
5829 Bitwise invert. The argument is converted to a number. A
5830 List, Dict or Float argument causes an error. Example: >
5831 :let bits = invert(bits)
5832
Bram Moolenaar071d4272004-06-13 20:20:40 +00005833isdirectory({directory}) *isdirectory()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005834 The result is a Number, which is |TRUE| when a directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00005835 with the name {directory} exists. If {directory} doesn't
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005836 exist, or isn't a directory, the result is |FALSE|. {directory}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005837 is any expression, which is used as a String.
5838
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02005839isinf({expr}) *isinf()*
5840 Return 1 if {expr} is a positive infinity, or -1 a negative
5841 infinity, otherwise 0. >
5842 :echo isinf(1.0 / 0.0)
5843< 1 >
5844 :echo isinf(-1.0 / 0.0)
5845< -1
5846
5847 {only available when compiled with the |+float| feature}
5848
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005849islocked({expr}) *islocked()* *E786*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005850 The result is a Number, which is |TRUE| when {expr} is the
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005851 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005852 {expr} must be the name of a variable, |List| item or
5853 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005854 :let alist = [0, ['a', 'b'], 2, 3]
5855 :lockvar 1 alist
5856 :echo islocked('alist') " 1
5857 :echo islocked('alist[1]') " 0
5858
5859< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005860 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005861
Bram Moolenaarf3913272016-02-25 00:00:01 +01005862isnan({expr}) *isnan()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005863 Return |TRUE| if {expr} is a float with value NaN. >
Bram Moolenaarf3913272016-02-25 00:00:01 +01005864 echo isnan(0.0 / 0.0)
Bram Moolenaar0f248b02019-04-04 15:36:05 +02005865< 1
Bram Moolenaarf3913272016-02-25 00:00:01 +01005866
5867 {only available when compiled with the |+float| feature}
5868
Bram Moolenaar677ee682005-01-27 14:41:15 +00005869items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005870 Return a |List| with all the key-value pairs of {dict}. Each
5871 |List| item is a list with two items: the key of a {dict}
5872 entry and the value of this entry. The |List| is in arbitrary
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01005873 order. Also see |keys()| and |values()|.
5874 Example: >
5875 for [key, value] in items(mydict)
5876 echo key . ': ' . value
5877 endfor
Bram Moolenaar677ee682005-01-27 14:41:15 +00005878
Bram Moolenaar38a55632016-02-15 22:07:32 +01005879job_getchannel({job}) *job_getchannel()*
5880 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01005881 To check if the job has no channel: >
5882 if string(job_getchannel()) == 'channel fail'
5883<
Bram Moolenaar38a55632016-02-15 22:07:32 +01005884 {only available when compiled with the |+job| feature}
5885
Bram Moolenaar65a54642018-04-28 16:56:53 +02005886job_info([{job}]) *job_info()*
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005887 Returns a Dictionary with information about {job}:
5888 "status" what |job_status()| returns
5889 "channel" what |job_getchannel()| returns
Bram Moolenaar65a54642018-04-28 16:56:53 +02005890 "cmd" List of command arguments used to start the job
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02005891 "process" process ID
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02005892 "tty_in" terminal input name, empty when none
5893 "tty_out" terminal output name, empty when none
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005894 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01005895 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005896 "stoponexit" |job-stoponexit|
5897
Bram Moolenaarb3051ce2019-01-31 15:52:11 +01005898 Only in Unix:
5899 "termsig" the signal which terminated the process
5900 (See |job_stop()| for the values)
5901 only valid when "status" is "dead"
5902
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01005903 Only in MS-Windows:
5904 "tty_type" Type of virtual console in use.
5905 Values are "winpty" or "conpty".
5906 See 'termwintype'.
5907
Bram Moolenaar65a54642018-04-28 16:56:53 +02005908 Without any arguments, returns a List with all Job objects.
5909
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005910job_setoptions({job}, {options}) *job_setoptions()*
5911 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005912 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01005913 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005914
Bram Moolenaar38a55632016-02-15 22:07:32 +01005915job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005916 Start a job and return a Job object. Unlike |system()| and
5917 |:!cmd| this does not wait for the job to finish.
Bram Moolenaarc572da52017-08-27 16:52:01 +02005918 To start a job in a terminal window see |term_start()|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005919
Bram Moolenaar5e66b422019-01-24 21:58:10 +01005920 If the job fails to start then |job_status()| on the returned
5921 Job object results in "fail" and none of the callbacks will be
5922 invoked.
5923
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005924 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01005925 Unix it is split up in white-separated parts to be passed to
5926 execvp(). Arguments in double quotes can contain white space.
5927
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005928 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01005929 and further items are the arguments. All items are converted
5930 to String. This works best on Unix.
5931
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005932 On MS-Windows, job_start() makes a GUI application hidden. If
5933 want to show it, Use |:!start| instead.
5934
Bram Moolenaar835dc632016-02-07 14:27:38 +01005935 The command is executed directly, not through a shell, the
5936 'shell' option is not used. To use the shell: >
5937 let job = job_start(["/bin/sh", "-c", "echo hello"])
5938< Or: >
5939 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005940< Note that this will start two processes, the shell and the
5941 command it executes. If you don't want this use the "exec"
5942 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005943
5944 On Unix $PATH is used to search for the executable only when
5945 the command does not contain a slash.
5946
5947 The job will use the same terminal as Vim. If it reads from
5948 stdin the job and Vim will be fighting over input, that
5949 doesn't work. Redirect stdin and stdout to avoid problems: >
5950 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
5951<
5952 The returned Job object can be used to get the status with
5953 |job_status()| and stop the job with |job_stop()|.
5954
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02005955 Note that the job object will be deleted if there are no
5956 references to it. This closes the stdin and stderr, which may
5957 cause the job to fail with an error. To avoid this keep a
5958 reference to the job. Thus instead of: >
5959 call job_start('my-command')
5960< use: >
5961 let myjob = job_start('my-command')
5962< and unlet "myjob" once the job is not needed or is past the
5963 point where it would fail (e.g. when it prints a message on
5964 startup). Keep in mind that variables local to a function
5965 will cease to exist if the function returns. Use a
5966 script-local variable if needed: >
5967 let s:myjob = job_start('my-command')
5968<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005969 {options} must be a Dictionary. It can contain many optional
5970 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005971
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005972 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005973
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005974job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005975 Returns a String with the status of {job}:
5976 "run" job is running
5977 "fail" job failed to start
5978 "dead" job died or was stopped after running
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005979
Bram Moolenaar511972d2016-06-04 18:09:59 +02005980 On Unix a non-existing command results in "dead" instead of
5981 "fail", because a fork happens before the failure can be
5982 detected.
5983
Bram Moolenaar03413f42016-04-12 21:07:15 +02005984 If an exit callback was set with the "exit_cb" option and the
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005985 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005986
Bram Moolenaar8950a562016-03-12 15:22:55 +01005987 For more information see |job_info()|.
5988
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005989 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005990
5991job_stop({job} [, {how}]) *job_stop()*
5992 Stop the {job}. This can also be used to signal the job.
5993
Bram Moolenaar923d9262016-02-25 20:56:01 +01005994 When {how} is omitted or is "term" the job will be terminated.
5995 For Unix SIGTERM is sent. On MS-Windows the job will be
5996 terminated forcedly (there is no "gentle" way).
5997 This goes to the process group, thus children may also be
5998 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005999
Bram Moolenaar923d9262016-02-25 20:56:01 +01006000 Effect for Unix:
6001 "term" SIGTERM (default)
6002 "hup" SIGHUP
6003 "quit" SIGQUIT
6004 "int" SIGINT
6005 "kill" SIGKILL (strongest way to stop)
6006 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01006007
Bram Moolenaar923d9262016-02-25 20:56:01 +01006008 Effect for MS-Windows:
6009 "term" terminate process forcedly (default)
6010 "hup" CTRL_BREAK
6011 "quit" CTRL_BREAK
6012 "int" CTRL_C
6013 "kill" terminate process forcedly
6014 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006015
6016 On Unix the signal is sent to the process group. This means
6017 that when the job is "sh -c command" it affects both the shell
6018 and the command.
6019
Bram Moolenaar835dc632016-02-07 14:27:38 +01006020 The result is a Number: 1 if the operation could be executed,
6021 0 if "how" is not supported on the system.
6022 Note that even when the operation was executed, whether the
6023 job was actually stopped needs to be checked with
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02006024 |job_status()|.
6025
6026 If the status of the job is "dead", the signal will not be
6027 sent. This is to avoid to stop the wrong job (esp. on Unix,
6028 where process numbers are recycled).
6029
6030 When using "kill" Vim will assume the job will die and close
6031 the channel.
Bram Moolenaar835dc632016-02-07 14:27:38 +01006032
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006033 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01006034
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006035join({list} [, {sep}]) *join()*
6036 Join the items in {list} together into one String.
6037 When {sep} is specified it is put in between the items. If
6038 {sep} is omitted a single space is used.
6039 Note that {sep} is not added at the end. You might want to
6040 add it there too: >
6041 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006042< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006043 converted into a string like with |string()|.
6044 The opposite function is |split()|.
6045
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006046js_decode({string}) *js_decode()*
6047 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006048 - Object key names do not have to be in quotes.
Bram Moolenaaree142ad2017-01-11 21:50:08 +01006049 - Strings can be in single quotes.
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006050 - Empty items in an array (between two commas) are allowed and
6051 result in v:none items.
6052
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006053js_encode({expr}) *js_encode()*
6054 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006055 - Object key names are not in quotes.
6056 - v:none items in an array result in an empty item between
6057 commas.
6058 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006059 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006060 Will be encoded as:
6061 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006062 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006063 [1,null,{"one":1},null] ~
6064 This encoding is valid for JavaScript. It is more efficient
6065 than JSON, especially when using an array with optional items.
6066
6067
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006068json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006069 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006070 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01006071 JSON and Vim values.
6072 The decoding is permissive:
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006073 - A trailing comma in an array and object is ignored, e.g.
6074 "[1, 2, ]" is the same as "[1, 2]".
Bram Moolenaard09091d2019-01-17 16:07:22 +01006075 - Integer keys are accepted in objects, e.g. {1:2} is the
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006076 same as {"1":2}.
Bram Moolenaar705ada12016-01-24 17:56:50 +01006077 - More floating point numbers are recognized, e.g. "1." for
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006078 "1.0", or "001.2" for "1.2". Special floating point values
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006079 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6080 are accepted.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006081 - Leading zeroes in integer numbers are ignored, e.g. "012"
6082 for "12" or "-012" for "-12".
6083 - Capitalization is ignored in literal names null, true or
6084 false, e.g. "NULL" for "null", "True" for "true".
6085 - Control characters U+0000 through U+001F which are not
6086 escaped in strings are accepted, e.g. " " (tab
6087 character in string) for "\t".
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006088 - An empty JSON expression or made of only spaces is accepted
6089 and results in v:none.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006090 - Backslash in an invalid 2-character sequence escape is
6091 ignored, e.g. "\a" is decoded as "a".
6092 - A correct surrogate pair in JSON strings should normally be
6093 a 12 character sequence such as "\uD834\uDD1E", but
6094 json_decode() silently accepts truncated surrogate pairs
6095 such as "\uD834" or "\uD834\u"
6096 *E938*
6097 A duplicate key in an object, valid in rfc7159, is not
6098 accepted by json_decode() as the result must be a valid Vim
6099 type, e.g. this fails: {"a":"b", "a":"c"}
6100
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006101
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006102json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006103 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006104 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006105 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006106 Vim values are converted as follows:
Bram Moolenaard09091d2019-01-17 16:07:22 +01006107 |Number| decimal number
6108 |Float| floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006109 Float nan "NaN"
6110 Float inf "Infinity"
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006111 Float -inf "-Infinity"
Bram Moolenaard09091d2019-01-17 16:07:22 +01006112 |String| in double quotes (possibly null)
6113 |Funcref| not possible, error
6114 |List| as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006115 used recursively: []
Bram Moolenaard09091d2019-01-17 16:07:22 +01006116 |Dict| as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006117 used recursively: {}
Bram Moolenaard09091d2019-01-17 16:07:22 +01006118 |Blob| as an array of the individual bytes
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006119 v:false "false"
6120 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006121 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006122 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006123 Note that NaN and Infinity are passed on as values. This is
6124 missing in the JSON standard, but several implementations do
6125 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006126
Bram Moolenaard8b02732005-01-14 21:48:43 +00006127keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006128 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006129 arbitrary order. Also see |items()| and |values()|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00006130
Bram Moolenaar13065c42005-01-08 16:08:21 +00006131 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006132len({expr}) The result is a Number, which is the length of the argument.
6133 When {expr} is a String or a Number the length in bytes is
6134 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006135 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006136 returned.
Bram Moolenaard09091d2019-01-17 16:07:22 +01006137 When {expr} is a |Blob| the number of bytes is returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006138 When {expr} is a |Dictionary| the number of entries in the
6139 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006140 Otherwise an error is given.
6141
Bram Moolenaar071d4272004-06-13 20:20:40 +00006142 *libcall()* *E364* *E368*
6143libcall({libname}, {funcname}, {argument})
6144 Call function {funcname} in the run-time library {libname}
6145 with single argument {argument}.
6146 This is useful to call functions in a library that you
6147 especially made to be used with Vim. Since only one argument
6148 is possible, calling standard library functions is rather
6149 limited.
6150 The result is the String returned by the function. If the
6151 function returns NULL, this will appear as an empty string ""
6152 to Vim.
6153 If the function returns a number, use libcallnr()!
6154 If {argument} is a number, it is passed to the function as an
6155 int; if {argument} is a string, it is passed as a
6156 null-terminated string.
6157 This function will fail in |restricted-mode|.
6158
6159 libcall() allows you to write your own 'plug-in' extensions to
6160 Vim without having to recompile the program. It is NOT a
6161 means to call system functions! If you try to do so Vim will
6162 very probably crash.
6163
6164 For Win32, the functions you write must be placed in a DLL
6165 and use the normal C calling convention (NOT Pascal which is
6166 used in Windows System DLLs). The function must take exactly
6167 one parameter, either a character pointer or a long integer,
6168 and must return a character pointer or NULL. The character
6169 pointer returned must point to memory that will remain valid
6170 after the function has returned (e.g. in static data in the
6171 DLL). If it points to allocated memory, that memory will
6172 leak away. Using a static buffer in the function should work,
6173 it's then freed when the DLL is unloaded.
6174
6175 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00006176 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006177 because Vim thinks it's a pointer.
6178 For Win32 systems, {libname} should be the filename of the DLL
6179 without the ".DLL" suffix. A full path is only required if
6180 the DLL is not in the usual places.
6181 For Unix: When compiling your own plugins, remember that the
6182 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006183 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006184 feature is present}
6185 Examples: >
6186 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006187<
6188 *libcallnr()*
6189libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006190 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00006191 int instead of a string.
6192 {only in Win32 on some Unix versions, when the |+libcall|
6193 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006194 Examples: >
6195 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006196 :call libcallnr("libc.so", "printf", "Hello World!\n")
6197 :call libcallnr("libc.so", "sleep", 10)
6198<
6199 *line()*
6200line({expr}) The result is a Number, which is the line number of the file
6201 position given with {expr}. The accepted positions are:
6202 . the cursor position
6203 $ the last line in the current buffer
6204 'x position of mark x (if the mark is not set, 0 is
6205 returned)
Bram Moolenaara1d5fa62017-04-03 22:02:55 +02006206 w0 first line visible in current window (one if the
6207 display isn't updated, e.g. in silent Ex mode)
6208 w$ last line visible in current window (this is one
6209 less than "w0" if no lines are visible)
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00006210 v In Visual mode: the start of the Visual area (the
6211 cursor is the end). When not in Visual mode
6212 returns the cursor position. Differs from |'<| in
6213 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006214 Note that a mark in another file can be used. The line number
6215 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006216 To get the column number use |col()|. To get both use
6217 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006218 Examples: >
6219 line(".") line number of the cursor
6220 line("'t") line number of mark t
6221 line("'" . marker) line number of mark marker
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006222<
6223 To jump to the last known position when opening a file see
6224 |last-position-jump|.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006225
Bram Moolenaar071d4272004-06-13 20:20:40 +00006226line2byte({lnum}) *line2byte()*
6227 Return the byte count from the start of the buffer for line
6228 {lnum}. This includes the end-of-line character, depending on
6229 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006230 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006231 This can also be used to get the byte count for the line just
6232 below the last line: >
6233 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006234< This is the buffer size plus one. If 'fileencoding' is empty
6235 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006236 When {lnum} is invalid, or the |+byte_offset| feature has been
6237 disabled at compile time, -1 is returned.
6238 Also see |byte2line()|, |go| and |:goto|.
6239
6240lispindent({lnum}) *lispindent()*
6241 Get the amount of indent for line {lnum} according the lisp
6242 indenting rules, as with 'lisp'.
6243 The indent is counted in spaces, the value of 'tabstop' is
6244 relevant. {lnum} is used just like in |getline()|.
6245 When {lnum} is invalid or Vim was not compiled the
6246 |+lispindent| feature, -1 is returned.
6247
Bram Moolenaar9d401282019-04-06 13:18:12 +02006248list2str({list} [, {utf8}]) *list2str()*
6249 Convert each number in {list} to a character string can
6250 concatenate them all. Examples: >
6251 list2str([32]) returns " "
6252 list2str([65, 66, 67]) returns "ABC"
6253< The same can be done (slowly) with: >
6254 join(map(list, {nr, val -> nr2char(val)}), '')
6255< |str2list()| does the opposite.
6256
6257 When {utf8} is omitted or zero, the current 'encoding' is used.
6258 With {utf8} is 1, always return utf-8 characters.
6259 With utf-8 composing characters work as expected: >
6260 list2str([97, 769]) returns "á"
6261<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006262localtime() *localtime()*
6263 Return the current time, measured as seconds since 1st Jan
6264 1970. See also |strftime()| and |getftime()|.
6265
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006266
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006267log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006268 Return the natural logarithm (base e) of {expr} as a |Float|.
6269 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006270 (0, inf].
6271 Examples: >
6272 :echo log(10)
6273< 2.302585 >
6274 :echo log(exp(5))
6275< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02006276 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006277
6278
Bram Moolenaar446cb832008-06-24 21:56:24 +00006279log10({expr}) *log10()*
6280 Return the logarithm of Float {expr} to base 10 as a |Float|.
6281 {expr} must evaluate to a |Float| or a |Number|.
6282 Examples: >
6283 :echo log10(1000)
6284< 3.0 >
6285 :echo log10(0.01)
6286< -2.0
6287 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006288
6289luaeval({expr} [, {expr}]) *luaeval()*
6290 Evaluate Lua expression {expr} and return its result converted
6291 to Vim data structures. Second {expr} may hold additional
Bram Moolenaard38b0552012-04-25 19:07:41 +02006292 argument accessible as _A inside first {expr}.
6293 Strings are returned as they are.
6294 Boolean objects are converted to numbers.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006295 Numbers are converted to |Float| values if vim was compiled
Bram Moolenaard38b0552012-04-25 19:07:41 +02006296 with |+float| and to numbers otherwise.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006297 Dictionaries and lists obtained by vim.eval() are returned
Bram Moolenaard38b0552012-04-25 19:07:41 +02006298 as-is.
6299 Other objects are returned as zero without any errors.
6300 See |lua-luaeval| for more details.
6301 {only available when compiled with the |+lua| feature}
6302
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006303map({expr1}, {expr2}) *map()*
6304 {expr1} must be a |List| or a |Dictionary|.
6305 Replace each item in {expr1} with the result of evaluating
6306 {expr2}. {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006307
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006308 If {expr2} is a |string|, inside {expr2} |v:val| has the value
6309 of the current item. For a |Dictionary| |v:key| has the key
6310 of the current item and for a |List| |v:key| has the index of
6311 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006312 Example: >
6313 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006314< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006315
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006316 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006317 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006318 |literal-string| to avoid having to double backslashes. You
6319 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006320
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006321 If {expr2} is a |Funcref| it is called with two arguments:
6322 1. The key or the index of the current item.
6323 2. the value of the current item.
6324 The function must return the new value of the item. Example
6325 that changes each value by "key-value": >
6326 func KeyValue(key, val)
6327 return a:key . '-' . a:val
6328 endfunc
6329 call map(myDict, function('KeyValue'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006330< It is shorter when using a |lambda|: >
6331 call map(myDict, {key, val -> key . '-' . val})
6332< If you do not use "val" you can leave it out: >
6333 call map(myDict, {key -> 'item: ' . key})
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006334<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006335 The operation is done in-place. If you want a |List| or
6336 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02006337 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006338
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006339< Returns {expr1}, the |List| or |Dictionary| that was filtered.
6340 When an error is encountered while evaluating {expr2} no
6341 further items in {expr1} are processed. When {expr2} is a
6342 Funcref errors inside a function are ignored, unless it was
6343 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006344
6345
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006346maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
Bram Moolenaarbd743252010-10-20 21:23:33 +02006347 When {dict} is omitted or zero: Return the rhs of mapping
6348 {name} in mode {mode}. The returned String has special
6349 characters translated like in the output of the ":map" command
6350 listing.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006351
Bram Moolenaarbd743252010-10-20 21:23:33 +02006352 When there is no mapping for {name}, an empty String is
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006353 returned. When the mapping for {name} is empty, then "<Nop>"
6354 is returned.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006355
6356 The {name} can have special key names, like in the ":map"
6357 command.
6358
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006359 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006360 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02006361 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006362 "o" Operator-pending
6363 "i" Insert
6364 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02006365 "s" Select
6366 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00006367 "l" langmap |language-mapping|
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006368 "t" Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +00006369 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006370 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006371
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006372 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006373 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006374
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006375 When {dict} is there and it is |TRUE| return a dictionary
Bram Moolenaarbd743252010-10-20 21:23:33 +02006376 containing all the information of the mapping with the
6377 following items:
6378 "lhs" The {lhs} of the mapping.
6379 "rhs" The {rhs} of the mapping as typed.
6380 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02006381 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006382 "expr" 1 for an expression mapping (|:map-<expr>|).
6383 "buffer" 1 for a buffer local mapping (|:map-local|).
6384 "mode" Modes for which the mapping is defined. In
6385 addition to the modes mentioned above, these
6386 characters will be used:
6387 " " Normal, Visual and Operator-pending
6388 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01006389 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02006390 "sid" The script local ID, used for <sid> mappings
6391 (|<SID>|).
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02006392 "lnum" The line number in "sid", zero if unknown.
Bram Moolenaardfb18412013-12-11 18:53:29 +01006393 "nowait" Do not wait for other, longer mappings.
6394 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02006395
Bram Moolenaar071d4272004-06-13 20:20:40 +00006396 The mappings local to the current buffer are checked first,
6397 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00006398 This function can be used to map a key even when it's already
6399 mapped, and have it do the original mapping too. Sketch: >
6400 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
6401
Bram Moolenaar071d4272004-06-13 20:20:40 +00006402
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006403mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006404 Check if there is a mapping that matches with {name} in mode
6405 {mode}. See |maparg()| for {mode} and special names in
6406 {name}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006407 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006408 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006409 A match happens with a mapping that starts with {name} and
6410 with a mapping which is equal to the start of {name}.
6411
Bram Moolenaar446cb832008-06-24 21:56:24 +00006412 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00006413 mapcheck("a") yes yes yes
6414 mapcheck("abc") yes yes yes
6415 mapcheck("ax") yes no no
6416 mapcheck("b") no no no
6417
6418 The difference with maparg() is that mapcheck() finds a
6419 mapping that matches with {name}, while maparg() only finds a
6420 mapping for {name} exactly.
6421 When there is no mapping that starts with {name}, an empty
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006422 String is returned. If there is one, the RHS of that mapping
Bram Moolenaar071d4272004-06-13 20:20:40 +00006423 is returned. If there are several mappings that start with
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006424 {name}, the RHS of one of them is returned. This will be
6425 "<Nop>" if the RHS is empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006426 The mappings local to the current buffer are checked first,
6427 then the global mappings.
6428 This function can be used to check if a mapping can be added
6429 without being ambiguous. Example: >
6430 :if mapcheck("_vv") == ""
6431 : map _vv :set guifont=7x13<CR>
6432 :endif
6433< This avoids adding the "_vv" mapping when there already is a
6434 mapping for "_v" or for "_vvv".
6435
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006436match({expr}, {pat} [, {start} [, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006437 When {expr} is a |List| then this returns the index of the
6438 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006439 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006440
Bram Moolenaar58b85342016-08-14 19:54:54 +02006441 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006442 Number, which gives the index (byte offset) in {expr} where
6443 {pat} matches.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006444
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006445 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006446 If there is no match -1 is returned.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006447
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006448 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006449 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006450 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006451 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006452< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006453 *strpbrk()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02006454 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00006455 :let sepidx = match(line, '[.,;: \t]')
6456< *strcasestr()*
6457 Vim doesn't have a strcasestr() function. But you can add
6458 "\c" to the pattern to ignore case: >
6459 :let idx = match(haystack, '\cneedle')
6460<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006461 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006462 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006463 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006464 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006465 :echo match("testing", "ing", 2)
6466< result is again "4". >
6467 :echo match("testing", "ing", 4)
6468< result is again "4". >
6469 :echo match("testing", "t", 2)
6470< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006471 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00006472 {start} bytes later, thus "^" will match at {start}. Except
6473 when {count} is given, then it's like matches before the
6474 {start} byte are ignored (this is a bit complicated to keep it
6475 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006476 For a String, if {start} < 0, it will be set to 0. For a list
6477 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006478 If {start} is out of range ({start} > strlen({expr}) for a
6479 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006480
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006481 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006482 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006483 character further. Thus this example results in 1: >
6484 echo match("testing", "..", 0, 2)
6485< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006486 Note that when {count} is added the way {start} works changes,
6487 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006488
Bram Moolenaar071d4272004-06-13 20:20:40 +00006489 See |pattern| for the patterns that are accepted.
6490 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar58b85342016-08-14 19:54:54 +02006491 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00006492 done like 'magic' is set and 'cpoptions' is empty.
6493
Bram Moolenaar95e51472018-07-28 16:55:56 +02006494 *matchadd()* *E798* *E799* *E801* *E957*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006495matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006496 Defines a pattern to be highlighted in the current window (a
6497 "match"). It will be highlighted with {group}. Returns an
6498 identification number (ID), which can be used to delete the
Bram Moolenaaraff74912019-03-30 18:11:49 +01006499 match using |matchdelete()|. The ID is bound to the window.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01006500 Matching is case sensitive and magic, unless case sensitivity
6501 or magicness are explicitly overridden in {pattern}. The
6502 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02006503 The "Conceal" value is special, it causes the match to be
6504 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006505
6506 The optional {priority} argument assigns a priority to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006507 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006508 highlighting overrule that of a match with a lower priority.
6509 A priority is specified as an integer (negative numbers are no
6510 exception). If the {priority} argument is not specified, the
6511 default priority is 10. The priority of 'hlsearch' is zero,
6512 hence all matches with a priority greater than zero will
6513 overrule it. Syntax highlighting (see 'syntax') is a separate
6514 mechanism, and regardless of the chosen priority a match will
6515 always overrule syntax highlighting.
6516
6517 The optional {id} argument allows the request for a specific
6518 match ID. If a specified ID is already taken, an error
6519 message will appear and the match will not be added. An ID
6520 is specified as a positive integer (zero excluded). IDs 1, 2
6521 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02006522 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006523 |matchadd()| automatically chooses a free ID.
6524
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006525 The optional {dict} argument allows for further custom
6526 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02006527 conceal character that will be shown for |hl-Conceal|
6528 highlighted matches. The dict can have the following members:
6529
6530 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006531 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02006532 matches, see |:syn-cchar|)
Bram Moolenaar95e51472018-07-28 16:55:56 +02006533 window Instead of the current window use the
6534 window with this number or window ID.
Bram Moolenaar6561d522015-07-21 15:48:27 +02006535
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006536 The number of matches is not limited, as it is the case with
6537 the |:match| commands.
6538
6539 Example: >
6540 :highlight MyGroup ctermbg=green guibg=green
6541 :let m = matchadd("MyGroup", "TODO")
6542< Deletion of the pattern: >
6543 :call matchdelete(m)
6544
6545< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar58b85342016-08-14 19:54:54 +02006546 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006547 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006548
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02006549 *matchaddpos()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006550matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02006551 Same as |matchadd()|, but requires a list of positions {pos}
6552 instead of a pattern. This command is faster than |matchadd()|
6553 because it does not require to handle regular expressions and
6554 sets buffer line boundaries to redraw screen. It is supposed
6555 to be used when fast match additions and deletions are
6556 required, for example to highlight matching parentheses.
6557
6558 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006559 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02006560 line has number 1.
6561 - A list with one number, e.g., [23]. The whole line with this
6562 number will be highlighted.
6563 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006564 the line number, the second one is the column number (first
6565 column is 1, the value must correspond to the byte index as
6566 |col()| would return). The character at this position will
6567 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006568 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006569 the third number gives the length of the highlight in bytes.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006570
Bram Moolenaarb3414592014-06-17 17:48:32 +02006571 The maximum number of positions is 8.
6572
6573 Example: >
6574 :highlight MyGroup ctermbg=green guibg=green
6575 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6576< Deletion of the pattern: >
6577 :call matchdelete(m)
6578
6579< Matches added by |matchaddpos()| are returned by
6580 |getmatches()| with an entry "pos1", "pos2", etc., with the
6581 value a list like the {pos} item.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006582
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006583matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006584 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006585 |:2match| or |:3match| command.
6586 Return a |List| with two elements:
6587 The name of the highlight group used
6588 The pattern used.
6589 When {nr} is not 1, 2 or 3 returns an empty |List|.
6590 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006591 This is useful to save and restore a |:match|.
6592 Highlighting matches using the |:match| commands are limited
6593 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006594
Bram Moolenaaraff74912019-03-30 18:11:49 +01006595matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006596 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00006597 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006598 otherwise -1. See example for |matchadd()|. All matches can
6599 be deleted in one operation by |clearmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01006600 If {win} is specified, use the window with this number or
6601 window ID instead of the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006602
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006603matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006604 Same as |match()|, but return the index of first character
6605 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006606 :echo matchend("testing", "ing")
6607< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00006608 *strspn()* *strcspn()*
6609 Vim doesn't have a strspn() or strcspn() function, but you can
6610 do it with matchend(): >
6611 :let span = matchend(line, '[a-zA-Z]')
6612 :let span = matchend(line, '[^a-zA-Z]')
6613< Except that -1 is returned when there are no matches.
6614
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006615 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006616 :echo matchend("testing", "ing", 2)
6617< results in "7". >
6618 :echo matchend("testing", "ing", 5)
6619< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006620 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006621
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006622matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006623 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006624 list is the matched string, same as what matchstr() would
6625 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00006626 in |:substitute|. When an optional submatch didn't match an
6627 empty string is used. Example: >
6628 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6629< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006630 When there is no match an empty list is returned.
6631
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006632matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006633 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006634 :echo matchstr("testing", "ing")
6635< results in "ing".
6636 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006637 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006638 :echo matchstr("testing", "ing", 2)
6639< results in "ing". >
6640 :echo matchstr("testing", "ing", 5)
6641< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006642 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006643 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006644
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006645matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02006646 Same as |matchstr()|, but return the matched string, the start
6647 position and the end position of the match. Example: >
6648 :echo matchstrpos("testing", "ing")
6649< results in ["ing", 4, 7].
6650 When there is no match ["", -1, -1] is returned.
6651 The {start}, if given, has the same meaning as for |match()|. >
6652 :echo matchstrpos("testing", "ing", 2)
6653< results in ["ing", 4, 7]. >
6654 :echo matchstrpos("testing", "ing", 5)
6655< result is ["", -1, -1].
6656 When {expr} is a |List| then the matching item, the index
6657 of first item where {pat} matches, the start position and the
6658 end position of the match are returned. >
6659 :echo matchstrpos([1, '__x'], '\a')
6660< result is ["x", 1, 2, 3].
6661 The type isn't changed, it's not necessarily a String.
6662
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006663 *max()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006664max({expr}) Return the maximum value of all items in {expr}.
6665 {expr} can be a list or a dictionary. For a dictionary,
6666 it returns the maximum of all values in the dictionary.
6667 If {expr} is neither a list nor a dictionary, or one of the
6668 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006669 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006670
6671 *min()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006672min({expr}) Return the minimum value of all items in {expr}.
6673 {expr} can be a list or a dictionary. For a dictionary,
6674 it returns the minimum of all values in the dictionary.
6675 If {expr} is neither a list nor a dictionary, or one of the
6676 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006677 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006678
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006679 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006680mkdir({name} [, {path} [, {prot}]])
6681 Create directory {name}.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006682
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006683 If {path} is "p" then intermediate directories are created as
6684 necessary. Otherwise it must be "".
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006685
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006686 If {prot} is given it is used to set the protection bits of
6687 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar58b85342016-08-14 19:54:54 +02006688 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006689 for others. This is only used for the last part of {name}.
6690 Thus if you create /tmp/foo/bar then /tmp/foo will be created
6691 with 0755.
6692 Example: >
6693 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006694
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006695< This function is not available in the |sandbox|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006696
Bram Moolenaar78a16b02018-04-14 13:51:55 +02006697 There is no error if the directory already exists and the "p"
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006698 flag is passed (since patch 8.0.1708). However, without the
6699 "p" option the call will fail.
6700
6701 The function result is a Number, which is 1 if the call was
6702 successful or 0 if the directory creation failed or partly
6703 failed.
6704
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006705 Not available on all systems. To check use: >
6706 :if exists("*mkdir")
6707<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006708 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006709mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006710 If [expr] is supplied and it evaluates to a non-zero Number or
6711 a non-empty String (|non-zero-arg|), then the full mode is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006712 returned, otherwise only the first letter is returned.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006713
Bram Moolenaar612cc382018-07-29 15:34:26 +02006714 n Normal, Terminal-Normal
6715 no Operator-pending
Bram Moolenaar5976f8f2018-12-27 23:44:44 +01006716 nov Operator-pending (forced characterwise |o_v|)
6717 noV Operator-pending (forced linewise |o_V|)
6718 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006719 CTRL-V is one character
Bram Moolenaar612cc382018-07-29 15:34:26 +02006720 niI Normal using |i_CTRL-O| in |Insert-mode|
6721 niR Normal using |i_CTRL-O| in |Replace-mode|
6722 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6723 v Visual by character
6724 V Visual by line
6725 CTRL-V Visual blockwise
6726 s Select by character
6727 S Select by line
6728 CTRL-S Select blockwise
6729 i Insert
6730 ic Insert mode completion |compl-generic|
6731 ix Insert mode |i_CTRL-X| completion
6732 R Replace |R|
6733 Rc Replace mode completion |compl-generic|
6734 Rv Virtual Replace |gR|
6735 Rx Replace mode |i_CTRL-X| completion
6736 c Command-line editing
6737 cv Vim Ex mode |gQ|
6738 ce Normal Ex mode |Q|
6739 r Hit-enter prompt
6740 rm The -- more -- prompt
6741 r? A |:confirm| query of some sort
6742 ! Shell or external command is executing
6743 t Terminal-Job mode: keys go to the job
Bram Moolenaar446cb832008-06-24 21:56:24 +00006744 This is useful in the 'statusline' option or when used
6745 with |remote_expr()| In most other places it always returns
6746 "c" or "n".
Bram Moolenaar612cc382018-07-29 15:34:26 +02006747 Note that in the future more modes and more specific modes may
6748 be added. It's better not to compare the whole string but only
6749 the leading character(s).
Bram Moolenaar446cb832008-06-24 21:56:24 +00006750 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006751
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006752mzeval({expr}) *mzeval()*
6753 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02006754 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006755 Numbers and strings are returned as they are.
6756 Pairs (including lists and improper lists) and vectors are
6757 returned as Vim |Lists|.
6758 Hash tables are represented as Vim |Dictionary| type with keys
6759 converted to strings.
6760 All other types are converted to string with display function.
6761 Examples: >
6762 :mz (define l (list 1 2 3))
6763 :mz (define h (make-hash)) (hash-set! h "list" l)
6764 :echo mzeval("l")
6765 :echo mzeval("h")
6766<
6767 {only available when compiled with the |+mzscheme| feature}
6768
Bram Moolenaar071d4272004-06-13 20:20:40 +00006769nextnonblank({lnum}) *nextnonblank()*
6770 Return the line number of the first line at or below {lnum}
6771 that is not blank. Example: >
6772 if getline(nextnonblank(1)) =~ "Java"
6773< When {lnum} is invalid or there is no non-blank line at or
6774 below it, zero is returned.
6775 See also |prevnonblank()|.
6776
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006777nr2char({expr} [, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006778 Return a string with a single character, which has the number
6779 value {expr}. Examples: >
6780 nr2char(64) returns "@"
6781 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01006782< When {utf8} is omitted or zero, the current 'encoding' is used.
6783 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006784 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01006785< With {utf8} set to 1, always return utf-8 characters.
6786 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006787 nr2char(10), because NULs are represented with newline
6788 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00006789 string, thus results in an empty string.
Bram Moolenaaraff74912019-03-30 18:11:49 +01006790 To turn a list of character numbers into a string: >
6791 let list = [65, 66, 67]
6792 let str = join(map(list, {_, val -> nr2char(val)}), '')
6793< Result: "ABC"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006794
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006795or({expr}, {expr}) *or()*
6796 Bitwise OR on the two arguments. The arguments are converted
6797 to a number. A List, Dict or Float argument causes an error.
6798 Example: >
6799 :let bits = or(bits, 0x80)
6800
6801
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006802pathshorten({expr}) *pathshorten()*
6803 Shorten directory names in the path {expr} and return the
6804 result. The tail, the file name, is kept as-is. The other
6805 components in the path are reduced to single letters. Leading
6806 '~' and '.' characters are kept. Example: >
6807 :echo pathshorten('~/.vim/autoload/myfile.vim')
6808< ~/.v/a/myfile.vim ~
6809 It doesn't matter if the path exists or not.
6810
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006811perleval({expr}) *perleval()*
6812 Evaluate Perl expression {expr} in scalar context and return
6813 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006814 converted, it is returned as a string Perl representation.
6815 Note: If you want an array or hash, {expr} must return a
6816 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006817 Example: >
6818 :echo perleval('[1 .. 4]')
6819< [1, 2, 3, 4]
6820 {only available when compiled with the |+perl| feature}
6821
Bram Moolenaar446cb832008-06-24 21:56:24 +00006822pow({x}, {y}) *pow()*
6823 Return the power of {x} to the exponent {y} as a |Float|.
6824 {x} and {y} must evaluate to a |Float| or a |Number|.
6825 Examples: >
6826 :echo pow(3, 3)
6827< 27.0 >
6828 :echo pow(2, 16)
6829< 65536.0 >
6830 :echo pow(32, 0.20)
6831< 2.0
6832 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006833
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006834prevnonblank({lnum}) *prevnonblank()*
6835 Return the line number of the first line at or above {lnum}
6836 that is not blank. Example: >
6837 let ind = indent(prevnonblank(v:lnum - 1))
6838< When {lnum} is invalid or there is no non-blank line at or
6839 above it, zero is returned.
6840 Also see |nextnonblank()|.
6841
6842
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006843printf({fmt}, {expr1} ...) *printf()*
6844 Return a String with {fmt}, where "%" items are replaced by
6845 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006846 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006847< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006848 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006849
6850 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006851 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006852 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00006853 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006854 %.9s string truncated to 9 bytes
6855 %c single byte
6856 %d decimal number
6857 %5d decimal number padded with spaces to 5 characters
6858 %x hex number
6859 %04x hex number padded with zeros to at least 4 characters
6860 %X hex number using upper case letters
6861 %o octal number
Bram Moolenaar91984b92016-08-16 21:58:41 +02006862 %08b binary number padded with zeros to at least 8 chars
Bram Moolenaar04186092016-08-29 21:55:35 +02006863 %f floating point number as 12.23, inf, -inf or nan
6864 %F floating point number as 12.23, INF, -INF or NAN
6865 %e floating point number as 1.23e3, inf, -inf or nan
6866 %E floating point number as 1.23E3, INF, -INF or NAN
Bram Moolenaar446cb832008-06-24 21:56:24 +00006867 %g floating point number, as %f or %e depending on value
Bram Moolenaar3df01732017-02-17 22:47:16 +01006868 %G floating point number, as %F or %E depending on value
Bram Moolenaar446cb832008-06-24 21:56:24 +00006869 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006870
6871 Conversion specifications start with '%' and end with the
6872 conversion type. All other characters are copied unchanged to
6873 the result.
6874
6875 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006876 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006877
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006878 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006879
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006880 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006881 Zero or more of the following flags:
6882
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006883 # The value should be converted to an "alternate
6884 form". For c, d, and s conversions, this option
6885 has no effect. For o conversions, the precision
6886 of the number is increased to force the first
6887 character of the output string to a zero (except
6888 if a zero value is printed with an explicit
6889 precision of zero).
Bram Moolenaar91984b92016-08-16 21:58:41 +02006890 For b and B conversions, a non-zero result has
6891 the string "0b" (or "0B" for B conversions)
6892 prepended to it.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006893 For x and X conversions, a non-zero result has
6894 the string "0x" (or "0X" for X conversions)
6895 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006896
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006897 0 (zero) Zero padding. For all conversions the converted
6898 value is padded on the left with zeros rather
6899 than blanks. If a precision is given with a
Bram Moolenaar91984b92016-08-16 21:58:41 +02006900 numeric conversion (d, b, B, o, x, and X), the 0
6901 flag is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006902
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006903 - A negative field width flag; the converted value
6904 is to be left adjusted on the field boundary.
6905 The converted value is padded on the right with
6906 blanks, rather than on the left with blanks or
6907 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006908
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006909 ' ' (space) A blank should be left before a positive
6910 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006911
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006912 + A sign must always be placed before a number
Bram Moolenaar58b85342016-08-14 19:54:54 +02006913 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006914 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006915
6916 field-width
6917 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00006918 field width. If the converted value has fewer bytes
6919 than the field width, it will be padded with spaces on
6920 the left (or right, if the left-adjustment flag has
6921 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006922
6923 .precision
6924 An optional precision, in the form of a period '.'
6925 followed by an optional digit string. If the digit
6926 string is omitted, the precision is taken as zero.
6927 This gives the minimum number of digits to appear for
6928 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00006929 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006930 For floating point it is the number of digits after
6931 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006932
6933 type
6934 A character that specifies the type of conversion to
6935 be applied, see below.
6936
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006937 A field width or precision, or both, may be indicated by an
6938 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar58b85342016-08-14 19:54:54 +02006939 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006940 negative field width is treated as a left adjustment flag
6941 followed by a positive field width; a negative precision is
6942 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006943 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006944< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006945 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006946
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006947 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006948
Bram Moolenaar91984b92016-08-16 21:58:41 +02006949 *printf-d* *printf-b* *printf-B* *printf-o*
6950 *printf-x* *printf-X*
6951 dbBoxX The Number argument is converted to signed decimal
6952 (d), unsigned binary (b and B), unsigned octal (o), or
6953 unsigned hexadecimal (x and X) notation. The letters
6954 "abcdef" are used for x conversions; the letters
6955 "ABCDEF" are used for X conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006956 The precision, if any, gives the minimum number of
6957 digits that must appear; if the converted value
6958 requires fewer digits, it is padded on the left with
6959 zeros.
6960 In no case does a non-existent or small field width
6961 cause truncation of a numeric field; if the result of
6962 a conversion is wider than the field width, the field
6963 is expanded to contain the conversion result.
Bram Moolenaar30567352016-08-27 21:25:44 +02006964 The 'h' modifier indicates the argument is 16 bits.
6965 The 'l' modifier indicates the argument is 32 bits.
6966 The 'L' modifier indicates the argument is 64 bits.
6967 Generally, these modifiers are not useful. They are
6968 ignored when type is known from the argument.
6969
6970 i alias for d
6971 D alias for ld
6972 U alias for lu
6973 O alias for lo
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006974
Bram Moolenaar446cb832008-06-24 21:56:24 +00006975 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006976 c The Number argument is converted to a byte, and the
6977 resulting character is written.
6978
Bram Moolenaar446cb832008-06-24 21:56:24 +00006979 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006980 s The text of the String argument is used. If a
6981 precision is specified, no more bytes than the number
6982 specified are used.
Bram Moolenaar7571d552016-08-18 22:54:46 +02006983 If the argument is not a String type, it is
6984 automatically converted to text with the same format
6985 as ":echo".
Bram Moolenaar0122c402015-02-03 19:13:34 +01006986 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006987 S The text of the String argument is used. If a
6988 precision is specified, no more display cells than the
Bram Moolenaar4c92e752019-02-17 21:18:32 +01006989 number specified are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006990
Bram Moolenaar446cb832008-06-24 21:56:24 +00006991 *printf-f* *E807*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006992 f F The Float argument is converted into a string of the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006993 form 123.456. The precision specifies the number of
6994 digits after the decimal point. When the precision is
6995 zero the decimal point is omitted. When the precision
6996 is not specified 6 is used. A really big number
Bram Moolenaar04186092016-08-29 21:55:35 +02006997 (out of range or dividing by zero) results in "inf"
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006998 or "-inf" with %f (INF or -INF with %F).
6999 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007000 Example: >
7001 echo printf("%.2f", 12.115)
7002< 12.12
7003 Note that roundoff depends on the system libraries.
7004 Use |round()| when in doubt.
7005
7006 *printf-e* *printf-E*
7007 e E The Float argument is converted into a string of the
7008 form 1.234e+03 or 1.234E+03 when using 'E'. The
7009 precision specifies the number of digits after the
7010 decimal point, like with 'f'.
7011
7012 *printf-g* *printf-G*
7013 g G The Float argument is converted like with 'f' if the
7014 value is between 0.001 (inclusive) and 10000000.0
7015 (exclusive). Otherwise 'e' is used for 'g' and 'E'
7016 for 'G'. When no precision is specified superfluous
7017 zeroes and '+' signs are removed, except for the zero
7018 immediately after the decimal point. Thus 10000000.0
7019 results in 1.0e7.
7020
7021 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007022 % A '%' is written. No argument is converted. The
7023 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007024
Bram Moolenaarc236c162008-07-13 17:41:49 +00007025 When a Number argument is expected a String argument is also
7026 accepted and automatically converted.
7027 When a Float or String argument is expected a Number argument
7028 is also accepted and automatically converted.
7029 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007030
Bram Moolenaar83bab712005-08-01 21:58:57 +00007031 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007032 The number of {exprN} arguments must exactly match the number
7033 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007034 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007035
7036
Bram Moolenaarf2732452018-06-03 14:47:35 +02007037prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007038 Set prompt callback for buffer {buf} to {expr}. When {expr}
7039 is an empty string the callback is removed. This has only
Bram Moolenaarf2732452018-06-03 14:47:35 +02007040 effect if {buf} has 'buftype' set to "prompt".
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007041
Bram Moolenaarf2732452018-06-03 14:47:35 +02007042 The callback is invoked when pressing Enter. The current
7043 buffer will always be the prompt buffer. A new line for a
7044 prompt is added before invoking the callback, thus the prompt
7045 for which the callback was invoked will be in the last but one
7046 line.
7047 If the callback wants to add text to the buffer, it must
7048 insert it above the last line, since that is where the current
7049 prompt is. This can also be done asynchronously.
7050 The callback is invoked with one argument, which is the text
7051 that was entered at the prompt. This can be an empty string
7052 if the user only typed Enter.
7053 Example: >
7054 call prompt_setcallback(bufnr(''), function('s:TextEntered'))
7055 func s:TextEntered(text)
7056 if a:text == 'exit' || a:text == 'quit'
7057 stopinsert
7058 close
7059 else
7060 call append(line('$') - 1, 'Entered: "' . a:text . '"')
7061 " Reset 'modified' to allow the buffer to be closed.
7062 set nomodified
7063 endif
7064 endfunc
7065
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007066prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
7067 Set a callback for buffer {buf} to {expr}. When {expr} is an
7068 empty string the callback is removed. This has only effect if
7069 {buf} has 'buftype' set to "prompt".
7070
7071 This callback will be invoked when pressing CTRL-C in Insert
7072 mode. Without setting a callback Vim will exit Insert mode,
7073 as in any buffer.
7074
7075prompt_setprompt({buf}, {text}) *prompt_setprompt()*
7076 Set prompt for buffer {buf} to {text}. You most likely want
7077 {text} to end in a space.
7078 The result is only visible if {buf} has 'buftype' set to
7079 "prompt". Example: >
7080 call prompt_setprompt(bufnr(''), 'command: ')
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007081<
7082 *prop_add()* *E965*
7083prop_add({lnum}, {col}, {props})
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007084 Attach a text property at position {lnum}, {col}. {col} is
7085 counted in bytes, use one for the first column.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007086 If {lnum} is invalid an error is given. *E966*
7087 If {col} is invalid an error is given. *E964*
7088
7089 {props} is a dictionary with these fields:
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007090 length length of text in bytes, can only be used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007091 for a property that does not continue in
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007092 another line; can be zero
7093 end_lnum line number for the end of text
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007094 end_col column just after the text; not used when
7095 "length" is present; when {col} and "end_col"
7096 are equal, and "end_lnum" is omitted or equal
7097 to {lnum}, this is a zero-width text property
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007098 bufnr buffer to add the property to; when omitted
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007099 the current buffer is used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007100 id user defined ID for the property; when omitted
7101 zero is used
7102 type name of the text property type
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007103 All fields except "type" are optional.
7104
7105 It is an error when both "length" and "end_lnum" or "end_col"
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007106 are given. Either use "length" or "end_col" for a property
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007107 within one line, or use "end_lnum" and "end_col" for a
7108 property that spans more than one line.
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01007109 When neither "length" nor "end_col" are given the property
7110 will be zero-width. That means it will not be highlighted but
7111 will move with the text, as a kind of mark.
Bram Moolenaare3d31b02018-12-24 23:07:04 +01007112 The property can end exactly at the last character of the
7113 text, or just after it. In the last case, if text is appended
7114 to the line, the text property size will increase, also when
7115 the property type does not have "end_incl" set.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007116
7117 "type" will first be looked up in the buffer the property is
7118 added to. When not found, the global property types are used.
7119 If not found an error is given.
7120
7121 See |text-properties| for information about text properties.
7122
7123
Bram Moolenaar9d87a372018-12-18 21:41:50 +01007124prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007125 Remove all text properties from line {lnum}.
Bram Moolenaar9d87a372018-12-18 21:41:50 +01007126 When {lnum-end} is given, remove all text properties from line
7127 {lnum} to {lnum-end} (inclusive).
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007128
7129 When {props} contains a "bufnr" item use this buffer,
7130 otherwise use the current buffer.
7131
7132 See |text-properties| for information about text properties.
7133
7134 *prop_find()*
7135prop_find({props} [, {direction}])
7136 NOT IMPLEMENTED YET
7137 Search for a text property as specified with {props}:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007138 id property with this ID
7139 type property with this type name
7140 bufnr buffer to search in; when present a
7141 start position with "lnum" and "col"
7142 must be given; when omitted the
7143 current buffer is used
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007144 lnum start in this line (when omitted start
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007145 at the cursor)
7146 col start at this column (when omitted
7147 and "lnum" is given: use column 1,
7148 otherwise start at the cursor)
7149 skipstart do not look for a match at the start
7150 position
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007151
7152 {direction} can be "f" for forward and "b" for backward. When
7153 omitted forward search is performed.
7154
7155 If a match is found then a Dict is returned with the entries
7156 as with prop_list(), and additionally an "lnum" entry.
7157 If no match is found then an empty Dict is returned.
7158
7159 See |text-properties| for information about text properties.
7160
7161
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007162prop_list({lnum} [, {props}]) *prop_list()*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007163 Return a List with all text properties in line {lnum}.
7164
7165 When {props} contains a "bufnr" item, use this buffer instead
7166 of the current buffer.
7167
7168 The properties are ordered by starting column and priority.
7169 Each property is a Dict with these entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007170 col starting column
Bram Moolenaar4c05fa02019-01-01 15:32:17 +01007171 length length in bytes, one more if line break is
7172 included
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007173 id property ID
7174 type name of the property type, omitted if
7175 the type was deleted
7176 start when TRUE property starts in this line
7177 end when TRUE property ends in this line
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007178
7179 When "start" is zero the property started in a previous line,
7180 the current one is a continuation.
7181 When "end" is zero the property continues in the next line.
7182 The line break after this line is included.
7183
7184 See |text-properties| for information about text properties.
7185
7186
7187 *prop_remove()* *E968*
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007188prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007189 Remove a matching text property from line {lnum}. When
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007190 {lnum-end} is given, remove matching text properties from line
7191 {lnum} to {lnum-end} (inclusive).
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007192 When {lnum} is omitted remove matching text properties from
7193 all lines.
7194
7195 {props} is a dictionary with these fields:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007196 id remove text properties with this ID
7197 type remove text properties with this type name
7198 bufnr use this buffer instead of the current one
7199 all when TRUE remove all matching text properties,
7200 not just the first one
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007201 A property matches when either "id" or "type" matches.
7202
7203 Returns the number of properties that were removed.
7204
7205 See |text-properties| for information about text properties.
7206
7207
7208prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970*
7209 Add a text property type {name}. If a property type with this
7210 name already exists an error is given.
7211 {props} is a dictionary with these optional fields:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007212 bufnr define the property only for this buffer; this
7213 avoids name collisions and automatically
7214 clears the property types when the buffer is
7215 deleted.
7216 highlight name of highlight group to use
7217 priority when a character has multiple text
7218 properties the one with the highest priority
7219 will be used; negative values can be used, the
7220 default priority is zero
Bram Moolenaarde24a872019-05-05 15:48:00 +02007221 combine when TRUE combine the highlight with any
7222 syntax highlight; when omitted of FALSE syntax
7223 highlight will not be used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007224 start_incl when TRUE inserts at the start position will
7225 be included in the text property
7226 end_incl when TRUE inserts at the end position will be
7227 included in the text property
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007228
7229 See |text-properties| for information about text properties.
7230
7231
7232prop_type_change({name}, {props}) *prop_type_change()*
7233 Change properties of an existing text property type. If a
7234 property with this name does not exist an error is given.
7235 The {props} argument is just like |prop_type_add()|.
7236
7237 See |text-properties| for information about text properties.
7238
7239
7240prop_type_delete({name} [, {props}]) *prop_type_delete()*
7241 Remove the text property type {name}. When text properties
7242 using the type {name} are still in place, they will not have
7243 an effect and can no longer be removed by name.
7244
7245 {props} can contain a "bufnr" item. When it is given, delete
7246 a property type from this buffer instead of from the global
7247 property types.
7248
7249 When text property type {name} is not found there is no error.
7250
7251 See |text-properties| for information about text properties.
7252
7253
7254prop_type_get([{name} [, {props}]) *prop_type_get()*
7255 Returns the properties of property type {name}. This is a
7256 dictionary with the same fields as was given to
7257 prop_type_add().
7258 When the property type {name} does not exist, an empty
7259 dictionary is returned.
7260
7261 {props} can contain a "bufnr" item. When it is given, use
7262 this buffer instead of the global property types.
7263
7264 See |text-properties| for information about text properties.
7265
7266
7267prop_type_list([{props}]) *prop_type_list()*
7268 Returns a list with all property type names.
7269
7270 {props} can contain a "bufnr" item. When it is given, use
7271 this buffer instead of the global property types.
7272
7273 See |text-properties| for information about text properties.
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007274
Bram Moolenaarf2732452018-06-03 14:47:35 +02007275
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007276pumvisible() *pumvisible()*
7277 Returns non-zero when the popup menu is visible, zero
7278 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007279 This can be used to avoid some things that would remove the
7280 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007281
Bram Moolenaar30b65812012-07-12 22:01:11 +02007282py3eval({expr}) *py3eval()*
7283 Evaluate Python expression {expr} and return its result
7284 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007285 Numbers and strings are returned as they are (strings are
7286 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02007287 'encoding').
7288 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007289 Dictionaries are represented as Vim |Dictionary| type with
Bram Moolenaar30b65812012-07-12 22:01:11 +02007290 keys converted to strings.
7291 {only available when compiled with the |+python3| feature}
7292
7293 *E858* *E859*
7294pyeval({expr}) *pyeval()*
7295 Evaluate Python expression {expr} and return its result
7296 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007297 Numbers and strings are returned as they are (strings are
Bram Moolenaar30b65812012-07-12 22:01:11 +02007298 copied though).
7299 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007300 Dictionaries are represented as Vim |Dictionary| type,
Bram Moolenaard09acef2012-09-21 14:54:30 +02007301 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02007302 {only available when compiled with the |+python| feature}
7303
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01007304pyxeval({expr}) *pyxeval()*
7305 Evaluate Python expression {expr} and return its result
7306 converted to Vim data structures.
7307 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7308 See also: |pyeval()|, |py3eval()|
7309 {only available when compiled with the |+python| or the
7310 |+python3| feature}
7311
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007312 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00007313range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007314 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00007315 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7316 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7317 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7318 {max}] (increasing {expr} with {stride} each time, not
7319 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00007320 When the maximum is one before the start the result is an
7321 empty list. When the maximum is more than one before the
7322 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00007323 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007324 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00007325 range(2, 4) " [2, 3, 4]
7326 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007327 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00007328 range(0) " []
7329 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00007330<
Bram Moolenaar543c9b12019-04-05 22:50:40 +02007331 *readdir()*
7332readdir({directory} [, {expr}])
7333 Return a list with file and directory names in {directory}.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02007334 You can also use |glob()| if you don't need to do complicated
7335 things, such as limiting the number of matches.
Bram Moolenaar543c9b12019-04-05 22:50:40 +02007336
7337 When {expr} is omitted all entries are included.
7338 When {expr} is given, it is evaluated to check what to do:
7339 If {expr} results in -1 then no further entries will
7340 be handled.
7341 If {expr} results in 0 then this entry will not be
7342 added to the list.
7343 If {expr} results in 1 then this entry will be added
7344 to the list.
7345 Each time {expr} is evaluated |v:val| is set to the entry name.
7346 When {expr} is a function the name is passed as the argument.
7347 For example, to get a list of files ending in ".txt": >
7348 readdir(dirname, {n -> n =~ '.txt$'})
7349< To skip hidden and backup files: >
7350 readdir(dirname, {n -> n !~ '^\.\|\~$'})
7351
7352< If you want to get a directory tree: >
7353 function! s:tree(dir)
7354 return {a:dir : map(readdir(a:dir),
7355 \ {_, x -> isdirectory(x) ?
7356 \ {x : s:tree(a:dir . '/' . x)} : x})}
7357 endfunction
7358 echo s:tree(".")
7359<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007360 *readfile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007361readfile({fname} [, {type} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007362 Read file {fname} and return a |List|, each line of the file
Bram Moolenaar6100d022016-10-02 16:51:57 +02007363 as an item. Lines are broken at NL characters. Macintosh
7364 files separated with CR will result in a single long line
7365 (unless a NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02007366 All NUL characters are replaced with a NL character.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007367 When {type} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007368 - When the last line ends in a NL an extra empty list item is
7369 added.
7370 - No CR characters are removed.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007371 When {type} contains "B" a |Blob| is returned with the binary
7372 data of the file unmodified.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007373 Otherwise:
7374 - CR characters that appear before a NL are removed.
7375 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02007376 - When 'encoding' is Unicode any UTF-8 byte order mark is
7377 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007378 When {max} is given this specifies the maximum number of lines
7379 to be read. Useful if you only want to check the first ten
7380 lines of a file: >
7381 :for line in readfile(fname, '', 10)
7382 : if line =~ 'Date' | echo line | endif
7383 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00007384< When {max} is negative -{max} lines from the end of the file
7385 are returned, or as many as there are.
7386 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007387 Note that without {max} the whole file is read into memory.
7388 Also note that there is no recognition of encoding. Read a
7389 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007390 When the file can't be opened an error message is given and
7391 the result is an empty list.
7392 Also see |writefile()|.
7393
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007394reg_executing() *reg_executing()*
7395 Returns the single letter name of the register being executed.
7396 Returns an empty string when no register is being executed.
7397 See |@|.
7398
7399reg_recording() *reg_recording()*
7400 Returns the single letter name of the register being recorded.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02007401 Returns an empty string when not recording. See |q|.
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007402
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007403reltime([{start} [, {end}]]) *reltime()*
7404 Return an item that represents a time value. The format of
7405 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02007406 |reltimestr()| to convert it to a string or |reltimefloat()|
7407 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007408 Without an argument it returns the current time.
7409 With one argument is returns the time passed since the time
7410 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007411 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007412 and {end}.
7413 The {start} and {end} arguments must be values returned by
7414 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02007415 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007416
Bram Moolenaar03413f42016-04-12 21:07:15 +02007417reltimefloat({time}) *reltimefloat()*
7418 Return a Float that represents the time value of {time}.
7419 Example: >
7420 let start = reltime()
7421 call MyFunction()
7422 let seconds = reltimefloat(reltime(start))
7423< See the note of reltimestr() about overhead.
7424 Also see |profiling|.
7425 {only available when compiled with the |+reltime| feature}
7426
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007427reltimestr({time}) *reltimestr()*
7428 Return a String that represents the time value of {time}.
7429 This is the number of seconds, a dot and the number of
7430 microseconds. Example: >
7431 let start = reltime()
7432 call MyFunction()
7433 echo reltimestr(reltime(start))
7434< Note that overhead for the commands will be added to the time.
7435 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007436 Leading spaces are used to make the string align nicely. You
7437 can use split() to remove it. >
7438 echo split(reltimestr(reltime(start)))[0]
7439< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02007440 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007441
Bram Moolenaar071d4272004-06-13 20:20:40 +00007442 *remote_expr()* *E449*
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007443remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007444 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00007445 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007446 The result must be a String or a |List|. A |List| is turned
7447 into a String by joining the items with a line break in
7448 between (not at the end), like with join(expr, "\n").
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007449 If {idvar} is present and not empty, it is taken as the name
7450 of a variable and a {serverid} for later use with
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01007451 |remote_read()| is stored there.
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007452 If {timeout} is given the read times out after this many
7453 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007454 See also |clientserver| |RemoteReply|.
7455 This function is not available in the |sandbox|.
7456 {only available when compiled with the |+clientserver| feature}
7457 Note: Any errors will cause a local error message to be issued
7458 and the result will be the empty string.
Bram Moolenaar01164a62017-11-02 22:58:42 +01007459
7460 Variables will be evaluated in the global namespace,
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007461 independent of a function currently being active. Except
Bram Moolenaar01164a62017-11-02 22:58:42 +01007462 when in debug mode, then local function variables and
7463 arguments can be evaluated.
7464
Bram Moolenaar071d4272004-06-13 20:20:40 +00007465 Examples: >
7466 :echo remote_expr("gvim", "2+2")
7467 :echo remote_expr("gvim1", "b:current_syntax")
7468<
7469
7470remote_foreground({server}) *remote_foreground()*
7471 Move the Vim server with the name {server} to the foreground.
7472 This works like: >
7473 remote_expr({server}, "foreground()")
7474< Except that on Win32 systems the client does the work, to work
7475 around the problem that the OS doesn't always allow the server
7476 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00007477 Note: This does not restore the window if it was minimized,
7478 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007479 This function is not available in the |sandbox|.
7480 {only in the Win32, Athena, Motif and GTK GUI versions and the
7481 Win32 console version}
7482
7483
7484remote_peek({serverid} [, {retvar}]) *remote_peek()*
7485 Returns a positive number if there are available strings
7486 from {serverid}. Copies any reply string into the variable
Bram Moolenaar58b85342016-08-14 19:54:54 +02007487 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007488 name of a variable.
7489 Returns zero if none are available.
7490 Returns -1 if something is wrong.
7491 See also |clientserver|.
7492 This function is not available in the |sandbox|.
7493 {only available when compiled with the |+clientserver| feature}
7494 Examples: >
7495 :let repl = ""
7496 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
7497
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007498remote_read({serverid}, [{timeout}]) *remote_read()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007499 Return the oldest available reply from {serverid} and consume
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007500 it. Unless a {timeout} in seconds is given, it blocks until a
7501 reply is available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007502 See also |clientserver|.
7503 This function is not available in the |sandbox|.
7504 {only available when compiled with the |+clientserver| feature}
7505 Example: >
7506 :echo remote_read(id)
7507<
7508 *remote_send()* *E241*
7509remote_send({server}, {string} [, {idvar}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007510 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00007511 keys and the function returns immediately. At the Vim server
7512 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007513 If {idvar} is present, it is taken as the name of a variable
7514 and a {serverid} for later use with remote_read() is stored
7515 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007516 See also |clientserver| |RemoteReply|.
7517 This function is not available in the |sandbox|.
7518 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007519
Bram Moolenaar071d4272004-06-13 20:20:40 +00007520 Note: Any errors will be reported in the server and may mess
7521 up the display.
7522 Examples: >
7523 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
7524 \ remote_read(serverid)
7525
7526 :autocmd NONE RemoteReply *
7527 \ echo remote_read(expand("<amatch>"))
7528 :echo remote_send("gvim", ":sleep 10 | echo ".
7529 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007530<
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007531 *remote_startserver()* *E941* *E942*
7532remote_startserver({name})
7533 Become the server {name}. This fails if already running as a
7534 server, when |v:servername| is not empty.
7535 {only available when compiled with the |+clientserver| feature}
7536
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007537remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007538 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007539 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007540 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007541 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007542 item as {end} a list with one item is returned. When {end}
7543 points to an item before {idx} this is an error.
7544 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007545 Example: >
7546 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007547 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007548<
7549 Use |delete()| to remove a file.
7550
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007551remove({blob}, {idx} [, {end}])
7552 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7553 return the byte.
7554 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7555 return a |Blob| with these bytes. When {idx} points to the same
7556 byte as {end} a |Blob| with one byte is returned. When {end}
7557 points to a byte before {idx} this is an error.
7558 Example: >
7559 :echo "last byte: " . remove(myblob, -1)
7560 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007561
Bram Moolenaard8b02732005-01-14 21:48:43 +00007562remove({dict}, {key})
7563 Remove the entry from {dict} with key {key}. Example: >
7564 :echo "removed " . remove(dict, "one")
7565< If there is no {key} in {dict} this is an error.
7566
Bram Moolenaar071d4272004-06-13 20:20:40 +00007567rename({from}, {to}) *rename()*
7568 Rename the file by the name {from} to the name {to}. This
7569 should also work to move files across file systems. The
7570 result is a Number, which is 0 if the file was renamed
7571 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00007572 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007573 This function is not available in the |sandbox|.
7574
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007575repeat({expr}, {count}) *repeat()*
7576 Repeat {expr} {count} times and return the concatenated
7577 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007578 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007579< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007580 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar58b85342016-08-14 19:54:54 +02007581 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007582 :let longlist = repeat(['a', 'b'], 3)
7583< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007584
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007585
Bram Moolenaar071d4272004-06-13 20:20:40 +00007586resolve({filename}) *resolve()* *E655*
7587 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7588 returns the path the shortcut points to in a simplified form.
Bram Moolenaardce1e892019-02-10 23:18:53 +01007589 When {filename} is a symbolic link or junction point, return
7590 the full path to the target. If the target of junction is
7591 removed, return {filename}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007592 On Unix, repeat resolving symbolic links in all path
7593 components of {filename} and return the simplified result.
7594 To cope with link cycles, resolving of symbolic links is
7595 stopped after 100 iterations.
7596 On other systems, return the simplified {filename}.
7597 The simplification step is done as by |simplify()|.
7598 resolve() keeps a leading path component specifying the
7599 current directory (provided the result is still a relative
7600 path name) and also keeps a trailing path separator.
7601
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007602 *reverse()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007603reverse({object})
7604 Reverse the order of items in {object} in-place.
7605 {object} can be a |List| or a |Blob|.
7606 Returns {object}.
7607 If you want an object to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007608 :let revlist = reverse(copy(mylist))
7609
Bram Moolenaar446cb832008-06-24 21:56:24 +00007610round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007611 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00007612 as a |Float|. If {expr} lies halfway between two integral
7613 values, then use the larger one (away from zero).
7614 {expr} must evaluate to a |Float| or a |Number|.
7615 Examples: >
7616 echo round(0.456)
7617< 0.0 >
7618 echo round(4.5)
7619< 5.0 >
7620 echo round(-4.5)
7621< -5.0
7622 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007623
Bram Moolenaare99be0e2019-03-26 22:51:09 +01007624rubyeval({expr}) *rubyeval()*
7625 Evaluate Ruby expression {expr} and return its result
7626 converted to Vim data structures.
7627 Numbers, floats and strings are returned as they are (strings
7628 are copied though).
7629 Arrays are represented as Vim |List| type.
7630 Hashes are represented as Vim |Dictionary| type.
7631 Other objects are represented as strings resulted from their
7632 "Object#to_s" method.
7633 {only available when compiled with the |+ruby| feature}
7634
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007635screenattr({row}, {col}) *screenattr()*
Bram Moolenaar36f44c22016-08-28 18:17:20 +02007636 Like |screenchar()|, but return the attribute. This is a rather
Bram Moolenaar9a773482013-06-11 18:40:13 +02007637 arbitrary number that can only be used to compare to the
7638 attribute at other positions.
7639
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007640screenchar({row}, {col}) *screenchar()*
Bram Moolenaar9a773482013-06-11 18:40:13 +02007641 The result is a Number, which is the character at position
7642 [row, col] on the screen. This works for every possible
7643 screen position, also status lines, window separators and the
7644 command line. The top left position is row one, column one
7645 The character excludes composing characters. For double-byte
7646 encodings it may only be the first byte.
7647 This is mainly to be used for testing.
7648 Returns -1 when row or col is out of range.
7649
Bram Moolenaar2912abb2019-03-29 14:16:42 +01007650screenchars({row}, {col}) *screenchars()*
7651 The result is a List of Numbers. The first number is the same
7652 as what |screenchar()| returns. Further numbers are
7653 composing characters on top of the base character.
7654 This is mainly to be used for testing.
7655 Returns an empty List when row or col is out of range.
7656
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007657screencol() *screencol()*
7658 The result is a Number, which is the current screen column of
7659 the cursor. The leftmost column has number 1.
7660 This function is mainly used for testing.
7661
7662 Note: Always returns the current screen column, thus if used
7663 in a command (e.g. ":echo screencol()") it will return the
7664 column inside the command line, which is 1 when the command is
7665 executed. To get the cursor position in the file use one of
7666 the following mappings: >
7667 nnoremap <expr> GG ":echom ".screencol()."\n"
7668 nnoremap <silent> GG :echom screencol()<CR>
7669<
7670screenrow() *screenrow()*
7671 The result is a Number, which is the current screen row of the
7672 cursor. The top line has number one.
7673 This function is mainly used for testing.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02007674 Alternatively you can use |winline()|.
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007675
7676 Note: Same restrictions as with |screencol()|.
7677
Bram Moolenaar2912abb2019-03-29 14:16:42 +01007678screenstring({row}, {col}) *screenstring()*
7679 The result is a String that contains the base character and
7680 any composing characters at position [row, col] on the screen.
7681 This is like |screenchars()| but returning a String with the
7682 characters.
7683 This is mainly to be used for testing.
7684 Returns an empty String when row or col is out of range.
7685
Bram Moolenaar76929292008-01-06 19:07:36 +00007686search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007687 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00007688 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007689
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007690 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007691 If there is no match a 0 is returned and the cursor doesn't
7692 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007693
Bram Moolenaar071d4272004-06-13 20:20:40 +00007694 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007695 'b' search Backward instead of forward
7696 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007697 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007698 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007699 'p' return number of matching sub-Pattern (see below)
7700 's' Set the ' mark at the previous location of the cursor
7701 'w' Wrap around the end of the file
7702 'W' don't Wrap around the end of the file
7703 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00007704 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7705
Bram Moolenaar02743632005-07-25 20:42:36 +00007706 If the 's' flag is supplied, the ' mark is set, only if the
7707 cursor is moved. The 's' flag cannot be combined with the 'n'
7708 flag.
7709
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007710 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007711
Bram Moolenaar85084ef2016-01-17 22:26:33 +01007712 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007713 column zero and then matches before the cursor are skipped.
7714 When the 'c' flag is present in 'cpo' the next search starts
7715 after the match. Without the 'c' flag the next search starts
7716 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007717
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007718 When the {stopline} argument is given then the search stops
7719 after searching this line. This is useful to restrict the
7720 search to a range of lines. Examples: >
7721 let match = search('(', 'b', line("w0"))
7722 let end = search('END', '', line("w$"))
7723< When {stopline} is used and it is not zero this also implies
7724 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00007725 A zero value is equal to not giving the argument.
7726
7727 When the {timeout} argument is given the search stops when
Bram Moolenaar58b85342016-08-14 19:54:54 +02007728 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00007729 {timeout} is 500 the search stops after half a second.
7730 The value must not be negative. A zero value is like not
7731 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02007732 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007733
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007734 *search()-sub-match*
7735 With the 'p' flag the returned value is one more than the
7736 first sub-match in \(\). One if none of them matched but the
7737 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007738 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007739
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007740 The cursor will be positioned at the match, unless the 'n'
7741 flag is used.
7742
Bram Moolenaar071d4272004-06-13 20:20:40 +00007743 Example (goes over all files in the argument list): >
7744 :let n = 1
7745 :while n <= argc() " loop over all files in arglist
7746 : exe "argument " . n
7747 : " start at the last char in the file and wrap for the
7748 : " first search to find match at start of file
7749 : normal G$
7750 : let flags = "w"
7751 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00007752 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00007753 : let flags = "W"
7754 : endwhile
7755 : update " write the file if modified
7756 : let n = n + 1
7757 :endwhile
7758<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007759 Example for using some flags: >
7760 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7761< This will search for the keywords "if", "else", and "endif"
7762 under or after the cursor. Because of the 'p' flag, it
7763 returns 1, 2, or 3 depending on which keyword is found, or 0
7764 if the search fails. With the cursor on the first word of the
7765 line:
7766 if (foo == 0) | let foo = foo + 1 | endif ~
7767 the function returns 1. Without the 'c' flag, the function
7768 finds the "endif" and returns 3. The same thing happens
7769 without the 'e' flag if the cursor is on the "f" of "if".
7770 The 'n' flag tells the function not to move the cursor.
7771
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007772
Bram Moolenaarf75a9632005-09-13 21:20:47 +00007773searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7774 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007775
Bram Moolenaarf75a9632005-09-13 21:20:47 +00007776 With a non-zero {global} argument it works like |gD|, find
7777 first match in the file. Otherwise it works like |gd|, find
7778 first match in the function.
7779
7780 With a non-zero {thisblock} argument matches in a {} block
7781 that ends before the cursor position are ignored. Avoids
7782 finding variable declarations only valid in another scope.
7783
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007784 Moves the cursor to the found match.
7785 Returns zero for success, non-zero for failure.
7786 Example: >
7787 if searchdecl('myvar') == 0
7788 echo getline('.')
7789 endif
7790<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007791 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00007792searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7793 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00007794 Search for the match of a nested start-end pair. This can be
7795 used to find the "endif" that matches an "if", while other
7796 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007797 The search starts at the cursor. The default is to search
7798 forward, include 'b' in {flags} to search backward.
7799 If a match is found, the cursor is positioned at it and the
7800 line number is returned. If no match is found 0 or -1 is
7801 returned and the cursor doesn't move. No error message is
7802 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007803
7804 {start}, {middle} and {end} are patterns, see |pattern|. They
7805 must not contain \( \) pairs. Use of \%( \) is allowed. When
7806 {middle} is not empty, it is found when searching from either
7807 direction, but only when not in a nested start-end pair. A
7808 typical use is: >
7809 searchpair('\<if\>', '\<else\>', '\<endif\>')
7810< By leaving {middle} empty the "else" is skipped.
7811
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007812 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7813 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00007814 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007815 outer pair. Implies the 'W' flag.
7816 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007817 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007818 Note: it's nearly always a good idea to use the 'W' flag, to
7819 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007820
7821 When a match for {start}, {middle} or {end} is found, the
7822 {skip} expression is evaluated with the cursor positioned on
7823 the start of the match. It should return non-zero if this
7824 match is to be skipped. E.g., because it is inside a comment
7825 or a string.
7826 When {skip} is omitted or empty, every match is accepted.
7827 When evaluating {skip} causes an error the search is aborted
7828 and -1 returned.
Bram Moolenaar48570482017-10-30 21:48:41 +01007829 {skip} can be a string, a lambda, a funcref or a partial.
Bram Moolenaar675e8d62018-06-24 20:42:01 +02007830 Anything else makes the function fail.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007831
Bram Moolenaar76929292008-01-06 19:07:36 +00007832 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007833
Bram Moolenaar071d4272004-06-13 20:20:40 +00007834 The value of 'ignorecase' is used. 'magic' is ignored, the
7835 patterns are used like it's on.
7836
7837 The search starts exactly at the cursor. A match with
7838 {start}, {middle} or {end} at the next character, in the
7839 direction of searching, is the first one found. Example: >
7840 if 1
7841 if 2
7842 endif 2
7843 endif 1
7844< When starting at the "if 2", with the cursor on the "i", and
7845 searching forwards, the "endif 2" is found. When starting on
7846 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar58b85342016-08-14 19:54:54 +02007847 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007848 then this is considered to be a nested if/endif from "if 2" to
7849 "endif 2".
7850 When searching backwards and {end} is more than one character,
7851 it may be useful to put "\zs" at the end of the pattern, so
7852 that when the cursor is inside a match with the end it finds
7853 the matching start.
7854
7855 Example, to find the "endif" command in a Vim script: >
7856
7857 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7858 \ 'getline(".") =~ "^\\s*\""')
7859
7860< The cursor must be at or after the "if" for which a match is
7861 to be found. Note that single-quote strings are used to avoid
7862 having to double the backslashes. The skip expression only
7863 catches comments at the start of a line, not after a command.
7864 Also, a word "en" or "if" halfway a line is considered a
7865 match.
7866 Another example, to search for the matching "{" of a "}": >
7867
7868 :echo searchpair('{', '', '}', 'bW')
7869
7870< This works when the cursor is at or before the "}" for which a
7871 match is to be found. To reject matches that syntax
7872 highlighting recognized as strings: >
7873
7874 :echo searchpair('{', '', '}', 'bW',
7875 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7876<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007877 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00007878searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7879 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007880 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007881 column position of the match. The first element of the |List|
7882 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007883 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007884 returns [0, 0]. >
7885
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007886 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7887<
7888 See |match-parens| for a bigger and more useful example.
7889
Bram Moolenaar76929292008-01-06 19:07:36 +00007890searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007891 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007892 column position of the match. The first element of the |List|
7893 is the line number and the second element is the byte index of
7894 the column position of the match. If no match is found,
7895 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007896 Example: >
7897 :let [lnum, col] = searchpos('mypattern', 'n')
7898
7899< When the 'p' flag is given then there is an extra item with
7900 the sub-pattern match number |search()-sub-match|. Example: >
7901 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7902< In this example "submatch" is 2 when a lowercase letter is
7903 found |/\l|, 3 when an uppercase letter is found |/\u|.
7904
Bram Moolenaar81edd172016-04-14 13:51:37 +02007905server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007906 Send a reply string to {clientid}. The most recent {clientid}
7907 that sent a string can be retrieved with expand("<client>").
7908 {only available when compiled with the |+clientserver| feature}
7909 Note:
7910 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007911 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007912 before calling any commands that waits for input.
7913 See also |clientserver|.
7914 Example: >
7915 :echo server2client(expand("<client>"), "HELLO")
7916<
7917serverlist() *serverlist()*
7918 Return a list of available server names, one per line.
7919 When there are no servers or the information is not available
7920 an empty string is returned. See also |clientserver|.
7921 {only available when compiled with the |+clientserver| feature}
7922 Example: >
7923 :echo serverlist()
7924<
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007925setbufline({expr}, {lnum}, {text}) *setbufline()*
7926 Set line {lnum} to {text} in buffer {expr}. To insert
Bram Moolenaarb328cca2019-01-06 16:24:01 +01007927 lines use |append()|. Any text properties in {lnum} are
7928 cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007929
7930 For the use of {expr}, see |bufname()| above.
7931
7932 {lnum} is used like with |setline()|.
7933 This works like |setline()| for the specified buffer.
7934 On success 0 is returned, on failure 1 is returned.
7935
7936 If {expr} is not a valid buffer or {lnum} is not valid, an
7937 error message is given.
7938
Bram Moolenaar071d4272004-06-13 20:20:40 +00007939setbufvar({expr}, {varname}, {val}) *setbufvar()*
7940 Set option or local variable {varname} in buffer {expr} to
7941 {val}.
7942 This also works for a global or local window option, but it
7943 doesn't work for a global or local window variable.
7944 For a local window option the global value is unchanged.
7945 For the use of {expr}, see |bufname()| above.
7946 Note that the variable name without "b:" must be used.
7947 Examples: >
7948 :call setbufvar(1, "&mod", 1)
7949 :call setbufvar("todo", "myvar", "foobar")
7950< This function is not available in the |sandbox|.
7951
Bram Moolenaar12969c02015-09-08 23:36:10 +02007952setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02007953 Set the current character search information to {dict},
7954 which contains one or more of the following entries:
7955
7956 char character which will be used for a subsequent
7957 |,| or |;| command; an empty string clears the
7958 character search
7959 forward direction of character search; 1 for forward,
7960 0 for backward
7961 until type of character search; 1 for a |t| or |T|
7962 character search, 0 for an |f| or |F|
7963 character search
7964
7965 This can be useful to save/restore a user's character search
7966 from a script: >
7967 :let prevsearch = getcharsearch()
7968 :" Perform a command which clobbers user's search
7969 :call setcharsearch(prevsearch)
7970< Also see |getcharsearch()|.
7971
Bram Moolenaar071d4272004-06-13 20:20:40 +00007972setcmdpos({pos}) *setcmdpos()*
7973 Set the cursor position in the command line to byte position
Bram Moolenaar58b85342016-08-14 19:54:54 +02007974 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007975 Use |getcmdpos()| to obtain the current position.
7976 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00007977 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7978 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7979 set after the command line is set to the expression. For
7980 |c_CTRL-R_=| it is set after evaluating the expression but
7981 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007982 When the number is too big the cursor is put at the end of the
7983 line. A number smaller than one has undefined results.
7984 Returns 0 when successful, 1 when not editing the command
7985 line.
7986
Bram Moolenaar80492532016-03-08 17:08:53 +01007987setfperm({fname}, {mode}) *setfperm()* *chmod*
7988 Set the file permissions for {fname} to {mode}.
7989 {mode} must be a string with 9 characters. It is of the form
7990 "rwxrwxrwx", where each group of "rwx" flags represent, in
7991 turn, the permissions of the owner of the file, the group the
7992 file belongs to, and other users. A '-' character means the
7993 permission is off, any other character means on. Multi-byte
7994 characters are not supported.
7995
7996 For example "rw-r-----" means read-write for the user,
7997 readable by the group, not accessible by others. "xx-x-----"
7998 would do the same thing.
7999
8000 Returns non-zero for success, zero for failure.
8001
8002 To read permissions see |getfperm()|.
8003
8004
Bram Moolenaar446cb832008-06-24 21:56:24 +00008005setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008006 Set line {lnum} of the current buffer to {text}. To insert
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008007 lines use |append()|. To set lines in another buffer use
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008008 |setbufline()|. Any text properties in {lnum} are cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008009
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008010 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008011 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008012 added as a new line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008013
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008014 If this succeeds, 0 is returned. If this fails (most likely
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008015 because {lnum} is invalid) 1 is returned.
8016
8017 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008018 :call setline(5, strftime("%c"))
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02008019
Bram Moolenaar446cb832008-06-24 21:56:24 +00008020< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008021 will be set to the items in the list. Example: >
8022 :call setline(5, ['aaa', 'bbb', 'ccc'])
8023< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02008024 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008025 : call setline(n, l)
8026 :endfor
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008027
Bram Moolenaar071d4272004-06-13 20:20:40 +00008028< Note: The '[ and '] marks are not set.
8029
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008030setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00008031 Create or replace or add to the location list for window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008032 {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02008033 When {nr} is zero the current window is used.
8034
8035 For a location list window, the displayed location list is
8036 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00008037 Otherwise, same as |setqflist()|.
8038 Also see |location-list|.
8039
Bram Moolenaard823fa92016-08-12 16:29:27 +02008040 If the optional {what} dictionary argument is supplied, then
8041 only the items listed in {what} are set. Refer to |setqflist()|
8042 for the list of supported keys in {what}.
8043
Bram Moolenaaraff74912019-03-30 18:11:49 +01008044setmatches({list} [, {win}]) *setmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01008045 Restores a list of matches saved by |getmatches() for the
8046 current window|. Returns 0 if successful, otherwise -1. All
8047 current matches are cleared before the list is restored. See
8048 example for |getmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01008049 If {win} is specified, use the window with this number or
8050 window ID instead of the current window.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008051
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008052 *setpos()*
8053setpos({expr}, {list})
8054 Set the position for {expr}. Possible values:
8055 . the cursor
8056 'x mark x
8057
Bram Moolenaar493c1782014-05-28 14:34:46 +02008058 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008059 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02008060 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008061
Bram Moolenaar58b85342016-08-14 19:54:54 +02008062 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarf13e00b2017-01-28 18:23:54 +01008063 current buffer. When setting an uppercase mark "bufnum" is
8064 used for the mark position. For other marks it specifies the
8065 buffer to set the mark in. You can use the |bufnr()| function
8066 to turn a file name into a buffer number.
8067 For setting the cursor and the ' mark "bufnum" is ignored,
8068 since these are associated with a window, not a buffer.
Bram Moolenaardb552d602006-03-23 22:59:57 +00008069 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008070
8071 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008072 column is 1. Use a zero "lnum" to delete a mark. If "col" is
8073 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008074
8075 The "off" number is only used when 'virtualedit' is set. Then
8076 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008077 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008078 character.
8079
Bram Moolenaar493c1782014-05-28 14:34:46 +02008080 The "curswant" number is only used when setting the cursor
8081 position. It sets the preferred column for when moving the
8082 cursor vertically. When the "curswant" number is missing the
8083 preferred column is not set. When it is present and setting a
8084 mark position it is not used.
8085
Bram Moolenaardfb18412013-12-11 18:53:29 +01008086 Note that for '< and '> changing the line number may result in
8087 the marks to be effectively be swapped, so that '< is always
8088 before '>.
8089
Bram Moolenaar08250432008-02-13 11:42:46 +00008090 Returns 0 when the position could be set, -1 otherwise.
8091 An error message is given if {expr} is invalid.
8092
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02008093 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008094
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008095 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02008096 vertically; if you set the cursor position with this, |j| and
8097 |k| motions will jump to previous columns! Use |cursor()| to
8098 also set the preferred column. Also see the "curswant" key in
8099 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008100
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008101setqflist({list} [, {action} [, {what}]]) *setqflist()*
Bram Moolenaarae338332017-08-11 20:25:26 +02008102 Create or replace or add to the quickfix list.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008103
Bram Moolenaarae338332017-08-11 20:25:26 +02008104 When {what} is not present, use the items in {list}. Each
8105 item must be a dictionary. Non-dictionary items in {list} are
8106 ignored. Each dictionary item can contain the following
8107 entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008108
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008109 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00008110 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008111 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00008112 present or it is invalid.
Bram Moolenaard76ce852018-05-01 15:02:04 +02008113 module name of a module; if given it will be used in
8114 quickfix error window instead of the filename.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008115 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008116 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00008117 col column number
8118 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008119 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00008120 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008121 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00008122 type single-character error type, 'E', 'W', etc.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02008123 valid recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008124
Bram Moolenaar582fd852005-03-28 20:58:01 +00008125 The "col", "vcol", "nr", "type" and "text" entries are
8126 optional. Either "lnum" or "pattern" entry can be used to
8127 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008128 If the "filename" and "bufnr" entries are not present or
8129 neither the "lnum" or "pattern" entries are present, then the
8130 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008131 If both "pattern" and "lnum" are present then "pattern" will
8132 be used.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02008133 If the "valid" entry is not supplied, then the valid flag is
8134 set when "bufnr" is a valid buffer or "filename" exists.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008135 If you supply an empty {list}, the quickfix list will be
8136 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00008137 Note that the list is not exactly the same as what
8138 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008139
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008140 {action} values: *E927*
8141 'a' The items from {list} are added to the existing
8142 quickfix list. If there is no existing list, then a
8143 new list is created.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008144
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008145 'r' The items from the current quickfix list are replaced
8146 with the items from {list}. This can also be used to
8147 clear the list: >
8148 :call setqflist([], 'r')
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008149<
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02008150 'f' All the quickfix lists in the quickfix stack are
8151 freed.
8152
Bram Moolenaar511972d2016-06-04 18:09:59 +02008153 If {action} is not present or is set to ' ', then a new list
Bram Moolenaar55b69262017-08-13 13:42:01 +02008154 is created. The new quickfix list is added after the current
8155 quickfix list in the stack and all the following lists are
8156 freed. To add a new quickfix list at the end of the stack,
Bram Moolenaar36538222017-09-02 19:51:44 +02008157 set "nr" in {what} to "$".
Bram Moolenaar35c54e52005-05-20 21:25:31 +00008158
Bram Moolenaard823fa92016-08-12 16:29:27 +02008159 If the optional {what} dictionary argument is supplied, then
8160 only the items listed in {what} are set. The first {list}
8161 argument is ignored. The following items can be specified in
8162 {what}:
Bram Moolenaar15142e22018-04-30 22:19:58 +02008163 context quickfix list context. See |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02008164 efm errorformat to use when parsing text from
8165 "lines". If this is not present, then the
8166 'errorformat' option value is used.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008167 See |quickfix-parse|
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008168 id quickfix list identifier |quickfix-ID|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008169 idx index of the current entry in the quickfix
8170 list specified by 'id' or 'nr'. If set to '$',
8171 then the last entry in the list is set as the
8172 current entry. See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02008173 items list of quickfix entries. Same as the {list}
8174 argument.
Bram Moolenaar2c809b72017-09-01 18:34:02 +02008175 lines use 'errorformat' to parse a list of lines and
8176 add the resulting entries to the quickfix list
8177 {nr} or {id}. Only a |List| value is supported.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008178 See |quickfix-parse|
Bram Moolenaar875feea2017-06-11 16:07:51 +02008179 nr list number in the quickfix stack; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02008180 means the current quickfix list and "$" means
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008181 the last quickfix list.
8182 title quickfix list title text. See |quickfix-title|
Bram Moolenaard823fa92016-08-12 16:29:27 +02008183 Unsupported keys in {what} are ignored.
8184 If the "nr" item is not present, then the current quickfix list
Bram Moolenaar86f100dc2017-06-28 21:26:27 +02008185 is modified. When creating a new quickfix list, "nr" can be
8186 set to a value one greater than the quickfix stack size.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008187 When modifying a quickfix list, to guarantee that the correct
Bram Moolenaar36538222017-09-02 19:51:44 +02008188 list is modified, "id" should be used instead of "nr" to
Bram Moolenaara539f4f2017-08-30 20:33:55 +02008189 specify the list.
Bram Moolenaard823fa92016-08-12 16:29:27 +02008190
Bram Moolenaar15142e22018-04-30 22:19:58 +02008191 Examples (See also |setqflist-examples|): >
Bram Moolenaar2c809b72017-09-01 18:34:02 +02008192 :call setqflist([], 'r', {'title': 'My search'})
8193 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
Bram Moolenaar15142e22018-04-30 22:19:58 +02008194 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02008195<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008196 Returns zero for success, -1 for failure.
8197
8198 This function can be used to create a quickfix list
8199 independent of the 'errorformat' setting. Use a command like
Bram Moolenaar94237492017-04-23 18:40:21 +02008200 `:cc 1` to jump to the first position.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00008201
8202
Bram Moolenaar071d4272004-06-13 20:20:40 +00008203 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01008204setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00008205 Set the register {regname} to {value}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008206 {value} may be any value returned by |getreg()|, including
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008207 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008208 If {options} contains "a" or {regname} is upper case,
8209 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02008210 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008211 "c" or "v" |characterwise| mode
8212 "l" or "V" |linewise| mode
8213 "b" or "<CTRL-V>" |blockwise-visual| mode
8214 If a number immediately follows "b" or "<CTRL-V>" then this is
8215 used as the width of the selection - if it is not specified
8216 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00008217 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008218
8219 If {options} contains no register settings, then the default
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008220 is to use character mode unless {value} ends in a <NL> for
8221 string {value} and linewise mode for list {value}. Blockwise
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008222 mode is never selected automatically.
8223 Returns zero for success, non-zero for failure.
8224
8225 *E883*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008226 Note: you may not use |List| containing more than one item to
8227 set search and expression registers. Lists containing no
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008228 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008229
8230 Examples: >
8231 :call setreg(v:register, @*)
8232 :call setreg('*', @%, 'ac')
8233 :call setreg('a', "1\n2\n3", 'b5')
8234
8235< This example shows using the functions to save and restore a
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008236 register: >
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008237 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008238 :let var_amode = getregtype('a')
8239 ....
8240 :call setreg('a', var_a, var_amode)
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008241< Note: you may not reliably restore register value
8242 without using the third argument to |getreg()| as without it
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008243 newlines are represented as newlines AND Nul bytes are
8244 represented as newlines as well, see |NL-used-for-Nul|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008245
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008246 You can also change the type of a register by appending
Bram Moolenaar071d4272004-06-13 20:20:40 +00008247 nothing: >
8248 :call setreg('a', '', 'al')
8249
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008250settabvar({tabnr}, {varname}, {val}) *settabvar()*
8251 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8252 |t:var|
8253 Note that the variable name without "t:" must be used.
8254 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008255 This function is not available in the |sandbox|.
8256
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008257settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8258 Set option or local variable {varname} in window {winnr} to
8259 {val}.
8260 Tabs are numbered starting with one. For the current tabpage
8261 use |setwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008262 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008263 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008264 This also works for a global or local buffer option, but it
8265 doesn't work for a global or local buffer variable.
8266 For a local buffer option the global value is unchanged.
8267 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008268 Examples: >
8269 :call settabwinvar(1, 1, "&list", 0)
8270 :call settabwinvar(3, 2, "myvar", "foobar")
8271< This function is not available in the |sandbox|.
8272
Bram Moolenaarf49cc602018-11-11 15:21:05 +01008273settagstack({nr}, {dict} [, {action}]) *settagstack()*
8274 Modify the tag stack of the window {nr} using {dict}.
8275 {nr} can be the window number or the |window-ID|.
8276
8277 For a list of supported items in {dict}, refer to
8278 |gettagstack()|
8279 *E962*
8280 If {action} is not present or is set to 'r', then the tag
8281 stack is replaced. If {action} is set to 'a', then new entries
8282 from {dict} are pushed onto the tag stack.
8283
8284 Returns zero for success, -1 for failure.
8285
8286 Examples:
8287 Set current index of the tag stack to 4: >
8288 call settagstack(1005, {'curidx' : 4})
8289
8290< Empty the tag stack of window 3: >
8291 call settagstack(3, {'items' : []})
8292
8293< Push a new item onto the tag stack: >
8294 let pos = [bufnr('myfile.txt'), 10, 1, 0]
8295 let newtag = [{'tagname' : 'mytag', 'from' : pos}]
8296 call settagstack(2, {'items' : newtag}, 'a')
8297
8298< Save and restore the tag stack: >
8299 let stack = gettagstack(1003)
8300 " do something else
8301 call settagstack(1003, stack)
8302 unlet stack
8303<
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008304setwinvar({nr}, {varname}, {val}) *setwinvar()*
8305 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008306 Examples: >
8307 :call setwinvar(1, "&list", 0)
8308 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008309
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008310sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01008311 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008312 checksum of {string}.
8313 {only available when compiled with the |+cryptv| feature}
8314
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008315shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008316 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008317 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008318 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008319 quotes within {string}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02008320 Otherwise it will enclose {string} in single quotes and
8321 replace all "'" with "'\''".
Bram Moolenaar875feea2017-06-11 16:07:51 +02008322
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008323 When the {special} argument is present and it's a non-zero
8324 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008325 items such as "!", "%", "#" and "<cword>" will be preceded by
8326 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008327 command.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008328
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008329 The "!" character will be escaped (again with a |non-zero-arg|
8330 {special}) when 'shell' contains "csh" in the tail. That is
8331 because for csh and tcsh "!" is used for history replacement
8332 even when inside single quotes.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008333
8334 With a |non-zero-arg| {special} the <NL> character is also
8335 escaped. When 'shell' containing "csh" in the tail it's
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008336 escaped a second time.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008337
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008338 Example of use with a |:!| command: >
8339 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
8340< This results in a directory listing for the file under the
8341 cursor. Example of use with |system()|: >
8342 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01008343< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008344
8345
Bram Moolenaarf9514162018-11-22 03:08:29 +01008346shiftwidth([{col}]) *shiftwidth()*
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008347 Returns the effective value of 'shiftwidth'. This is the
8348 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01008349 'tabstop' value. This function was introduced with patch
Bram Moolenaarf9514162018-11-22 03:08:29 +01008350 7.3.694 in 2012, everybody should have it by now (however it
8351 did not allow for the optional {col} argument until 8.1.542).
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008352
Bram Moolenaarf9514162018-11-22 03:08:29 +01008353 When there is one argument {col} this is used as column number
8354 for which to return the 'shiftwidth' value. This matters for the
8355 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8356 no {col} argument is given, column 1 will be assumed.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008357
Bram Moolenaar162b7142018-12-21 15:17:36 +01008358sign_define({name} [, {dict}]) *sign_define()*
8359 Define a new sign named {name} or modify the attributes of an
8360 existing sign. This is similar to the |:sign-define| command.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008361
Bram Moolenaar162b7142018-12-21 15:17:36 +01008362 Prefix {name} with a unique text to avoid name collisions.
8363 There is no {group} like with placing signs.
8364
8365 The {name} can be a String or a Number. The optional {dict}
8366 argument specifies the sign attributes. The following values
8367 are supported:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008368 icon full path to the bitmap file for the sign.
8369 linehl highlight group used for the whole line the
Bram Moolenaar162b7142018-12-21 15:17:36 +01008370 sign is placed in.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008371 text text that is displayed when there is no icon
Bram Moolenaar162b7142018-12-21 15:17:36 +01008372 or the GUI is not being used.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008373 texthl highlight group used for the text item
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008374
8375 If the sign named {name} already exists, then the attributes
8376 of the sign are updated.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008377
8378 Returns 0 on success and -1 on failure.
8379
8380 Examples: >
8381 call sign_define("mySign", {"text" : "=>", "texthl" :
8382 \ "Error", "linehl" : "Search"})
8383<
8384sign_getdefined([{name}]) *sign_getdefined()*
8385 Get a list of defined signs and their attributes.
8386 This is similar to the |:sign-list| command.
8387
8388 If the {name} is not supplied, then a list of all the defined
8389 signs is returned. Otherwise the attribute of the specified
8390 sign is returned.
8391
8392 Each list item in the returned value is a dictionary with the
8393 following entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008394 icon full path to the bitmap file of the sign
8395 linehl highlight group used for the whole line the
Bram Moolenaar162b7142018-12-21 15:17:36 +01008396 sign is placed in.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008397 name name of the sign
8398 text text that is displayed when there is no icon
Bram Moolenaar162b7142018-12-21 15:17:36 +01008399 or the GUI is not being used.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008400 texthl highlight group used for the text item
Bram Moolenaar162b7142018-12-21 15:17:36 +01008401
8402 Returns an empty List if there are no signs and when {name} is
8403 not found.
8404
8405 Examples: >
8406 " Get a list of all the defined signs
8407 echo sign_getdefined()
8408
8409 " Get the attribute of the sign named mySign
8410 echo sign_getdefined("mySign")
8411<
8412sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()*
8413 Return a list of signs placed in a buffer or all the buffers.
8414 This is similar to the |:sign-place-list| command.
8415
8416 If the optional buffer name {expr} is specified, then only the
8417 list of signs placed in that buffer is returned. For the use
8418 of {expr}, see |bufname()|. The optional {dict} can contain
8419 the following entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008420 group select only signs in this group
8421 id select sign with this identifier
8422 lnum select signs placed in this line. For the use
Bram Moolenaar162b7142018-12-21 15:17:36 +01008423 of {lnum}, see |line()|.
8424 If {group} is '*', then signs in all the groups including the
Bram Moolenaar6436cd82018-12-27 00:28:33 +01008425 global group are returned. If {group} is not supplied or is an
8426 empty string, then only signs in the global group are
8427 returned. If no arguments are supplied, then signs in the
8428 global group placed in all the buffers are returned.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008429 See |sign-group|.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008430
8431 Each list item in the returned value is a dictionary with the
8432 following entries:
8433 bufnr number of the buffer with the sign
8434 signs list of signs placed in {bufnr}. Each list
8435 item is a dictionary with the below listed
8436 entries
8437
8438 The dictionary for each sign contains the following entries:
8439 group sign group. Set to '' for the global group.
8440 id identifier of the sign
8441 lnum line number where the sign is placed
8442 name name of the defined sign
8443 priority sign priority
8444
Bram Moolenaarb589f952019-01-07 22:10:00 +01008445 The returned signs in a buffer are ordered by their line
8446 number.
8447
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008448 Returns an empty list on failure or if there are no placed
8449 signs.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008450
8451 Examples: >
8452 " Get a List of signs placed in eval.c in the
8453 " global group
8454 echo sign_getplaced("eval.c")
8455
8456 " Get a List of signs in group 'g1' placed in eval.c
8457 echo sign_getplaced("eval.c", {'group' : 'g1'})
8458
8459 " Get a List of signs placed at line 10 in eval.c
8460 echo sign_getplaced("eval.c", {'lnum' : 10})
8461
8462 " Get sign with identifier 10 placed in a.py
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008463 echo sign_getplaced("a.py", {'id' : 10})
Bram Moolenaar162b7142018-12-21 15:17:36 +01008464
8465 " Get sign with id 20 in group 'g1' placed in a.py
8466 echo sign_getplaced("a.py", {'group' : 'g1',
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008467 \ 'id' : 20})
Bram Moolenaar162b7142018-12-21 15:17:36 +01008468
8469 " Get a List of all the placed signs
8470 echo sign_getplaced()
8471<
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01008472 *sign_jump()*
8473sign_jump({id}, {group}, {expr})
8474 Open the buffer {expr} or jump to the window that contains
8475 {expr} and position the cursor at sign {id} in group {group}.
8476 This is similar to the |:sign-jump| command.
8477
8478 For the use of {expr}, see |bufname()|.
8479
8480 Returns the line number of the sign. Returns -1 if the
8481 arguments are invalid.
8482
8483 Example: >
8484 " Jump to sign 10 in the current buffer
8485 call sign_jump(10, '', '')
8486<
Bram Moolenaar162b7142018-12-21 15:17:36 +01008487 *sign_place()*
8488sign_place({id}, {group}, {name}, {expr} [, {dict}])
8489 Place the sign defined as {name} at line {lnum} in file {expr}
8490 and assign {id} and {group} to sign. This is similar to the
8491 |:sign-place| command.
8492
8493 If the sign identifier {id} is zero, then a new identifier is
8494 allocated. Otherwise the specified number is used. {group} is
8495 the sign group name. To use the global sign group, use an
8496 empty string. {group} functions as a namespace for {id}, thus
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008497 two groups can use the same IDs. Refer to |sign-identifier|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008498 and |sign-group| for more information.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008499
Bram Moolenaar162b7142018-12-21 15:17:36 +01008500 {name} refers to a defined sign.
8501 {expr} refers to a buffer name or number. For the accepted
8502 values, see |bufname()|.
8503
8504 The optional {dict} argument supports the following entries:
8505 lnum line number in the buffer {expr} where
8506 the sign is to be placed. For the
8507 accepted values, see |line()|.
8508 priority priority of the sign. See
8509 |sign-priority| for more information.
8510
8511 If the optional {dict} is not specified, then it modifies the
8512 placed sign {id} in group {group} to use the defined sign
8513 {name}.
8514
8515 Returns the sign identifier on success and -1 on failure.
8516
8517 Examples: >
8518 " Place a sign named sign1 with id 5 at line 20 in
8519 " buffer json.c
8520 call sign_place(5, '', 'sign1', 'json.c',
8521 \ {'lnum' : 20})
8522
8523 " Updates sign 5 in buffer json.c to use sign2
8524 call sign_place(5, '', 'sign2', 'json.c')
8525
8526 " Place a sign named sign3 at line 30 in
8527 " buffer json.c with a new identifier
8528 let id = sign_place(0, '', 'sign3', 'json.c',
8529 \ {'lnum' : 30})
8530
8531 " Place a sign named sign4 with id 10 in group 'g3'
8532 " at line 40 in buffer json.c with priority 90
8533 call sign_place(10, 'g3', 'sign4', 'json.c',
8534 \ {'lnum' : 40, 'priority' : 90})
8535<
8536sign_undefine([{name}]) *sign_undefine()*
8537 Deletes a previously defined sign {name}. This is similar to
8538 the |:sign-undefine| command. If {name} is not supplied, then
8539 deletes all the defined signs.
8540
8541 Returns 0 on success and -1 on failure.
8542
8543 Examples: >
8544 " Delete a sign named mySign
8545 call sign_undefine("mySign")
8546
8547 " Delete all the signs
8548 call sign_undefine()
8549<
8550sign_unplace({group} [, {dict}]) *sign_unplace()*
8551 Remove a previously placed sign in one or more buffers. This
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008552 is similar to the |:sign-unplace| command.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008553
8554 {group} is the sign group name. To use the global sign group,
8555 use an empty string. If {group} is set to '*', then all the
8556 groups including the global group are used.
8557 The signs in {group} are selected based on the entries in
8558 {dict}. The following optional entries in {dict} are
8559 supported:
8560 buffer buffer name or number. See |bufname()|.
8561 id sign identifier
8562 If {dict} is not supplied, then all the signs in {group} are
8563 removed.
8564
8565 Returns 0 on success and -1 on failure.
8566
8567 Examples: >
8568 " Remove sign 10 from buffer a.vim
8569 call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
8570
8571 " Remove sign 20 in group 'g1' from buffer 3
8572 call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
8573
8574 " Remove all the signs in group 'g2' from buffer 10
8575 call sign_unplace('g2', {'buffer' : 10})
8576
8577 " Remove sign 30 in group 'g3' from all the buffers
8578 call sign_unplace('g3', {'id' : 30})
8579
8580 " Remove all the signs placed in buffer 5
8581 call sign_unplace('*', {'buffer' : 5})
8582
8583 " Remove the signs in group 'g4' from all the buffers
8584 call sign_unplace('g4')
8585
8586 " Remove sign 40 from all the buffers
8587 call sign_unplace('*', {'id' : 40})
8588
8589 " Remove all the placed signs from all the buffers
8590 call sign_unplace('*')
8591<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008592simplify({filename}) *simplify()*
8593 Simplify the file name as much as possible without changing
8594 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8595 Unix) are not resolved. If the first path component in
8596 {filename} designates the current directory, this will be
8597 valid for the result as well. A trailing path separator is
8598 not removed either.
8599 Example: >
8600 simplify("./dir/.././/file/") == "./file/"
8601< Note: The combination "dir/.." is only removed if "dir" is
8602 a searchable directory or does not exist. On Unix, it is also
8603 removed when "dir" is a symbolic link within the same
8604 directory. In order to resolve all the involved symbolic
8605 links before simplifying the path name, use |resolve()|.
8606
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008607
Bram Moolenaar446cb832008-06-24 21:56:24 +00008608sin({expr}) *sin()*
8609 Return the sine of {expr}, measured in radians, as a |Float|.
8610 {expr} must evaluate to a |Float| or a |Number|.
8611 Examples: >
8612 :echo sin(100)
8613< -0.506366 >
8614 :echo sin(-4.01)
8615< 0.763301
8616 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008617
Bram Moolenaar446cb832008-06-24 21:56:24 +00008618
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008619sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008620 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008621 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008622 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008623 Examples: >
8624 :echo sinh(0.5)
8625< 0.521095 >
8626 :echo sinh(-0.9)
8627< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02008628 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008629
8630
Bram Moolenaar5f894962011-06-19 02:55:37 +02008631sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01008632 Sort the items in {list} in-place. Returns {list}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008633
Bram Moolenaar327aa022014-03-25 18:24:23 +01008634 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008635 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02008636
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008637< When {func} is omitted, is empty or zero, then sort() uses the
8638 string representation of each item to sort on. Numbers sort
8639 after Strings, |Lists| after Numbers. For sorting text in the
8640 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008641
Bram Moolenaar34401cc2014-08-29 15:12:19 +02008642 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008643 ignored.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008644
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008645 When {func} is given and it is 'n' then all items will be
8646 sorted numerical (Implementation detail: This uses the
8647 strtod() function to parse numbers, Strings, Lists, Dicts and
8648 Funcrefs will be considered as being 0).
8649
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01008650 When {func} is given and it is 'N' then all items will be
8651 sorted numerical. This is like 'n' but a string containing
8652 digits will be used as the number they represent.
8653
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01008654 When {func} is given and it is 'f' then all items will be
8655 sorted numerical. All values must be a Number or a Float.
8656
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008657 When {func} is a |Funcref| or a function name, this function
8658 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008659 items as argument and must return zero if they are equal, 1 or
8660 bigger if the first one sorts after the second one, -1 or
8661 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008662
8663 {dict} is for functions with the "dict" attribute. It will be
8664 used to set the local variable "self". |Dictionary-function|
8665
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008666 The sort is stable, items which compare equal (as number or as
8667 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02008668 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008669 same order as they were originally.
8670
Bram Moolenaar327aa022014-03-25 18:24:23 +01008671 Also see |uniq()|.
8672
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008673 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008674 func MyCompare(i1, i2)
8675 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8676 endfunc
8677 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008678< A shorter compare version for this specific simple case, which
8679 ignores overflow: >
8680 func MyCompare(i1, i2)
8681 return a:i1 - a:i2
8682 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008683<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008684 *soundfold()*
8685soundfold({word})
8686 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00008687 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008688 soundfolding. 'spell' must be set. When no sound folding is
8689 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008690 This can be used for making spelling suggestions. Note that
8691 the method can be quite slow.
8692
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008693 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00008694spellbadword([{sentence}])
8695 Without argument: The result is the badly spelled word under
8696 or after the cursor. The cursor is moved to the start of the
8697 bad word. When no bad word is found in the cursor line the
8698 result is an empty string and the cursor doesn't move.
8699
8700 With argument: The result is the first word in {sentence} that
8701 is badly spelled. If there are no spelling mistakes the
8702 result is an empty string.
8703
8704 The return value is a list with two items:
8705 - The badly spelled word or an empty string.
8706 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008707 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00008708 "rare" rare word
8709 "local" word only valid in another region
8710 "caps" word should start with Capital
8711 Example: >
8712 echo spellbadword("the quik brown fox")
8713< ['quik', 'bad'] ~
8714
8715 The spelling information for the current window is used. The
8716 'spell' option must be set and the value of 'spelllang' is
8717 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008718
8719 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008720spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008721 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008722 When {max} is given up to this number of suggestions are
8723 returned. Otherwise up to 25 suggestions are returned.
8724
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008725 When the {capital} argument is given and it's non-zero only
8726 suggestions with a leading capital will be given. Use this
8727 after a match with 'spellcapcheck'.
8728
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008729 {word} can be a badly spelled word followed by other text.
8730 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00008731 suggestions also include the following text, thus you can
8732 replace a line.
8733
8734 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008735 returned. {word} itself is not included in the suggestions,
8736 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008737
8738 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008739 'spell' option must be set and the values of 'spelllang' and
8740 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008741
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008742
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008743split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008744 Make a |List| out of {expr}. When {pattern} is omitted or
8745 empty each white-separated sequence of characters becomes an
8746 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008747 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01008748 removing the matched characters. 'ignorecase' is not used
8749 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008750 When the first or last item is empty it is omitted, unless the
8751 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008752 Other empty items are kept when {pattern} matches at least one
8753 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008754 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008755 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008756< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008757 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02008758< If you want to keep the separator you can also use '\zs' at
8759 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00008760 :echo split('abc:def:ghi', ':\zs')
8761< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008762 Splitting a table where the first element can be empty: >
8763 :let items = split(line, ':', 1)
8764< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008765
8766
Bram Moolenaar446cb832008-06-24 21:56:24 +00008767sqrt({expr}) *sqrt()*
8768 Return the non-negative square root of Float {expr} as a
8769 |Float|.
8770 {expr} must evaluate to a |Float| or a |Number|. When {expr}
8771 is negative the result is NaN (Not a Number).
8772 Examples: >
8773 :echo sqrt(100)
8774< 10.0 >
8775 :echo sqrt(-4.01)
8776< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00008777 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008778 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008779
Bram Moolenaar446cb832008-06-24 21:56:24 +00008780
Bram Moolenaar81edd172016-04-14 13:51:37 +02008781str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008782 Convert String {expr} to a Float. This mostly works the same
8783 as when using a floating point number in an expression, see
8784 |floating-point-format|. But it's a bit more permissive.
8785 E.g., "1e40" is accepted, while in an expression you need to
Bram Moolenaard47d5222018-12-09 20:43:55 +01008786 write "1.0e40". The hexadecimal form "0x123" is also
8787 accepted, but not others, like binary or octal.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008788 Text after the number is silently ignored.
8789 The decimal point is always '.', no matter what the locale is
8790 set to. A comma ends the number: "12,345.67" is converted to
8791 12.0. You can strip out thousands separators with
8792 |substitute()|: >
8793 let f = str2float(substitute(text, ',', '', 'g'))
8794< {only available when compiled with the |+float| feature}
8795
Bram Moolenaar9d401282019-04-06 13:18:12 +02008796str2list({expr} [, {utf8}]) *str2list()*
8797 Return a list containing the number values which represent
8798 each character in String {expr}. Examples: >
8799 str2list(" ") returns [32]
8800 str2list("ABC") returns [65, 66, 67]
8801< |list2str()| does the opposite.
8802
8803 When {utf8} is omitted or zero, the current 'encoding' is used.
8804 With {utf8} set to 1, always treat the String as utf-8
8805 characters. With utf-8 composing characters are handled
8806 properly: >
8807 str2list("á") returns [97, 769]
Bram Moolenaar446cb832008-06-24 21:56:24 +00008808
Bram Moolenaar81edd172016-04-14 13:51:37 +02008809str2nr({expr} [, {base}]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008810 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01008811 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008812 When {base} is omitted base 10 is used. This also means that
8813 a leading zero doesn't cause octal conversion to be used, as
8814 with the default String to Number conversion.
8815 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01008816 different base the result will be zero. Similarly, when
8817 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
8818 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008819 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008820
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008821
Bram Moolenaar979243b2015-06-26 19:35:49 +02008822strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02008823 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02008824 in String {expr}.
8825 When {skipcc} is omitted or zero, composing characters are
8826 counted separately.
8827 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02008828 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008829
Bram Moolenaar86ae7202015-07-10 19:31:35 +02008830 {skipcc} is only available after 7.4.755. For backward
8831 compatibility, you can define a wrapper function: >
8832 if has("patch-7.4.755")
8833 function s:strchars(str, skipcc)
8834 return strchars(a:str, a:skipcc)
8835 endfunction
8836 else
8837 function s:strchars(str, skipcc)
8838 if a:skipcc
8839 return strlen(substitute(a:str, ".", "x", "g"))
8840 else
8841 return strchars(a:str)
8842 endif
8843 endfunction
8844 endif
8845<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008846strcharpart({src}, {start} [, {len}]) *strcharpart()*
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008847 Like |strpart()| but using character index and length instead
8848 of byte index and length.
8849 When a character index is used where a character does not
Bram Moolenaar369b6f52017-01-17 12:22:32 +01008850 exist it is assumed to be one character. For example: >
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008851 strcharpart('abc', -1, 2)
8852< results in 'a'.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02008853
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008854strdisplaywidth({expr} [, {col}]) *strdisplaywidth()*
Bram Moolenaardc536092010-07-18 15:45:49 +02008855 The result is a Number, which is the number of display cells
Bram Moolenaar4c92e752019-02-17 21:18:32 +01008856 String {expr} occupies on the screen when it starts at {col}
8857 (first column is zero). When {col} is omitted zero is used.
8858 Otherwise it is the screen column where to start. This
8859 matters for Tab characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02008860 The option settings of the current window are used. This
8861 matters for anything that's displayed differently, such as
8862 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02008863 When {expr} contains characters with East Asian Width Class
8864 Ambiguous, this function's return value depends on 'ambiwidth'.
8865 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02008866
Bram Moolenaar071d4272004-06-13 20:20:40 +00008867strftime({format} [, {time}]) *strftime()*
8868 The result is a String, which is a formatted date and time, as
8869 specified by the {format} string. The given {time} is used,
8870 or the current time if no time is given. The accepted
8871 {format} depends on your system, thus this is not portable!
8872 See the manual page of the C function strftime() for the
8873 format. The maximum length of the result is 80 characters.
8874 See also |localtime()| and |getftime()|.
8875 The language can be changed with the |:language| command.
8876 Examples: >
8877 :echo strftime("%c") Sun Apr 27 11:49:23 1997
8878 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
8879 :echo strftime("%y%m%d %T") 970427 11:53:55
8880 :echo strftime("%H:%M") 11:55
8881 :echo strftime("%c", getftime("file.c"))
8882 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008883< Not available on all systems. To check use: >
8884 :if exists("*strftime")
8885
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008886strgetchar({str}, {index}) *strgetchar()*
8887 Get character {index} from {str}. This uses a character
8888 index, not a byte index. Composing characters are considered
8889 separate characters here.
8890 Also see |strcharpart()| and |strchars()|.
8891
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008892stridx({haystack}, {needle} [, {start}]) *stridx()*
8893 The result is a Number, which gives the byte index in
8894 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00008895 If {start} is specified, the search starts at index {start}.
8896 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01008897 :let colon1 = stridx(line, ":")
8898 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00008899< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00008900 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008901 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00008902 See also |strridx()|.
8903 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008904 :echo stridx("An Example", "Example") 3
8905 :echo stridx("Starting point", "Start") 0
8906 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008907< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00008908 stridx() works similar to the C function strstr(). When used
8909 with a single character it works similar to strchr().
8910
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008911 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008912string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01008913 Float, String, Blob or a composition of them, then the result
8914 can be parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008915 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01008916 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008917 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00008918 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00008919 Funcref function('name')
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01008920 Blob 0z00112233.44556677.8899
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008921 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00008922 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01008923
8924 When a List or Dictionary has a recursive reference it is
8925 replaced by "[...]" or "{...}". Using eval() on the result
8926 will then fail.
8927
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008928 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008929
Bram Moolenaar071d4272004-06-13 20:20:40 +00008930 *strlen()*
8931strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00008932 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008933 If the argument is a Number it is first converted to a String.
8934 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02008935 If you want to count the number of multi-byte characters use
8936 |strchars()|.
8937 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008938
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008939strpart({src}, {start} [, {len}]) *strpart()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008940 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00008941 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008942 To count characters instead of bytes use |strcharpart()|.
8943
8944 When bytes are selected which do not exist, this doesn't
8945 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008946 If {len} is missing, the copy continues from {start} till the
8947 end of the {src}. >
8948 strpart("abcdefg", 3, 2) == "de"
8949 strpart("abcdefg", -2, 4) == "ab"
8950 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00008951 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008952
Bram Moolenaar071d4272004-06-13 20:20:40 +00008953< Note: To get the first character, {start} must be 0. For
8954 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00008955 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008956<
Bram Moolenaar677ee682005-01-27 14:41:15 +00008957strridx({haystack}, {needle} [, {start}]) *strridx()*
8958 The result is a Number, which gives the byte index in
8959 {haystack} of the last occurrence of the String {needle}.
8960 When {start} is specified, matches beyond this index are
8961 ignored. This can be used to find a match before a previous
8962 match: >
8963 :let lastcomma = strridx(line, ",")
8964 :let comma2 = strridx(line, ",", lastcomma - 1)
8965< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008966 For pattern searches use |match()|.
8967 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00008968 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008969 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008970 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008971< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00008972 When used with a single character it works similar to the C
8973 function strrchr().
8974
Bram Moolenaar071d4272004-06-13 20:20:40 +00008975strtrans({expr}) *strtrans()*
8976 The result is a String, which is {expr} with all unprintable
8977 characters translated into printable characters |'isprint'|.
8978 Like they are shown in a window. Example: >
8979 echo strtrans(@a)
8980< This displays a newline in register a as "^@" instead of
8981 starting a new line.
8982
Bram Moolenaar72597a52010-07-18 15:31:08 +02008983strwidth({expr}) *strwidth()*
8984 The result is a Number, which is the number of display cells
8985 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02008986 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02008987 When {expr} contains characters with East Asian Width Class
8988 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02008989 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02008990
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008991submatch({nr} [, {list}]) *submatch()* *E935*
Bram Moolenaar251e1912011-06-19 05:09:16 +02008992 Only for an expression in a |:substitute| command or
8993 substitute() function.
8994 Returns the {nr}'th submatch of the matched text. When {nr}
8995 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02008996 Note that a NL in the string can stand for a line break of a
8997 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02008998 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02008999
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009000 If {list} is present and non-zero then submatch() returns
9001 a list of strings, similar to |getline()| with two arguments.
Bram Moolenaar41571762014-04-02 19:00:58 +02009002 NL characters in the text represent NUL characters in the
9003 text.
9004 Only returns more than one item for |:substitute|, inside
9005 |substitute()| this list will always contain one or zero
9006 items, since there are no real line breaks.
9007
Bram Moolenaar6100d022016-10-02 16:51:57 +02009008 When substitute() is used recursively only the submatches in
9009 the current (deepest) call can be obtained.
9010
Bram Moolenaar2f058492017-11-30 20:27:52 +01009011 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009012 :s/\d\+/\=submatch(0) + 1/
Bram Moolenaar2f058492017-11-30 20:27:52 +01009013 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009014< This finds the first number in the line and adds one to it.
9015 A line break is included as a newline character.
9016
9017substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
9018 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02009019 the first match of {pat} is replaced with {sub}.
9020 When {flags} is "g", all matches of {pat} in {expr} are
9021 replaced. Otherwise {flags} should be "".
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009022
Bram Moolenaar251e1912011-06-19 05:09:16 +02009023 This works like the ":substitute" command (without any flags).
9024 But the matching with {pat} is always done like the 'magic'
9025 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01009026 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
9027 if you want to ignore or match case and ignore 'ignorecase'.
9028 'smartcase' is not used. See |string-match| for how {pat} is
9029 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009030
9031 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009032 Note that some codes in {sub} have a special meaning
Bram Moolenaar58b85342016-08-14 19:54:54 +02009033 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00009034 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009035
Bram Moolenaar071d4272004-06-13 20:20:40 +00009036 When {pat} does not match in {expr}, {expr} is returned
9037 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02009038
Bram Moolenaar071d4272004-06-13 20:20:40 +00009039 Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009040 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009041< This removes the last component of the 'path' option. >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009042 :echo substitute("testing", ".*", "\\U\\0", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009043< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02009044
9045 When {sub} starts with "\=", the remainder is interpreted as
9046 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009047 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02009048 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009049
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009050< When {sub} is a Funcref that function is called, with one
9051 optional argument. Example: >
9052 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
9053< The optional argument is a list which contains the whole
Bram Moolenaar58b85342016-08-14 19:54:54 +02009054 matched string and up to nine submatches, like what
9055 |submatch()| returns. Example: >
9056 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009057
Bram Moolenaar20aac6c2018-09-02 21:07:30 +02009058swapinfo({fname}) *swapinfo()*
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009059 The result is a dictionary, which holds information about the
9060 swapfile {fname}. The available fields are:
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009061 version Vim version
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009062 user user name
9063 host host name
9064 fname original file name
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009065 pid PID of the Vim process that created the swap
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009066 file
9067 mtime last modification time in seconds
9068 inode Optional: INODE number of the file
Bram Moolenaar47ad5652018-08-21 21:09:07 +02009069 dirty 1 if file was modified, 0 if not
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02009070 Note that "user" and "host" are truncated to at most 39 bytes.
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009071 In case of failure an "error" item is added with the reason:
9072 Cannot open file: file not found or in accessible
9073 Cannot read file: cannot read first block
Bram Moolenaar47ad5652018-08-21 21:09:07 +02009074 Not a swap file: does not contain correct block ID
9075 Magic number mismatch: Info in first block is invalid
Bram Moolenaar00f123a2018-08-21 20:28:54 +02009076
Bram Moolenaar110bd602018-09-16 18:46:59 +02009077swapname({expr}) *swapname()*
9078 The result is the swap file path of the buffer {expr}.
9079 For the use of {expr}, see |bufname()| above.
9080 If buffer {expr} is the current buffer, the result is equal to
9081 |:swapname| (unless no swap file).
9082 If buffer {expr} has no swap file, returns an empty string.
9083
Bram Moolenaar47136d72004-10-12 20:02:24 +00009084synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009085 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00009086 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009087 The syntax ID can be used with |synIDattr()| and
9088 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009089
Bram Moolenaar47136d72004-10-12 20:02:24 +00009090 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009091 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02009092 Note that when the position is after the last character,
9093 that's where the cursor can be in Insert mode, synID() returns
9094 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00009095
Bram Moolenaar79815f12016-07-09 17:07:29 +02009096 When {trans} is |TRUE|, transparent items are reduced to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02009097 item that they reveal. This is useful when wanting to know
Bram Moolenaar79815f12016-07-09 17:07:29 +02009098 the effective color. When {trans} is |FALSE|, the transparent
Bram Moolenaar071d4272004-06-13 20:20:40 +00009099 item is returned. This is useful when wanting to know which
9100 syntax item is effective (e.g. inside parens).
9101 Warning: This function can be very slow. Best speed is
9102 obtained by going through the file in forward direction.
9103
9104 Example (echoes the name of the syntax item under the cursor): >
9105 :echo synIDattr(synID(line("."), col("."), 1), "name")
9106<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02009107
Bram Moolenaar071d4272004-06-13 20:20:40 +00009108synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
9109 The result is a String, which is the {what} attribute of
9110 syntax ID {synID}. This can be used to obtain information
9111 about a syntax item.
9112 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar58b85342016-08-14 19:54:54 +02009113 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00009114 used, the attributes for the currently active highlighting are
9115 used (GUI, cterm or term).
9116 Use synIDtrans() to follow linked highlight groups.
9117 {what} result
9118 "name" the name of the syntax item
9119 "fg" foreground color (GUI: color name used to set
9120 the color, cterm: color number as a string,
9121 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009122 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01009123 "font" font name (only available in the GUI)
9124 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009125 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009126 "fg#" like "fg", but for the GUI and the GUI is
9127 running the name in "#RRGGBB" form
9128 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00009129 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009130 "bold" "1" if bold
9131 "italic" "1" if italic
9132 "reverse" "1" if reverse
9133 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01009134 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00009135 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009136 "undercurl" "1" if undercurled
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02009137 "strike" "1" if strikethrough
Bram Moolenaar071d4272004-06-13 20:20:40 +00009138
9139 Example (echoes the color of the syntax item under the
9140 cursor): >
9141 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
9142<
9143synIDtrans({synID}) *synIDtrans()*
9144 The result is a Number, which is the translated syntax ID of
9145 {synID}. This is the syntax group ID of what is being used to
9146 highlight the character. Highlight links given with
9147 ":highlight link" are followed.
9148
Bram Moolenaar483c5d82010-10-20 18:45:33 +02009149synconcealed({lnum}, {col}) *synconcealed()*
Bram Moolenaar4d785892017-06-22 22:00:50 +02009150 The result is a List with currently three items:
9151 1. The first item in the list is 0 if the character at the
9152 position {lnum} and {col} is not part of a concealable
9153 region, 1 if it is.
9154 2. The second item in the list is a string. If the first item
9155 is 1, the second item contains the text which will be
9156 displayed in place of the concealed text, depending on the
9157 current setting of 'conceallevel' and 'listchars'.
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02009158 3. The third and final item in the list is a number
9159 representing the specific syntax region matched in the
9160 line. When the character is not concealed the value is
9161 zero. This allows detection of the beginning of a new
9162 concealable region if there are two consecutive regions
9163 with the same replacement character. For an example, if
9164 the text is "123456" and both "23" and "45" are concealed
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009165 and replaced by the character "X", then:
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02009166 call returns ~
Bram Moolenaarc572da52017-08-27 16:52:01 +02009167 synconcealed(lnum, 1) [0, '', 0]
9168 synconcealed(lnum, 2) [1, 'X', 1]
9169 synconcealed(lnum, 3) [1, 'X', 1]
9170 synconcealed(lnum, 4) [1, 'X', 2]
9171 synconcealed(lnum, 5) [1, 'X', 2]
9172 synconcealed(lnum, 6) [0, '', 0]
Bram Moolenaar483c5d82010-10-20 18:45:33 +02009173
9174
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009175synstack({lnum}, {col}) *synstack()*
9176 Return a |List|, which is the stack of syntax items at the
9177 position {lnum} and {col} in the current window. Each item in
9178 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009179 The first item in the List is the outer region, following are
9180 items contained in that one. The last one is what |synID()|
9181 returns, unless not the whole item is highlighted or it is a
9182 transparent item.
9183 This function is useful for debugging a syntax file.
9184 Example that shows the syntax stack under the cursor: >
9185 for id in synstack(line("."), col("."))
9186 echo synIDattr(id, "name")
9187 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02009188< When the position specified with {lnum} and {col} is invalid
9189 nothing is returned. The position just after the last
9190 character in a line and the first column in an empty line are
9191 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00009192
Bram Moolenaarc0197e22004-09-13 20:26:32 +00009193system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009194 Get the output of the shell command {expr} as a string. See
9195 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009196
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009197 When {input} is given and is a string this string is written
9198 to a file and passed as stdin to the command. The string is
9199 written as-is, you need to take care of using the correct line
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009200 separators yourself.
9201 If {input} is given and is a |List| it is written to the file
9202 in a way |writefile()| does with {binary} set to "b" (i.e.
9203 with a newline between each list item with newlines inside
Bram Moolenaar12c44922017-01-08 13:26:03 +01009204 list items converted to NULs).
9205 When {input} is given and is a number that is a valid id for
9206 an existing buffer then the content of the buffer is written
9207 to the file line by line, each line terminated by a NL and
9208 NULs characters where the text has a NL.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02009209
9210 Pipes are not used, the 'shelltemp' option is not used.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02009211
Bram Moolenaar04186092016-08-29 21:55:35 +02009212 When prepended by |:silent| the terminal will not be set to
Bram Moolenaar52a72462014-08-29 15:53:52 +02009213 cooked mode. This is meant to be used for commands that do
9214 not need the user to type. It avoids stray characters showing
9215 up on the screen which require |CTRL-L| to remove. >
9216 :silent let f = system('ls *.vim')
9217<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009218 Note: Use |shellescape()| or |::S| with |expand()| or
9219 |fnamemodify()| to escape special characters in a command
9220 argument. Newlines in {expr} may cause the command to fail.
9221 The characters in 'shellquote' and 'shellxquote' may also
Bram Moolenaar26df0922014-02-23 23:39:13 +01009222 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009223 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009224
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009225 The result is a String. Example: >
9226 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01009227 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00009228
9229< To make the result more system-independent, the shell output
9230 is filtered to replace <CR> with <NL> for Macintosh, and
9231 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02009232 To avoid the string being truncated at a NUL, all NUL
9233 characters are replaced with SOH (0x01).
9234
Bram Moolenaar071d4272004-06-13 20:20:40 +00009235 The command executed is constructed using several options:
9236 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
9237 ({tmp} is an automatically generated file name).
9238 For Unix and OS/2 braces are put around {expr} to allow for
9239 concatenated commands.
9240
Bram Moolenaar433f7c82006-03-21 21:29:36 +00009241 The command will be executed in "cooked" mode, so that a
9242 CTRL-C will interrupt the command (on Unix at least).
9243
Bram Moolenaar071d4272004-06-13 20:20:40 +00009244 The resulting error code can be found in |v:shell_error|.
9245 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00009246
9247 Note that any wrong value in the options mentioned above may
9248 make the function fail. It has also been reported to fail
9249 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009250 Unlike ":!cmd" there is no automatic check for changed files.
9251 Use |:checktime| to force a check.
9252
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009253
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009254systemlist({expr} [, {input}]) *systemlist()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009255 Same as |system()|, but returns a |List| with lines (parts of
9256 output separated by NL) with NULs transformed into NLs. Output
9257 is the same as |readfile()| will output with {binary} argument
Bram Moolenaar68563932017-01-10 13:31:15 +01009258 set to "b". Note that on MS-Windows you may get trailing CR
9259 characters.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009260
Bram Moolenaar975b5272016-03-15 23:10:59 +01009261 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009262
9263
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009264tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009265 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009266 buffer associated with each window in the current tab page.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009267 {arg} specifies the number of the tab page to be used. When
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009268 omitted the current tab page is used.
9269 When {arg} is invalid the number zero is returned.
9270 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009271 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009272 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009273 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009274 endfor
9275< Note that a buffer may appear in more than one window.
9276
9277
9278tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00009279 The result is a Number, which is the number of the current
9280 tab page. The first tab page has number 1.
9281 When the optional argument is "$", the number of the last tab
9282 page is returned (the tab page count).
9283 The number can be used with the |:tab| command.
9284
9285
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01009286tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02009287 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009288 {tabarg} specifies the number of tab page to be used.
9289 {arg} is used like with |winnr()|:
9290 - When omitted the current window number is returned. This is
9291 the window which will be used when going to this tab page.
9292 - When "$" the number of windows is returned.
9293 - When "#" the previous window nr is returned.
9294 Useful examples: >
9295 tabpagewinnr(1) " current window of tab page 1
9296 tabpagewinnr(4, '$') " number of windows in tab page 4
9297< When {tabarg} is invalid zero is returned.
9298
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00009299 *tagfiles()*
9300tagfiles() Returns a |List| with the file names used to search for tags
9301 for the current buffer. This is the 'tags' option expanded.
9302
9303
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009304taglist({expr} [, {filename}]) *taglist()*
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009305 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaarc6aafba2017-03-21 17:09:10 +01009306
9307 If {filename} is passed it is used to prioritize the results
9308 in the same way that |:tselect| does. See |tag-priority|.
9309 {filename} should be the full path of the file.
9310
Bram Moolenaard8c00872005-07-22 21:52:15 +00009311 Each list item is a dictionary with at least the following
9312 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00009313 name Name of the tag.
9314 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009315 defined. It is either relative to the
9316 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009317 cmd Ex command used to locate the tag in
9318 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009319 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009320 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009321 kind values. Only available when
9322 using a tags file generated by
9323 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009324 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009325 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009326 More entries may be present, depending on the content of the
9327 tags file: access, implementation, inherits and signature.
9328 Refer to the ctags documentation for information about these
9329 fields. For C code the fields "struct", "class" and "enum"
9330 may appear, they give the name of the entity the tag is
9331 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00009332
Bram Moolenaar214641f2017-03-05 17:04:09 +01009333 The ex-command "cmd" can be either an ex search pattern, a
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00009334 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009335
9336 If there are no matching tags, then an empty list is returned.
9337
9338 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01009339 used in {expr}. This also make the function work faster.
9340 Refer to |tag-regexp| for more information about the tag
9341 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009342
9343 Refer to |'tags'| for information about how the tags file is
9344 located by Vim. Refer to |tags-file-format| for the format of
9345 the tags file generated by the different ctags tools.
9346
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009347tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009348 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009349 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009350 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009351 Examples: >
9352 :echo tan(10)
9353< 0.648361 >
9354 :echo tan(-4.01)
9355< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02009356 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009357
9358
9359tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009360 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009361 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009362 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009363 Examples: >
9364 :echo tanh(0.5)
9365< 0.462117 >
9366 :echo tanh(-1)
9367< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02009368 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009369
9370
Bram Moolenaar574860b2016-05-24 17:33:34 +02009371tempname() *tempname()* *temp-file-name*
9372 The result is a String, which is the name of a file that
Bram Moolenaar58b85342016-08-14 19:54:54 +02009373 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar574860b2016-05-24 17:33:34 +02009374 is different for at least 26 consecutive calls. Example: >
9375 :let tmpfile = tempname()
9376 :exe "redir > " . tmpfile
9377< For Unix, the file will be in a private directory |tempfile|.
9378 For MS-Windows forward slashes are used when the 'shellslash'
9379 option is set or when 'shellcmdflag' starts with '-'.
9380
Bram Moolenaard96ff162018-02-18 22:13:29 +01009381 *term_dumpdiff()*
9382term_dumpdiff({filename}, {filename} [, {options}])
9383 Open a new window displaying the difference between the two
9384 files. The files must have been created with
9385 |term_dumpwrite()|.
9386 Returns the buffer number or zero when the diff fails.
9387 Also see |terminal-diff|.
9388 NOTE: this does not work with double-width characters yet.
9389
9390 The top part of the buffer contains the contents of the first
9391 file, the bottom part of the buffer contains the contents of
9392 the second file. The middle part shows the differences.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009393 The parts are separated by a line of equals.
Bram Moolenaard96ff162018-02-18 22:13:29 +01009394
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009395 If the {options} argument is present, it must be a Dict with
9396 these possible members:
9397 "term_name" name to use for the buffer name, instead
9398 of the first file name.
9399 "term_rows" vertical size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009400 instead of using 'termwinsize'
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009401 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009402 instead of using 'termwinsize'
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009403 "vertical" split the window vertically
9404 "curwin" use the current window, do not split the
9405 window; fails if the current buffer
9406 cannot be |abandon|ed
9407 "norestore" do not add the terminal window to a
9408 session file
Bram Moolenaard96ff162018-02-18 22:13:29 +01009409
9410 Each character in the middle part indicates a difference. If
9411 there are multiple differences only the first in this list is
9412 used:
9413 X different character
9414 w different width
9415 f different foreground color
9416 b different background color
9417 a different attribute
9418 + missing position in first file
9419 - missing position in second file
9420
9421 Using the "s" key the top and bottom parts are swapped. This
9422 makes it easy to spot a difference.
9423
9424 *term_dumpload()*
9425term_dumpload({filename} [, {options}])
9426 Open a new window displaying the contents of {filename}
9427 The file must have been created with |term_dumpwrite()|.
9428 Returns the buffer number or zero when it fails.
9429 Also see |terminal-diff|.
9430
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009431 For {options} see |term_dumpdiff()|.
Bram Moolenaard96ff162018-02-18 22:13:29 +01009432
9433 *term_dumpwrite()*
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01009434term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01009435 Dump the contents of the terminal screen of {buf} in the file
9436 {filename}. This uses a format that can be used with
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01009437 |term_dumpload()| and |term_dumpdiff()|.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02009438 If the job in the terminal already finished an error is given:
9439 *E958*
9440 If {filename} already exists an error is given: *E953*
Bram Moolenaard96ff162018-02-18 22:13:29 +01009441 Also see |terminal-diff|.
9442
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01009443 {options} is a dictionary with these optional entries:
9444 "rows" maximum number of rows to dump
9445 "columns" maximum number of columns to dump
9446
Bram Moolenaare41e3b42017-08-11 16:24:50 +02009447term_getaltscreen({buf}) *term_getaltscreen()*
9448 Returns 1 if the terminal of {buf} is using the alternate
9449 screen.
9450 {buf} is used as with |term_getsize()|.
9451 {only available when compiled with the |+terminal| feature}
9452
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009453term_getansicolors({buf}) *term_getansicolors()*
9454 Get the ANSI color palette in use by terminal {buf}.
9455 Returns a List of length 16 where each element is a String
9456 representing a color in hexadecimal "#rrggbb" format.
9457 Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
9458 If neither was used returns the default colors.
9459
9460 {buf} is used as with |term_getsize()|. If the buffer does not
9461 exist or is not a terminal window, an empty list is returned.
9462 {only available when compiled with the |+terminal| feature and
9463 with GUI enabled and/or the |+termguicolors| feature}
9464
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009465term_getattr({attr}, {what}) *term_getattr()*
9466 Given {attr}, a value returned by term_scrape() in the "attr"
9467 item, return whether {what} is on. {what} can be one of:
9468 bold
9469 italic
9470 underline
9471 strike
9472 reverse
Bram Moolenaar45356542017-08-06 17:53:31 +02009473 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009474
Bram Moolenaar97870002017-07-30 18:28:38 +02009475term_getcursor({buf}) *term_getcursor()*
Bram Moolenaar45356542017-08-06 17:53:31 +02009476 Get the cursor position of terminal {buf}. Returns a list with
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009477 two numbers and a dictionary: [row, col, dict].
Bram Moolenaar45356542017-08-06 17:53:31 +02009478
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009479 "row" and "col" are one based, the first screen cell is row
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009480 1, column 1. This is the cursor position of the terminal
9481 itself, not of the Vim window.
9482
9483 "dict" can have these members:
9484 "visible" one when the cursor is visible, zero when it
9485 is hidden.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009486 "blink" one when the cursor is blinking, zero when it
9487 is not blinking.
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009488 "shape" 1 for a block cursor, 2 for underline and 3
9489 for a vertical bar.
Bram Moolenaar911ead12019-04-21 00:03:35 +02009490 "color" color of the cursor, e.g. "green"
Bram Moolenaar97870002017-07-30 18:28:38 +02009491
9492 {buf} must be the buffer number of a terminal window. If the
9493 buffer does not exist or is not a terminal window, an empty
9494 list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009495 {only available when compiled with the |+terminal| feature}
Bram Moolenaar97870002017-07-30 18:28:38 +02009496
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009497term_getjob({buf}) *term_getjob()*
9498 Get the Job associated with terminal window {buf}.
9499 {buf} is used as with |term_getsize()|.
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009500 Returns |v:null| when there is no job.
Bram Moolenaar45356542017-08-06 17:53:31 +02009501 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009502
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009503term_getline({buf}, {row}) *term_getline()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009504 Get a line of text from the terminal window of {buf}.
9505 {buf} is used as with |term_getsize()|.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009506
Bram Moolenaar45356542017-08-06 17:53:31 +02009507 The first line has {row} one. When {row} is "." the cursor
9508 line is used. When {row} is invalid an empty string is
9509 returned.
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009510
9511 To get attributes of each character use |term_scrape()|.
Bram Moolenaar45356542017-08-06 17:53:31 +02009512 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009513
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02009514term_getscrolled({buf}) *term_getscrolled()*
9515 Return the number of lines that scrolled to above the top of
9516 terminal {buf}. This is the offset between the row number
9517 used for |term_getline()| and |getline()|, so that: >
9518 term_getline(buf, N)
9519< is equal to: >
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009520 getline(N + term_getscrolled(buf))
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02009521< (if that line exists).
9522
9523 {buf} is used as with |term_getsize()|.
9524 {only available when compiled with the |+terminal| feature}
9525
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009526term_getsize({buf}) *term_getsize()*
9527 Get the size of terminal {buf}. Returns a list with two
9528 numbers: [rows, cols]. This is the size of the terminal, not
9529 the window containing the terminal.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009530
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009531 {buf} must be the buffer number of a terminal window. Use an
9532 empty string for the current buffer. If the buffer does not
9533 exist or is not a terminal window, an empty list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009534 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009535
Bram Moolenaarb000e322017-07-30 19:38:21 +02009536term_getstatus({buf}) *term_getstatus()*
9537 Get the status of terminal {buf}. This returns a comma
9538 separated list of these items:
9539 running job is running
9540 finished job has finished
Bram Moolenaar45356542017-08-06 17:53:31 +02009541 normal in Terminal-Normal mode
Bram Moolenaarb000e322017-07-30 19:38:21 +02009542 One of "running" or "finished" is always present.
9543
9544 {buf} must be the buffer number of a terminal window. If the
9545 buffer does not exist or is not a terminal window, an empty
9546 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009547 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02009548
9549term_gettitle({buf}) *term_gettitle()*
9550 Get the title of terminal {buf}. This is the title that the
9551 job in the terminal has set.
9552
9553 {buf} must be the buffer number of a terminal window. If the
9554 buffer does not exist or is not a terminal window, an empty
9555 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009556 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02009557
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009558term_gettty({buf} [, {input}]) *term_gettty()*
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009559 Get the name of the controlling terminal associated with
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009560 terminal window {buf}. {buf} is used as with |term_getsize()|.
9561
9562 When {input} is omitted or 0, return the name for writing
9563 (stdout). When {input} is 1 return the name for reading
9564 (stdin). On UNIX, both return same name.
Bram Moolenaar45356542017-08-06 17:53:31 +02009565 {only available when compiled with the |+terminal| feature}
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009566
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02009567term_list() *term_list()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009568 Return a list with the buffer numbers of all buffers for
9569 terminal windows.
Bram Moolenaar45356542017-08-06 17:53:31 +02009570 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009571
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009572term_scrape({buf}, {row}) *term_scrape()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009573 Get the contents of {row} of terminal screen of {buf}.
9574 For {buf} see |term_getsize()|.
9575
Bram Moolenaar45356542017-08-06 17:53:31 +02009576 The first line has {row} one. When {row} is "." the cursor
9577 line is used. When {row} is invalid an empty string is
9578 returned.
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02009579
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009580 Return a List containing a Dict for each screen cell:
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009581 "chars" character(s) at the cell
9582 "fg" foreground color as #rrggbb
9583 "bg" background color as #rrggbb
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009584 "attr" attributes of the cell, use |term_getattr()|
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009585 to get the individual flags
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009586 "width" cell width: 1 or 2
Bram Moolenaar45356542017-08-06 17:53:31 +02009587 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009588
9589term_sendkeys({buf}, {keys}) *term_sendkeys()*
9590 Send keystrokes {keys} to terminal {buf}.
9591 {buf} is used as with |term_getsize()|.
9592
9593 {keys} are translated as key sequences. For example, "\<c-x>"
9594 means the character CTRL-X.
Bram Moolenaar45356542017-08-06 17:53:31 +02009595 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009596
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009597term_setansicolors({buf}, {colors}) *term_setansicolors()*
9598 Set the ANSI color palette used by terminal {buf}.
9599 {colors} must be a List of 16 valid color names or hexadecimal
9600 color codes, like those accepted by |highlight-guifg|.
9601 Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
9602
Bram Moolenaara42d3632018-04-14 17:05:38 +02009603 The colors normally are:
9604 0 black
9605 1 dark red
9606 2 dark green
9607 3 brown
9608 4 dark blue
9609 5 dark magenta
9610 6 dark cyan
9611 7 light grey
9612 8 dark grey
9613 9 red
9614 10 green
9615 11 yellow
9616 12 blue
9617 13 magenta
9618 14 cyan
9619 15 white
9620
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009621 These colors are used in the GUI and in the terminal when
9622 'termguicolors' is set. When not using GUI colors (GUI mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009623 or 'termguicolors'), the terminal window always uses the 16
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009624 ANSI colors of the underlying terminal.
9625 {only available when compiled with the |+terminal| feature and
9626 with GUI enabled and/or the |+termguicolors| feature}
9627
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009628term_setkill({buf}, {how}) *term_setkill()*
9629 When exiting Vim or trying to close the terminal window in
9630 another way, {how} defines whether the job in the terminal can
9631 be stopped.
9632 When {how} is empty (the default), the job will not be
9633 stopped, trying to exit will result in |E947|.
9634 Otherwise, {how} specifies what signal to send to the job.
9635 See |job_stop()| for the values.
9636
9637 After sending the signal Vim will wait for up to a second to
9638 check that the job actually stopped.
9639
Bram Moolenaarb5b75622018-03-09 22:22:21 +01009640term_setrestore({buf}, {command}) *term_setrestore()*
9641 Set the command to write in a session file to restore the job
9642 in this terminal. The line written in the session file is: >
9643 terminal ++curwin ++cols=%d ++rows=%d {command}
9644< Make sure to escape the command properly.
9645
9646 Use an empty {command} to run 'shell'.
9647 Use "NONE" to not restore this window.
9648 {only available when compiled with the |+terminal| feature}
9649
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009650term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955*
Bram Moolenaara42d3632018-04-14 17:05:38 +02009651 Set the size of terminal {buf}. The size of the window
9652 containing the terminal will also be adjusted, if possible.
9653 If {rows} or {cols} is zero or negative, that dimension is not
9654 changed.
9655
9656 {buf} must be the buffer number of a terminal window. Use an
9657 empty string for the current buffer. If the buffer does not
9658 exist or is not a terminal window, an error is given.
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009659 {only available when compiled with the |+terminal| feature}
9660
Bram Moolenaar911ead12019-04-21 00:03:35 +02009661term_start({cmd} [, {options}]) *term_start()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009662 Open a terminal window and run {cmd} in it.
9663
Bram Moolenaar01164a62017-11-02 22:58:42 +01009664 {cmd} can be a string or a List, like with |job_start()|. The
9665 string "NONE" can be used to open a terminal window without
9666 starting a job, the pty of the terminal can be used by a
9667 command like gdb.
9668
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009669 Returns the buffer number of the terminal window. If {cmd}
9670 cannot be executed the window does open and shows an error
9671 message.
9672 If opening the window fails zero is returned.
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009673
Bram Moolenaar78712a72017-08-05 14:50:12 +02009674 {options} are similar to what is used for |job_start()|, see
9675 |job-options|. However, not all options can be used. These
9676 are supported:
9677 all timeout options
Bram Moolenaard473c8c2018-08-11 18:00:22 +02009678 "stoponexit", "cwd", "env"
9679 "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
Bram Moolenaar78712a72017-08-05 14:50:12 +02009680 "in_io", "in_top", "in_bot", "in_name", "in_buf"
9681 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
9682 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
9683 However, at least one of stdin, stdout or stderr must be
9684 connected to the terminal. When I/O is connected to the
9685 terminal then the callback function for that part is not used.
9686
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009687 There are extra options:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02009688 "term_name" name to use for the buffer name, instead
9689 of the command name.
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009690 "term_rows" vertical size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009691 instead of using 'termwinsize'
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009692 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009693 instead of using 'termwinsize'
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02009694 "vertical" split the window vertically; note that
9695 other window position can be defined with
9696 command modifiers, such as |:belowright|.
Bram Moolenaarda43b612017-08-11 22:27:50 +02009697 "curwin" use the current window, do not split the
9698 window; fails if the current buffer
9699 cannot be |abandon|ed
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009700 "hidden" do not open a window
Bram Moolenaarb5b75622018-03-09 22:22:21 +01009701 "norestore" do not add the terminal window to a
9702 session file
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009703 "term_kill" what to do when trying to close the
9704 terminal window, see |term_setkill()|
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009705 "term_finish" What to do when the job is finished:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02009706 "close": close any windows
9707 "open": open window if needed
9708 Note that "open" can be interruptive.
9709 See |term++close| and |term++open|.
Bram Moolenaar37c45832017-08-12 16:01:04 +02009710 "term_opencmd" command to use for opening the window when
9711 "open" is used for "term_finish"; must
9712 have "%d" where the buffer number goes,
9713 e.g. "10split|buffer %d"; when not
9714 specified "botright sbuf %d" is used
Bram Moolenaaref68e4f2017-09-02 16:28:36 +02009715 "eof_chars" Text to send after all buffer lines were
9716 written to the terminal. When not set
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009717 CTRL-D is used on MS-Windows. For Python
9718 use CTRL-Z or "exit()". For a shell use
9719 "exit". A CR is always added.
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009720 "ansi_colors" A list of 16 color names or hex codes
9721 defining the ANSI palette used in GUI
9722 color modes. See |g:terminal_ansi_colors|.
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01009723 "tty_type" (MS-Windows only): Specify which pty to
9724 use. See 'termwintype' for the values.
Bram Moolenaar37c45832017-08-12 16:01:04 +02009725
Bram Moolenaar45356542017-08-06 17:53:31 +02009726 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009727
Bram Moolenaarf3402b12017-08-06 19:07:08 +02009728term_wait({buf} [, {time}]) *term_wait()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009729 Wait for pending updates of {buf} to be handled.
9730 {buf} is used as with |term_getsize()|.
Bram Moolenaarf3402b12017-08-06 19:07:08 +02009731 {time} is how long to wait for updates to arrive in msec. If
9732 not set then 10 msec will be used.
Bram Moolenaar45356542017-08-06 17:53:31 +02009733 {only available when compiled with the |+terminal| feature}
Bram Moolenaar574860b2016-05-24 17:33:34 +02009734
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009735test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()*
9736 This is for testing: If the memory allocation with {id} is
9737 called, then decrement {countdown}, and when it reaches zero
9738 let memory allocation fail {repeat} times. When {repeat} is
9739 smaller than one it fails one time.
9740
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02009741test_autochdir() *test_autochdir()*
9742 Set a flag to enable the effect of 'autochdir' before Vim
9743 startup has finished.
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009744
Bram Moolenaar5e80de32017-09-03 15:48:12 +02009745test_feedinput({string}) *test_feedinput()*
9746 Characters in {string} are queued for processing as if they
9747 were typed by the user. This uses a low level input buffer.
9748 This function works only when with |+unix| or GUI is running.
9749
Bram Moolenaar574860b2016-05-24 17:33:34 +02009750test_garbagecollect_now() *test_garbagecollect_now()*
9751 Like garbagecollect(), but executed right away. This must
9752 only be called directly to avoid any structure to exist
9753 internally, and |v:testing| must have been set before calling
9754 any function.
9755
Bram Moolenaare0c31f62017-03-01 15:07:05 +01009756test_ignore_error({expr}) *test_ignore_error()*
9757 Ignore any error containing {expr}. A normal message is given
9758 instead.
9759 This is only meant to be used in tests, where catching the
9760 error with try/catch cannot be used (because it skips over
9761 following code).
9762 {expr} is used literally, not as a pattern.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +01009763 When the {expr} is the string "RESET" then the list of ignored
9764 errors is made empty.
Bram Moolenaare0c31f62017-03-01 15:07:05 +01009765
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009766test_null_blob() *test_null_blob()*
9767 Return a |Blob| that is null. Only useful for testing.
9768
Bram Moolenaar574860b2016-05-24 17:33:34 +02009769test_null_channel() *test_null_channel()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009770 Return a |Channel| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009771 {only available when compiled with the +channel feature}
9772
9773test_null_dict() *test_null_dict()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009774 Return a |Dict| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009775
9776test_null_job() *test_null_job()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009777 Return a |Job| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009778 {only available when compiled with the +job feature}
9779
9780test_null_list() *test_null_list()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009781 Return a |List| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009782
9783test_null_partial() *test_null_partial()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009784 Return a |Partial| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009785
9786test_null_string() *test_null_string()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009787 Return a |String| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009788
Bram Moolenaarfe8ef982018-09-13 20:31:54 +02009789test_option_not_set({name}) *test_option_not_set()*
9790 Reset the flag that indicates option {name} was set. Thus it
9791 looks like it still has the default value. Use like this: >
9792 set ambiwidth=double
9793 call test_option_not_set('ambiwidth')
9794< Now the 'ambiwidth' option behaves like it was never changed,
9795 even though the value is "double".
9796 Only to be used for testing!
9797
Bram Moolenaar036986f2017-03-16 17:41:02 +01009798test_override({name}, {val}) *test_override()*
Bram Moolenaar9d87a372018-12-18 21:41:50 +01009799 Overrides certain parts of Vim's internal processing to be able
Bram Moolenaar036986f2017-03-16 17:41:02 +01009800 to run tests. Only to be used for testing Vim!
9801 The override is enabled when {val} is non-zero and removed
9802 when {val} is zero.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009803 Current supported values for name are:
Bram Moolenaar036986f2017-03-16 17:41:02 +01009804
9805 name effect when {val} is non-zero ~
9806 redraw disable the redrawing() function
Bram Moolenaared5a9d62018-09-06 13:14:43 +02009807 redraw_flag ignore the RedrawingDisabled flag
Bram Moolenaar036986f2017-03-16 17:41:02 +01009808 char_avail disable the char_avail() function
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009809 starting reset the "starting" variable, see below
Bram Moolenaarbcf94422018-06-23 14:21:42 +02009810 nfa_fail makes the NFA regexp engine fail to force a
9811 fallback to the old engine
Bram Moolenaar92fd5992019-05-02 23:00:22 +02009812 no_query_mouse do not query the mouse position for "dec"
9813 terminals
Bram Moolenaar036986f2017-03-16 17:41:02 +01009814 ALL clear all overrides ({val} is not used)
9815
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009816 "starting" is to be used when a test should behave like
9817 startup was done. Since the tests are run by sourcing a
9818 script the "starting" variable is non-zero. This is usually a
9819 good thing (tests run faster), but sometimes changes behavior
9820 in a way that the test doesn't work properly.
9821 When using: >
9822 call test_override('starting', 1)
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009823< The value of "starting" is saved. It is restored by: >
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009824 call test_override('starting', 0)
9825
Bram Moolenaarc3e92c12019-03-23 14:23:07 +01009826test_refcount({expr}) *test_refcount()*
9827 Return the reference count of {expr}. When {expr} is of a
9828 type that does not have a reference count, returns -1. Only
9829 to be used for testing.
9830
Bram Moolenaarab186732018-09-14 21:27:06 +02009831test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()*
9832 Pretend using scrollbar {which} to move it to position
9833 {value}. {which} can be:
9834 left Left scrollbar of the current window
9835 right Right scrollbar of the current window
9836 hor Horizontal scrollbar
9837
9838 For the vertical scrollbars {value} can be 1 to the
9839 line-count of the buffer. For the horizontal scrollbar the
9840 {value} can be between 1 and the maximum line length, assuming
9841 'wrap' is not set.
9842
9843 When {dragging} is non-zero it's like dragging the scrollbar,
9844 otherwise it's like clicking in the scrollbar.
9845 Only works when the {which} scrollbar actually exists,
9846 obviously only when using the GUI.
9847
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02009848test_setmouse({row}, {col}) *test_setmouse()*
9849 Set the mouse position to be used for the next mouse action.
9850 {row} and {col} are one based.
9851 For example: >
9852 call test_setmouse(4, 20)
9853 call feedkeys("\<LeftMouse>", "xt")
9854
Bram Moolenaarc95a3022016-06-12 23:01:46 +02009855test_settime({expr}) *test_settime()*
9856 Set the time Vim uses internally. Currently only used for
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02009857 timestamps in the history, as they are used in viminfo, and
9858 for undo.
Bram Moolenaar3df01732017-02-17 22:47:16 +01009859 Using a value of 1 makes Vim not sleep after a warning or
9860 error message.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02009861 {expr} must evaluate to a number. When the value is zero the
9862 normal behavior is restored.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009863
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009864 *timer_info()*
9865timer_info([{id}])
9866 Return a list with information about timers.
9867 When {id} is given only information about this timer is
9868 returned. When timer {id} does not exist an empty list is
9869 returned.
9870 When {id} is omitted information about all timers is returned.
9871
9872 For each timer the information is stored in a Dictionary with
9873 these items:
9874 "id" the timer ID
9875 "time" time the timer was started with
9876 "remaining" time until the timer fires
9877 "repeat" number of times the timer will still fire;
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009878 -1 means forever
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009879 "callback" the callback
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009880 "paused" 1 if the timer is paused, 0 otherwise
9881
9882 {only available when compiled with the |+timers| feature}
9883
9884timer_pause({timer}, {paused}) *timer_pause()*
9885 Pause or unpause a timer. A paused timer does not invoke its
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009886 callback when its time expires. Unpausing a timer may cause
9887 the callback to be invoked almost immediately if enough time
9888 has passed.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009889
9890 Pausing a timer is useful to avoid the callback to be called
9891 for a short time.
9892
9893 If {paused} evaluates to a non-zero Number or a non-empty
9894 String, then the timer is paused, otherwise it is unpaused.
9895 See |non-zero-arg|.
9896
9897 {only available when compiled with the |+timers| feature}
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009898
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009899 *timer_start()* *timer* *timers*
Bram Moolenaar975b5272016-03-15 23:10:59 +01009900timer_start({time}, {callback} [, {options}])
9901 Create a timer and return the timer ID.
9902
9903 {time} is the waiting time in milliseconds. This is the
9904 minimum time before invoking the callback. When the system is
9905 busy or Vim is not waiting for input the time will be longer.
9906
9907 {callback} is the function to call. It can be the name of a
Bram Moolenaarf37506f2016-08-31 22:22:10 +02009908 function or a |Funcref|. It is called with one argument, which
Bram Moolenaar975b5272016-03-15 23:10:59 +01009909 is the timer ID. The callback is only invoked when Vim is
9910 waiting for input.
9911
9912 {options} is a dictionary. Supported entries:
9913 "repeat" Number of times to repeat calling the
Bram Moolenaarabd468e2016-09-08 22:22:43 +02009914 callback. -1 means forever. When not present
9915 the callback will be called once.
Bram Moolenaarc577d812017-07-08 22:37:34 +02009916 If the timer causes an error three times in a
9917 row the repeat is cancelled. This avoids that
9918 Vim becomes unusable because of all the error
9919 messages.
Bram Moolenaar975b5272016-03-15 23:10:59 +01009920
9921 Example: >
9922 func MyHandler(timer)
9923 echo 'Handler called'
9924 endfunc
9925 let timer = timer_start(500, 'MyHandler',
9926 \ {'repeat': 3})
9927< This will invoke MyHandler() three times at 500 msec
9928 intervals.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009929
Bram Moolenaar975b5272016-03-15 23:10:59 +01009930 {only available when compiled with the |+timers| feature}
9931
Bram Moolenaar03602ec2016-03-20 20:57:45 +01009932timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +02009933 Stop a timer. The timer callback will no longer be invoked.
9934 {timer} is an ID returned by timer_start(), thus it must be a
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009935 Number. If {timer} does not exist there is no error.
Bram Moolenaar03602ec2016-03-20 20:57:45 +01009936
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009937 {only available when compiled with the |+timers| feature}
9938
9939timer_stopall() *timer_stopall()*
9940 Stop all timers. The timer callbacks will no longer be
9941 invoked. Useful if some timers is misbehaving. If there are
9942 no timers there is no error.
9943
9944 {only available when compiled with the |+timers| feature}
9945
Bram Moolenaar071d4272004-06-13 20:20:40 +00009946tolower({expr}) *tolower()*
9947 The result is a copy of the String given, with all uppercase
9948 characters turned into lowercase (just like applying |gu| to
9949 the string).
9950
9951toupper({expr}) *toupper()*
9952 The result is a copy of the String given, with all lowercase
9953 characters turned into uppercase (just like applying |gU| to
9954 the string).
9955
Bram Moolenaar8299df92004-07-10 09:47:34 +00009956tr({src}, {fromstr}, {tostr}) *tr()*
9957 The result is a copy of the {src} string with all characters
9958 which appear in {fromstr} replaced by the character in that
9959 position in the {tostr} string. Thus the first character in
9960 {fromstr} is translated into the first character in {tostr}
9961 and so on. Exactly like the unix "tr" command.
9962 This code also deals with multibyte characters properly.
9963
9964 Examples: >
9965 echo tr("hello there", "ht", "HT")
9966< returns "Hello THere" >
9967 echo tr("<blob>", "<>", "{}")
9968< returns "{blob}"
9969
Bram Moolenaard473c8c2018-08-11 18:00:22 +02009970trim({text} [, {mask}]) *trim()*
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009971 Return {text} as a String where any character in {mask} is
9972 removed from the beginning and end of {text}.
9973 If {mask} is not given, {mask} is all characters up to 0x20,
9974 which includes Tab, space, NL and CR, plus the non-breaking
9975 space character 0xa0.
9976 This code deals with multibyte characters properly.
9977
9978 Examples: >
Bram Moolenaarab943432018-03-29 18:27:07 +02009979 echo trim(" some text ")
9980< returns "some text" >
9981 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009982< returns "RESERVE_TAIL" >
Bram Moolenaarab943432018-03-29 18:27:07 +02009983 echo trim("rm<Xrm<>X>rrm", "rm<>")
9984< returns "Xrm<>X" (characters in the middle are not removed)
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009985
Bram Moolenaar446cb832008-06-24 21:56:24 +00009986trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00009987 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00009988 equal to {expr} as a |Float| (truncate towards zero).
9989 {expr} must evaluate to a |Float| or a |Number|.
9990 Examples: >
9991 echo trunc(1.456)
9992< 1.0 >
9993 echo trunc(-5.456)
9994< -5.0 >
9995 echo trunc(4.0)
9996< 4.0
9997 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009998
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00009999 *type()*
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010000type({expr}) The result is a Number representing the type of {expr}.
10001 Instead of using the number directly, it is better to use the
10002 v:t_ variable that has the value:
10003 Number: 0 |v:t_number|
10004 String: 1 |v:t_string|
10005 Funcref: 2 |v:t_func|
10006 List: 3 |v:t_list|
10007 Dictionary: 4 |v:t_dict|
10008 Float: 5 |v:t_float|
10009 Boolean: 6 |v:t_bool| (v:false and v:true)
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010010 None: 7 |v:t_none| (v:null and v:none)
10011 Job: 8 |v:t_job|
10012 Channel: 9 |v:t_channel|
10013 Blob: 10 |v:t_blob|
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010014 For backward compatibility, this method can be used: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000010015 :if type(myvar) == type(0)
10016 :if type(myvar) == type("")
10017 :if type(myvar) == type(function("tr"))
10018 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +000010019 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +000010020 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +010010021 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +010010022 :if type(myvar) == type(v:none)
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010023< To check if the v:t_ variables exist use this: >
10024 :if exists('v:t_number')
Bram Moolenaar071d4272004-06-13 20:20:40 +000010025
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010026undofile({name}) *undofile()*
10027 Return the name of the undo file that would be used for a file
10028 with name {name} when writing. This uses the 'undodir'
10029 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +020010030 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +020010031 {name} is always expanded to the full path, since that is what
10032 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +020010033 If {name} is empty undofile() returns an empty string, since a
10034 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010035 Useful in combination with |:wundo| and |:rundo|.
Bram Moolenaarb328cca2019-01-06 16:24:01 +010010036 When compiled without the |+persistent_undo| option this always
Bram Moolenaara17d4c12010-05-30 18:30:36 +020010037 returns an empty string.
10038
Bram Moolenaara800b422010-06-27 01:15:55 +020010039undotree() *undotree()*
10040 Return the current state of the undo tree in a dictionary with
10041 the following items:
10042 "seq_last" The highest undo sequence number used.
10043 "seq_cur" The sequence number of the current position in
10044 the undo tree. This differs from "seq_last"
10045 when some changes were undone.
10046 "time_cur" Time last used for |:earlier| and related
10047 commands. Use |strftime()| to convert to
10048 something readable.
10049 "save_last" Number of the last file write. Zero when no
10050 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +020010051 "save_cur" Number of the current position in the undo
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010052 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +020010053 "synced" Non-zero when the last undo block was synced.
10054 This happens when waiting from input from the
10055 user. See |undo-blocks|.
10056 "entries" A list of dictionaries with information about
10057 undo blocks.
10058
10059 The first item in the "entries" list is the oldest undo item.
10060 Each List item is a Dictionary with these items:
10061 "seq" Undo sequence number. Same as what appears in
10062 |:undolist|.
10063 "time" Timestamp when the change happened. Use
10064 |strftime()| to convert to something readable.
10065 "newhead" Only appears in the item that is the last one
10066 that was added. This marks the last change
10067 and where further changes will be added.
10068 "curhead" Only appears in the item that is the last one
10069 that was undone. This marks the current
10070 position in the undo tree, the block that will
10071 be used by a redo command. When nothing was
10072 undone after the last change this item will
10073 not appear anywhere.
10074 "save" Only appears on the last block before a file
10075 write. The number is the write count. The
10076 first write has number 1, the last one the
10077 "save_last" mentioned above.
10078 "alt" Alternate entry. This is again a List of undo
10079 blocks. Each item may again have an "alt"
10080 item.
10081
Bram Moolenaar327aa022014-03-25 18:24:23 +010010082uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
10083 Remove second and succeeding copies of repeated adjacent
10084 {list} items in-place. Returns {list}. If you want a list
10085 to remain unmodified make a copy first: >
10086 :let newlist = uniq(copy(mylist))
10087< The default compare function uses the string representation of
10088 each item. For the use of {func} and {dict} see |sort()|.
10089
Bram Moolenaar677ee682005-01-27 14:41:15 +000010090values({dict}) *values()*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010091 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +010010092 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaar677ee682005-01-27 14:41:15 +000010093
10094
Bram Moolenaar071d4272004-06-13 20:20:40 +000010095virtcol({expr}) *virtcol()*
10096 The result is a Number, which is the screen column of the file
10097 position given with {expr}. That is, the last screen position
10098 occupied by the character at that position, when the screen
10099 would be of unlimited width. When there is a <Tab> at the
10100 position, the returned Number will be the column at the end of
10101 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +020010102 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +000010103 For the byte position use |col()|.
10104 For the use of {expr} see |col()|.
10105 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +000010106 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +000010107 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +020010108 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010109 When Virtual editing is active in the current mode, a position
10110 beyond the end of the line can be returned. |'virtualedit'|
10111 The accepted positions are:
10112 . the cursor position
10113 $ the end of the cursor line (the result is the
10114 number of displayed characters in the cursor line
10115 plus one)
10116 'x position of mark x (if the mark is not set, 0 is
10117 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +010010118 v In Visual mode: the start of the Visual area (the
10119 cursor is the end). When not in Visual mode
10120 returns the cursor position. Differs from |'<| in
10121 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010122 Note that only marks in the current file can be used.
10123 Examples: >
10124 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
10125 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +000010126 virtcol("'t") with text " there", with 't at 'h', returns 6
Bram Moolenaar58b85342016-08-14 19:54:54 +020010127< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010128 A more advanced example that echoes the maximum length of
10129 all lines: >
10130 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
10131
Bram Moolenaar071d4272004-06-13 20:20:40 +000010132
10133visualmode([expr]) *visualmode()*
10134 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010135 used in the current buffer. Initially it returns an empty
10136 string, but once Visual mode has been used, it returns "v",
10137 "V", or "<CTRL-V>" (a single CTRL-V character) for
10138 character-wise, line-wise, or block-wise Visual mode
10139 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010140 Example: >
10141 :exe "normal " . visualmode()
10142< This enters the same Visual mode as before. It is also useful
10143 in scripts if you wish to act differently depending on the
10144 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010145 If Visual mode is active, use |mode()| to get the Visual mode
10146 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +000010147 If [expr] is supplied and it evaluates to a non-zero Number or
10148 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaare381d3d2016-07-07 14:50:41 +020010149 the old value is returned. See |non-zero-arg|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010150
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010151wildmenumode() *wildmenumode()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +020010152 Returns |TRUE| when the wildmenu is active and |FALSE|
Bram Moolenaar8738fc12013-02-20 17:59:11 +010010153 otherwise. See 'wildmenu' and 'wildmode'.
10154 This can be used in mappings to handle the 'wildcharm' option
10155 gracefully. (Makes only sense with |mapmode-c| mappings).
10156
10157 For example to make <c-j> work like <down> in wildmode, use: >
10158 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
10159<
10160 (Note, this needs the 'wildcharm' option set appropriately).
10161
10162
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010010163win_findbuf({bufnr}) *win_findbuf()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020010164 Returns a list with |window-ID|s for windows that contain
10165 buffer {bufnr}. When there is none the list is empty.
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010010166
Bram Moolenaar86edef62016-03-13 18:07:30 +010010167win_getid([{win} [, {tab}]]) *win_getid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020010168 Get the |window-ID| for the specified window.
Bram Moolenaar86edef62016-03-13 18:07:30 +010010169 When {win} is missing use the current window.
10170 With {win} this is the window number. The top window has
Bram Moolenaarba3ff532018-11-04 14:45:49 +010010171 number 1.
Bram Moolenaar86edef62016-03-13 18:07:30 +010010172 Without {tab} use the current tab, otherwise the tab with
10173 number {tab}. The first tab has number one.
10174 Return zero if the window cannot be found.
10175
10176win_gotoid({expr}) *win_gotoid()*
10177 Go to window with ID {expr}. This may also change the current
10178 tabpage.
10179 Return 1 if successful, 0 if the window cannot be found.
10180
Bram Moolenaar03413f42016-04-12 21:07:15 +020010181win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +010010182 Return a list with the tab number and window number of window
10183 with ID {expr}: [tabnr, winnr].
10184 Return [0, 0] if the window cannot be found.
10185
10186win_id2win({expr}) *win_id2win()*
10187 Return the window number of window with ID {expr}.
10188 Return 0 if the window cannot be found in the current tabpage.
10189
Bram Moolenaar22044dc2017-12-02 15:43:37 +010010190win_screenpos({nr}) *win_screenpos()*
10191 Return the screen position of window {nr} as a list with two
10192 numbers: [row, col]. The first window always has position
Bram Moolenaar7132ddc2018-07-15 17:01:11 +020010193 [1, 1], unless there is a tabline, then it is [2, 1].
Bram Moolenaar22044dc2017-12-02 15:43:37 +010010194 {nr} can be the window number or the |window-ID|.
10195 Return [0, 0] if the window cannot be found in the current
10196 tabpage.
10197
Bram Moolenaar071d4272004-06-13 20:20:40 +000010198 *winbufnr()*
10199winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +020010200 associated with window {nr}. {nr} can be the window number or
Bram Moolenaar7571d552016-08-18 22:54:46 +020010201 the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +020010202 When {nr} is zero, the number of the buffer in the current
10203 window is returned.
10204 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010205 Example: >
10206 :echo "The file in the current window is " . bufname(winbufnr(0))
10207<
10208 *wincol()*
10209wincol() The result is a Number, which is the virtual column of the
10210 cursor in the window. This is counting screen cells from the
10211 left side of the window. The leftmost column is one.
10212
10213winheight({nr}) *winheight()*
10214 The result is a Number, which is the height of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010215 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010216 When {nr} is zero, the height of the current window is
10217 returned. When window {nr} doesn't exist, -1 is returned.
10218 An existing window always has a height of zero or more.
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010219 This excludes any window toolbar line.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010220 Examples: >
10221 :echo "The current window has " . winheight(0) . " lines."
10222<
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +020010223winlayout([{tabnr}]) *winlayout()*
10224 The result is a nested List containing the layout of windows
10225 in a tabpage.
10226
10227 Without {tabnr} use the current tabpage, otherwise the tabpage
10228 with number {tabnr}. If the tabpage {tabnr} is not found,
10229 returns an empty list.
10230
10231 For a leaf window, it returns:
10232 ['leaf', {winid}]
10233 For horizontally split windows, which form a column, it
10234 returns:
10235 ['col', [{nested list of windows}]]
10236 For vertically split windows, which form a row, it returns:
10237 ['row', [{nested list of windows}]]
10238
10239 Example: >
10240 " Only one window in the tab page
10241 :echo winlayout()
10242 ['leaf', 1000]
10243 " Two horizontally split windows
10244 :echo winlayout()
10245 ['col', [['leaf', 1000], ['leaf', 1001]]]
10246 " Three horizontally split windows, with two
10247 " vertically split windows in the middle window
10248 :echo winlayout(2)
10249 ['col', [['leaf', 1002], ['row', ['leaf', 1003],
10250 ['leaf', 1001]]], ['leaf', 1000]]
10251<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010252 *winline()*
10253winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar58b85342016-08-14 19:54:54 +020010254 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +000010255 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +000010256 If the cursor was moved the view on the file will be updated
10257 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010258
10259 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010260winnr([{arg}]) The result is a Number, which is the number of the current
10261 window. The top window has number 1.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010262
10263 The optional argument {arg} supports the following values:
10264 $ the number of the last window (the window
10265 count).
10266 # the number of the last accessed window (where
10267 |CTRL-W_p| goes to). If there is no previous
10268 window or it is in another tab page 0 is
10269 returned.
10270 {N}j the number of the Nth window below the
10271 current window (where |CTRL-W_j| goes to).
10272 {N}k the number of the Nth window above the current
10273 window (where |CTRL-W_k| goes to).
10274 {N}h the number of the Nth window left of the
10275 current window (where |CTRL-W_h| goes to).
10276 {N}l the number of the Nth window right of the
10277 current window (where |CTRL-W_l| goes to).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010278 The number can be used with |CTRL-W_w| and ":wincmd w"
10279 |:wincmd|.
Bram Moolenaar690afe12017-01-28 18:34:47 +010010280 Also see |tabpagewinnr()| and |win_getid()|.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020010281 Examples: >
10282 let window_count = winnr('$')
10283 let prev_window = winnr('#')
10284 let wnum = winnr('3k')
10285<
Bram Moolenaar071d4272004-06-13 20:20:40 +000010286 *winrestcmd()*
10287winrestcmd() Returns a sequence of |:resize| commands that should restore
10288 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010289 are opened or closed and the current window and tab page is
10290 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010291 Example: >
10292 :let cmd = winrestcmd()
10293 :call MessWithWindowSizes()
10294 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010295<
10296 *winrestview()*
10297winrestview({dict})
10298 Uses the |Dictionary| returned by |winsaveview()| to restore
10299 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +020010300 Note: The {dict} does not have to contain all values, that are
10301 returned by |winsaveview()|. If values are missing, those
10302 settings won't be restored. So you can use: >
10303 :call winrestview({'curswant': 4})
10304<
10305 This will only set the curswant value (the column the cursor
10306 wants to move on vertical movements) of the cursor to column 5
10307 (yes, that is 5), while all other settings will remain the
10308 same. This is useful, if you set the cursor position manually.
10309
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010310 If you have changed the values the result is unpredictable.
10311 If the window size changed the result won't be the same.
10312
10313 *winsaveview()*
10314winsaveview() Returns a |Dictionary| that contains information to restore
10315 the view of the current window. Use |winrestview()| to
10316 restore the view.
10317 This is useful if you have a mapping that jumps around in the
10318 buffer and you want to go back to the original view.
10319 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +000010320 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +020010321 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010322 The return value includes:
10323 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +020010324 col cursor column (Note: the first column
10325 zero, as opposed to what getpos()
10326 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010327 coladd cursor column offset for 'virtualedit'
10328 curswant column for vertical movement
10329 topline first line in the window
10330 topfill filler lines, only in diff mode
10331 leftcol first column displayed
10332 skipcol columns skipped
10333 Note that no option values are saved.
10334
Bram Moolenaar071d4272004-06-13 20:20:40 +000010335
10336winwidth({nr}) *winwidth()*
10337 The result is a Number, which is the width of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010338 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010339 When {nr} is zero, the width of the current window is
10340 returned. When window {nr} doesn't exist, -1 is returned.
10341 An existing window always has a width of zero or more.
10342 Examples: >
10343 :echo "The current window has " . winwidth(0) . " columns."
10344 :if winwidth(0) <= 50
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010345 : 50 wincmd |
Bram Moolenaar071d4272004-06-13 20:20:40 +000010346 :endif
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010347< For getting the terminal or screen size, see the 'columns'
10348 option.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010349
10350
Bram Moolenaared767a22016-01-03 22:49:16 +010010351wordcount() *wordcount()*
10352 The result is a dictionary of byte/chars/word statistics for
10353 the current buffer. This is the same info as provided by
10354 |g_CTRL-G|
10355 The return value includes:
10356 bytes Number of bytes in the buffer
10357 chars Number of chars in the buffer
10358 words Number of words in the buffer
10359 cursor_bytes Number of bytes before cursor position
10360 (not in Visual mode)
10361 cursor_chars Number of chars before cursor position
10362 (not in Visual mode)
10363 cursor_words Number of words before cursor position
10364 (not in Visual mode)
10365 visual_bytes Number of bytes visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010366 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010367 visual_chars Number of chars visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010368 (only in Visual mode)
Bram Moolenaarc572da52017-08-27 16:52:01 +020010369 visual_words Number of words visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010370 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010371
10372
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010373 *writefile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010374writefile({object}, {fname} [, {flags}])
10375 When {object} is a |List| write it to file {fname}. Each list
10376 item is separated with a NL. Each list item must be a String
10377 or Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010378 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010379 not be a NL after the last list item. An empty item at the
10380 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010381
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010382 When {object} is a |Blob| write the bytes to file {fname}
10383 unmodified.
10384
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010385 When {flags} contains "a" then append mode is used, lines are
Bram Moolenaar46fceaa2016-10-23 21:21:08 +020010386 appended to the file: >
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010387 :call writefile(["foo"], "event.log", "a")
10388 :call writefile(["bar"], "event.log", "a")
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010389<
10390 When {flags} contains "s" then fsync() is called after writing
10391 the file. This flushes the file to disk, if possible. This
10392 takes more time but avoids losing the file if the system
10393 crashes.
Bram Moolenaar74240d32017-12-10 15:26:15 +010010394 When {flags} does not contain "S" or "s" then fsync() is
10395 called if the 'fsync' option is set.
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010396 When {flags} contains "S" then fsync() is not called, even
10397 when 'fsync' is set.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010398
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010399 All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010400 Inserting CR characters needs to be done before passing {list}
10401 to writefile().
10402 An existing file is overwritten, if possible.
10403 When the write fails -1 is returned, otherwise 0. There is an
10404 error message if the file can't be created or when writing
10405 fails.
10406 Also see |readfile()|.
10407 To copy a file byte for byte: >
10408 :let fl = readfile("foo", "b")
10409 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010410
10411
10412xor({expr}, {expr}) *xor()*
10413 Bitwise XOR on the two arguments. The arguments are converted
10414 to a number. A List, Dict or Float argument causes an error.
10415 Example: >
10416 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +010010417<
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010418
Bram Moolenaar071d4272004-06-13 20:20:40 +000010419
10420 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +020010421There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000104221. Features that are only supported when they have been enabled when Vim
10423 was compiled |+feature-list|. Example: >
10424 :if has("cindent")
104252. Features that are only supported when certain conditions have been met.
10426 Example: >
10427 :if has("gui_running")
10428< *has-patch*
Bram Moolenaar2f018892018-05-18 18:12:06 +0200104293. Beyond a certain version or at a certain version and including a specific
10430 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10431 later, or it is version 7.4 and patch 248 was included. Example: >
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010432 :if has("patch-7.4.248")
Bram Moolenaar2f018892018-05-18 18:12:06 +020010433< Note that it's possible for patch 248 to be omitted even though 249 is
10434 included. Only happens when cherry-picking patches.
10435 Note that this form only works for patch 7.4.237 and later, before that
10436 you need to check for the patch and the v:version. Example (checking
10437 version 6.2.148 or later): >
10438 :if v:version > 602 || (v:version == 602 && has("patch148"))
Bram Moolenaar071d4272004-06-13 20:20:40 +000010439
Bram Moolenaard823fa92016-08-12 16:29:27 +020010440Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10441use: `if exists('+shellslash')`
10442
10443
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010444acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010445all_builtin_terms Compiled with all builtin terminals enabled.
10446amiga Amiga version of Vim.
10447arabic Compiled with Arabic support |Arabic|.
10448arp Compiled with ARP support (Amiga).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010449autocmd Compiled with autocommand support. (always true)
Bram Moolenaar91f84f62018-07-29 15:07:52 +020010450autochdir Compiled with support for 'autochdir'
Bram Moolenaare42a6d22017-11-12 19:21:51 +010010451autoservername Automatically enable |clientserver|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010452balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +000010453balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010454beos BeOS version of Vim.
10455browse Compiled with |:browse| support, and browse() will
10456 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +020010457browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010458bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010459builtin_terms Compiled with some builtin terminals.
10460byte_offset Compiled with support for 'o' in 'statusline'
10461cindent Compiled with 'cindent' support.
10462clientserver Compiled with remote invocation support |clientserver|.
10463clipboard Compiled with 'clipboard' support.
10464cmdline_compl Compiled with |cmdline-completion| support.
10465cmdline_hist Compiled with |cmdline-history| support.
10466cmdline_info Compiled with 'showcmd' and 'ruler' support.
10467comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010468compatible Compiled to be very Vi compatible.
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +010010469conpty Platform where |ConPTY| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010470cryptv Compiled with encryption support |encryption|.
10471cscope Compiled with |cscope| support.
Bram Moolenaar314dd792019-02-03 15:27:20 +010010472cursorbind Compiled with |'cursorbind'| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010473debug Compiled with "DEBUG" defined.
10474dialog_con Compiled with console dialog support.
10475dialog_gui Compiled with GUI dialog support.
10476diff Compiled with |vimdiff| and 'diff' support.
10477digraphs Compiled with support for digraphs.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010478directx Compiled with support for DirectX and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010479dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010480ebcdic Compiled on a machine with ebcdic character set.
10481emacs_tags Compiled with support for Emacs tags.
10482eval Compiled with expression evaluation support. Always
10483 true, of course!
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010484ex_extra |+ex_extra| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010485extra_search Compiled with support for |'incsearch'| and
10486 |'hlsearch'|
10487farsi Compiled with Farsi support |farsi|.
10488file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010489filterpipe When 'shelltemp' is off pipes are used for shell
10490 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000010491find_in_path Compiled with support for include file searches
10492 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010493float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010494fname_case Case in file names matters (for Amiga, MS-DOS, and
10495 Windows this is not present).
10496folding Compiled with |folding| support.
10497footer Compiled with GUI footer support. |gui-footer|
10498fork Compiled to use fork()/exec() instead of system().
10499gettext Compiled with message translation |multi-lang|
10500gui Compiled with GUI enabled.
10501gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010502gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010503gui_gtk Compiled with GTK+ GUI (any version).
10504gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +010010505gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010506gui_mac Compiled with Macintosh GUI.
10507gui_motif Compiled with Motif GUI.
10508gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010509gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010510gui_win32 Compiled with MS Windows Win32 GUI.
10511gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010512hangul_input Compiled with Hangul input support. |hangul|
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010513hpux HP-UX version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010514iconv Can use iconv() for conversion.
10515insert_expand Compiled with support for CTRL-X expansion commands in
10516 Insert mode.
10517jumplist Compiled with |jumplist| support.
10518keymap Compiled with 'keymap' support.
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010519lambda Compiled with |lambda| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010520langmap Compiled with 'langmap' support.
10521libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +020010522linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10523 'breakindent' support.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010524linux Linux version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010525lispindent Compiled with support for lisp indenting.
10526listcmds Compiled with commands for the buffer list |:files|
10527 and the argument list |arglist|.
10528localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +020010529lua Compiled with Lua interface |Lua|.
Bram Moolenaard0573012017-10-28 21:11:06 +020010530mac Any Macintosh version of Vim cf. osx
10531macunix Synonym for osxdarwin
Bram Moolenaar071d4272004-06-13 20:20:40 +000010532menu Compiled with support for |:menu|.
10533mksession Compiled with support for |:mksession|.
10534modify_fname Compiled with file name modifiers. |filename-modifiers|
10535mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010536mouse_dec Compiled with support for Dec terminal mouse.
10537mouse_gpm Compiled with support for gpm (Linux console mouse)
Bram Moolenaar4b8366b2019-05-04 17:34:34 +020010538mouse_gpm_enabled GPM mouse is working
Bram Moolenaar071d4272004-06-13 20:20:40 +000010539mouse_netterm Compiled with support for netterm mouse.
10540mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010541mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +020010542mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +010010543mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010544mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010545mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar4c92e752019-02-17 21:18:32 +010010546multi_byte Compiled with support for 'encoding' (always true)
Bram Moolenaar42022d52008-12-09 09:57:49 +000010547multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010548multi_byte_ime Compiled with support for IME input method.
10549multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000010550mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +020010551netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010552netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010553num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010554ole Compiled with OLE automation support for Win32.
Bram Moolenaard0573012017-10-28 21:11:06 +020010555osx Compiled for macOS cf. mac
10556osxdarwin Compiled for macOS, with |mac-darwin-feature|
Bram Moolenaar91c49372016-05-08 09:50:29 +020010557packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010558path_extra Compiled with up/downwards search in 'path' and 'tags'
10559perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +020010560persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010561postscript Compiled with PostScript file printing.
10562printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +000010563profile Compiled with |:profile| support.
Bram Moolenaar84b242c2018-01-28 17:45:49 +010010564python Python 2.x interface available. |has-python|
10565python_compiled Compiled with Python 2.x interface. |has-python|
10566python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10567python3 Python 3.x interface available. |has-python|
10568python3_compiled Compiled with Python 3.x interface. |has-python|
10569python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +010010570pythonx Compiled with |python_x| interface. |has-pythonx|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010571qnx QNX version of Vim.
10572quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +000010573reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010574rightleft Compiled with 'rightleft' support.
10575ruby Compiled with Ruby interface |ruby|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010576scrollbind Compiled with 'scrollbind' support. (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010577showcmd Compiled with 'showcmd' support.
10578signs Compiled with |:sign| support.
10579smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010580spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +000010581startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010582statusline Compiled with support for 'statusline', 'rulerformat'
10583 and special formats of 'titlestring' and 'iconstring'.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010584sun SunOS version of Vim.
Bram Moolenaard09091d2019-01-17 16:07:22 +010010585sun_workshop Support for Sun |workshop| has been removed.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +000010586syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010587syntax_items There are active syntax highlighting items for the
10588 current buffer.
10589system Compiled to use system() instead of fork()/exec().
10590tag_binary Compiled with binary searching in tags files
10591 |tag-binary-search|.
Bram Moolenaar723dd942019-04-04 13:11:03 +020010592tag_old_static Support for old static tags was removed, see
Bram Moolenaar071d4272004-06-13 20:20:40 +000010593 |tag-old-static|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010594tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +020010595termguicolors Compiled with true color in terminal support.
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +020010596terminal Compiled with |terminal| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010597terminfo Compiled with terminfo instead of termcap.
10598termresponse Compiled with support for |t_RV| and |v:termresponse|.
10599textobjects Compiled with support for |text-objects|.
Bram Moolenaar98aefe72018-12-13 22:20:09 +010010600textprop Compiled with support for |text-properties|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010601tgetent Compiled with tgetent support, able to use a termcap
10602 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +010010603timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010604title Compiled with window title support |'title'|.
10605toolbar Compiled with support for |gui-toolbar|.
Bram Moolenaar2cab0e12016-11-24 15:09:07 +010010606ttyin input is a terminal (tty)
10607ttyout output is a terminal (tty)
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010608unix Unix version of Vim. *+unix*
Bram Moolenaar3df01732017-02-17 22:47:16 +010010609unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
Bram Moolenaarac9fb182019-04-27 13:04:13 +020010610user_commands User-defined commands. (always true)
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010010611vcon Win32: Virtual console support is working, can use
10612 'termguicolors'. Also see |+vtp|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010613vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010614 (always true)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010615vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010616 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010617viminfo Compiled with viminfo support.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020010618vimscript-1 Compiled Vim script version 1 support
10619vimscript-2 Compiled Vim script version 2 support
Bram Moolenaar911ead12019-04-21 00:03:35 +020010620vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010621virtualedit Compiled with 'virtualedit' option. (always true)
Bram Moolenaar5b69c222019-01-11 14:50:06 +010010622visual Compiled with Visual mode. (always true)
10623visualextra Compiled with extra Visual mode commands. (always
10624 true) |blockwise-operators|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010625vms VMS version of Vim.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010626vreplace Compiled with |gR| and |gr| commands. (always true)
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010627vtp Compiled for vcon support |+vtp| (check vcon to find
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +010010628 out if it works in the current console).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010629wildignore Compiled with 'wildignore' option.
10630wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010631win16 old version for MS-Windows 3.1 (always false)
Bram Moolenaard58e9292011-02-09 17:07:58 +010010632win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10633 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010634win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010635win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010636win95 Win32 version for MS-Windows 95/98/ME (always false)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010637winaltkeys Compiled with 'winaltkeys' option.
10638windows Compiled with support for more than one window.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010639 (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010640writebackup Compiled with 'writebackup' default on.
10641xfontset Compiled with X fontset support |xfontset|.
10642xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010643xpm Compiled with pixmap support.
10644xpm_w32 Compiled with pixmap support for Win32. (Only for
10645 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010646xsmp Compiled with X session management support.
10647xsmp_interact Compiled with interactive X session management support.
10648xterm_clipboard Compiled with support for xterm clipboard.
10649xterm_save Compiled with support for saving and restoring the
10650 xterm screen.
10651x11 Compiled with X11 support.
10652
10653 *string-match*
10654Matching a pattern in a String
10655
10656A regexp pattern as explained at |pattern| is normally used to find a match in
10657the buffer lines. When a pattern is used to find a match in a String, almost
10658everything works in the same way. The difference is that a String is handled
10659like it is one line. When it contains a "\n" character, this is not seen as a
10660line break for the pattern. It can be matched with a "\n" in the pattern, or
10661with ".". Example: >
10662 :let a = "aaaa\nxxxx"
10663 :echo matchstr(a, "..\n..")
10664 aa
10665 xx
10666 :echo matchstr(a, "a.x")
10667 a
10668 x
10669
10670Don't forget that "^" will only match at the first character of the String and
10671"$" at the last character of the string. They don't match after or before a
10672"\n".
10673
10674==============================================================================
106755. Defining functions *user-functions*
10676
10677New functions can be defined. These can be called just like builtin
10678functions. The function executes a sequence of Ex commands. Normal mode
10679commands can be executed with the |:normal| command.
10680
10681The function name must start with an uppercase letter, to avoid confusion with
10682builtin functions. To prevent from using the same name in different scripts
10683avoid obvious, short names. A good habit is to start the function name with
10684the name of the script, e.g., "HTMLcolor()".
10685
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010686It's also possible to use curly braces, see |curly-braces-names|. And the
10687|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010688
10689 *local-function*
10690A function local to a script must start with "s:". A local script function
10691can only be called from within the script and from functions, user commands
10692and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +000010693function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +000010694instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010695There are only script-local functions, no buffer-local or window-local
10696functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010697
10698 *:fu* *:function* *E128* *E129* *E123*
10699:fu[nction] List all functions and their arguments.
10700
10701:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010702 {name} can also be a |Dictionary| entry that is a
10703 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010704 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010705
10706:fu[nction] /{pattern} List functions with a name matching {pattern}.
10707 Example that lists all functions ending with "File": >
10708 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010709<
10710 *:function-verbose*
10711When 'verbose' is non-zero, listing a function will also display where it was
10712last defined. Example: >
10713
10714 :verbose function SetFileTypeSH
10715 function SetFileTypeSH(name)
10716 Last set from /usr/share/vim/vim-7.0/filetype.vim
10717<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +000010718See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010719
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010720 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010721:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +010010722 Define a new function by the name {name}. The body of
10723 the function follows in the next lines, until the
10724 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010725
Bram Moolenaar01164a62017-11-02 22:58:42 +010010726 The name must be made of alphanumeric characters and
10727 '_', and must start with a capital or "s:" (see
10728 above). Note that using "b:" or "g:" is not allowed.
10729 (since patch 7.4.260 E884 is given if the function
10730 name has a colon in the name, e.g. for "foo:bar()".
10731 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010732
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010733 {name} can also be a |Dictionary| entry that is a
10734 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010735 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +020010736< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010737 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +020010738 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010739 result is a |Funcref| to a numbered function. The
10740 function can only be used with a |Funcref| and will be
10741 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010742 *E127* *E122*
10743 When a function by this name already exists and [!] is
Bram Moolenaarded5f1b2018-11-10 17:33:29 +010010744 not used an error message is given. There is one
10745 exception: When sourcing a script again, a function
10746 that was previously defined in that script will be
10747 silently replaced.
10748 When [!] is used, an existing function is silently
10749 replaced. Unless it is currently being executed, that
10750 is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010751 NOTE: Use ! wisely. If used without care it can cause
10752 an existing function to be replaced unexpectedly,
10753 which is hard to debug.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010754
10755 For the {arguments} see |function-argument|.
10756
Bram Moolenaar8d043172014-01-23 14:24:41 +010010757 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010758 When the [range] argument is added, the function is
10759 expected to take care of a range itself. The range is
10760 passed as "a:firstline" and "a:lastline". If [range]
10761 is excluded, ":{range}call" will call the function for
10762 each line in the range, with the cursor on the start
10763 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +010010764 The cursor is still moved to the first line of the
10765 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010766 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010767 When the [abort] argument is added, the function will
10768 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010769 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010770 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +020010771 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010772 local variable "self" will then be set to the
10773 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010774 *:func-closure* *E932*
10775 When the [closure] argument is added, the function
10776 can access variables and arguments from the outer
10777 scope. This is usually called a closure. In this
10778 example Bar() uses "x" from the scope of Foo(). It
10779 remains referenced even after Foo() returns: >
10780 :function! Foo()
10781 : let x = 0
10782 : function! Bar() closure
10783 : let x += 1
10784 : return x
10785 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +020010786 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010787 :endfunction
10788
10789 :let F = Foo()
10790 :echo F()
10791< 1 >
10792 :echo F()
10793< 2 >
10794 :echo F()
10795< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +000010796
Bram Moolenaar446cb832008-06-24 21:56:24 +000010797 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +000010798 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +000010799 will not be changed by the function. This also
10800 implies that the effect of |:nohlsearch| is undone
10801 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +000010802
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010803 *:endf* *:endfunction* *E126* *E193* *W22*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010804:endf[unction] [argument]
10805 The end of a function definition. Best is to put it
10806 on a line by its own, without [argument].
10807
10808 [argument] can be:
10809 | command command to execute next
10810 \n command command to execute next
10811 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010812 anything else ignored, warning given when
10813 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +020010814 The support for a following command was added in Vim
10815 8.0.0654, before that any argument was silently
10816 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010817
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010818 To be able to define a function inside an `:execute`
10819 command, use line breaks instead of |:bar|: >
10820 :exe "func Foo()\necho 'foo'\nendfunc"
10821<
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010822 *:delf* *:delfunction* *E130* *E131* *E933*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010823:delf[unction][!] {name}
10824 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010825 {name} can also be a |Dictionary| entry that is a
10826 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010827 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +020010828< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010829 function is deleted if there are no more references to
10830 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +020010831 With the ! there is no error if the function does not
10832 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010833 *:retu* *:return* *E133*
10834:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
10835 evaluated and returned as the result of the function.
10836 If "[expr]" is not given, the number 0 is returned.
10837 When a function ends without an explicit ":return",
10838 the number 0 is returned.
10839 Note that there is no check for unreachable lines,
10840 thus there is no warning if commands follow ":return".
10841
10842 If the ":return" is used after a |:try| but before the
10843 matching |:finally| (if present), the commands
10844 following the ":finally" up to the matching |:endtry|
10845 are executed first. This process applies to all
10846 nested ":try"s inside the function. The function
10847 returns at the outermost ":endtry".
10848
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010849 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010850An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010851be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010852 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010853Up to 20 arguments can be given, separated by commas. After the named
10854arguments an argument "..." can be specified, which means that more arguments
10855may optionally be following. In the function the extra arguments can be used
10856as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010857can be 0). "a:000" is set to a |List| that contains these arguments. Note
10858that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000010859 *E742*
10860The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +020010861However, if a composite type is used, such as |List| or |Dictionary| , you can
10862change their contents. Thus you can pass a |List| to a function and have the
10863function add an item to it. If you want to make sure the function cannot
10864change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010865
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010866When not using "...", the number of arguments in a function call must be equal
10867to the number of named arguments. When using "...", the number of arguments
10868may be larger.
10869
10870It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +010010871still supply the () then.
10872
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010873It is allowed to define another function inside a function body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010874
10875 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +020010876Inside a function local variables can be used. These will disappear when the
10877function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +000010878
10879Example: >
10880 :function Table(title, ...)
10881 : echohl Title
10882 : echo a:title
10883 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +000010884 : echo a:0 . " items:"
10885 : for s in a:000
10886 : echon ' ' . s
10887 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +000010888 :endfunction
10889
10890This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +000010891 call Table("Table", "line1", "line2")
10892 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +000010893
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010894To return more than one value, return a |List|: >
10895 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010896 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010897 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +000010898 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010899 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +000010900 :endfunction
10901
10902This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010903 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010904 :if success == "ok"
10905 : echo div
10906 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010907<
Bram Moolenaar39f05632006-03-19 22:15:26 +000010908 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010909:[range]cal[l] {name}([arguments])
10910 Call a function. The name of the function and its arguments
10911 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010912 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010913 Without a range and for functions that accept a range, the
10914 function is called once. When a range is given the cursor is
10915 positioned at the start of the first line before executing the
10916 function.
10917 When a range is given and the function doesn't handle it
10918 itself, the function is executed for each line in the range,
10919 with the cursor in the first column of that line. The cursor
10920 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +020010921 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +000010922 this works:
10923 *function-range-example* >
10924 :function Mynumber(arg)
10925 : echo line(".") . " " . a:arg
10926 :endfunction
10927 :1,5call Mynumber(getline("."))
10928<
10929 The "a:firstline" and "a:lastline" are defined anyway, they
10930 can be used to do something different at the start or end of
10931 the range.
10932
10933 Example of a function that handles the range itself: >
10934
10935 :function Cont() range
10936 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
10937 :endfunction
10938 :4,8call Cont()
10939<
10940 This function inserts the continuation character "\" in front
10941 of all the lines in the range, except the first one.
10942
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010943 When the function returns a composite value it can be further
10944 dereferenced, but the range will not be used then. Example: >
10945 :4,8call GetDict().method()
10946< Here GetDict() gets the range but method() does not.
10947
Bram Moolenaar071d4272004-06-13 20:20:40 +000010948 *E132*
10949The recursiveness of user functions is restricted with the |'maxfuncdepth'|
10950option.
10951
Bram Moolenaar7c626922005-02-07 22:01:03 +000010952
10953AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000010954 *autoload-functions*
10955When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +000010956only when they are used. There are two methods: with an autocommand and with
10957the "autoload" directory in 'runtimepath'.
10958
10959
10960Using an autocommand ~
10961
Bram Moolenaar05159a02005-02-26 23:04:13 +000010962This is introduced in the user manual, section |41.14|.
10963
Bram Moolenaar7c626922005-02-07 22:01:03 +000010964The autocommand is useful if you have a plugin that is a long Vim script file.
10965You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010966That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +000010967again, setting a variable to skip the |:finish| command.
10968
10969Use the FuncUndefined autocommand event with a pattern that matches the
10970function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010971
10972 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
10973
10974The file "~/vim/bufnetfuncs.vim" should then define functions that start with
10975"BufNet". Also see |FuncUndefined|.
10976
Bram Moolenaar7c626922005-02-07 22:01:03 +000010977
10978Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010979 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +000010980This is introduced in the user manual, section |41.15|.
10981
Bram Moolenaar7c626922005-02-07 22:01:03 +000010982Using a script in the "autoload" directory is simpler, but requires using
10983exactly the right file name. A function that can be autoloaded has a name
10984like this: >
10985
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010986 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000010987
10988When such a function is called, and it is not defined yet, Vim will search the
10989"autoload" directories in 'runtimepath' for a script file called
10990"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
10991then define the function like this: >
10992
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010993 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000010994 echo "Done!"
10995 endfunction
10996
Bram Moolenaar60a795a2005-09-16 21:55:43 +000010997The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +000010998exactly, and the defined function must have the name exactly as it will be
10999called.
11000
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011001It is possible to use subdirectories. Every # in the function name works like
11002a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +000011003
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011004 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +000011005
11006Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
11007
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011008This also works when reading a variable that has not been set yet: >
11009
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011010 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011011
Bram Moolenaara5792f52005-11-23 21:25:05 +000011012However, when the autoload script was already loaded it won't be loaded again
11013for an unknown variable.
11014
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011015When assigning a value to such a variable nothing special happens. This can
11016be used to pass settings to the autoload script before it's loaded: >
11017
Bram Moolenaara7fc0102005-05-18 22:17:12 +000011018 :let foo#bar#toggle = 1
11019 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011020
Bram Moolenaar4399ef42005-02-12 14:29:27 +000011021Note that when you make a mistake and call a function that is supposed to be
11022defined in an autoload script, but the script doesn't actually define the
11023function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011024And you will get an error message every time.
11025
11026Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +000011027other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011028Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +000011029
Bram Moolenaar433f7c82006-03-21 21:29:36 +000011030Hint: If you distribute a bunch of scripts you can pack them together with the
11031|vimball| utility. Also read the user manual |distribute-script|.
11032
Bram Moolenaar071d4272004-06-13 20:20:40 +000011033==============================================================================
110346. Curly braces names *curly-braces-names*
11035
Bram Moolenaar84f72352012-03-11 15:57:40 +010011036In most places where you can use a variable, you can use a "curly braces name"
11037variable. This is a regular variable name with one or more expressions
11038wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011039 my_{adjective}_variable
11040
11041When Vim encounters this, it evaluates the expression inside the braces, puts
11042that in place of the expression, and re-interprets the whole as a variable
11043name. So in the above example, if the variable "adjective" was set to
11044"noisy", then the reference would be to "my_noisy_variable", whereas if
11045"adjective" was set to "quiet", then it would be to "my_quiet_variable".
11046
11047One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +020011048value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011049 echo my_{&background}_message
11050
11051would output the contents of "my_dark_message" or "my_light_message" depending
11052on the current value of 'background'.
11053
11054You can use multiple brace pairs: >
11055 echo my_{adverb}_{adjective}_message
11056..or even nest them: >
11057 echo my_{ad{end_of_word}}_message
11058where "end_of_word" is either "verb" or "jective".
11059
11060However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000011061variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011062 :let foo='a + b'
11063 :echo c{foo}d
11064.. since the result of expansion is "ca + bd", which is not a variable name.
11065
11066 *curly-braces-function-names*
11067You can call and define functions by an evaluated name in a similar way.
11068Example: >
11069 :let func_end='whizz'
11070 :call my_func_{func_end}(parameter)
11071
11072This would call the function "my_func_whizz(parameter)".
11073
Bram Moolenaar84f72352012-03-11 15:57:40 +010011074This does NOT work: >
11075 :let i = 3
11076 :let @{i} = '' " error
11077 :echo @{i} " error
11078
Bram Moolenaar071d4272004-06-13 20:20:40 +000011079==============================================================================
110807. Commands *expression-commands*
11081
11082:let {var-name} = {expr1} *:let* *E18*
11083 Set internal variable {var-name} to the result of the
11084 expression {expr1}. The variable will get the type
11085 from the {expr}. If {var-name} didn't exist yet, it
11086 is created.
11087
Bram Moolenaar13065c42005-01-08 16:08:21 +000011088:let {var-name}[{idx}] = {expr1} *E689*
11089 Set a list item to the result of the expression
11090 {expr1}. {var-name} must refer to a list and {idx}
11091 must be a valid index in that list. For nested list
11092 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011093 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020011094 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +000011095 can do that like this: >
11096 :let var = var[0:2] . 'X' . var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010011097< When {var-name} is a |Blob| then {idx} can be the
11098 length of the blob, in which case one byte is
11099 appended.
11100
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011101 *E711* *E719*
11102:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011103 Set a sequence of items in a |List| to the result of
11104 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011105 correct number of items.
11106 {idx1} can be omitted, zero is used instead.
11107 {idx2} can be omitted, meaning the end of the list.
11108 When the selected range of items is partly past the
11109 end of the list, items will be added.
11110
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011111 *:let+=* *:let-=* *:letstar=*
11112 *:let/=* *:let%=* *:let.=* *:let..=* *E734* *E985*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011113:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
11114:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +010011115:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
11116:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
11117:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011118:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011119:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011120 These fail if {var} was not set yet and when the type
11121 of {var} and {expr1} don't fit the operator.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011122 `.=` is not supported with Vim script version 2 and
11123 later, see |vimscript-version|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011124
11125
Bram Moolenaar071d4272004-06-13 20:20:40 +000011126:let ${env-name} = {expr1} *:let-environment* *:let-$*
11127 Set environment variable {env-name} to the result of
11128 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011129:let ${env-name} .= {expr1}
11130 Append {expr1} to the environment variable {env-name}.
11131 If the environment variable didn't exist yet this
11132 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +000011133
11134:let @{reg-name} = {expr1} *:let-register* *:let-@*
11135 Write the result of the expression {expr1} in register
11136 {reg-name}. {reg-name} must be a single letter, and
11137 must be the name of a writable register (see
11138 |registers|). "@@" can be used for the unnamed
11139 register, "@/" for the search pattern.
11140 If the result of {expr1} ends in a <CR> or <NL>, the
11141 register will be linewise, otherwise it will be set to
11142 characterwise.
11143 This can be used to clear the last search pattern: >
11144 :let @/ = ""
11145< This is different from searching for an empty string,
11146 that would match everywhere.
11147
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011148:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +020011149 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011150 register was empty it's like setting it to {expr1}.
11151
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011152:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011153 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011154 expression {expr1}. A String or Number value is
11155 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011156 For an option local to a window or buffer the effect
11157 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +000011158 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011159 Example: >
11160 :let &path = &path . ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +010011161< This also works for terminal codes in the form t_xx.
11162 But only for alphanumerical names. Example: >
11163 :let &t_k1 = "\<Esc>[234;"
11164< When the code does not exist yet it will be created as
11165 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011166
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011167:let &{option-name} .= {expr1}
11168 For a string option: Append {expr1} to the value.
11169 Does not insert a comma like |:set+=|.
11170
11171:let &{option-name} += {expr1}
11172:let &{option-name} -= {expr1}
11173 For a number or boolean option: Add or subtract
11174 {expr1}.
11175
Bram Moolenaar071d4272004-06-13 20:20:40 +000011176:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011177:let &l:{option-name} .= {expr1}
11178:let &l:{option-name} += {expr1}
11179:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000011180 Like above, but only set the local value of an option
11181 (if there is one). Works like |:setlocal|.
11182
11183:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011184:let &g:{option-name} .= {expr1}
11185:let &g:{option-name} += {expr1}
11186:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000011187 Like above, but only set the global value of an option
11188 (if there is one). Works like |:setglobal|.
11189
Bram Moolenaar13065c42005-01-08 16:08:21 +000011190:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011191 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011192 the list is assigned to {name1}, the second item to
11193 {name2}, etc.
11194 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011195 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011196 Each name can be one of the items of the ":let"
11197 command as mentioned above.
11198 Example: >
11199 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011200< Detail: {expr1} is evaluated first, then the
11201 assignments are done in sequence. This matters if
11202 {name2} depends on {name1}. Example: >
11203 :let x = [0, 1]
11204 :let i = 0
11205 :let [i, x[i]] = [1, 2]
11206 :echo x
11207< The result is [0, 2].
11208
11209:let [{name1}, {name2}, ...] .= {expr1}
11210:let [{name1}, {name2}, ...] += {expr1}
11211:let [{name1}, {name2}, ...] -= {expr1}
11212 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011213 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011214
11215:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011216 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011217 items than there are names. A list of the remaining
11218 items is assigned to {lastname}. If there are no
11219 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000011220 Example: >
11221 :let [a, b; rest] = ["aval", "bval", 3, 4]
11222<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011223:let [{name}, ..., ; {lastname}] .= {expr1}
11224:let [{name}, ..., ; {lastname}] += {expr1}
11225:let [{name}, ..., ; {lastname}] -= {expr1}
11226 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011227 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +020011228
11229 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +020011230:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000011231 variable names may be given. Special names recognized
11232 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +000011233 g: global variables
11234 b: local buffer variables
11235 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011236 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +000011237 s: script-local variables
11238 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000011239 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011240
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000011241:let List the values of all variables. The type of the
11242 variable is indicated before the value:
11243 <nothing> String
11244 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000011245 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +000011246
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011247
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011248:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011249 Remove the internal variable {name}. Several variable
11250 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011251 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011252 With [!] no error message is given for non-existing
11253 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011254 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000011255 :unlet list[3] " remove fourth item
11256 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011257< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000011258 :unlet dict['two']
11259 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +000011260< This is especially useful to clean up used global
11261 variables and script-local variables (these are not
11262 deleted when the script ends). Function-local
11263 variables are automatically deleted when the function
11264 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011265
Bram Moolenaar137374f2018-05-13 15:59:50 +020011266:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
11267 Remove environment variable {env-name}.
11268 Can mix {name} and ${env-name} in one :unlet command.
11269 No error message is given for a non-existing
11270 variable, also without !.
11271 If the system does not support deleting an environment
11272 variable, it is made emtpy.
11273
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011274:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
11275 Lock the internal variable {name}. Locking means that
11276 it can no longer be changed (until it is unlocked).
11277 A locked variable can be deleted: >
11278 :lockvar v
11279 :let v = 'asdf' " fails!
11280 :unlet v
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011281< *E741* *E940*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011282 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011283 error message: "E741: Value is locked: {name}".
11284 If you try to lock or unlock a built-in variable you
11285 get an error message: "E940: Cannot lock or unlock
11286 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011287
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011288 [depth] is relevant when locking a |List| or
11289 |Dictionary|. It specifies how deep the locking goes:
11290 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011291 cannot add or remove items, but can
11292 still change their values.
11293 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011294 the items. If an item is a |List| or
11295 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011296 items, but can still change the
11297 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011298 3 Like 2 but for the |List| /
11299 |Dictionary| in the |List| /
11300 |Dictionary|, one level deeper.
11301 The default [depth] is 2, thus when {name} is a |List|
11302 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011303 *E743*
11304 For unlimited depth use [!] and omit [depth].
11305 However, there is a maximum depth of 100 to catch
11306 loops.
11307
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011308 Note that when two variables refer to the same |List|
11309 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011310 locked when used through the other variable.
11311 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011312 :let l = [0, 1, 2, 3]
11313 :let cl = l
11314 :lockvar l
11315 :let cl[1] = 99 " won't work!
11316< You may want to make a copy of a list to avoid this.
11317 See |deepcopy()|.
11318
11319
11320:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
11321 Unlock the internal variable {name}. Does the
11322 opposite of |:lockvar|.
11323
11324
Bram Moolenaar071d4272004-06-13 20:20:40 +000011325:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
11326:en[dif] Execute the commands until the next matching ":else"
11327 or ":endif" if {expr1} evaluates to non-zero.
11328
11329 From Vim version 4.5 until 5.0, every Ex command in
11330 between the ":if" and ":endif" is ignored. These two
11331 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +010011332 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +000011333 that any ":else" or ":elseif" was ignored, the "else"
11334 part was not executed either.
11335
11336 You can use this to remain compatible with older
11337 versions: >
11338 :if version >= 500
11339 : version-5-specific-commands
11340 :endif
11341< The commands still need to be parsed to find the
11342 "endif". Sometimes an older Vim has a problem with a
11343 new command. For example, ":silent" is recognized as
11344 a ":substitute" command. In that case ":execute" can
11345 avoid problems: >
11346 :if version >= 600
11347 : execute "silent 1,$delete"
11348 :endif
11349<
11350 NOTE: The ":append" and ":insert" commands don't work
11351 properly in between ":if" and ":endif".
11352
11353 *:else* *:el* *E581* *E583*
11354:el[se] Execute the commands until the next matching ":else"
11355 or ":endif" if they previously were not being
11356 executed.
11357
11358 *:elseif* *:elsei* *E582* *E584*
11359:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
11360 is no extra ":endif".
11361
11362:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011363 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011364:endw[hile] Repeat the commands between ":while" and ":endwhile",
11365 as long as {expr1} evaluates to non-zero.
11366 When an error is detected from a command inside the
11367 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +000011368 Example: >
11369 :let lnum = 1
11370 :while lnum <= line("$")
11371 :call FixLine(lnum)
11372 :let lnum = lnum + 1
11373 :endwhile
11374<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011375 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +000011376 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011377
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011378:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +000011379:endfo[r] *:endfo* *:endfor*
11380 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011381 each item in {object}. {object} can be a |List| or
11382 a |Blob|. Variable {var} is set to the value of each
11383 item. When an error is detected for a command inside
11384 the loop, execution continues after the "endfor".
11385 Changing {object} inside the loop affects what items
11386 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +000011387 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011388<
11389 When {object} is a |List| and not making a copy, Vim
11390 stores a reference to the next item in the |List|
11391 before executing the commands with the current item.
11392 Thus the current item can be removed without effect.
11393 Removing any later item means it will not be found.
11394 Thus the following example works (an inefficient way
11395 to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011396 for item in mylist
11397 call remove(mylist, 0)
11398 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011399< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011400 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +000011401
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011402 When {object} is a |Blob|, Vim always makes a copy to
11403 iterate over. Unlike with |List|, modifying the
11404 |Blob| does not affect the iteration.
11405
Bram Moolenaar12805862005-01-05 22:16:17 +000011406:for [{var1}, {var2}, ...] in {listlist}
11407:endfo[r]
11408 Like ":for" above, but each item in {listlist} must be
11409 a list, of which each item is assigned to {var1},
11410 {var2}, etc. Example: >
11411 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
11412 :echo getline(lnum)[col]
11413 :endfor
11414<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011415 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +000011416:con[tinue] When used inside a ":while" or ":for" loop, jumps back
11417 to the start of the loop.
11418 If it is used after a |:try| inside the loop but
11419 before the matching |:finally| (if present), the
11420 commands following the ":finally" up to the matching
11421 |:endtry| are executed first. This process applies to
11422 all nested ":try"s inside the loop. The outermost
11423 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011424
11425 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +000011426:brea[k] When used inside a ":while" or ":for" loop, skips to
11427 the command after the matching ":endwhile" or
11428 ":endfor".
11429 If it is used after a |:try| inside the loop but
11430 before the matching |:finally| (if present), the
11431 commands following the ":finally" up to the matching
11432 |:endtry| are executed first. This process applies to
11433 all nested ":try"s inside the loop. The outermost
11434 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011435
11436:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
11437:endt[ry] Change the error handling for the commands between
11438 ":try" and ":endtry" including everything being
11439 executed across ":source" commands, function calls,
11440 or autocommand invocations.
11441
11442 When an error or interrupt is detected and there is
11443 a |:finally| command following, execution continues
11444 after the ":finally". Otherwise, or when the
11445 ":endtry" is reached thereafter, the next
11446 (dynamically) surrounding ":try" is checked for
11447 a corresponding ":finally" etc. Then the script
11448 processing is terminated. (Whether a function
11449 definition has an "abort" argument does not matter.)
11450 Example: >
11451 :try | edit too much | finally | echo "cleanup" | endtry
11452 :echo "impossible" " not reached, script terminated above
11453<
11454 Moreover, an error or interrupt (dynamically) inside
11455 ":try" and ":endtry" is converted to an exception. It
11456 can be caught as if it were thrown by a |:throw|
11457 command (see |:catch|). In this case, the script
11458 processing is not terminated.
11459
11460 The value "Vim:Interrupt" is used for an interrupt
11461 exception. An error in a Vim command is converted
11462 to a value of the form "Vim({command}):{errmsg}",
11463 other errors are converted to a value of the form
11464 "Vim:{errmsg}". {command} is the full command name,
11465 and {errmsg} is the message that is displayed if the
11466 error exception is not caught, always beginning with
11467 the error number.
11468 Examples: >
11469 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
11470 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
11471<
11472 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011473:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011474 |:finally|, or |:endtry| that belongs to the same
11475 |:try| as the ":catch" are executed when an exception
11476 matching {pattern} is being thrown and has not yet
11477 been caught by a previous ":catch". Otherwise, these
11478 commands are skipped.
11479 When {pattern} is omitted all errors are caught.
11480 Examples: >
Bram Moolenaar647e24b2019-03-17 16:39:46 +010011481 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
11482 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
11483 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
11484 :catch /^Vim(write):/ " catch all errors in :write
11485 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
11486 :catch /my-exception/ " catch user exception
11487 :catch /.*/ " catch everything
11488 :catch " same as /.*/
Bram Moolenaar071d4272004-06-13 20:20:40 +000011489<
11490 Another character can be used instead of / around the
11491 {pattern}, so long as it does not have a special
11492 meaning (e.g., '|' or '"') and doesn't occur inside
11493 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020011494 Information about the exception is available in
11495 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011496 NOTE: It is not reliable to ":catch" the TEXT of
11497 an error message because it may vary in different
11498 locales.
11499
11500 *:fina* *:finally* *E606* *E607*
11501:fina[lly] The following commands until the matching |:endtry|
11502 are executed whenever the part between the matching
11503 |:try| and the ":finally" is left: either by falling
11504 through to the ":finally" or by a |:continue|,
11505 |:break|, |:finish|, or |:return|, or by an error or
11506 interrupt or exception (see |:throw|).
11507
11508 *:th* *:throw* *E608*
11509:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
11510 If the ":throw" is used after a |:try| but before the
11511 first corresponding |:catch|, commands are skipped
11512 until the first ":catch" matching {expr1} is reached.
11513 If there is no such ":catch" or if the ":throw" is
11514 used after a ":catch" but before the |:finally|, the
11515 commands following the ":finally" (if present) up to
11516 the matching |:endtry| are executed. If the ":throw"
11517 is after the ":finally", commands up to the ":endtry"
11518 are skipped. At the ":endtry", this process applies
11519 again for the next dynamically surrounding ":try"
11520 (which may be found in a calling function or sourcing
11521 script), until a matching ":catch" has been found.
11522 If the exception is not caught, the command processing
11523 is terminated.
11524 Example: >
11525 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +010011526< Note that "catch" may need to be on a separate line
11527 for when an error causes the parsing to skip the whole
11528 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011529
11530 *:ec* *:echo*
11531:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
11532 first {expr1} starts on a new line.
11533 Also see |:comment|.
11534 Use "\n" to start a new line. Use "\r" to move the
11535 cursor to the first column.
11536 Uses the highlighting set by the |:echohl| command.
11537 Cannot be followed by a comment.
11538 Example: >
11539 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011540< *:echo-redraw*
11541 A later redraw may make the message disappear again.
11542 And since Vim mostly postpones redrawing until it's
11543 finished with a sequence of commands this happens
11544 quite often. To avoid that a command from before the
11545 ":echo" causes a redraw afterwards (redraws are often
11546 postponed until you type something), force a redraw
11547 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011548 :new | redraw | echo "there is a new window"
11549<
11550 *:echon*
11551:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
11552 |:comment|.
11553 Uses the highlighting set by the |:echohl| command.
11554 Cannot be followed by a comment.
11555 Example: >
11556 :echon "the value of 'shell' is " &shell
11557<
11558 Note the difference between using ":echo", which is a
11559 Vim command, and ":!echo", which is an external shell
11560 command: >
11561 :!echo % --> filename
11562< The arguments of ":!" are expanded, see |:_%|. >
11563 :!echo "%" --> filename or "filename"
11564< Like the previous example. Whether you see the double
11565 quotes or not depends on your 'shell'. >
11566 :echo % --> nothing
11567< The '%' is an illegal character in an expression. >
11568 :echo "%" --> %
11569< This just echoes the '%' character. >
11570 :echo expand("%") --> filename
11571< This calls the expand() function to expand the '%'.
11572
11573 *:echoh* *:echohl*
11574:echoh[l] {name} Use the highlight group {name} for the following
11575 |:echo|, |:echon| and |:echomsg| commands. Also used
11576 for the |input()| prompt. Example: >
11577 :echohl WarningMsg | echo "Don't panic!" | echohl None
11578< Don't forget to set the group back to "None",
11579 otherwise all following echo's will be highlighted.
11580
11581 *:echom* *:echomsg*
11582:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
11583 message in the |message-history|.
11584 Spaces are placed between the arguments as with the
11585 |:echo| command. But unprintable characters are
11586 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011587 The parsing works slightly different from |:echo|,
11588 more like |:execute|. All the expressions are first
11589 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011590 If expressions does not evaluate to a Number or
11591 String, string() is used to turn it into a string.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011592 Uses the highlighting set by the |:echohl| command.
11593 Example: >
11594 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011595< See |:echo-redraw| to avoid the message disappearing
11596 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011597 *:echoe* *:echoerr*
11598:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
11599 message in the |message-history|. When used in a
11600 script or function the line number will be added.
11601 Spaces are placed between the arguments as with the
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011602 |:echomsg| command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011603 the message is raised as an error exception instead
11604 (see |try-echoerr|).
11605 Example: >
11606 :echoerr "This script just failed!"
11607< If you just want a highlighted message use |:echohl|.
11608 And to get a beep: >
11609 :exe "normal \<Esc>"
11610<
11611 *:exe* *:execute*
11612:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011613 of {expr1} as an Ex command.
11614 Multiple arguments are concatenated, with a space in
11615 between. To avoid the extra space use the "."
11616 operator to concatenate strings into one argument.
11617 {expr1} is used as the processed command, command line
11618 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011619 Cannot be followed by a comment.
11620 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011621 :execute "buffer" nextbuf
11622 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +000011623<
11624 ":execute" can be used to append a command to commands
11625 that don't accept a '|'. Example: >
11626 :execute '!ls' | echo "theend"
11627
11628< ":execute" is also a nice way to avoid having to type
11629 control characters in a Vim script for a ":normal"
11630 command: >
11631 :execute "normal ixxx\<Esc>"
11632< This has an <Esc> character, see |expr-string|.
11633
Bram Moolenaar446cb832008-06-24 21:56:24 +000011634 Be careful to correctly escape special characters in
11635 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +000011636 for Vim commands, |shellescape()| for |:!| commands.
11637 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +000011638 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +010011639 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +000011640<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011641 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010011642 starting or ending "if", "while" and "for" does not
11643 always work, because when commands are skipped the
11644 ":execute" is not evaluated and Vim loses track of
11645 where blocks start and end. Also "break" and
11646 "continue" should not be inside ":execute".
11647 This example does not work, because the ":execute" is
11648 not evaluated and Vim does not see the "while", and
11649 gives an error for finding an ":endwhile": >
11650 :if 0
11651 : execute 'while i > 5'
11652 : echo "test"
11653 : endwhile
11654 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +000011655<
11656 It is allowed to have a "while" or "if" command
11657 completely in the executed string: >
11658 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
11659<
11660
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011661 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011662 ":execute", ":echo" and ":echon" cannot be followed by
11663 a comment directly, because they see the '"' as the
11664 start of a string. But, you can use '|' followed by a
11665 comment. Example: >
11666 :echo "foo" | "this is a comment
11667
11668==============================================================================
116698. Exception handling *exception-handling*
11670
11671The Vim script language comprises an exception handling feature. This section
11672explains how it can be used in a Vim script.
11673
11674Exceptions may be raised by Vim on an error or on interrupt, see
11675|catch-errors| and |catch-interrupt|. You can also explicitly throw an
11676exception by using the ":throw" command, see |throw-catch|.
11677
11678
11679TRY CONDITIONALS *try-conditionals*
11680
11681Exceptions can be caught or can cause cleanup code to be executed. You can
11682use a try conditional to specify catch clauses (that catch exceptions) and/or
11683a finally clause (to be executed for cleanup).
11684 A try conditional begins with a |:try| command and ends at the matching
11685|:endtry| command. In between, you can use a |:catch| command to start
11686a catch clause, or a |:finally| command to start a finally clause. There may
11687be none or multiple catch clauses, but there is at most one finally clause,
11688which must not be followed by any catch clauses. The lines before the catch
11689clauses and the finally clause is called a try block. >
11690
11691 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +000011692 : ...
11693 : ... TRY BLOCK
11694 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011695 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011696 : ...
11697 : ... CATCH CLAUSE
11698 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011699 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011700 : ...
11701 : ... CATCH CLAUSE
11702 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011703 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +000011704 : ...
11705 : ... FINALLY CLAUSE
11706 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011707 :endtry
11708
11709The try conditional allows to watch code for exceptions and to take the
11710appropriate actions. Exceptions from the try block may be caught. Exceptions
11711from the try block and also the catch clauses may cause cleanup actions.
11712 When no exception is thrown during execution of the try block, the control
11713is transferred to the finally clause, if present. After its execution, the
11714script continues with the line following the ":endtry".
11715 When an exception occurs during execution of the try block, the remaining
11716lines in the try block are skipped. The exception is matched against the
11717patterns specified as arguments to the ":catch" commands. The catch clause
11718after the first matching ":catch" is taken, other catch clauses are not
11719executed. The catch clause ends when the next ":catch", ":finally", or
11720":endtry" command is reached - whatever is first. Then, the finally clause
11721(if present) is executed. When the ":endtry" is reached, the script execution
11722continues in the following line as usual.
11723 When an exception that does not match any of the patterns specified by the
11724":catch" commands is thrown in the try block, the exception is not caught by
11725that try conditional and none of the catch clauses is executed. Only the
11726finally clause, if present, is taken. The exception pends during execution of
11727the finally clause. It is resumed at the ":endtry", so that commands after
11728the ":endtry" are not executed and the exception might be caught elsewhere,
11729see |try-nesting|.
11730 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +020011731remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +000011732not matched against the patterns in any of the ":catch" commands of the same
11733try conditional and none of its catch clauses is taken. If there is, however,
11734a finally clause, it is executed, and the exception pends during its
11735execution. The commands following the ":endtry" are not executed. The new
11736exception might, however, be caught elsewhere, see |try-nesting|.
11737 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +020011738thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000011739clause has been taken because of an exception from the try block or one of the
11740catch clauses, the original (pending) exception is discarded. The commands
11741following the ":endtry" are not executed, and the exception from the finally
11742clause is propagated and can be caught elsewhere, see |try-nesting|.
11743
11744The finally clause is also executed, when a ":break" or ":continue" for
11745a ":while" loop enclosing the complete try conditional is executed from the
11746try block or a catch clause. Or when a ":return" or ":finish" is executed
11747from the try block or a catch clause of a try conditional in a function or
11748sourced script, respectively. The ":break", ":continue", ":return", or
11749":finish" pends during execution of the finally clause and is resumed when the
11750":endtry" is reached. It is, however, discarded when an exception is thrown
11751from the finally clause.
11752 When a ":break" or ":continue" for a ":while" loop enclosing the complete
11753try conditional or when a ":return" or ":finish" is encountered in the finally
11754clause, the rest of the finally clause is skipped, and the ":break",
11755":continue", ":return" or ":finish" is executed as usual. If the finally
11756clause has been taken because of an exception or an earlier ":break",
11757":continue", ":return", or ":finish" from the try block or a catch clause,
11758this pending exception or command is discarded.
11759
11760For examples see |throw-catch| and |try-finally|.
11761
11762
11763NESTING OF TRY CONDITIONALS *try-nesting*
11764
11765Try conditionals can be nested arbitrarily. That is, a complete try
11766conditional can be put into the try block, a catch clause, or the finally
11767clause of another try conditional. If the inner try conditional does not
11768catch an exception thrown in its try block or throws a new exception from one
11769of its catch clauses or its finally clause, the outer try conditional is
11770checked according to the rules above. If the inner try conditional is in the
11771try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +020011772otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +000011773nesting, whether the inner try conditional is directly contained in the outer
11774one, or whether the outer one sources a script or calls a function containing
11775the inner try conditional.
11776
11777When none of the active try conditionals catches an exception, just their
11778finally clauses are executed. Thereafter, the script processing terminates.
11779An error message is displayed in case of an uncaught exception explicitly
11780thrown by a ":throw" command. For uncaught error and interrupt exceptions
11781implicitly raised by Vim, the error message(s) or interrupt message are shown
11782as usual.
11783
11784For examples see |throw-catch|.
11785
11786
11787EXAMINING EXCEPTION HANDLING CODE *except-examine*
11788
11789Exception handling code can get tricky. If you are in doubt what happens, set
11790'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
11791script file. Then you see when an exception is thrown, discarded, caught, or
11792finished. When using a verbosity level of at least 14, things pending in
11793a finally clause are also shown. This information is also given in debug mode
11794(see |debug-scripts|).
11795
11796
11797THROWING AND CATCHING EXCEPTIONS *throw-catch*
11798
11799You can throw any number or string as an exception. Use the |:throw| command
11800and pass the value to be thrown as argument: >
11801 :throw 4711
11802 :throw "string"
11803< *throw-expression*
11804You can also specify an expression argument. The expression is then evaluated
11805first, and the result is thrown: >
11806 :throw 4705 + strlen("string")
11807 :throw strpart("strings", 0, 6)
11808
11809An exception might be thrown during evaluation of the argument of the ":throw"
11810command. Unless it is caught there, the expression evaluation is abandoned.
11811The ":throw" command then does not throw a new exception.
11812 Example: >
11813
11814 :function! Foo(arg)
11815 : try
11816 : throw a:arg
11817 : catch /foo/
11818 : endtry
11819 : return 1
11820 :endfunction
11821 :
11822 :function! Bar()
11823 : echo "in Bar"
11824 : return 4710
11825 :endfunction
11826 :
11827 :throw Foo("arrgh") + Bar()
11828
11829This throws "arrgh", and "in Bar" is not displayed since Bar() is not
11830executed. >
11831 :throw Foo("foo") + Bar()
11832however displays "in Bar" and throws 4711.
11833
11834Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +020011835abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000011836exception is then propagated to the caller of the command.
11837 Example: >
11838
11839 :if Foo("arrgh")
11840 : echo "then"
11841 :else
11842 : echo "else"
11843 :endif
11844
11845Here neither of "then" or "else" is displayed.
11846
11847 *catch-order*
11848Exceptions can be caught by a try conditional with one or more |:catch|
11849commands, see |try-conditionals|. The values to be caught by each ":catch"
11850command can be specified as a pattern argument. The subsequent catch clause
11851gets executed when a matching exception is caught.
11852 Example: >
11853
11854 :function! Foo(value)
11855 : try
11856 : throw a:value
11857 : catch /^\d\+$/
11858 : echo "Number thrown"
11859 : catch /.*/
11860 : echo "String thrown"
11861 : endtry
11862 :endfunction
11863 :
11864 :call Foo(0x1267)
11865 :call Foo('string')
11866
11867The first call to Foo() displays "Number thrown", the second "String thrown".
11868An exception is matched against the ":catch" commands in the order they are
11869specified. Only the first match counts. So you should place the more
11870specific ":catch" first. The following order does not make sense: >
11871
11872 : catch /.*/
11873 : echo "String thrown"
11874 : catch /^\d\+$/
11875 : echo "Number thrown"
11876
11877The first ":catch" here matches always, so that the second catch clause is
11878never taken.
11879
11880 *throw-variables*
11881If you catch an exception by a general pattern, you may access the exact value
11882in the variable |v:exception|: >
11883
11884 : catch /^\d\+$/
11885 : echo "Number thrown. Value is" v:exception
11886
11887You may also be interested where an exception was thrown. This is stored in
11888|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
11889exception most recently caught as long it is not finished.
11890 Example: >
11891
11892 :function! Caught()
11893 : if v:exception != ""
11894 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
11895 : else
11896 : echo 'Nothing caught'
11897 : endif
11898 :endfunction
11899 :
11900 :function! Foo()
11901 : try
11902 : try
11903 : try
11904 : throw 4711
11905 : finally
11906 : call Caught()
11907 : endtry
11908 : catch /.*/
11909 : call Caught()
11910 : throw "oops"
11911 : endtry
11912 : catch /.*/
11913 : call Caught()
11914 : finally
11915 : call Caught()
11916 : endtry
11917 :endfunction
11918 :
11919 :call Foo()
11920
11921This displays >
11922
11923 Nothing caught
11924 Caught "4711" in function Foo, line 4
11925 Caught "oops" in function Foo, line 10
11926 Nothing caught
11927
11928A practical example: The following command ":LineNumber" displays the line
11929number in the script or function where it has been used: >
11930
11931 :function! LineNumber()
11932 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
11933 :endfunction
11934 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
11935<
11936 *try-nested*
11937An exception that is not caught by a try conditional can be caught by
11938a surrounding try conditional: >
11939
11940 :try
11941 : try
11942 : throw "foo"
11943 : catch /foobar/
11944 : echo "foobar"
11945 : finally
11946 : echo "inner finally"
11947 : endtry
11948 :catch /foo/
11949 : echo "foo"
11950 :endtry
11951
11952The inner try conditional does not catch the exception, just its finally
11953clause is executed. The exception is then caught by the outer try
11954conditional. The example displays "inner finally" and then "foo".
11955
11956 *throw-from-catch*
11957You can catch an exception and throw a new one to be caught elsewhere from the
11958catch clause: >
11959
11960 :function! Foo()
11961 : throw "foo"
11962 :endfunction
11963 :
11964 :function! Bar()
11965 : try
11966 : call Foo()
11967 : catch /foo/
11968 : echo "Caught foo, throw bar"
11969 : throw "bar"
11970 : endtry
11971 :endfunction
11972 :
11973 :try
11974 : call Bar()
11975 :catch /.*/
11976 : echo "Caught" v:exception
11977 :endtry
11978
11979This displays "Caught foo, throw bar" and then "Caught bar".
11980
11981 *rethrow*
11982There is no real rethrow in the Vim script language, but you may throw
11983"v:exception" instead: >
11984
11985 :function! Bar()
11986 : try
11987 : call Foo()
11988 : catch /.*/
11989 : echo "Rethrow" v:exception
11990 : throw v:exception
11991 : endtry
11992 :endfunction
11993< *try-echoerr*
11994Note that this method cannot be used to "rethrow" Vim error or interrupt
11995exceptions, because it is not possible to fake Vim internal exceptions.
11996Trying so causes an error exception. You should throw your own exception
11997denoting the situation. If you want to cause a Vim error exception containing
11998the original error exception value, you can use the |:echoerr| command: >
11999
12000 :try
12001 : try
12002 : asdf
12003 : catch /.*/
12004 : echoerr v:exception
12005 : endtry
12006 :catch /.*/
12007 : echo v:exception
12008 :endtry
12009
12010This code displays
12011
Bram Moolenaar446cb832008-06-24 21:56:24 +000012012 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012013
12014
12015CLEANUP CODE *try-finally*
12016
12017Scripts often change global settings and restore them at their end. If the
12018user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +020012019an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +000012020a script when an error occurs or you explicitly throw an exception without
12021catching it. You can solve these problems by using a try conditional with
12022a finally clause for restoring the settings. Its execution is guaranteed on
12023normal control flow, on error, on an explicit ":throw", and on interrupt.
12024(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +020012025to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000012026clause has been executed.)
12027Example: >
12028
12029 :try
12030 : let s:saved_ts = &ts
12031 : set ts=17
12032 :
12033 : " Do the hard work here.
12034 :
12035 :finally
12036 : let &ts = s:saved_ts
12037 : unlet s:saved_ts
12038 :endtry
12039
12040This method should be used locally whenever a function or part of a script
12041changes global settings which need to be restored on failure or normal exit of
12042that function or script part.
12043
12044 *break-finally*
12045Cleanup code works also when the try block or a catch clause is left by
12046a ":continue", ":break", ":return", or ":finish".
12047 Example: >
12048
12049 :let first = 1
12050 :while 1
12051 : try
12052 : if first
12053 : echo "first"
12054 : let first = 0
12055 : continue
12056 : else
12057 : throw "second"
12058 : endif
12059 : catch /.*/
12060 : echo v:exception
12061 : break
12062 : finally
12063 : echo "cleanup"
12064 : endtry
12065 : echo "still in while"
12066 :endwhile
12067 :echo "end"
12068
12069This displays "first", "cleanup", "second", "cleanup", and "end". >
12070
12071 :function! Foo()
12072 : try
12073 : return 4711
12074 : finally
12075 : echo "cleanup\n"
12076 : endtry
12077 : echo "Foo still active"
12078 :endfunction
12079 :
12080 :echo Foo() "returned by Foo"
12081
12082This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +020012083extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +000012084return value.)
12085
12086 *except-from-finally*
12087Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
12088a finally clause is possible, but not recommended since it abandons the
12089cleanup actions for the try conditional. But, of course, interrupt and error
12090exceptions might get raised from a finally clause.
12091 Example where an error in the finally clause stops an interrupt from
12092working correctly: >
12093
12094 :try
12095 : try
12096 : echo "Press CTRL-C for interrupt"
12097 : while 1
12098 : endwhile
12099 : finally
12100 : unlet novar
12101 : endtry
12102 :catch /novar/
12103 :endtry
12104 :echo "Script still running"
12105 :sleep 1
12106
12107If you need to put commands that could fail into a finally clause, you should
12108think about catching or ignoring the errors in these commands, see
12109|catch-errors| and |ignore-errors|.
12110
12111
12112CATCHING ERRORS *catch-errors*
12113
12114If you want to catch specific errors, you just have to put the code to be
12115watched in a try block and add a catch clause for the error message. The
12116presence of the try conditional causes all errors to be converted to an
12117exception. No message is displayed and |v:errmsg| is not set then. To find
12118the right pattern for the ":catch" command, you have to know how the format of
12119the error exception is.
12120 Error exceptions have the following format: >
12121
12122 Vim({cmdname}):{errmsg}
12123or >
12124 Vim:{errmsg}
12125
12126{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +020012127the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +000012128when the error occurs outside try conditionals. It always begins with
12129a capital "E", followed by a two or three-digit error number, a colon, and
12130a space.
12131
12132Examples:
12133
12134The command >
12135 :unlet novar
12136normally produces the error message >
12137 E108: No such variable: "novar"
12138which is converted inside try conditionals to an exception >
12139 Vim(unlet):E108: No such variable: "novar"
12140
12141The command >
12142 :dwim
12143normally produces the error message >
12144 E492: Not an editor command: dwim
12145which is converted inside try conditionals to an exception >
12146 Vim:E492: Not an editor command: dwim
12147
12148You can catch all ":unlet" errors by a >
12149 :catch /^Vim(unlet):/
12150or all errors for misspelled command names by a >
12151 :catch /^Vim:E492:/
12152
12153Some error messages may be produced by different commands: >
12154 :function nofunc
12155and >
12156 :delfunction nofunc
12157both produce the error message >
12158 E128: Function name must start with a capital: nofunc
12159which is converted inside try conditionals to an exception >
12160 Vim(function):E128: Function name must start with a capital: nofunc
12161or >
12162 Vim(delfunction):E128: Function name must start with a capital: nofunc
12163respectively. You can catch the error by its number independently on the
12164command that caused it if you use the following pattern: >
12165 :catch /^Vim(\a\+):E128:/
12166
12167Some commands like >
12168 :let x = novar
12169produce multiple error messages, here: >
12170 E121: Undefined variable: novar
12171 E15: Invalid expression: novar
12172Only the first is used for the exception value, since it is the most specific
12173one (see |except-several-errors|). So you can catch it by >
12174 :catch /^Vim(\a\+):E121:/
12175
12176You can catch all errors related to the name "nofunc" by >
12177 :catch /\<nofunc\>/
12178
12179You can catch all Vim errors in the ":write" and ":read" commands by >
12180 :catch /^Vim(\(write\|read\)):E\d\+:/
12181
12182You can catch all Vim errors by the pattern >
12183 :catch /^Vim\((\a\+)\)\=:E\d\+:/
12184<
12185 *catch-text*
12186NOTE: You should never catch the error message text itself: >
12187 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +010012188only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +000012189a different language by the |:language| command. It is however helpful to
12190cite the message text in a comment: >
12191 :catch /^Vim(\a\+):E108:/ " No such variable
12192
12193
12194IGNORING ERRORS *ignore-errors*
12195
12196You can ignore errors in a specific Vim command by catching them locally: >
12197
12198 :try
12199 : write
12200 :catch
12201 :endtry
12202
12203But you are strongly recommended NOT to use this simple form, since it could
12204catch more than you want. With the ":write" command, some autocommands could
12205be executed and cause errors not related to writing, for instance: >
12206
12207 :au BufWritePre * unlet novar
12208
12209There could even be such errors you are not responsible for as a script
12210writer: a user of your script might have defined such autocommands. You would
12211then hide the error from the user.
12212 It is much better to use >
12213
12214 :try
12215 : write
12216 :catch /^Vim(write):/
12217 :endtry
12218
12219which only catches real write errors. So catch only what you'd like to ignore
12220intentionally.
12221
12222For a single command that does not cause execution of autocommands, you could
12223even suppress the conversion of errors to exceptions by the ":silent!"
12224command: >
12225 :silent! nunmap k
12226This works also when a try conditional is active.
12227
12228
12229CATCHING INTERRUPTS *catch-interrupt*
12230
12231When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +020012232the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000012233script is not terminated, then.
12234 Example: >
12235
12236 :function! TASK1()
12237 : sleep 10
12238 :endfunction
12239
12240 :function! TASK2()
12241 : sleep 20
12242 :endfunction
12243
12244 :while 1
12245 : let command = input("Type a command: ")
12246 : try
12247 : if command == ""
12248 : continue
12249 : elseif command == "END"
12250 : break
12251 : elseif command == "TASK1"
12252 : call TASK1()
12253 : elseif command == "TASK2"
12254 : call TASK2()
12255 : else
12256 : echo "\nIllegal command:" command
12257 : continue
12258 : endif
12259 : catch /^Vim:Interrupt$/
12260 : echo "\nCommand interrupted"
12261 : " Caught the interrupt. Continue with next prompt.
12262 : endtry
12263 :endwhile
12264
12265You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +020012266a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012267
12268For testing what happens when CTRL-C would be pressed on a specific line in
12269your script, use the debug mode and execute the |>quit| or |>interrupt|
12270command on that line. See |debug-scripts|.
12271
12272
12273CATCHING ALL *catch-all*
12274
12275The commands >
12276
12277 :catch /.*/
12278 :catch //
12279 :catch
12280
12281catch everything, error exceptions, interrupt exceptions and exceptions
12282explicitly thrown by the |:throw| command. This is useful at the top level of
12283a script in order to catch unexpected things.
12284 Example: >
12285
12286 :try
12287 :
12288 : " do the hard work here
12289 :
12290 :catch /MyException/
12291 :
12292 : " handle known problem
12293 :
12294 :catch /^Vim:Interrupt$/
12295 : echo "Script interrupted"
12296 :catch /.*/
12297 : echo "Internal error (" . v:exception . ")"
12298 : echo " - occurred at " . v:throwpoint
12299 :endtry
12300 :" end of script
12301
12302Note: Catching all might catch more things than you want. Thus, you are
12303strongly encouraged to catch only for problems that you can really handle by
12304specifying a pattern argument to the ":catch".
12305 Example: Catching all could make it nearly impossible to interrupt a script
12306by pressing CTRL-C: >
12307
12308 :while 1
12309 : try
12310 : sleep 1
12311 : catch
12312 : endtry
12313 :endwhile
12314
12315
12316EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
12317
12318Exceptions may be used during execution of autocommands. Example: >
12319
12320 :autocmd User x try
12321 :autocmd User x throw "Oops!"
12322 :autocmd User x catch
12323 :autocmd User x echo v:exception
12324 :autocmd User x endtry
12325 :autocmd User x throw "Arrgh!"
12326 :autocmd User x echo "Should not be displayed"
12327 :
12328 :try
12329 : doautocmd User x
12330 :catch
12331 : echo v:exception
12332 :endtry
12333
12334This displays "Oops!" and "Arrgh!".
12335
12336 *except-autocmd-Pre*
12337For some commands, autocommands get executed before the main action of the
12338command takes place. If an exception is thrown and not caught in the sequence
12339of autocommands, the sequence and the command that caused its execution are
12340abandoned and the exception is propagated to the caller of the command.
12341 Example: >
12342
12343 :autocmd BufWritePre * throw "FAIL"
12344 :autocmd BufWritePre * echo "Should not be displayed"
12345 :
12346 :try
12347 : write
12348 :catch
12349 : echo "Caught:" v:exception "from" v:throwpoint
12350 :endtry
12351
12352Here, the ":write" command does not write the file currently being edited (as
12353you can see by checking 'modified'), since the exception from the BufWritePre
12354autocommand abandons the ":write". The exception is then caught and the
12355script displays: >
12356
12357 Caught: FAIL from BufWrite Auto commands for "*"
12358<
12359 *except-autocmd-Post*
12360For some commands, autocommands get executed after the main action of the
12361command has taken place. If this main action fails and the command is inside
12362an active try conditional, the autocommands are skipped and an error exception
12363is thrown that can be caught by the caller of the command.
12364 Example: >
12365
12366 :autocmd BufWritePost * echo "File successfully written!"
12367 :
12368 :try
12369 : write /i/m/p/o/s/s/i/b/l/e
12370 :catch
12371 : echo v:exception
12372 :endtry
12373
12374This just displays: >
12375
12376 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
12377
12378If you really need to execute the autocommands even when the main action
12379fails, trigger the event from the catch clause.
12380 Example: >
12381
12382 :autocmd BufWritePre * set noreadonly
12383 :autocmd BufWritePost * set readonly
12384 :
12385 :try
12386 : write /i/m/p/o/s/s/i/b/l/e
12387 :catch
12388 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
12389 :endtry
12390<
12391You can also use ":silent!": >
12392
12393 :let x = "ok"
12394 :let v:errmsg = ""
12395 :autocmd BufWritePost * if v:errmsg != ""
12396 :autocmd BufWritePost * let x = "after fail"
12397 :autocmd BufWritePost * endif
12398 :try
12399 : silent! write /i/m/p/o/s/s/i/b/l/e
12400 :catch
12401 :endtry
12402 :echo x
12403
12404This displays "after fail".
12405
12406If the main action of the command does not fail, exceptions from the
12407autocommands will be catchable by the caller of the command: >
12408
12409 :autocmd BufWritePost * throw ":-("
12410 :autocmd BufWritePost * echo "Should not be displayed"
12411 :
12412 :try
12413 : write
12414 :catch
12415 : echo v:exception
12416 :endtry
12417<
12418 *except-autocmd-Cmd*
12419For some commands, the normal action can be replaced by a sequence of
12420autocommands. Exceptions from that sequence will be catchable by the caller
12421of the command.
12422 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +020012423had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +000012424some way. >
12425
12426 :if !exists("cnt")
12427 : let cnt = 0
12428 :
12429 : autocmd BufWriteCmd * if &modified
12430 : autocmd BufWriteCmd * let cnt = cnt + 1
12431 : autocmd BufWriteCmd * if cnt % 3 == 2
12432 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12433 : autocmd BufWriteCmd * endif
12434 : autocmd BufWriteCmd * write | set nomodified
12435 : autocmd BufWriteCmd * if cnt % 3 == 0
12436 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12437 : autocmd BufWriteCmd * endif
12438 : autocmd BufWriteCmd * echo "File successfully written!"
12439 : autocmd BufWriteCmd * endif
12440 :endif
12441 :
12442 :try
12443 : write
12444 :catch /^BufWriteCmdError$/
12445 : if &modified
12446 : echo "Error on writing (file contents not changed)"
12447 : else
12448 : echo "Error after writing"
12449 : endif
12450 :catch /^Vim(write):/
12451 : echo "Error on writing"
12452 :endtry
12453
12454When this script is sourced several times after making changes, it displays
12455first >
12456 File successfully written!
12457then >
12458 Error on writing (file contents not changed)
12459then >
12460 Error after writing
12461etc.
12462
12463 *except-autocmd-ill*
12464You cannot spread a try conditional over autocommands for different events.
12465The following code is ill-formed: >
12466
12467 :autocmd BufWritePre * try
12468 :
12469 :autocmd BufWritePost * catch
12470 :autocmd BufWritePost * echo v:exception
12471 :autocmd BufWritePost * endtry
12472 :
12473 :write
12474
12475
12476EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
12477
12478Some programming languages allow to use hierarchies of exception classes or to
12479pass additional information with the object of an exception class. You can do
12480similar things in Vim.
12481 In order to throw an exception from a hierarchy, just throw the complete
12482class name with the components separated by a colon, for instance throw the
12483string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
12484 When you want to pass additional information with your exception class, add
12485it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
12486for an error when writing "myfile".
12487 With the appropriate patterns in the ":catch" command, you can catch for
12488base classes or derived classes of your hierarchy. Additional information in
12489parentheses can be cut out from |v:exception| with the ":substitute" command.
12490 Example: >
12491
12492 :function! CheckRange(a, func)
12493 : if a:a < 0
12494 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
12495 : endif
12496 :endfunction
12497 :
12498 :function! Add(a, b)
12499 : call CheckRange(a:a, "Add")
12500 : call CheckRange(a:b, "Add")
12501 : let c = a:a + a:b
12502 : if c < 0
12503 : throw "EXCEPT:MATHERR:OVERFLOW"
12504 : endif
12505 : return c
12506 :endfunction
12507 :
12508 :function! Div(a, b)
12509 : call CheckRange(a:a, "Div")
12510 : call CheckRange(a:b, "Div")
12511 : if (a:b == 0)
12512 : throw "EXCEPT:MATHERR:ZERODIV"
12513 : endif
12514 : return a:a / a:b
12515 :endfunction
12516 :
12517 :function! Write(file)
12518 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +000012519 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012520 : catch /^Vim(write):/
12521 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
12522 : endtry
12523 :endfunction
12524 :
12525 :try
12526 :
12527 : " something with arithmetics and I/O
12528 :
12529 :catch /^EXCEPT:MATHERR:RANGE/
12530 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
12531 : echo "Range error in" function
12532 :
12533 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
12534 : echo "Math error"
12535 :
12536 :catch /^EXCEPT:IO/
12537 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
12538 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
12539 : if file !~ '^/'
12540 : let file = dir . "/" . file
12541 : endif
12542 : echo 'I/O error for "' . file . '"'
12543 :
12544 :catch /^EXCEPT/
12545 : echo "Unspecified error"
12546 :
12547 :endtry
12548
12549The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
12550a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
12551exceptions with the "Vim" prefix; they are reserved for Vim.
12552 Vim error exceptions are parameterized with the name of the command that
12553failed, if known. See |catch-errors|.
12554
12555
12556PECULIARITIES
12557 *except-compat*
12558The exception handling concept requires that the command sequence causing the
12559exception is aborted immediately and control is transferred to finally clauses
12560and/or a catch clause.
12561
12562In the Vim script language there are cases where scripts and functions
12563continue after an error: in functions without the "abort" flag or in a command
12564after ":silent!", control flow goes to the following line, and outside
12565functions, control flow goes to the line following the outermost ":endwhile"
12566or ":endif". On the other hand, errors should be catchable as exceptions
12567(thus, requiring the immediate abortion).
12568
12569This problem has been solved by converting errors to exceptions and using
12570immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +020012571conditional is active. This is no restriction since an (error) exception can
12572be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +000012573termination without catching the error, just use a try conditional without
12574catch clause. (You can cause cleanup code being executed before termination
12575by specifying a finally clause.)
12576
12577When no try conditional is active, the usual abortion and continuation
12578behavior is used instead of immediate abortion. This ensures compatibility of
12579scripts written for Vim 6.1 and earlier.
12580
12581However, when sourcing an existing script that does not use exception handling
12582commands (or when calling one of its functions) from inside an active try
12583conditional of a new script, you might change the control flow of the existing
12584script on error. You get the immediate abortion on error and can catch the
12585error in the new script. If however the sourced script suppresses error
12586messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +020012587|v:errmsg| if appropriate), its execution path is not changed. The error is
12588not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +000012589where this happens is for scripts that don't care about errors and produce
12590error messages. You probably won't want to use such code from your new
12591scripts.
12592
12593 *except-syntax-err*
12594Syntax errors in the exception handling commands are never caught by any of
12595the ":catch" commands of the try conditional they belong to. Its finally
12596clauses, however, is executed.
12597 Example: >
12598
12599 :try
12600 : try
12601 : throw 4711
12602 : catch /\(/
12603 : echo "in catch with syntax error"
12604 : catch
12605 : echo "inner catch-all"
12606 : finally
12607 : echo "inner finally"
12608 : endtry
12609 :catch
12610 : echo 'outer catch-all caught "' . v:exception . '"'
12611 : finally
12612 : echo "outer finally"
12613 :endtry
12614
12615This displays: >
12616 inner finally
12617 outer catch-all caught "Vim(catch):E54: Unmatched \("
12618 outer finally
12619The original exception is discarded and an error exception is raised, instead.
12620
12621 *except-single-line*
12622The ":try", ":catch", ":finally", and ":endtry" commands can be put on
12623a single line, but then syntax errors may make it difficult to recognize the
12624"catch" line, thus you better avoid this.
12625 Example: >
12626 :try | unlet! foo # | catch | endtry
12627raises an error exception for the trailing characters after the ":unlet!"
12628argument, but does not see the ":catch" and ":endtry" commands, so that the
12629error exception is discarded and the "E488: Trailing characters" message gets
12630displayed.
12631
12632 *except-several-errors*
12633When several errors appear in a single command, the first error message is
12634usually the most specific one and therefor converted to the error exception.
12635 Example: >
12636 echo novar
12637causes >
12638 E121: Undefined variable: novar
12639 E15: Invalid expression: novar
12640The value of the error exception inside try conditionals is: >
12641 Vim(echo):E121: Undefined variable: novar
12642< *except-syntax-error*
12643But when a syntax error is detected after a normal error in the same command,
12644the syntax error is used for the exception being thrown.
12645 Example: >
12646 unlet novar #
12647causes >
12648 E108: No such variable: "novar"
12649 E488: Trailing characters
12650The value of the error exception inside try conditionals is: >
12651 Vim(unlet):E488: Trailing characters
12652This is done because the syntax error might change the execution path in a way
12653not intended by the user. Example: >
12654 try
12655 try | unlet novar # | catch | echo v:exception | endtry
12656 catch /.*/
12657 echo "outer catch:" v:exception
12658 endtry
12659This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
12660a "E600: Missing :endtry" error message is given, see |except-single-line|.
12661
12662==============================================================================
126639. Examples *eval-examples*
12664
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012665Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012666>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010012667 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012668 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012669 : let n = a:nr
12670 : let r = ""
12671 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012672 : let r = '01'[n % 2] . r
12673 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +000012674 : endwhile
12675 : return r
12676 :endfunc
12677
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012678 :" The function String2Bin() converts each character in a string to a
12679 :" binary string, separated with dashes.
12680 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012681 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012682 : for ix in range(strlen(a:str))
12683 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
12684 : endfor
12685 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +000012686 :endfunc
12687
12688Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012689 :echo Nr2Bin(32)
12690result: "100000" >
12691 :echo String2Bin("32")
12692result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +000012693
12694
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012695Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012696
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012697This example sorts lines with a specific compare function. >
12698
12699 :func SortBuffer()
12700 : let lines = getline(1, '$')
12701 : call sort(lines, function("Strcmp"))
12702 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012703 :endfunction
12704
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012705As a one-liner: >
12706 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +000012707
Bram Moolenaar071d4272004-06-13 20:20:40 +000012708
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012709scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012710 *sscanf*
12711There is no sscanf() function in Vim. If you need to extract parts from a
12712line, you can use matchstr() and substitute() to do it. This example shows
12713how to get the file name, line number and column number out of a line like
12714"foobar.txt, 123, 45". >
12715 :" Set up the match bit
12716 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
12717 :"get the part matching the whole expression
12718 :let l = matchstr(line, mx)
12719 :"get each item out of the match
12720 :let file = substitute(l, mx, '\1', '')
12721 :let lnum = substitute(l, mx, '\2', '')
12722 :let col = substitute(l, mx, '\3', '')
12723
12724The input is in the variable "line", the results in the variables "file",
12725"lnum" and "col". (idea from Michael Geddes)
12726
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012727
12728getting the scriptnames in a Dictionary ~
12729 *scriptnames-dictionary*
12730The |:scriptnames| command can be used to get a list of all script files that
12731have been sourced. There is no equivalent function or variable for this
12732(because it's rarely needed). In case you need to manipulate the list this
12733code can be used: >
12734 " Get the output of ":scriptnames" in the scriptnames_output variable.
12735 let scriptnames_output = ''
12736 redir => scriptnames_output
12737 silent scriptnames
12738 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010012739
Bram Moolenaar446cb832008-06-24 21:56:24 +000012740 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012741 " "scripts" dictionary.
12742 let scripts = {}
12743 for line in split(scriptnames_output, "\n")
12744 " Only do non-blank lines.
12745 if line =~ '\S'
12746 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +000012747 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012748 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +000012749 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012750 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +000012751 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012752 endif
12753 endfor
12754 unlet scriptnames_output
12755
Bram Moolenaar071d4272004-06-13 20:20:40 +000012756==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001275710. Vim script versions *vimscript-version* *vimscript-versions*
Bram Moolenaar911ead12019-04-21 00:03:35 +020012758 *scriptversion*
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020012759Over time many features have been added to Vim script. This includes Ex
12760commands, functions, variable types, etc. Each individual feature can be
12761checked with the |has()| and |exists()| functions.
12762
12763Sometimes old syntax of functionality gets in the way of making Vim better.
12764When support is taken away this will break older Vim scripts. To make this
12765explicit the |:scriptversion| command can be used. When a Vim script is not
12766compatible with older versions of Vim this will give an explicit error,
12767instead of failing in mysterious ways. >
12768
12769 :scriptversion 1
12770< This is the original Vim script, same as not using a |:scriptversion|
12771 command. Can be used to go back to old syntax for a range of lines.
12772 Test for support with: >
12773 has('vimscript-1')
12774
12775 :scriptversion 2
12776< String concatenation with "." is not supported, use ".." instead.
12777 This avoids the ambiguity using "." for Dict member access and
12778 floating point numbers. Now ".5" means the number 0.5.
Bram Moolenaar911ead12019-04-21 00:03:35 +020012779>
12780 :scriptversion 3
12781< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't
12782 work as |v:version| anymore, it can be used as a normal variable.
12783 Same for some obvious names as "count" and others.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020012784
Bram Moolenaar911ead12019-04-21 00:03:35 +020012785 Test for support with: >
12786 has('vimscript-3')
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020012787
12788==============================================================================
1278911. No +eval feature *no-eval-feature*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012790
12791When the |+eval| feature was disabled at compile time, none of the expression
12792evaluation commands are available. To prevent this from causing Vim scripts
12793to generate all kinds of errors, the ":if" and ":endif" commands are still
12794recognized, though the argument of the ":if" and everything between the ":if"
12795and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
12796only if the commands are at the start of the line. The ":else" command is not
12797recognized.
12798
12799Example of how to avoid executing commands when the |+eval| feature is
12800missing: >
12801
12802 :if 1
12803 : echo "Expression evaluation is compiled in"
12804 :else
12805 : echo "You will _never_ see this message"
12806 :endif
12807
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020012808To execute a command only when the |+eval| feature is disabled requires a trick,
12809as this example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +020012810
12811 silent! while 0
12812 set history=111
12813 silent! endwhile
12814
12815When the |+eval| feature is available the command is skipped because of the
12816"while 0". Without the |+eval| feature the "while 0" is an error, which is
12817silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020012818
Bram Moolenaar071d4272004-06-13 20:20:40 +000012819==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001282012. The sandbox *eval-sandbox* *sandbox* *E48*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012821
Bram Moolenaar368373e2010-07-19 20:46:22 +020012822The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
12823'foldtext' options may be evaluated in a sandbox. This means that you are
12824protected from these expressions having nasty side effects. This gives some
12825safety for when these options are set from a modeline. It is also used when
12826the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000012827The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012828
12829These items are not allowed in the sandbox:
12830 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +020012831 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000012832 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012833 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012834 - executing a shell command
12835 - reading or writing a file
12836 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000012837 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000012838This is not guaranteed 100% secure, but it should block most attacks.
12839
12840 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000012841:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000012842 option that may have been set from a modeline, e.g.
12843 'foldexpr'.
12844
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012845 *sandbox-option*
12846A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000012847have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012848restrictive, thus this only happens when the option was set from an insecure
12849location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000012850- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012851- while executing in the sandbox
12852- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +020012853- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012854
12855Note that when in the sandbox and saving an option value and restoring it, the
12856option will still be marked as it was set in the sandbox.
12857
12858==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001285913. Textlock *textlock*
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012860
12861In a few situations it is not allowed to change the text in the buffer, jump
12862to another window and some other things that might confuse or break what Vim
12863is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +020012864actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012865happen any moment the mouse cursor is resting at some position.
12866
12867This is not allowed when the textlock is active:
12868 - changing the buffer text
12869 - jumping to another buffer or window
12870 - editing another file
12871 - closing a window or quitting Vim
12872 - etc.
12873
Bram Moolenaardc1f1642016-08-16 18:33:43 +020012874==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001287514. Testing *testing*
Bram Moolenaardc1f1642016-08-16 18:33:43 +020012876
12877Vim can be tested after building it, usually with "make test".
12878The tests are located in the directory "src/testdir".
12879
12880There are several types of tests added over time:
12881 test33.in oldest, don't add any more
12882 test_something.in old style tests
12883 test_something.vim new style tests
12884
12885 *new-style-testing*
12886New tests should be added as new style tests. These use functions such as
12887|assert_equal()| to keep the test commands and the expected result in one
12888place.
12889 *old-style-testing*
12890In some cases an old style test needs to be used. E.g. when testing Vim
12891without the |+eval| feature.
12892
12893Find more information in the file src/testdir/README.txt.
12894
Bram Moolenaar071d4272004-06-13 20:20:40 +000012895
Bram Moolenaar91f84f62018-07-29 15:07:52 +020012896 vim:tw=78:ts=8:noet:ft=help:norl: