blob: 642f0ad768ef9018ced38921790a8126616d853c [file] [log] [blame]
Bram Moolenaar03602ec2016-03-20 20:57:45 +01001*eval.txt* For Vim version 7.4. Last change: 2016 Mar 20
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
Bram Moolenaar446cb832008-06-24 21:56:24 +00004 VIM REFERENCE MANUAL by Bram Moolenaar
Bram Moolenaar071d4272004-06-13 20:20:40 +00005
6
7Expression evaluation *expression* *expr* *E15* *eval*
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 Moolenaar446cb832008-06-24 21:56:24 +000012done, 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|
20 1.5 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000212. Expression syntax |expression-syntax|
223. Internal variable |internal-variables|
234. Builtin Functions |functions|
245. Defining functions |user-functions|
256. Curly braces names |curly-braces-names|
267. Commands |expression-commands|
278. Exception handling |exception-handling|
289. Examples |eval-examples|
2910. No +eval feature |no-eval-feature|
3011. The sandbox |eval-sandbox|
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003112. Textlock |textlock|
Bram Moolenaar071d4272004-06-13 20:20:40 +000032
33{Vi does not have any of these commands}
34
35==============================================================================
361. Variables *variables*
37
Bram Moolenaar13065c42005-01-08 16:08:21 +0000381.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000039 *E712*
Bram Moolenaar38a55632016-02-15 22:07:32 +010040There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000041
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020042Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaard8b02732005-01-14 21:48:43 +000043 Examples: -123 0x10 0177
44
Bram Moolenaar446cb832008-06-24 21:56:24 +000045Float A floating point number. |floating-point-format| *Float*
46 {only when compiled with the |+float| feature}
47 Examples: 123.456 1.15e-6 -1.1e3
48
Bram Moolenaard8b02732005-01-14 21:48:43 +000049String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000050 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000051
Bram Moolenaard8b02732005-01-14 21:48:43 +000052List An ordered sequence of items |List|.
53 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000054
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000055Dictionary An associative, unordered array: Each entry has a key and a
56 value. |Dictionary|
57 Example: {'blue': "#0000ff", 'red': "#ff0000"}
58
Bram Moolenaar835dc632016-02-07 14:27:38 +010059Funcref A reference to a function |Funcref|.
60 Example: function("strlen")
61
Bram Moolenaar02e83b42016-02-21 20:10:26 +010062Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010063
Bram Moolenaar02e83b42016-02-21 20:10:26 +010064Job Used for a job, see |job_start()|. *Job*
Bram Moolenaar38a55632016-02-15 22:07:32 +010065
Bram Moolenaar02e83b42016-02-21 20:10:26 +010066Channel Used for a channel, see |ch_open()|. *Channel*
Bram Moolenaar835dc632016-02-07 14:27:38 +010067
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000068The Number and String types are converted automatically, depending on how they
69are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000070
71Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020072the Number. Examples:
73 Number 123 --> String "123" ~
74 Number 0 --> String "0" ~
75 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020076 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010077Conversion from a String to a Number is done by converting the first digits to
78a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
79recognized. If the String doesn't start with digits, the result is zero.
80Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020081 String "456" --> Number 456 ~
82 String "6bar" --> Number 6 ~
83 String "foo" --> Number 0 ~
84 String "0xf1" --> Number 241 ~
85 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +010086 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020087 String "-8" --> Number -8 ~
88 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000089
90To force conversion from String to Number, add zero to it: >
91 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000092< 64 ~
93
94To avoid a leading zero to cause octal conversion, or for using a different
95base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000096
97For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
98
99Note that in the command >
100 :if "foo"
101"foo" is converted to 0, which means FALSE. To test for a non-empty string,
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200102use empty(): >
103 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100104<
Bram Moolenaar38a55632016-02-15 22:07:32 +0100105 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar835dc632016-02-07 14:27:38 +0100106List, Dictionary, Funcref and Job types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000107
Bram Moolenaar446cb832008-06-24 21:56:24 +0000108 *E805* *E806* *E808*
109When mixing Number and Float the Number is converted to Float. Otherwise
110there is no automatic conversion of Float. You can use str2float() for String
111to Float, printf() for Float to String and float2nr() for Float to Number.
112
Bram Moolenaar38a55632016-02-15 22:07:32 +0100113 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100114When expecting a Float a Number can also be used, but nothing else.
115
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100116 *no-type-checking*
117You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000118
Bram Moolenaar13065c42005-01-08 16:08:21 +0000119
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001201.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000121 *Funcref* *E695* *E718*
Bram Moolenaar446cb832008-06-24 21:56:24 +0000122A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000123in an expression in the place of a function name, before the parenthesis
124around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000125
126 :let Fn = function("MyFunc")
127 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000128< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000129A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200130can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000131cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000132
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000133A special case is defining a function and directly assigning its Funcref to a
134Dictionary entry. Example: >
135 :function dict.init() dict
136 : let self.val = 0
137 :endfunction
138
139The key of the Dictionary can start with a lower case letter. The actual
140function name is not used here. Also see |numbered-function|.
141
142A Funcref can also be used with the |:call| command: >
143 :call Fn()
144 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000145
146The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000147 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000148
149You can use |call()| to invoke a Funcref and use a list variable for the
150arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000151 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000152
153
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001541.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200155 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000156A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar446cb832008-06-24 21:56:24 +0000157can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000158position in the sequence.
159
Bram Moolenaar13065c42005-01-08 16:08:21 +0000160
161List creation ~
162 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000163A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000164Examples: >
165 :let mylist = [1, two, 3, "four"]
166 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000167
Bram Moolenaar446cb832008-06-24 21:56:24 +0000168An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000169List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000170 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000171
172An extra comma after the last item is ignored.
173
Bram Moolenaar13065c42005-01-08 16:08:21 +0000174
175List index ~
176 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000177An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000178after the List. Indexes are zero-based, thus the first item has index zero. >
179 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000180 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000181
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000182When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000183 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000184<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000185A negative index is counted from the end. Index -1 refers to the last item in
186the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000187 :let last = mylist[-1] " get the last item: "four"
188
Bram Moolenaar13065c42005-01-08 16:08:21 +0000189To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000190is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000191 :echo get(mylist, idx)
192 :echo get(mylist, idx, "NONE")
193
194
195List concatenation ~
196
197Two lists can be concatenated with the "+" operator: >
198 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000199 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000200
201To prepend or append an item turn the item into a list by putting [] around
202it. To change a list in-place see |list-modification| below.
203
204
205Sublist ~
206
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000207A part of the List can be obtained by specifying the first and last index,
208separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000209 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000210
211Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000212similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000213 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
214 :let shortlist = mylist[2:2] " List with one item: [3]
215 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000216
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000217If the first index is beyond the last item of the List or the second item is
218before the first item, the result is an empty list. There is no error
219message.
220
221If the second index is equal to or greater than the length of the list the
222length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000223 :let mylist = [0, 1, 2, 3]
224 :echo mylist[2:8] " result: [2, 3]
225
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000226NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar446cb832008-06-24 21:56:24 +0000227using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000228mylist[s : e].
229
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000230
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000232 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000233When variable "aa" is a list and you assign it to another variable "bb", both
234variables refer to the same list. Thus changing the list "aa" will also
235change "bb": >
236 :let aa = [1, 2, 3]
237 :let bb = aa
238 :call add(aa, 4)
239 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000240< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241
242Making a copy of a list is done with the |copy()| function. Using [:] also
243works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000244a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000245 :let aa = [[1, 'a'], 2, 3]
246 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000247 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000248 :let aa[0][1] = 'aaa'
249 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000250< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000251 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000252< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000253
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000254To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000255copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000256
257The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000258List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000259the same value. >
260 :let alist = [1, 2, 3]
261 :let blist = [1, 2, 3]
262 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000263< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000264 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000265< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000266
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000267Note about comparing lists: Two lists are considered equal if they have the
268same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000269exception: When comparing a number with a string they are considered
270different. There is no automatic type conversion, as with using "==" on
271variables. Example: >
272 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000273< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000274 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000275< 0
276
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000277Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000278can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000279
280 :let a = 5
281 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000282 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000283< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000284 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000285< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000286
Bram Moolenaar13065c42005-01-08 16:08:21 +0000287
288List unpack ~
289
290To unpack the items in a list to individual variables, put the variables in
291square brackets, like list items: >
292 :let [var1, var2] = mylist
293
294When the number of variables does not match the number of items in the list
295this produces an error. To handle any extra items from the list append ";"
296and a variable name: >
297 :let [var1, var2; rest] = mylist
298
299This works like: >
300 :let var1 = mylist[0]
301 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000302 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000303
304Except that there is no error if there are only two items. "rest" will be an
305empty list then.
306
307
308List modification ~
309 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000310To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000311 :let list[4] = "four"
312 :let listlist[0][3] = item
313
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000314To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000315modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000316 :let list[3:5] = [3, 4, 5]
317
Bram Moolenaar13065c42005-01-08 16:08:21 +0000318Adding and removing items from a list is done with functions. Here are a few
319examples: >
320 :call insert(list, 'a') " prepend item 'a'
321 :call insert(list, 'a', 3) " insert item 'a' before list[3]
322 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000323 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000324 :call extend(list, [1, 2]) " extend the list with two more items
325 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000326 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000327 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000328 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000329 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000330
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000331Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000332 :call sort(list) " sort a list alphabetically
333 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100334 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000335
Bram Moolenaar13065c42005-01-08 16:08:21 +0000336
337For loop ~
338
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000339The |:for| loop executes commands for each item in a list. A variable is set
340to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000341 :for item in mylist
342 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000343 :endfor
344
345This works like: >
346 :let index = 0
347 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000348 : let item = mylist[index]
349 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000350 : let index = index + 1
351 :endwhile
352
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000353If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000354function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000355
Bram Moolenaar446cb832008-06-24 21:56:24 +0000356Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000357requires the argument to be a list of lists. >
358 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
359 : call Doit(lnum, col)
360 :endfor
361
362This works like a |:let| command is done for each list item. Again, the types
363must remain the same to avoid an error.
364
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000365It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000366 :for [i, j; rest] in listlist
367 : call Doit(i, j)
368 : if !empty(rest)
369 : echo "remainder: " . string(rest)
370 : endif
371 :endfor
372
373
374List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000375 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000376Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000377 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000378 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000379 :let l = len(list) " number of items in list
380 :let big = max(list) " maximum value in list
381 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000382 :let xs = count(list, 'x') " count nr of times 'x' appears in list
383 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000384 :let lines = getline(1, 10) " get ten text lines from buffer
385 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000386 :let list = split("a b c") " create list from items in a string
387 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000388 :let s = string(list) " String representation of list
389 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000390
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000391Don't forget that a combination of features can make things simple. For
392example, to add up all the numbers in a list: >
393 :exe 'let sum = ' . join(nrlist, '+')
394
Bram Moolenaar13065c42005-01-08 16:08:21 +0000395
Bram Moolenaard8b02732005-01-14 21:48:43 +00003961.4 Dictionaries ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200397 *dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000398A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399entry can be located with the key. The entries are stored without a specific
400ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000401
402
403Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000404 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000405A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000406braces. Each entry has a key and a value, separated by a colon. Each key can
407only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000408 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
409 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000410< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000411A key is always a String. You can use a Number, it will be converted to a
412String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar446cb832008-06-24 21:56:24 +0000413entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000414Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000415
Bram Moolenaar446cb832008-06-24 21:56:24 +0000416A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000417nested Dictionary: >
418 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
419
420An extra comma after the last entry is ignored.
421
422
423Accessing entries ~
424
425The normal way to access an entry is by putting the key in square brackets: >
426 :let val = mydict["one"]
427 :let mydict["four"] = 4
428
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000429You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000430
431For keys that consist entirely of letters, digits and underscore the following
432form can be used |expr-entry|: >
433 :let val = mydict.one
434 :let mydict.four = 4
435
436Since an entry can be any type, also a List and a Dictionary, the indexing and
437key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000438 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000439
440
441Dictionary to List conversion ~
442
Bram Moolenaar446cb832008-06-24 21:56:24 +0000443You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000444turn the Dictionary into a List and pass it to |:for|.
445
446Most often you want to loop over the keys, using the |keys()| function: >
447 :for key in keys(mydict)
448 : echo key . ': ' . mydict[key]
449 :endfor
450
451The List of keys is unsorted. You may want to sort them first: >
452 :for key in sort(keys(mydict))
453
454To loop over the values use the |values()| function: >
455 :for v in values(mydict)
456 : echo "value: " . v
457 :endfor
458
459If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000460a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000461 :for [key, value] in items(mydict)
462 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000463 :endfor
464
465
466Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000467 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000468Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
469Dictionary. Otherwise, assignment results in referring to the same
470Dictionary: >
471 :let onedict = {'a': 1, 'b': 2}
472 :let adict = onedict
473 :let adict['a'] = 11
474 :echo onedict['a']
475 11
476
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000477Two Dictionaries compare equal if all the key-value pairs compare equal. For
478more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000479
480
481Dictionary modification ~
482 *dict-modification*
483To change an already existing entry of a Dictionary, or to add a new entry,
484use |:let| this way: >
485 :let dict[4] = "four"
486 :let dict['one'] = item
487
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000488Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
489Three ways to remove the entry with key "aaa" from dict: >
490 :let i = remove(dict, 'aaa')
491 :unlet dict.aaa
492 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000493
494Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000495 :call extend(adict, bdict)
496This extends adict with all entries from bdict. Duplicate keys cause entries
497in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000498Note that the order of entries in a Dictionary is irrelevant, thus don't
499expect ":echo adict" to show the items from bdict after the older entries in
500adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000501
502Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000503 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000504This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000505
506
507Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100508 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000509When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000510special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000511 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000512 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000513 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000514 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
515 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000516
517This is like a method in object oriented programming. The entry in the
518Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
519the function was invoked from.
520
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000521It is also possible to add a function without the "dict" attribute as a
522Funcref to a Dictionary, but the "self" variable is not available then.
523
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000524 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000525To avoid the extra name for the function it can be defined and directly
526assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000527 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200528 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000529 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000530 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000531 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000532
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000533The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar446cb832008-06-24 21:56:24 +0000534that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000535|Funcref|. It will automatically be deleted when there is no |Funcref|
536remaining that refers to it.
537
538It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000539
Bram Moolenaar1affd722010-08-04 17:49:30 +0200540If you get an error for a numbered function, you can find out what it is with
541a trick. Assuming the function is 42, the command is: >
542 :function {42}
543
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000544
545Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000546 *E715*
547Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000548 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
549 :if empty(dict) " TRUE if dict is empty
550 :let l = len(dict) " number of items in dict
551 :let big = max(dict) " maximum value in dict
552 :let small = min(dict) " minimum value in dict
553 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
554 :let s = string(dict) " String representation of dict
555 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000556
557
5581.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000559 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000560If you need to know the type of a variable or expression, use the |type()|
561function.
562
563When the '!' flag is included in the 'viminfo' option, global variables that
564start with an uppercase letter, and don't contain a lowercase letter, are
565stored in the viminfo file |viminfo-file|.
566
567When the 'sessionoptions' option contains "global", global variables that
568start with an uppercase letter and contain at least one lowercase letter are
569stored in the session file |session-file|.
570
571variable name can be stored where ~
572my_var_6 not
573My_Var_6 session file
574MY_VAR_6 viminfo file
575
576
577It's possible to form a variable name with curly braces, see
578|curly-braces-names|.
579
580==============================================================================
5812. Expression syntax *expression-syntax*
582
583Expression syntax summary, from least to most significant:
584
585|expr1| expr2 ? expr1 : expr1 if-then-else
586
587|expr2| expr3 || expr3 .. logical OR
588
589|expr3| expr4 && expr4 .. logical AND
590
591|expr4| expr5 == expr5 equal
592 expr5 != expr5 not equal
593 expr5 > expr5 greater than
594 expr5 >= expr5 greater than or equal
595 expr5 < expr5 smaller than
596 expr5 <= expr5 smaller than or equal
597 expr5 =~ expr5 regexp matches
598 expr5 !~ expr5 regexp doesn't match
599
600 expr5 ==? expr5 equal, ignoring case
601 expr5 ==# expr5 equal, match case
602 etc. As above, append ? for ignoring case, # for
603 matching case
604
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000605 expr5 is expr5 same |List| instance
606 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000607
608|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000609 expr6 - expr6 .. number subtraction
610 expr6 . expr6 .. string concatenation
611
612|expr6| expr7 * expr7 .. number multiplication
613 expr7 / expr7 .. number division
614 expr7 % expr7 .. number modulo
615
616|expr7| ! expr7 logical NOT
617 - expr7 unary minus
618 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000619
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000620|expr8| expr8[expr1] byte of a String or item of a |List|
621 expr8[expr1 : expr1] substring of a String or sublist of a |List|
622 expr8.name entry in a |Dictionary|
623 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000624
625|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000626 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000627 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000628 [expr1, ...] |List|
629 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000630 &option option value
631 (expr1) nested expression
632 variable internal variable
633 va{ria}ble internal variable with curly braces
634 $VAR environment variable
635 @r contents of register 'r'
636 function(expr1, ...) function call
637 func{ti}on(expr1, ...) function call with curly braces
638
639
640".." indicates that the operations in this level can be concatenated.
641Example: >
642 &nu || &list && &shell == "csh"
643
644All expressions within one level are parsed from left to right.
645
646
647expr1 *expr1* *E109*
648-----
649
650expr2 ? expr1 : expr1
651
652The expression before the '?' is evaluated to a number. If it evaluates to
653non-zero, the result is the value of the expression between the '?' and ':',
654otherwise the result is the value of the expression after the ':'.
655Example: >
656 :echo lnum == 1 ? "top" : lnum
657
658Since the first expression is an "expr2", it cannot contain another ?:. The
659other two expressions can, thus allow for recursive use of ?:.
660Example: >
661 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
662
663To keep this readable, using |line-continuation| is suggested: >
664 :echo lnum == 1
665 :\ ? "top"
666 :\ : lnum == 1000
667 :\ ? "last"
668 :\ : lnum
669
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000670You should always put a space before the ':', otherwise it can be mistaken for
671use in a variable such as "a:1".
672
Bram Moolenaar071d4272004-06-13 20:20:40 +0000673
674expr2 and expr3 *expr2* *expr3*
675---------------
676
677 *expr-barbar* *expr-&&*
678The "||" and "&&" operators take one argument on each side. The arguments
679are (converted to) Numbers. The result is:
680
681 input output ~
682n1 n2 n1 || n2 n1 && n2 ~
683zero zero zero zero
684zero non-zero non-zero zero
685non-zero zero non-zero zero
686non-zero non-zero non-zero non-zero
687
688The operators can be concatenated, for example: >
689
690 &nu || &list && &shell == "csh"
691
692Note that "&&" takes precedence over "||", so this has the meaning of: >
693
694 &nu || (&list && &shell == "csh")
695
696Once the result is known, the expression "short-circuits", that is, further
697arguments are not evaluated. This is like what happens in C. For example: >
698
699 let a = 1
700 echo a || b
701
702This is valid even if there is no variable called "b" because "a" is non-zero,
703so the result must be non-zero. Similarly below: >
704
705 echo exists("b") && b == "yes"
706
707This is valid whether "b" has been defined or not. The second clause will
708only be evaluated if "b" has been defined.
709
710
711expr4 *expr4*
712-----
713
714expr5 {cmp} expr5
715
716Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
717if it evaluates to true.
718
Bram Moolenaar446cb832008-06-24 21:56:24 +0000719 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000720 *expr-<* *expr-<=* *expr-=~* *expr-!~*
721 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
722 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
723 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
724 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200725 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
726 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000727 use 'ignorecase' match case ignore case ~
728equal == ==# ==?
729not equal != !=# !=?
730greater than > ># >?
731greater than or equal >= >=# >=?
732smaller than < <# <?
733smaller than or equal <= <=# <=?
734regexp matches =~ =~# =~?
735regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200736same instance is is# is?
737different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000738
739Examples:
740"abc" ==# "Abc" evaluates to 0
741"abc" ==? "Abc" evaluates to 1
742"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
743
Bram Moolenaar13065c42005-01-08 16:08:21 +0000744 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000745A |List| can only be compared with a |List| and only "equal", "not equal" and
746"is" can be used. This compares the values of the list, recursively.
747Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000748
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000749 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000750A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
751equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000752recursively. Ignoring case means case is ignored when comparing item values.
753
Bram Moolenaar13065c42005-01-08 16:08:21 +0000754 *E693* *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000755A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
Bram Moolenaar03602ec2016-03-20 20:57:45 +0100756equal" can be used. Case is never ignored. Whether arguments or a Dictionary
757are bound (with a partial) is ignored. This is so that when a function is
758made a member of a Dictionary it is still considered to be the same function.
759To compare partials to see if they bind the same argument and Dictionary
760values use string(): >
761 echo string(Partial1) == string(Partial2)
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000762
Bram Moolenaar251e1912011-06-19 05:09:16 +0200763When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the
764expressions are referring to the same |List| or |Dictionary| instance. A copy
765of a |List| is different from the original |List|. When using "is" without
766a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot"
767equivalent to using "not equal". Except that a different type means the
Bram Moolenaar86edef62016-03-13 18:07:30 +0100768values are different: >
769 echo 4 == '4'
770 1
771 echo 4 is '4'
772 0
773 echo 0 is []
774 0
775"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000776
Bram Moolenaar071d4272004-06-13 20:20:40 +0000777When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar86edef62016-03-13 18:07:30 +0100778and the comparison is done on Numbers. This means that: >
779 echo 0 == 'x'
780 1
781because 'x' converted to a Number is zero. However: >
782 echo [0] == ['x']
783 0
784Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000785
786When comparing two Strings, this is done with strcmp() or stricmp(). This
787results in the mathematical difference (comparing byte values), not
788necessarily the alphabetical difference in the local language.
789
Bram Moolenaar446cb832008-06-24 21:56:24 +0000790When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000791'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000792
793When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000794'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
795
796'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797
798The "=~" and "!~" operators match the lefthand argument with the righthand
799argument, which is used as a pattern. See |pattern| for what a pattern is.
800This matching is always done like 'magic' was set and 'cpoptions' is empty, no
801matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
802portable. To avoid backslashes in the regexp pattern to be doubled, use a
803single-quote string, see |literal-string|.
804Since a string is considered to be a single line, a multi-line pattern
805(containing \n, backslash-n) will not match. However, a literal NL character
806can be matched like an ordinary character. Examples:
807 "foo\nbar" =~ "\n" evaluates to 1
808 "foo\nbar" =~ "\\n" evaluates to 0
809
810
811expr5 and expr6 *expr5* *expr6*
812---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000813expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000814expr6 - expr6 .. Number subtraction *expr--*
815expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000816
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000817For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000818result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000819
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100820expr7 * expr7 .. Number multiplication *expr-star*
821expr7 / expr7 .. Number division *expr-/*
822expr7 % expr7 .. Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000823
824For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100825For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000826
827Note the difference between "+" and ".":
828 "123" + "456" = 579
829 "123" . "456" = "123456"
830
Bram Moolenaar446cb832008-06-24 21:56:24 +0000831Since '.' has the same precedence as '+' and '-', you need to read: >
832 1 . 90 + 90.0
833As: >
834 (1 . 90) + 90.0
835That works, since the String "190" is automatically converted to the Number
836190, which can be added to the Float 90.0. However: >
837 1 . 90 * 90.0
838Should be read as: >
839 1 . (90 * 90.0)
840Since '.' has lower precedence than '*'. This does NOT work, since this
841attempts to concatenate a Float and a String.
842
843When dividing a Number by zero the result depends on the value:
844 0 / 0 = -0x80000000 (like NaN for Float)
845 >0 / 0 = 0x7fffffff (like positive infinity)
846 <0 / 0 = -0x7fffffff (like negative infinity)
847 (before Vim 7.2 it was always 0x7fffffff)
848
Bram Moolenaar071d4272004-06-13 20:20:40 +0000849When the righthand side of '%' is zero, the result is 0.
850
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000851None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000852
Bram Moolenaar446cb832008-06-24 21:56:24 +0000853. and % do not work for Float. *E804*
854
Bram Moolenaar071d4272004-06-13 20:20:40 +0000855
856expr7 *expr7*
857-----
858! expr7 logical NOT *expr-!*
859- expr7 unary minus *expr-unary--*
860+ expr7 unary plus *expr-unary-+*
861
862For '!' non-zero becomes zero, zero becomes one.
863For '-' the sign of the number is changed.
864For '+' the number is unchanged.
865
866A String will be converted to a Number first.
867
Bram Moolenaar446cb832008-06-24 21:56:24 +0000868These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000869 !-1 == 0
870 !!8 == 1
871 --9 == 9
872
873
874expr8 *expr8*
875-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000876expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar835dc632016-02-07 14:27:38 +0100877 *E909*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000878If expr8 is a Number or String this results in a String that contains the
879expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100880Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
881an alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000882
Bram Moolenaar256972a2015-12-29 19:10:25 +0100883Index zero gives the first byte. This is like it works in C. Careful:
884text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000885cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000886 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000887
888If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +0100889String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000890compatibility). Use [-1:] to get the last byte.
891
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000892If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000893for possible index values. If the index is out of range this results in an
Bram Moolenaar446cb832008-06-24 21:56:24 +0000894error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000895 :let item = mylist[-1] " get last item
896
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000897Generally, if a |List| index is equal to or higher than the length of the
898|List|, or more negative than the length of the |List|, this results in an
899error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000900
Bram Moolenaard8b02732005-01-14 21:48:43 +0000901
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000902expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000903
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000904If expr8 is a Number or String this results in the substring with the bytes
905from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100906expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
907|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000908
909If expr1a is omitted zero is used. If expr1b is omitted the length of the
910string minus one is used.
911
912A negative number can be used to measure from the end of the string. -1 is
913the last character, -2 the last but one, etc.
914
915If an index goes out of range for the string characters are omitted. If
916expr1b is smaller than expr1a the result is an empty string.
917
918Examples: >
919 :let c = name[-1:] " last byte of a string
920 :let c = name[-2:-2] " last but one byte of a string
921 :let s = line(".")[4:] " from the fifth byte to the end
922 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100923<
924 *sublist* *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000925If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar446cb832008-06-24 21:56:24 +0000926the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000927just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000928 :let l = mylist[:3] " first four items
929 :let l = mylist[4:4] " List with one item
930 :let l = mylist[:] " shallow copy of a List
931
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000932Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
933error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000934
Bram Moolenaarda440d22016-01-16 21:27:23 +0100935Watch out for confusion between a namespace and a variable followed by a colon
936for a sublist: >
937 mylist[n:] " uses variable n
938 mylist[s:] " uses namespace s:, error!
939
Bram Moolenaard8b02732005-01-14 21:48:43 +0000940
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000941expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000942
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000943If expr8 is a |Dictionary| and it is followed by a dot, then the following
944name will be used as a key in the |Dictionary|. This is just like:
945expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000946
947The name must consist of alphanumeric characters, just like a variable name,
948but it may start with a number. Curly braces cannot be used.
949
950There must not be white space before or after the dot.
951
952Examples: >
953 :let dict = {"one": 1, 2: "two"}
954 :echo dict.one
955 :echo dict .2
956
957Note that the dot is also used for String concatenation. To avoid confusion
958always put spaces around the dot for String concatenation.
959
960
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000961expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000962
963When expr8 is a |Funcref| type variable, invoke the function it refers to.
964
965
966
967 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000968number
969------
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100970number number constant *expr-number*
971 *hex-number* *octal-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000972
973Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
974
Bram Moolenaar446cb832008-06-24 21:56:24 +0000975 *floating-point-format*
976Floating point numbers can be written in two forms:
977
978 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +0100979 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +0000980
981{N} and {M} are numbers. Both {N} and {M} must be present and can only
982contain digits.
983[-+] means there is an optional plus or minus sign.
984{exp} is the exponent, power of 10.
985Only a decimal point is accepted, not a comma. No matter what the current
986locale is.
987{only when compiled with the |+float| feature}
988
989Examples:
990 123.456
991 +0.0001
992 55.0
993 -0.123
994 1.234e03
995 1.0E-6
996 -3.1416e+88
997
998These are INVALID:
999 3. empty {M}
1000 1e40 missing .{M}
1001
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001002 *float-pi* *float-e*
1003A few useful values to copy&paste: >
1004 :let pi = 3.14159265359
1005 :let e = 2.71828182846
1006
Bram Moolenaar446cb832008-06-24 21:56:24 +00001007Rationale:
1008Before floating point was introduced, the text "123.456" was interpreted as
1009the two numbers "123" and "456", both converted to a string and concatenated,
1010resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001011could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001012incompatibility was accepted in favor of being able to use the normal notation
1013for floating point numbers.
1014
1015 *floating-point-precision*
1016The precision and range of floating points numbers depends on what "double"
1017means in the library Vim was compiled with. There is no way to change this at
1018runtime.
1019
1020The default for displaying a |Float| is to use 6 decimal places, like using
1021printf("%g", f). You can select something else when using the |printf()|
1022function. Example: >
1023 :echo printf('%.15e', atan(1))
1024< 7.853981633974483e-01
1025
1026
Bram Moolenaar071d4272004-06-13 20:20:40 +00001027
Bram Moolenaar979243b2015-06-26 19:35:49 +02001028string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029------
1030"string" string constant *expr-quote*
1031
1032Note that double quotes are used.
1033
1034A string constant accepts these special characters:
1035\... three-digit octal number (e.g., "\316")
1036\.. two-digit octal number (must be followed by non-digit)
1037\. one-digit octal number (must be followed by non-digit)
1038\x.. byte specified with two hex numbers (e.g., "\x1f")
1039\x. byte specified with one hex number (must be followed by non-hex char)
1040\X.. same as \x..
1041\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001042\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001043 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001044\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001045\b backspace <BS>
1046\e escape <Esc>
1047\f formfeed <FF>
1048\n newline <NL>
1049\r return <CR>
1050\t tab <Tab>
1051\\ backslash
1052\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001053\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
1054 in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a
1055 utf-8 character, use \uxxxx as mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001056
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001057Note that "\xff" is stored as the byte 255, which may be invalid in some
1058encodings. Use "\u00ff" to store character 255 according to the current value
1059of 'encoding'.
1060
Bram Moolenaar071d4272004-06-13 20:20:40 +00001061Note that "\000" and "\x00" force the end of the string.
1062
1063
1064literal-string *literal-string* *E115*
1065---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001066'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001067
1068Note that single quotes are used.
1069
Bram Moolenaar446cb832008-06-24 21:56:24 +00001070This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001071meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001072
1073Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar446cb832008-06-24 21:56:24 +00001074to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001075 if a =~ "\\s*"
1076 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001077
1078
1079option *expr-option* *E112* *E113*
1080------
1081&option option value, local value if possible
1082&g:option global option value
1083&l:option local option value
1084
1085Examples: >
1086 echo "tabstop is " . &tabstop
1087 if &insertmode
1088
1089Any option name can be used here. See |options|. When using the local value
1090and there is no buffer-local or window-local value, the global value is used
1091anyway.
1092
1093
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001094register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001095--------
1096@r contents of register 'r'
1097
1098The result is the contents of the named register, as a single string.
1099Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar446cb832008-06-24 21:56:24 +00001100register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001101registers.
1102
1103When using the '=' register you get the expression itself, not what it
1104evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001105
1106
1107nesting *expr-nesting* *E110*
1108-------
1109(expr1) nested expression
1110
1111
1112environment variable *expr-env*
1113--------------------
1114$VAR environment variable
1115
1116The String value of any environment variable. When it is not defined, the
1117result is an empty string.
1118 *expr-env-expand*
1119Note that there is a difference between using $VAR directly and using
1120expand("$VAR"). Using it directly will only expand environment variables that
1121are known inside the current Vim session. Using expand() will first try using
1122the environment variables known inside the current Vim session. If that
1123fails, a shell will be used to expand the variable. This can be slow, but it
1124does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001125 :echo $shell
1126 :echo expand("$shell")
1127The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001128variable (if your shell supports it).
1129
1130
1131internal variable *expr-variable*
1132-----------------
1133variable internal variable
1134See below |internal-variables|.
1135
1136
Bram Moolenaar05159a02005-02-26 23:04:13 +00001137function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001138-------------
1139function(expr1, ...) function call
1140See below |functions|.
1141
1142
1143==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020011443. Internal variable *internal-variables* *E461*
1145
Bram Moolenaar071d4272004-06-13 20:20:40 +00001146An internal variable name can be made up of letters, digits and '_'. But it
1147cannot start with a digit. It's also possible to use curly braces, see
1148|curly-braces-names|.
1149
1150An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001151An internal variable is explicitly destroyed with the ":unlet" command
1152|:unlet|.
1153Using a name that is not an internal variable or refers to a variable that has
1154been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001155
1156There are several name spaces for variables. Which one is to be used is
1157specified by what is prepended:
1158
1159 (nothing) In a function: local to a function; otherwise: global
1160|buffer-variable| b: Local to the current buffer.
1161|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001162|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001163|global-variable| g: Global.
1164|local-variable| l: Local to a function.
1165|script-variable| s: Local to a |:source|'ed Vim script.
1166|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001167|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001168
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001169The scope name by itself can be used as a |Dictionary|. For example, to
1170delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001171 :for k in keys(s:)
1172 : unlet s:[k]
1173 :endfor
1174<
Bram Moolenaar531da592013-05-06 05:58:55 +02001175 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001176A variable name that is preceded with "b:" is local to the current buffer.
1177Thus you can have several "b:foo" variables, one for each buffer.
1178This kind of variable is deleted when the buffer is wiped out or deleted with
1179|:bdelete|.
1180
1181One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001182 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001183b:changedtick The total number of changes to the current buffer. It is
1184 incremented for each change. An undo command is also a change
1185 in this case. This can be used to perform an action only when
1186 the buffer has changed. Example: >
1187 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001188 : let my_changedtick = b:changedtick
1189 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001190 :endif
1191<
Bram Moolenaar531da592013-05-06 05:58:55 +02001192 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001193A variable name that is preceded with "w:" is local to the current window. It
1194is deleted when the window is closed.
1195
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001196 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001197A variable name that is preceded with "t:" is local to the current tab page,
1198It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001199without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001200
Bram Moolenaar531da592013-05-06 05:58:55 +02001201 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001202Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar446cb832008-06-24 21:56:24 +00001203access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001204place if you like.
1205
Bram Moolenaar531da592013-05-06 05:58:55 +02001206 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001208But you can also prepend "l:" if you like. However, without prepending "l:"
1209you may run into reserved variable names. For example "count". By itself it
1210refers to "v:count". Using "l:count" you can have a local variable with the
1211same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001212
1213 *script-variable* *s:var*
1214In a Vim script variables starting with "s:" can be used. They cannot be
1215accessed from outside of the scripts, thus are local to the script.
1216
1217They can be used in:
1218- commands executed while the script is sourced
1219- functions defined in the script
1220- autocommands defined in the script
1221- functions and autocommands defined in functions and autocommands which were
1222 defined in the script (recursively)
1223- user defined commands defined in the script
1224Thus not in:
1225- other scripts sourced from this one
1226- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001227- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001228- etc.
1229
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001230Script variables can be used to avoid conflicts with global variable names.
1231Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001232
1233 let s:counter = 0
1234 function MyCounter()
1235 let s:counter = s:counter + 1
1236 echo s:counter
1237 endfunction
1238 command Tick call MyCounter()
1239
1240You can now invoke "Tick" from any script, and the "s:counter" variable in
1241that script will not be changed, only the "s:counter" in the script where
1242"Tick" was defined is used.
1243
1244Another example that does the same: >
1245
1246 let s:counter = 0
1247 command Tick let s:counter = s:counter + 1 | echo s:counter
1248
1249When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001250script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001251defined.
1252
1253The script variables are also available when a function is defined inside a
1254function that is defined in a script. Example: >
1255
1256 let s:counter = 0
1257 function StartCounting(incr)
1258 if a:incr
1259 function MyCounter()
1260 let s:counter = s:counter + 1
1261 endfunction
1262 else
1263 function MyCounter()
1264 let s:counter = s:counter - 1
1265 endfunction
1266 endif
1267 endfunction
1268
1269This defines the MyCounter() function either for counting up or counting down
1270when calling StartCounting(). It doesn't matter from where StartCounting() is
1271called, the s:counter variable will be accessible in MyCounter().
1272
1273When the same script is sourced again it will use the same script variables.
1274They will remain valid as long as Vim is running. This can be used to
1275maintain a counter: >
1276
1277 if !exists("s:counter")
1278 let s:counter = 1
1279 echo "script executed for the first time"
1280 else
1281 let s:counter = s:counter + 1
1282 echo "script executed " . s:counter . " times now"
1283 endif
1284
1285Note that this means that filetype plugins don't get a different set of script
1286variables for each buffer. Use local buffer variables instead |b:var|.
1287
1288
Bram Moolenaar531da592013-05-06 05:58:55 +02001289Predefined Vim variables: *vim-variable* *v:var* *v:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001290
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001291 *v:beval_col* *beval_col-variable*
1292v:beval_col The number of the column, over which the mouse pointer is.
1293 This is the byte index in the |v:beval_lnum| line.
1294 Only valid while evaluating the 'balloonexpr' option.
1295
1296 *v:beval_bufnr* *beval_bufnr-variable*
1297v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1298 valid while evaluating the 'balloonexpr' option.
1299
1300 *v:beval_lnum* *beval_lnum-variable*
1301v:beval_lnum The number of the line, over which the mouse pointer is. Only
1302 valid while evaluating the 'balloonexpr' option.
1303
1304 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001305v:beval_text The text under or after the mouse pointer. Usually a word as
1306 it is useful for debugging a C program. 'iskeyword' applies,
1307 but a dot and "->" before the position is included. When on a
1308 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001309 word before it. When on a Visual area within one line the
1310 highlighted text is used.
1311 Only valid while evaluating the 'balloonexpr' option.
1312
1313 *v:beval_winnr* *beval_winnr-variable*
1314v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001315 valid while evaluating the 'balloonexpr' option. The first
1316 window has number zero (unlike most other places where a
1317 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001318
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001319 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001320v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001321 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001322 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001323
Bram Moolenaar071d4272004-06-13 20:20:40 +00001324 *v:charconvert_from* *charconvert_from-variable*
1325v:charconvert_from
1326 The name of the character encoding of a file to be converted.
1327 Only valid while evaluating the 'charconvert' option.
1328
1329 *v:charconvert_to* *charconvert_to-variable*
1330v:charconvert_to
1331 The name of the character encoding of a file after conversion.
1332 Only valid while evaluating the 'charconvert' option.
1333
1334 *v:cmdarg* *cmdarg-variable*
1335v:cmdarg This variable is used for two purposes:
1336 1. The extra arguments given to a file read/write command.
1337 Currently these are "++enc=" and "++ff=". This variable is
1338 set before an autocommand event for a file read/write
1339 command is triggered. There is a leading space to make it
1340 possible to append this variable directly after the
Bram Moolenaar446cb832008-06-24 21:56:24 +00001341 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001342 included here, because it will be executed anyway.
1343 2. When printing a PostScript file with ":hardcopy" this is
1344 the argument for the ":hardcopy" command. This can be used
1345 in 'printexpr'.
1346
1347 *v:cmdbang* *cmdbang-variable*
1348v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1349 was used the value is 1, otherwise it is 0. Note that this
1350 can only be used in autocommands. For user commands |<bang>|
1351 can be used.
1352
Bram Moolenaar42a45122015-07-10 17:56:23 +02001353 *v:completed_item* *completed_item-variable*
1354v:completed_item
1355 |Dictionary| containing the |complete-items| for the most
1356 recently completed word after |CompleteDone|. The
1357 |Dictionary| is empty if the completion failed.
1358
Bram Moolenaar071d4272004-06-13 20:20:40 +00001359 *v:count* *count-variable*
1360v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar446cb832008-06-24 21:56:24 +00001361 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001362 :map _x :<C-U>echo "the count is " . v:count<CR>
1363< Note: The <C-U> is required to remove the line range that you
1364 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001365 When there are two counts, as in "3d2w", they are multiplied,
1366 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001367 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001368 "count" also works, for backwards compatibility.
1369
1370 *v:count1* *count1-variable*
1371v:count1 Just like "v:count", but defaults to one when no count is
1372 used.
1373
1374 *v:ctype* *ctype-variable*
1375v:ctype The current locale setting for characters of the runtime
1376 environment. This allows Vim scripts to be aware of the
1377 current locale encoding. Technical: it's the value of
1378 LC_CTYPE. When not using a locale the value is "C".
1379 This variable can not be set directly, use the |:language|
1380 command.
1381 See |multi-lang|.
1382
1383 *v:dying* *dying-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001384v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001385 one. When multiple signals are caught the number increases.
1386 Can be used in an autocommand to check if Vim didn't
1387 terminate normally. {only works on Unix}
1388 Example: >
1389 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001390< Note: if another deadly signal is caught when v:dying is one,
1391 VimLeave autocommands will not be executed.
1392
Bram Moolenaar071d4272004-06-13 20:20:40 +00001393 *v:errmsg* *errmsg-variable*
1394v:errmsg Last given error message. It's allowed to set this variable.
1395 Example: >
1396 :let v:errmsg = ""
1397 :silent! next
1398 :if v:errmsg != ""
1399 : ... handle error
1400< "errmsg" also works, for backwards compatibility.
1401
Bram Moolenaar43345542015-11-29 17:35:35 +01001402 *v:errors* *errors-variable*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001403v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001404 This is a list of strings.
1405 The assert functions append an item when an assert fails.
1406 To remove old results make it empty: >
1407 :let v:errors = []
1408< If v:errors is set to anything but a list it is made an empty
1409 list by the assert function.
1410
Bram Moolenaar071d4272004-06-13 20:20:40 +00001411 *v:exception* *exception-variable*
1412v:exception The value of the exception most recently caught and not
1413 finished. See also |v:throwpoint| and |throw-variables|.
1414 Example: >
1415 :try
1416 : throw "oops"
1417 :catch /.*/
1418 : echo "caught" v:exception
1419 :endtry
1420< Output: "caught oops".
1421
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001422 *v:false* *false-variable*
1423v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001424 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001425 When used as a string this evaluates to "false". >
1426 echo v:false
1427< false ~
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001428
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001429 *v:fcs_reason* *fcs_reason-variable*
1430v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1431 Can be used in an autocommand to decide what to do and/or what
1432 to set v:fcs_choice to. Possible values:
1433 deleted file no longer exists
1434 conflict file contents, mode or timestamp was
1435 changed and buffer is modified
1436 changed file contents has changed
1437 mode mode of file changed
1438 time only file timestamp changed
1439
1440 *v:fcs_choice* *fcs_choice-variable*
1441v:fcs_choice What should happen after a |FileChangedShell| event was
1442 triggered. Can be used in an autocommand to tell Vim what to
1443 do with the affected buffer:
1444 reload Reload the buffer (does not work if
1445 the file was deleted).
1446 ask Ask the user what to do, as if there
1447 was no autocommand. Except that when
1448 only the timestamp changed nothing
1449 will happen.
1450 <empty> Nothing, the autocommand should do
1451 everything that needs to be done.
1452 The default is empty. If another (invalid) value is used then
1453 Vim behaves like it is empty, there is no warning message.
1454
Bram Moolenaar071d4272004-06-13 20:20:40 +00001455 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001456v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001457 option used for ~
1458 'charconvert' file to be converted
1459 'diffexpr' original file
1460 'patchexpr' original file
1461 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001462 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001463
1464 *v:fname_out* *fname_out-variable*
1465v:fname_out The name of the output file. Only valid while
1466 evaluating:
1467 option used for ~
1468 'charconvert' resulting converted file (*)
1469 'diffexpr' output of diff
1470 'patchexpr' resulting patched file
1471 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar446cb832008-06-24 21:56:24 +00001472 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001473 for a read command (e.g., ":e file") it will be a temporary
1474 file and different from v:fname_in.
1475
1476 *v:fname_new* *fname_new-variable*
1477v:fname_new The name of the new version of the file. Only valid while
1478 evaluating 'diffexpr'.
1479
1480 *v:fname_diff* *fname_diff-variable*
1481v:fname_diff The name of the diff (patch) file. Only valid while
1482 evaluating 'patchexpr'.
1483
1484 *v:folddashes* *folddashes-variable*
1485v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1486 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001487 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001488
1489 *v:foldlevel* *foldlevel-variable*
1490v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001491 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001492
1493 *v:foldend* *foldend-variable*
1494v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001495 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001496
1497 *v:foldstart* *foldstart-variable*
1498v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001499 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001500
Bram Moolenaar817a8802013-11-09 01:44:43 +01001501 *v:hlsearch* *hlsearch-variable*
Bram Moolenaar76440e22014-11-27 19:14:49 +01001502v:hlsearch Variable that indicates whether search highlighting is on.
1503 Setting it makes sense only if 'hlsearch' is enabled which
1504 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001505 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001506 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001507< Note that the value is restored when returning from a
1508 function. |function-search-undo|.
1509
Bram Moolenaar843ee412004-06-30 16:16:41 +00001510 *v:insertmode* *insertmode-variable*
1511v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1512 events. Values:
1513 i Insert mode
1514 r Replace mode
1515 v Virtual Replace mode
1516
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001517 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001518v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001519 evaluating the expression used with |map()| and |filter()|.
1520 Read-only.
1521
Bram Moolenaar071d4272004-06-13 20:20:40 +00001522 *v:lang* *lang-variable*
1523v:lang The current locale setting for messages of the runtime
1524 environment. This allows Vim scripts to be aware of the
1525 current language. Technical: it's the value of LC_MESSAGES.
1526 The value is system dependent.
1527 This variable can not be set directly, use the |:language|
1528 command.
1529 It can be different from |v:ctype| when messages are desired
1530 in a different language than what is used for character
1531 encoding. See |multi-lang|.
1532
1533 *v:lc_time* *lc_time-variable*
1534v:lc_time The current locale setting for time messages of the runtime
1535 environment. This allows Vim scripts to be aware of the
1536 current language. Technical: it's the value of LC_TIME.
1537 This variable can not be set directly, use the |:language|
1538 command. See |multi-lang|.
1539
1540 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001541v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1542 'indentexpr' expressions, tab page number for 'guitablabel'
1543 and 'guitabtooltip'. Only valid while one of these
1544 expressions is being evaluated. Read-only when in the
1545 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001546
Bram Moolenaar219b8702006-11-01 14:32:36 +00001547 *v:mouse_win* *mouse_win-variable*
1548v:mouse_win Window number for a mouse click obtained with |getchar()|.
1549 First window has number 1, like with |winnr()|. The value is
1550 zero when there was no mouse button click.
1551
1552 *v:mouse_lnum* *mouse_lnum-variable*
1553v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1554 This is the text line number, not the screen line number. The
1555 value is zero when there was no mouse button click.
1556
1557 *v:mouse_col* *mouse_col-variable*
1558v:mouse_col Column number for a mouse click obtained with |getchar()|.
1559 This is the screen column number, like with |virtcol()|. The
1560 value is zero when there was no mouse button click.
1561
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001562 *v:none* *none-variable*
1563v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001564 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001565 When used as a number this evaluates to zero.
1566 When used as a string this evaluates to "none". >
1567 echo v:none
1568< none ~
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001569
1570 *v:null* *null-variable*
1571v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001572 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001573 When used as a number this evaluates to zero.
1574 When used as a string this evaluates to "null". >
1575 echo v:null
1576< null ~
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001577
Bram Moolenaard812df62008-11-09 12:46:09 +00001578 *v:oldfiles* *oldfiles-variable*
1579v:oldfiles List of file names that is loaded from the |viminfo| file on
1580 startup. These are the files that Vim remembers marks for.
1581 The length of the List is limited by the ' argument of the
1582 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001583 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001584 Also see |:oldfiles| and |c_#<|.
1585 The List can be modified, but this has no effect on what is
1586 stored in the |viminfo| file later. If you use values other
1587 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001588 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001589
Bram Moolenaar53744302015-07-17 17:38:22 +02001590 *v:option_new*
1591v:option_new New value of the option. Valid while executing an |OptionSet|
1592 autocommand.
1593 *v:option_old*
1594v:option_old Old value of the option. Valid while executing an |OptionSet|
1595 autocommand.
1596 *v:option_type*
1597v:option_type Scope of the set command. Valid while executing an
1598 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001599 *v:operator* *operator-variable*
1600v:operator The last operator given in Normal mode. This is a single
1601 character except for commands starting with <g> or <z>,
1602 in which case it is two characters. Best used alongside
1603 |v:prevcount| and |v:register|. Useful if you want to cancel
1604 Operator-pending mode and then use the operator, e.g.: >
1605 :omap O <Esc>:call MyMotion(v:operator)<CR>
1606< The value remains set until another operator is entered, thus
1607 don't expect it to be empty.
1608 v:operator is not set for |:delete|, |:yank| or other Ex
1609 commands.
1610 Read-only.
1611
Bram Moolenaar071d4272004-06-13 20:20:40 +00001612 *v:prevcount* *prevcount-variable*
1613v:prevcount The count given for the last but one Normal mode command.
1614 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001615 you want to cancel Visual or Operator-pending mode and then
1616 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001617 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1618< Read-only.
1619
Bram Moolenaar05159a02005-02-26 23:04:13 +00001620 *v:profiling* *profiling-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001621v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001622 See |profiling|.
1623
Bram Moolenaar071d4272004-06-13 20:20:40 +00001624 *v:progname* *progname-variable*
1625v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001626 invoked. Allows you to do special initialisations for |view|,
1627 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001628 Read-only.
1629
Bram Moolenaara1706c92014-04-01 19:55:49 +02001630 *v:progpath* *progpath-variable*
1631v:progpath Contains the command with which Vim was invoked, including the
1632 path. Useful if you want to message a Vim server using a
1633 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001634 To get the full path use: >
1635 echo exepath(v:progpath)
1636< NOTE: This does not work when the command is a relative path
1637 and the current directory has changed.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001638 Read-only.
1639
Bram Moolenaar071d4272004-06-13 20:20:40 +00001640 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001641v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001642 command (regardless of whether that command actually used a
1643 register). Or for the currently executing normal mode mapping
1644 (use this in custom commands that take a register).
1645 If none is supplied it is the default register '"', unless
1646 'clipboard' contains "unnamed" or "unnamedplus", then it is
1647 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001648 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001649
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001650 *v:scrollstart* *scrollstart-variable*
1651v:scrollstart String describing the script or function that caused the
1652 screen to scroll up. It's only set when it is empty, thus the
1653 first reason is remembered. It is set to "Unknown" for a
1654 typed command.
1655 This can be used to find out why your script causes the
1656 hit-enter prompt.
1657
Bram Moolenaar071d4272004-06-13 20:20:40 +00001658 *v:servername* *servername-variable*
1659v:servername The resulting registered |x11-clientserver| name if any.
1660 Read-only.
1661
Bram Moolenaar446cb832008-06-24 21:56:24 +00001662
1663v:searchforward *v:searchforward* *searchforward-variable*
1664 Search direction: 1 after a forward search, 0 after a
1665 backward search. It is reset to forward when directly setting
1666 the last search pattern, see |quote/|.
1667 Note that the value is restored when returning from a
1668 function. |function-search-undo|.
1669 Read-write.
1670
Bram Moolenaar071d4272004-06-13 20:20:40 +00001671 *v:shell_error* *shell_error-variable*
1672v:shell_error Result of the last shell command. When non-zero, the last
1673 shell command had an error. When zero, there was no problem.
1674 This only works when the shell returns the error code to Vim.
1675 The value -1 is often used when the command could not be
1676 executed. Read-only.
1677 Example: >
1678 :!mv foo bar
1679 :if v:shell_error
1680 : echo 'could not rename "foo" to "bar"!'
1681 :endif
1682< "shell_error" also works, for backwards compatibility.
1683
1684 *v:statusmsg* *statusmsg-variable*
1685v:statusmsg Last given status message. It's allowed to set this variable.
1686
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001687 *v:swapname* *swapname-variable*
1688v:swapname Only valid when executing |SwapExists| autocommands: Name of
1689 the swap file found. Read-only.
1690
1691 *v:swapchoice* *swapchoice-variable*
1692v:swapchoice |SwapExists| autocommands can set this to the selected choice
1693 for handling an existing swap file:
1694 'o' Open read-only
1695 'e' Edit anyway
1696 'r' Recover
1697 'd' Delete swapfile
1698 'q' Quit
1699 'a' Abort
Bram Moolenaar446cb832008-06-24 21:56:24 +00001700 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001701 results in the user being asked, as would happen when there is
1702 no SwapExists autocommand. The default is empty.
1703
Bram Moolenaarb3480382005-12-11 21:33:32 +00001704 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001705v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001706 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar446cb832008-06-24 21:56:24 +00001707 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001708 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001709 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001710
Bram Moolenaar071d4272004-06-13 20:20:40 +00001711 *v:termresponse* *termresponse-variable*
1712v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar446cb832008-06-24 21:56:24 +00001713 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001714 that starts with ESC [ or CSI and ends in a 'c', with only
1715 digits, ';' and '.' in between.
1716 When this option is set, the TermResponse autocommand event is
1717 fired, so that you can react to the response from the
1718 terminal.
1719 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1720 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1721 patch level (since this was introduced in patch 95, it's
1722 always 95 or bigger). Pc is always zero.
1723 {only when compiled with |+termresponse| feature}
1724
1725 *v:this_session* *this_session-variable*
1726v:this_session Full filename of the last loaded or saved session file. See
1727 |:mksession|. It is allowed to set this variable. When no
1728 session file has been saved, this variable is empty.
1729 "this_session" also works, for backwards compatibility.
1730
1731 *v:throwpoint* *throwpoint-variable*
1732v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001733 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001734 also |v:exception| and |throw-variables|.
1735 Example: >
1736 :try
1737 : throw "oops"
1738 :catch /.*/
1739 : echo "Exception from" v:throwpoint
1740 :endtry
1741< Output: "Exception from test.vim, line 2"
1742
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001743 *v:true* *true-variable*
1744v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001745 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001746 When used as a string this evaluates to "true". >
1747 echo v:true
1748< true ~
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001749 *v:val* *val-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001750v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001751 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001752 |filter()|. Read-only.
1753
Bram Moolenaar071d4272004-06-13 20:20:40 +00001754 *v:version* *version-variable*
1755v:version Version number of Vim: Major version number times 100 plus
1756 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1757 is 501. Read-only. "version" also works, for backwards
1758 compatibility.
1759 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02001760 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001761< Note that patch numbers are specific to the version, thus both
1762 version 5.0 and 5.1 may have a patch 123, but these are
1763 completely different.
1764
1765 *v:warningmsg* *warningmsg-variable*
1766v:warningmsg Last given warning message. It's allowed to set this variable.
1767
Bram Moolenaar727c8762010-10-20 19:17:48 +02001768 *v:windowid* *windowid-variable*
1769v:windowid When any X11 based GUI is running or when running in a
1770 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001771 set to the window ID.
1772 When an MS-Windows GUI is running this will be set to the
1773 window handle.
1774 Otherwise the value is zero.
1775 Note: for windows inside Vim use |winnr()|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001776
Bram Moolenaar071d4272004-06-13 20:20:40 +00001777==============================================================================
17784. Builtin Functions *functions*
1779
1780See |function-list| for a list grouped by what the function is used for.
1781
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001782(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001783
1784USAGE RESULT DESCRIPTION ~
1785
Bram Moolenaar446cb832008-06-24 21:56:24 +00001786abs( {expr}) Float or Number absolute value of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001787acos( {expr}) Float arc cosine of {expr}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001788add( {list}, {item}) List append {item} to |List| {list}
Bram Moolenaaracb4f222016-01-10 15:59:26 +01001789alloc_fail( {id}, {countdown}, {repeat})
1790 none make memory allocation fail
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001791and( {expr}, {expr}) Number bitwise AND
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001792append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001793append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001794argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001795argidx() Number current index in the argument list
Bram Moolenaar683fa182015-11-30 21:38:24 +01001796arglistid( [{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02001797 Number argument list id
Bram Moolenaar071d4272004-06-13 20:20:40 +00001798argv( {nr}) String {nr} entry of the argument list
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001799argv() List the argument list
Bram Moolenaara803c7f2016-01-15 15:31:39 +01001800assert_equal( {exp}, {act} [, {msg}]) none assert {exp} equals {act}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001801assert_exception( {error} [, {msg}]) none assert {error} is in v:exception
Bram Moolenaara260b872016-01-15 20:48:22 +01001802assert_fails( {cmd} [, {error}]) none assert {cmd} fails
Bram Moolenaara803c7f2016-01-15 15:31:39 +01001803assert_false( {actual} [, {msg}]) none assert {actual} is false
1804assert_true( {actual} [, {msg}]) none assert {actual} is true
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001805asin( {expr}) Float arc sine of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001806atan( {expr}) Float arc tangent of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001807atan2( {expr}, {expr}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001808browse( {save}, {title}, {initdir}, {default})
1809 String put up a file requester
Bram Moolenaar446cb832008-06-24 21:56:24 +00001810browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001811bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001812buflisted( {expr}) Number TRUE if buffer {expr} is listed
1813bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001814bufname( {expr}) String Name of the buffer {expr}
Bram Moolenaar12969c02015-09-08 23:36:10 +02001815bufnr( {expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001816bufwinnr( {expr}) Number window number of buffer {expr}
1817byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001818byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01001819byteidxcomp( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001820call( {func}, {arglist} [, {dict}])
1821 any call {func} with arguments {arglist}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001822ceil( {expr}) Float round {expr} up
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001823ch_close( {handle}) none close {handle}
1824ch_evalexpr( {handle}, {expr} [, {options}])
1825 any evaluate {expr} on JSON {handle}
1826ch_evalraw( {handle}, {string} [, {options}])
1827 any evaluate {string} on raw {handle}
1828ch_getbufnr( {handle}, {what}) Number get buffer number for {handle}/{what}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01001829ch_getjob( {channel}) Job get the Job of {channel}
Bram Moolenaar03602ec2016-03-20 20:57:45 +01001830ch_info( {handle}) String info about channel {handle}
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001831ch_log( {msg} [, {handle}]) none write {msg} in the channel log file
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001832ch_logfile( {fname} [, {mode}]) none start logging channel activity
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001833ch_open( {address} [, {options}]) Channel open a channel to {address}
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001834ch_read( {handle} [, {options}]) String read from {handle}
1835ch_readraw( {handle} [, {options}]) String read raw from {handle}
1836ch_sendexpr( {handle}, {expr} [, {options}])
1837 any send {expr} over JSON {handle}
1838ch_sendraw( {handle}, {string} [, {options}])
1839 any send {string} over raw {handle}
1840ch_setoptions( {handle}, {options}) none set options for {handle}
Bram Moolenaar03602ec2016-03-20 20:57:45 +01001841ch_status( {handle}) String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001842changenr() Number current change number
Bram Moolenaard35d7842013-01-23 17:17:10 +01001843char2nr( {expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001844cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001845clearmatches() none clear all matches
Bram Moolenaar071d4272004-06-13 20:20:40 +00001846col( {expr}) Number column nr of cursor or mark
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001847complete( {startcol}, {matches}) none set Insert mode completion
Bram Moolenaar572cb562005-08-05 21:35:02 +00001848complete_add( {expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00001849complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001850confirm( {msg} [, {choices} [, {default} [, {type}]]])
1851 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001852copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001853cos( {expr}) Float cosine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001854cosh( {expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02001855count( {list}, {expr} [, {ic} [, {start}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001856 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001857cscope_connection( [{num} , {dbpath} [, {prepend}]])
1858 Number checks existence of cscope connection
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01001859cursor( {lnum}, {col} [, {off}])
1860 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar0b238792006-03-02 22:49:12 +00001861cursor( {list}) Number move cursor to position in {list}
Bram Moolenaar92dff182014-02-11 19:15:50 +01001862deepcopy( {expr} [, {noref}]) any make a full copy of {expr}
Bram Moolenaarda440d22016-01-16 21:27:23 +01001863delete( {fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001864did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001865diff_filler( {lnum}) Number diff filler lines about {lnum}
1866diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001867disable_char_avail_for_testing( {expr}) none test without typeahead
Bram Moolenaar13065c42005-01-08 16:08:21 +00001868empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001869escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001870eval( {string}) any evaluate {string} into its value
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001871eventhandler() Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001872executable( {expr}) Number 1 if executable {expr} exists
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001873exepath( {expr}) String full path of the command {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001874exists( {expr}) Number TRUE if {expr} exists
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001875extend( {expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001876 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001877exp( {expr}) Float exponential of {expr}
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001878expand( {expr} [, {nosuf} [, {list}]])
1879 any expand special keywords in {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001880feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001881filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001882filewritable( {file}) Number TRUE if {file} is a writable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001883filter( {expr}, {string}) List/Dict remove items from {expr} where
1884 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001885finddir( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001886 String find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001887findfile( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001888 String find file {name} in {path}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001889float2nr( {expr}) Number convert Float {expr} to a Number
1890floor( {expr}) Float round {expr} down
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001891fmod( {expr1}, {expr2}) Float remainder of {expr1} / {expr2}
Bram Moolenaaraebaf892008-05-28 14:49:58 +00001892fnameescape( {fname}) String escape special characters in {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001893fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001894foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1895foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001896foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001897foldtext() String line displayed for closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001898foldtextresult( {lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001899foreground() Number bring the Vim window to the foreground
Bram Moolenaar1735bc92016-03-14 23:05:14 +01001900function({name} [, {arglist}] [, {dict}])
1901 Funcref reference to function {name}
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001902garbagecollect( [{atexit}]) none free memory, breaking cyclic references
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001903get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001904get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001905getbufline( {expr}, {lnum} [, {end}])
1906 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001907getbufvar( {expr}, {varname} [, {def}])
1908 any variable {varname} in buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001909getchar( [expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001910getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02001911getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00001912getcmdline() String return the current command-line
1913getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02001914getcmdtype() String return current command-line type
1915getcmdwintype() String return current command-line window type
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02001916getcurpos() List position of the cursor
Bram Moolenaarc9703302016-01-17 21:49:33 +01001917getcwd( [{winnr} [, {tabnr}]]) String get the current working directory
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02001918getfontname( [{name}]) String name of font being used
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001919getfperm( {fname}) String file permissions of file {fname}
1920getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001921getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001922getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001923getline( {lnum}) String line {lnum} of current buffer
1924getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001925getloclist( {nr}) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001926getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00001927getpid() Number process ID of Vim
Bram Moolenaar0b238792006-03-02 22:49:12 +00001928getpos( {expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001929getqflist() List list of quickfix items
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02001930getreg( [{regname} [, 1 [, {list}]]])
1931 String or List contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001932getregtype( [{regname}]) String type of register
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001933gettabvar( {nr}, {varname} [, {def}])
1934 any variable {varname} in tab {nr} or {def}
1935gettabwinvar( {tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001936 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001937getwinposx() Number X coord in pixels of GUI Vim window
1938getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001939getwinvar( {nr}, {varname} [, {def}])
1940 any variable {varname} in window {nr}
Bram Moolenaard8b77f72015-03-05 21:21:19 +01001941glob( {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001942 any expand file wildcards in {expr}
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01001943glob2regpat( {expr}) String convert a glob pat into a search pat
Bram Moolenaard8b77f72015-03-05 21:21:19 +01001944globpath( {path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00001945 String do glob({expr}) for all dirs in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001946has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001947has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaarc9703302016-01-17 21:49:33 +01001948haslocaldir( [{winnr} [, {tabnr}]])
1949 Number TRUE if the window executed |:lcd|
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001950hasmapto( {what} [, {mode} [, {abbr}]])
1951 Number TRUE if mapping to {what} exists
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001952histadd( {history}, {item}) String add an item to a history
Bram Moolenaar071d4272004-06-13 20:20:40 +00001953histdel( {history} [, {item}]) String remove an item from a history
1954histget( {history} [, {index}]) String get the item {index} from a history
1955histnr( {history}) Number highest index of a history
1956hlexists( {name}) Number TRUE if highlight group {name} exists
1957hlID( {name}) Number syntax ID of highlight group {name}
1958hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001959iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1960indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001961index( {list}, {expr} [, {start} [, {ic}]])
1962 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001963input( {prompt} [, {text} [, {completion}]])
1964 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001965inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001966inputlist( {textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001967inputrestore() Number restore typeahead
1968inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001969inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001970insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001971invert( {expr}) Number bitwise invert
Bram Moolenaar071d4272004-06-13 20:20:40 +00001972isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001973islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaarf3913272016-02-25 00:00:01 +01001974isnan( {expr}) Number TRUE if {expr} is NaN
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001975items( {dict}) List key-value pairs in {dict}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01001976job_getchannel( {job}) Channel get the channel handle for {job}
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01001977job_info( {job}) Dict get information about {job}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01001978job_setoptions( {job}, {options}) none set options for {job}
1979job_start( {command} [, {options}]) Job start a job
1980job_status( {job}) String get the status of {job}
1981job_stop( {job} [, {how}]) Number stop {job}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001982join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01001983js_decode( {string}) any decode JS style JSON
1984js_encode( {expr}) String encode JS style JSON
1985json_decode( {string}) any decode JSON
1986json_encode( {expr}) String encode JSON
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001987keys( {dict}) List keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001988len( {expr}) Number the length of {expr}
1989libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001990libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1991line( {expr}) Number line nr of cursor, last line or mark
1992line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001993lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001994localtime() Number current time
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001995log( {expr}) Float natural logarithm (base e) of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001996log10( {expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaard38b0552012-04-25 19:07:41 +02001997luaeval( {expr}[, {expr}]) any evaluate |Lua| expression
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001998map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaarbd743252010-10-20 21:23:33 +02001999maparg( {name}[, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002000 String or Dict
2001 rhs of mapping {name} in mode {mode}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002002mapcheck( {name}[, {mode} [, {abbr}]])
2003 String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002004match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002005 Number position where {pat} matches in {expr}
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002006matchadd( {group}, {pattern}[, {priority}[, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002007 Number highlight {pattern} with {group}
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002008matchaddpos( {group}, {pos}[, {priority}[, {id}[, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002009 Number highlight positions with {group}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002010matcharg( {nr}) List arguments of |:match|
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002011matchdelete( {id}) Number delete match identified by {id}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002012matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002013 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002014matchlist( {expr}, {pat}[, {start}[, {count}]])
2015 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002016matchstr( {expr}, {pat}[, {start}[, {count}]])
2017 String {count}'th match of {pat} in {expr}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002018max( {list}) Number maximum value of items in {list}
2019min( {list}) Number minimum value of items in {list}
2020mkdir( {name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002021 Number create directory {name}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002022mode( [expr]) String current editing mode
Bram Moolenaar7e506b62010-01-19 15:55:06 +01002023mzeval( {expr}) any evaluate |MzScheme| expression
Bram Moolenaar071d4272004-06-13 20:20:40 +00002024nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaard35d7842013-01-23 17:17:10 +01002025nr2char( {expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002026or( {expr}, {expr}) Number bitwise OR
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002027pathshorten( {expr}) String shorten directory names in a path
Bram Moolenaare9b892e2016-01-17 21:15:58 +01002028perleval( {expr}) any evaluate |Perl| expression
Bram Moolenaar446cb832008-06-24 21:56:24 +00002029pow( {x}, {y}) Float {x} to the power of {y}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002030prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002031printf( {fmt}, {expr1}...) String format text
2032pumvisible() Number whether popup menu is visible
Bram Moolenaar30b65812012-07-12 22:01:11 +02002033pyeval( {expr}) any evaluate |Python| expression
2034py3eval( {expr}) any evaluate |python3| expression
Bram Moolenaard8b02732005-01-14 21:48:43 +00002035range( {expr} [, {max} [, {stride}]])
2036 List items from {expr} to {max}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002037readfile( {fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002038 List get list of lines from file {fname}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002039reltime( [{start} [, {end}]]) List get time value
2040reltimestr( {time}) String turn time value into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00002041remote_expr( {server}, {string} [, {idvar}])
2042 String send expression
2043remote_foreground( {server}) Number bring Vim server to the foreground
2044remote_peek( {serverid} [, {retvar}])
2045 Number check for reply string
2046remote_read( {serverid}) String read reply string
2047remote_send( {server}, {string} [, {idvar}])
2048 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002049remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002050remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002051rename( {from}, {to}) Number rename (move) file from {from} to {to}
2052repeat( {expr}, {count}) String repeat {expr} {count} times
2053resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002054reverse( {list}) List reverse {list} in-place
Bram Moolenaar446cb832008-06-24 21:56:24 +00002055round( {expr}) Float round off {expr}
Bram Moolenaar9a773482013-06-11 18:40:13 +02002056screenattr( {row}, {col}) Number attribute at screen position
2057screenchar( {row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002058screencol() Number current cursor column
2059screenrow() Number current cursor row
Bram Moolenaar76929292008-01-06 19:07:36 +00002060search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
2061 Number search for {pattern}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002062searchdecl( {name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002063 Number search for variable declaration
Bram Moolenaar76929292008-01-06 19:07:36 +00002064searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002065 Number search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00002066searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002067 List search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00002068searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002069 List search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002070server2client( {clientid}, {string})
2071 Number send reply string
2072serverlist() String get a list of available servers
2073setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
Bram Moolenaardbd24b52015-08-11 14:26:19 +02002074setcharsearch( {dict}) Dict set character search from {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002075setcmdpos( {pos}) Number set cursor position in command-line
Bram Moolenaar80492532016-03-08 17:08:53 +01002076setfperm( {fname}, {mode}) Number set {fname} file permissions to {mode}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002077setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002078setloclist( {nr}, {list}[, {action}])
2079 Number modify location list using {list}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002080setmatches( {list}) Number restore a list of matches
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002081setpos( {expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002082setqflist( {list}[, {action}]) Number modify quickfix list using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002083setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar06b5d512010-05-22 15:37:44 +02002084settabvar( {nr}, {varname}, {val}) set {varname} in tab page {nr} to {val}
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002085settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
2086 {winnr} in tab page {tabnr} to {val}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002087setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01002088sha256( {string}) String SHA256 checksum of {string}
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002089shellescape( {string} [, {special}])
2090 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002091 command argument
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02002092shiftwidth() Number effective value of 'shiftwidth'
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002093simplify( {filename}) String simplify filename as much as possible
Bram Moolenaar446cb832008-06-24 21:56:24 +00002094sin( {expr}) Float sine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002095sinh( {expr}) Float hyperbolic sine of {expr}
Bram Moolenaar5f894962011-06-19 02:55:37 +02002096sort( {list} [, {func} [, {dict}]])
2097 List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00002098soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002099spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002100spellsuggest( {word} [, {max} [, {capital}]])
2101 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002102split( {expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002103 List make |List| from {pat} separated {expr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01002104sqrt( {expr}) Float square root of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002105str2float( {expr}) Float convert String to Float
2106str2nr( {expr} [, {base}]) Number convert String to Number
Bram Moolenaar641e48c2015-06-25 16:09:26 +02002107strchars( {expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaardc536092010-07-18 15:45:49 +02002108strdisplaywidth( {expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002109strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002110stridx( {haystack}, {needle}[, {start}])
2111 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002112string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00002113strlen( {expr}) Number length of the String {expr}
2114strpart( {src}, {start}[, {len}])
2115 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00002116strridx( {haystack}, {needle} [, {start}])
2117 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002118strtrans( {expr}) String translate string to make it printable
Bram Moolenaar72597a52010-07-18 15:31:08 +02002119strwidth( {expr}) Number display cell length of the String {expr}
Bram Moolenaar41571762014-04-02 19:00:58 +02002120submatch( {nr}[, {list}]) String or List
2121 specific match in ":s" or substitute()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002122substitute( {expr}, {pat}, {sub}, {flags})
2123 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00002124synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002125synIDattr( {synID}, {what} [, {mode}])
2126 String attribute {what} of syntax ID {synID}
2127synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaar483c5d82010-10-20 18:45:33 +02002128synconcealed( {lnum}, {col}) List info about concealing
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002129synstack( {lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002130system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02002131systemlist( {expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00002132tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
2133tabpagenr( [{arg}]) Number number of current or last tab page
2134tabpagewinnr( {tabarg}[, {arg}])
2135 Number number of current window in tab page
2136taglist( {expr}) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002137tagfiles() List tags files used
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002138tan( {expr}) Float tangent of {expr}
2139tanh( {expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002140tempname() String name for a temporary file
2141timer_start( {time}, {callback} [, {options}])
2142 Number create a timer
2143timer_stop( {timer}) none stop a timer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002144tolower( {expr}) String the String {expr} switched to lowercase
2145toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00002146tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
2147 to chars in {tostr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01002148trunc( {expr}) Float truncate Float {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002149type( {name}) Number type of variable {name}
Bram Moolenaara17d4c12010-05-30 18:30:36 +02002150undofile( {name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002151undotree() List undo file tree
Bram Moolenaar327aa022014-03-25 18:24:23 +01002152uniq( {list} [, {func} [, {dict}]])
2153 List remove adjacent duplicates from a list
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002154values( {dict}) List values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002155virtcol( {expr}) Number screen column of cursor or mark
2156visualmode( [expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002157wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01002158win_findbuf( {bufnr}) List find windows containing {bufnr}
Bram Moolenaar86edef62016-03-13 18:07:30 +01002159win_getid( [{win} [, {tab}]]) Number get window ID for {win} in {tab}
2160win_gotoid( {expr}) Number go to window with ID {expr}
2161win_id2tabwin( {expr}) List get tab and window nr from window ID
2162win_id2win( {expr}) Number get window nr from window ID
Bram Moolenaar071d4272004-06-13 20:20:40 +00002163winbufnr( {nr}) Number buffer number of window {nr}
2164wincol() Number window column of the cursor
2165winheight( {nr}) Number height of window {nr}
2166winline() Number window line of the cursor
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00002167winnr( [{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002168winrestcmd() String returns command to restore window sizes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002169winrestview( {dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002170winsaveview() Dict save view of current window
Bram Moolenaar071d4272004-06-13 20:20:40 +00002171winwidth( {nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002172wordcount() Dict get byte/char/word statistics
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01002173writefile( {list}, {fname} [, {flags}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002174 Number write list of lines to file {fname}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002175xor( {expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002176
Bram Moolenaar446cb832008-06-24 21:56:24 +00002177abs({expr}) *abs()*
2178 Return the absolute value of {expr}. When {expr} evaluates to
2179 a |Float| abs() returns a |Float|. When {expr} can be
2180 converted to a |Number| abs() returns a |Number|. Otherwise
2181 abs() gives an error message and returns -1.
2182 Examples: >
2183 echo abs(1.456)
2184< 1.456 >
2185 echo abs(-5.456)
2186< 5.456 >
2187 echo abs(-4)
2188< 4
2189 {only available when compiled with the |+float| feature}
2190
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002191
2192acos({expr}) *acos()*
2193 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002194 |Float| in the range of [0, pi].
2195 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002196 [-1, 1].
2197 Examples: >
2198 :echo acos(0)
2199< 1.570796 >
2200 :echo acos(-0.5)
2201< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002202 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002203
2204
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002205add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002206 Append the item {expr} to |List| {list}. Returns the
2207 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002208 :let alist = add([1, 2, 3], item)
2209 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002210< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002211 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002212 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002213
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002214
Bram Moolenaar75bdf6a2016-01-07 21:25:08 +01002215alloc_fail({id}, {countdown}, {repeat}) *alloc_fail()*
2216 This is for testing: If the memory allocation with {id} is
2217 called, then decrement {countdown}, and when it reaches zero
2218 let memory allocation fail {repeat} times. When {repeat} is
2219 smaller than one it fails one time.
2220
2221
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002222and({expr}, {expr}) *and()*
2223 Bitwise AND on the two arguments. The arguments are converted
2224 to a number. A List, Dict or Float argument causes an error.
2225 Example: >
2226 :let flag = and(bits, 0x80)
2227
2228
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002229append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002230 When {expr} is a |List|: Append each item of the |List| as a
2231 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002232 Otherwise append {expr} as one text line below line {lnum} in
2233 the current buffer.
2234 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002235 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar446cb832008-06-24 21:56:24 +00002236 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002237 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002238 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002239<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002240 *argc()*
2241argc() The result is the number of files in the argument list of the
2242 current window. See |arglist|.
2243
2244 *argidx()*
2245argidx() The result is the current index in the argument list. 0 is
2246 the first file. argc() - 1 is the last one. See |arglist|.
2247
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002248 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002249arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002250 Return the argument list ID. This is a number which
2251 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002252 global argument list. See |arglist|.
2253 Return -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002254
2255 Without arguments use the current window.
2256 With {winnr} only use this window in the current tab page.
2257 With {winnr} and {tabnr} use the window in the specified tab
2258 page.
2259
Bram Moolenaar071d4272004-06-13 20:20:40 +00002260 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002261argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002262 current window. See |arglist|. "argv(0)" is the first one.
2263 Example: >
2264 :let i = 0
2265 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002266 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002267 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2268 : let i = i + 1
2269 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002270< Without the {nr} argument a |List| with the whole |arglist| is
2271 returned.
2272
Bram Moolenaar683fa182015-11-30 21:38:24 +01002273 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002274assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002275 When {expected} and {actual} are not equal an error message is
2276 added to |v:errors|.
2277 There is no automatic conversion, the String "4" is different
2278 from the Number 4. And the number 4 is different from the
2279 Float 4.0. The value of 'ignorecase' is not used here, case
2280 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002281 When {msg} is omitted an error in the form "Expected
2282 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002283 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002284 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002285< Will result in a string to be added to |v:errors|:
2286 test.vim line 12: Expected 'foo' but got 'bar' ~
2287
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002288assert_exception({error} [, {msg}]) *assert_exception()*
2289 When v:exception does not contain the string {error} an error
2290 message is added to |v:errors|.
2291 This can be used to assert that a command throws an exception.
2292 Using the error number, followed by a colon, avoids problems
2293 with translations: >
2294 try
2295 commandthatfails
2296 call assert_false(1, 'command should have failed')
2297 catch
2298 call assert_exception('E492:')
2299 endtry
2300
Bram Moolenaara260b872016-01-15 20:48:22 +01002301assert_fails({cmd} [, {error}]) *assert_fails()*
2302 Run {cmd} and add an error message to |v:errors| if it does
2303 NOT produce an error.
2304 When {error} is given it must match |v:errmsg|.
2305
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002306assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002307 When {actual} is not false an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002308 |v:errors|, like with |assert_equal()|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002309 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002310 number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002311 When {msg} is omitted an error in the form "Expected False but
2312 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002313
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002314assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002315 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002316 |v:errors|, like with |assert_equal()|.
2317 A value is true when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002318 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002319 When {msg} is omitted an error in the form "Expected True but
2320 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002321
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002322asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002323 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002324 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002325 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002326 [-1, 1].
2327 Examples: >
2328 :echo asin(0.8)
2329< 0.927295 >
2330 :echo asin(-0.5)
2331< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002332 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002333
2334
Bram Moolenaar446cb832008-06-24 21:56:24 +00002335atan({expr}) *atan()*
2336 Return the principal value of the arc tangent of {expr}, in
2337 the range [-pi/2, +pi/2] radians, as a |Float|.
2338 {expr} must evaluate to a |Float| or a |Number|.
2339 Examples: >
2340 :echo atan(100)
2341< 1.560797 >
2342 :echo atan(-4.01)
2343< -1.326405
2344 {only available when compiled with the |+float| feature}
2345
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002346
2347atan2({expr1}, {expr2}) *atan2()*
2348 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002349 radians, as a |Float| in the range [-pi, pi].
2350 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002351 Examples: >
2352 :echo atan2(-1, 1)
2353< -0.785398 >
2354 :echo atan2(1, -1)
2355< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002356 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002357
2358
Bram Moolenaar071d4272004-06-13 20:20:40 +00002359 *browse()*
2360browse({save}, {title}, {initdir}, {default})
2361 Put up a file requester. This only works when "has("browse")"
2362 returns non-zero (only in some GUI versions).
2363 The input fields are:
2364 {save} when non-zero, select file to write
2365 {title} title for the requester
2366 {initdir} directory to start browsing in
2367 {default} default file name
2368 When the "Cancel" button is hit, something went wrong, or
2369 browsing is not possible, an empty string is returned.
2370
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002371 *browsedir()*
2372browsedir({title}, {initdir})
2373 Put up a directory requester. This only works when
2374 "has("browse")" returns non-zero (only in some GUI versions).
2375 On systems where a directory browser is not supported a file
2376 browser is used. In that case: select a file in the directory
2377 to be used.
2378 The input fields are:
2379 {title} title for the requester
2380 {initdir} directory to start browsing in
2381 When the "Cancel" button is hit, something went wrong, or
2382 browsing is not possible, an empty string is returned.
2383
Bram Moolenaar071d4272004-06-13 20:20:40 +00002384bufexists({expr}) *bufexists()*
2385 The result is a Number, which is non-zero if a buffer called
2386 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002387 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002388 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002389 exactly. The name can be:
2390 - Relative to the current directory.
2391 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002392 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002393 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002394 Unlisted buffers will be found.
2395 Note that help files are listed by their short name in the
2396 output of |:buffers|, but bufexists() requires using their
2397 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002398 bufexists() may report a buffer exists, but to use the name
2399 with a |:buffer| command you may need to use |expand()|. Esp
2400 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002401 Use "bufexists(0)" to test for the existence of an alternate
2402 file name.
2403 *buffer_exists()*
2404 Obsolete name: buffer_exists().
2405
2406buflisted({expr}) *buflisted()*
2407 The result is a Number, which is non-zero if a buffer called
2408 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002409 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002410
2411bufloaded({expr}) *bufloaded()*
2412 The result is a Number, which is non-zero if a buffer called
2413 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002414 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002415
2416bufname({expr}) *bufname()*
2417 The result is the name of a buffer, as it is displayed by the
2418 ":ls" command.
2419 If {expr} is a Number, that buffer number's name is given.
2420 Number zero is the alternate buffer for the current window.
2421 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002422 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002423 set and 'cpoptions' is empty. When there is more than one
2424 match an empty string is returned.
2425 "" or "%" can be used for the current buffer, "#" for the
2426 alternate buffer.
2427 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002428 or middle of the buffer name is accepted. If you only want a
2429 full match then put "^" at the start and "$" at the end of the
2430 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002431 Listed buffers are found first. If there is a single match
2432 with a listed buffer, that one is returned. Next unlisted
2433 buffers are searched for.
2434 If the {expr} is a String, but you want to use it as a buffer
2435 number, force it to be a Number by adding zero to it: >
2436 :echo bufname("3" + 0)
2437< If the buffer doesn't exist, or doesn't have a name, an empty
2438 string is returned. >
2439 bufname("#") alternate buffer name
2440 bufname(3) name of buffer 3
2441 bufname("%") name of current buffer
2442 bufname("file2") name of buffer where "file2" matches.
2443< *buffer_name()*
2444 Obsolete name: buffer_name().
2445
2446 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002447bufnr({expr} [, {create}])
2448 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002449 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002450 above.
2451 If the buffer doesn't exist, -1 is returned. Or, if the
2452 {create} argument is present and not zero, a new, unlisted,
2453 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002454 bufnr("$") is the last buffer: >
2455 :let last_buffer = bufnr("$")
2456< The result is a Number, which is the highest buffer number
2457 of existing buffers. Note that not all buffers with a smaller
2458 number necessarily exist, because ":bwipeout" may have removed
2459 them. Use bufexists() to test for the existence of a buffer.
2460 *buffer_number()*
2461 Obsolete name: buffer_number().
2462 *last_buffer_nr()*
2463 Obsolete name for bufnr("$"): last_buffer_nr().
2464
2465bufwinnr({expr}) *bufwinnr()*
2466 The result is a Number, which is the number of the first
2467 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar446cb832008-06-24 21:56:24 +00002468 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002469 there is no such window, -1 is returned. Example: >
2470
2471 echo "A window containing buffer 1 is " . (bufwinnr(1))
2472
2473< The number can be used with |CTRL-W_w| and ":wincmd w"
2474 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002475 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002476
Bram Moolenaar071d4272004-06-13 20:20:40 +00002477byte2line({byte}) *byte2line()*
2478 Return the line number that contains the character at byte
2479 count {byte} in the current buffer. This includes the
2480 end-of-line character, depending on the 'fileformat' option
2481 for the current buffer. The first character has byte count
2482 one.
2483 Also see |line2byte()|, |go| and |:goto|.
2484 {not available when compiled without the |+byte_offset|
2485 feature}
2486
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002487byteidx({expr}, {nr}) *byteidx()*
2488 Return byte index of the {nr}'th character in the string
2489 {expr}. Use zero for the first character, it returns zero.
2490 This function is only useful when there are multibyte
2491 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002492 Composing characters are not counted separately, their byte
2493 length is added to the preceding base character. See
2494 |byteidxcomp()| below for counting composing characters
2495 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002496 Example : >
2497 echo matchstr(str, ".", byteidx(str, 3))
2498< will display the fourth character. Another way to do the
2499 same: >
2500 let s = strpart(str, byteidx(str, 3))
2501 echo strpart(s, 0, byteidx(s, 1))
2502< If there are less than {nr} characters -1 is returned.
2503 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002504 in bytes is returned.
2505
2506byteidxcomp({expr}, {nr}) *byteidxcomp()*
2507 Like byteidx(), except that a composing character is counted
2508 as a separate character. Example: >
2509 let s = 'e' . nr2char(0x301)
2510 echo byteidx(s, 1)
2511 echo byteidxcomp(s, 1)
2512 echo byteidxcomp(s, 2)
2513< The first and third echo result in 3 ('e' plus composing
2514 character is 3 bytes), the second echo results in 1 ('e' is
2515 one byte).
2516 Only works different from byteidx() when 'encoding' is set to
2517 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002518
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002519call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002520 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002521 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002522 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002523 a:firstline and a:lastline are set to the cursor line.
2524 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002525 {dict} is for functions with the "dict" attribute. It will be
2526 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002527
Bram Moolenaar446cb832008-06-24 21:56:24 +00002528ceil({expr}) *ceil()*
2529 Return the smallest integral value greater than or equal to
2530 {expr} as a |Float| (round up).
2531 {expr} must evaluate to a |Float| or a |Number|.
2532 Examples: >
2533 echo ceil(1.456)
2534< 2.0 >
2535 echo ceil(-5.456)
2536< -5.0 >
2537 echo ceil(4.0)
2538< 4.0
2539 {only available when compiled with the |+float| feature}
2540
Bram Moolenaarca003e12006-03-17 23:19:38 +00002541changenr() *changenr()*
2542 Return the number of the most recent change. This is the same
2543 number as what is displayed with |:undolist| and can be used
2544 with the |:undo| command.
2545 When a change was made it is the number of that change. After
2546 redo it is the number of the redone change. After undo it is
2547 one less than the number of the undone change.
2548
Bram Moolenaard35d7842013-01-23 17:17:10 +01002549char2nr({expr}[, {utf8}]) *char2nr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002550 Return number value of the first char in {expr}. Examples: >
2551 char2nr(" ") returns 32
2552 char2nr("ABC") returns 65
Bram Moolenaard35d7842013-01-23 17:17:10 +01002553< When {utf8} is omitted or zero, the current 'encoding' is used.
2554 Example for "utf-8": >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002555 char2nr("á") returns 225
2556 char2nr("á"[0]) returns 195
Bram Moolenaard35d7842013-01-23 17:17:10 +01002557< With {utf8} set to 1, always treat as utf-8 characters.
2558 A combining character is a separate character.
Bram Moolenaar97293012011-07-18 19:40:27 +02002559 |nr2char()| does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002560
2561cindent({lnum}) *cindent()*
2562 Get the amount of indent for line {lnum} according the C
2563 indenting rules, as with 'cindent'.
2564 The indent is counted in spaces, the value of 'tabstop' is
2565 relevant. {lnum} is used just like in |getline()|.
2566 When {lnum} is invalid or Vim was not compiled the |+cindent|
2567 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00002568 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002569
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002570clearmatches() *clearmatches()*
2571 Clears all matches previously defined by |matchadd()| and the
2572 |:match| commands.
2573
Bram Moolenaar071d4272004-06-13 20:20:40 +00002574 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002575col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00002576 position given with {expr}. The accepted positions are:
2577 . the cursor position
2578 $ the end of the cursor line (the result is the
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02002579 number of bytes in the cursor line plus one)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002580 'x position of mark x (if the mark is not set, 0 is
2581 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01002582 v In Visual mode: the start of the Visual area (the
2583 cursor is the end). When not in Visual mode
2584 returns the cursor position. Differs from |'<| in
2585 that it's updated right away.
Bram Moolenaar477933c2007-07-17 14:32:23 +00002586 Additionally {expr} can be [lnum, col]: a |List| with the line
2587 and column number. Most useful when the column is "$", to get
Bram Moolenaar446cb832008-06-24 21:56:24 +00002588 the last column of a specific line. When "lnum" or "col" is
Bram Moolenaar477933c2007-07-17 14:32:23 +00002589 out of range then col() returns zero.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002590 To get the line number use |line()|. To get both use
Bram Moolenaar0b238792006-03-02 22:49:12 +00002591 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002592 For the screen column position use |virtcol()|.
2593 Note that only marks in the current file can be used.
2594 Examples: >
2595 col(".") column of cursor
2596 col("$") length of cursor line plus one
2597 col("'t") column of mark t
2598 col("'" . markname) column of mark markname
Bram Moolenaar446cb832008-06-24 21:56:24 +00002599< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002600 For an uppercase mark the column may actually be in another
2601 buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002602 For the cursor position, when 'virtualedit' is active, the
2603 column is one higher if the cursor is after the end of the
2604 line. This can be used to obtain the column in Insert mode: >
2605 :imap <F2> <C-O>:let save_ve = &ve<CR>
2606 \<C-O>:set ve=all<CR>
2607 \<C-O>:echo col(".") . "\n" <Bar>
2608 \let &ve = save_ve<CR>
2609<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002610
Bram Moolenaara94bc432006-03-10 21:42:59 +00002611complete({startcol}, {matches}) *complete()* *E785*
2612 Set the matches for Insert mode completion.
2613 Can only be used in Insert mode. You need to use a mapping
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002614 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2615 with an expression mapping.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002616 {startcol} is the byte offset in the line where the completed
2617 text start. The text up to the cursor is the original text
2618 that will be replaced by the matches. Use col('.') for an
2619 empty string. "col('.') - 1" will replace one character by a
2620 match.
2621 {matches} must be a |List|. Each |List| item is one match.
2622 See |complete-items| for the kind of items that are possible.
2623 Note that the after calling this function you need to avoid
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002624 inserting anything that would cause completion to stop.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002625 The match can be selected with CTRL-N and CTRL-P as usual with
2626 Insert mode completion. The popup menu will appear if
2627 specified, see |ins-completion-menu|.
2628 Example: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002629 inoremap <F5> <C-R>=ListMonths()<CR>
Bram Moolenaara94bc432006-03-10 21:42:59 +00002630
2631 func! ListMonths()
2632 call complete(col('.'), ['January', 'February', 'March',
2633 \ 'April', 'May', 'June', 'July', 'August', 'September',
2634 \ 'October', 'November', 'December'])
2635 return ''
2636 endfunc
2637< This isn't very useful, but it shows how it works. Note that
2638 an empty string is returned to avoid a zero being inserted.
2639
Bram Moolenaar572cb562005-08-05 21:35:02 +00002640complete_add({expr}) *complete_add()*
2641 Add {expr} to the list of matches. Only to be used by the
2642 function specified with the 'completefunc' option.
2643 Returns 0 for failure (empty string or out of memory),
2644 1 when the match was added, 2 when the match was already in
2645 the list.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002646 See |complete-functions| for an explanation of {expr}. It is
Bram Moolenaar39f05632006-03-19 22:15:26 +00002647 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002648
2649complete_check() *complete_check()*
2650 Check for a key typed while looking for completion matches.
2651 This is to be used when looking for matches takes some time.
2652 Returns non-zero when searching for matches is to be aborted,
2653 zero otherwise.
2654 Only to be used by the function specified with the
2655 'completefunc' option.
2656
Bram Moolenaar071d4272004-06-13 20:20:40 +00002657 *confirm()*
2658confirm({msg} [, {choices} [, {default} [, {type}]]])
2659 Confirm() offers the user a dialog, from which a choice can be
2660 made. It returns the number of the choice. For the first
2661 choice this is 1.
2662 Note: confirm() is only supported when compiled with dialog
2663 support, see |+dialog_con| and |+dialog_gui|.
Bram Moolenaara800b422010-06-27 01:15:55 +02002664
Bram Moolenaar071d4272004-06-13 20:20:40 +00002665 {msg} is displayed in a |dialog| with {choices} as the
2666 alternatives. When {choices} is missing or empty, "&OK" is
2667 used (and translated).
2668 {msg} is a String, use '\n' to include a newline. Only on
2669 some systems the string is wrapped when it doesn't fit.
Bram Moolenaara800b422010-06-27 01:15:55 +02002670
Bram Moolenaar071d4272004-06-13 20:20:40 +00002671 {choices} is a String, with the individual choices separated
2672 by '\n', e.g. >
2673 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2674< The letter after the '&' is the shortcut key for that choice.
2675 Thus you can type 'c' to select "Cancel". The shortcut does
2676 not need to be the first letter: >
2677 confirm("file has been modified", "&Save\nSave &All")
2678< For the console, the first letter of each choice is used as
2679 the default shortcut key.
Bram Moolenaara800b422010-06-27 01:15:55 +02002680
Bram Moolenaar071d4272004-06-13 20:20:40 +00002681 The optional {default} argument is the number of the choice
2682 that is made if the user hits <CR>. Use 1 to make the first
2683 choice the default one. Use 0 to not set a default. If
2684 {default} is omitted, 1 is used.
Bram Moolenaara800b422010-06-27 01:15:55 +02002685
2686 The optional {type} argument gives the type of dialog. This
2687 is only used for the icon of the GTK, Mac, Motif and Win32
2688 GUI. It can be one of these values: "Error", "Question",
2689 "Info", "Warning" or "Generic". Only the first character is
2690 relevant. When {type} is omitted, "Generic" is used.
2691
Bram Moolenaar071d4272004-06-13 20:20:40 +00002692 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2693 or another valid interrupt key, confirm() returns 0.
2694
2695 An example: >
2696 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2697 :if choice == 0
2698 : echo "make up your mind!"
2699 :elseif choice == 3
2700 : echo "tasteful"
2701 :else
2702 : echo "I prefer bananas myself."
2703 :endif
2704< In a GUI dialog, buttons are used. The layout of the buttons
2705 depends on the 'v' flag in 'guioptions'. If it is included,
Bram Moolenaar446cb832008-06-24 21:56:24 +00002706 the buttons are always put vertically. Otherwise, confirm()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002707 tries to put the buttons in one horizontal line. If they
2708 don't fit, a vertical layout is used anyway. For some systems
2709 the horizontal layout is always used.
2710
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002711ch_close({handle}) *ch_close()*
2712 Close {handle}. See |channel-close|.
2713 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002714
2715 Note that a channel is closed in three stages:
2716 - The I/O ends, log message: "Closing channel". There can
2717 still be queued messages to read or callbacks to invoke.
2718 - The readahead is cleared, log message: "Clearing channel".
2719 Some variables may still reference the channel.
2720 - The channel is freed, log message: "Freeing channel".
2721
Bram Moolenaar835dc632016-02-07 14:27:38 +01002722 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002723
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002724ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
2725 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002726 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01002727 with a raw channel. See |channel-use|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002728 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002729 *E917*
2730 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002731 entry. It can have a "timeout" entry.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002732
2733 ch_evalexpr() waits for a response and returns the decoded
2734 expression. When there is an error or timeout it returns an
2735 empty string.
2736
2737 {only available when compiled with the |+channel| feature}
2738
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002739ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
2740 Send {string} over {handle}.
2741 {handle} can be Channel or a Job that has a Channel.
2742
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002743 Works like |ch_evalexpr()|, but does not encode the request or
2744 decode the response. The caller is responsible for the
2745 correct contents. Also does not add a newline for a channel
2746 in NL mode, the caller must do that. The NL in the response
2747 is removed.
2748 See |channel-use|.
2749
2750 {only available when compiled with the |+channel| feature}
2751
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002752ch_getbufnr({handle}, {what}) *ch_getbufnr()*
2753 Get the buffer number that {handle} is using for {what}.
2754 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01002755 {what} can be "err" for stderr, "out" for stdout or empty for
2756 socket output.
2757 Returns -1 when there is no buffer.
2758 {only available when compiled with the |+channel| feature}
2759
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002760ch_getjob({channel}) *ch_getjob()*
2761 Get the Job associated with {channel}.
2762 If there is no job calling |job_status()| on the returned Job
2763 will result in "fail".
2764
2765 {only available when compiled with the |+channel| and
2766 |+job| features}
2767
Bram Moolenaar03602ec2016-03-20 20:57:45 +01002768ch_info({handle}) *ch_info()*
2769 Returns a Dictionary with information about {handle}. The
2770 items are:
2771 "id" number of the channel
2772 "status" "open" (any part is open) or "closed"
2773 When opened with ch_open():
2774 "hostname" the hostname of the address
2775 "port" the port of the address
2776 "sock_status" "open" or "closed"
2777 "sock_mode" "NL", "RAW", "JSON" or "JS"
2778 "sock_io" "socket"
2779 "sock_timeout" timeout in msec
2780 When opened with job_start():
2781 "out_status" "open" or "closed"
2782 "out_mode" "NL", "RAW", "JSON" or "JS"
2783 "out_io" "null", "pipe", "file" or "buffer"
2784 "out_timeout" timeout in msec
2785 "err_status" "open" or "closed"
2786 "err_mode" "NL", "RAW", "JSON" or "JS"
2787 "err_io" "out", "null", "pipe", "file" or "buffer"
2788 "err_timeout" timeout in msec
2789 "in_status" "open" or "closed"
2790 "in_mode" "NL", "RAW", "JSON" or "JS"
2791 "in_io" "null", "pipe", "file" or "buffer"
2792 "in_timeout" timeout in msec
2793
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002794ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002795 Write {msg} in the channel log file, if it was opened with
2796 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002797 When {handle} is passed the channel number is used for the
2798 message.
2799 {handle} can be Channel or a Job that has a Channel. The
2800 Channel must open.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002801
2802ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002803 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002804 When {fname} is an empty string: stop logging.
2805
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002806 When {mode} is omitted or "a" append to the file.
2807 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002808
2809 The file is flushed after every message, on Unix you can use
2810 "tail -f" to see what is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002811
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002812
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002813ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002814 Open a channel to {address}. See |channel|.
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002815 Returns a Channel. Use |ch_status()| to check for
2816 failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002817
2818 {address} has the form "hostname:port", e.g.,
2819 "localhost:8765".
2820
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002821 If {options} is given it must be a |Dictionary|. The optional
Bram Moolenaar4d919d72016-02-05 22:36:41 +01002822 items are:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01002823 mode "raw", "js" or "json".
Bram Moolenaar4d919d72016-02-05 22:36:41 +01002824 Default "json".
2825 callback function to call for requests with a zero
2826 sequence number. See |channel-callback|.
2827 Default: none.
2828 waittime Specify connect timeout as milliseconds.
2829 Negative means forever.
Bram Moolenaar835dc632016-02-07 14:27:38 +01002830 Default: 0 (don't wait)
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002831 timeout Specify response read timeout value in
Bram Moolenaar4d919d72016-02-05 22:36:41 +01002832 milliseconds.
2833 Default: 2000.
Bram Moolenaar835dc632016-02-07 14:27:38 +01002834 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002835
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002836ch_read({handle} [, {options}]) *ch_read()*
2837 Read from {handle} and return the received message.
2838 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002839
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002840 This uses the channel timeout. When there is nothing to read
2841 within that time an empty string is returned. To specify a
2842 different timeout in msec use the "timeout" option:
2843 {"timeout": 123} ~
2844 To read from the error output use the "part" option:
2845 {"part": "err"} ~
2846 To read a message with a specific ID, on a JS or JSON channel:
2847 {"id": 99} ~
2848 When no ID is specified or the ID is -1, the first message is
2849 returned. This overrules any callback waiting for this
2850 message.
2851
2852 For a RAW channel this returns whatever is available, since
2853 Vim does not know where a message ends.
2854 For a NL channel this returns one message.
2855 For a JS or JSON channel this returns one decoded message.
2856 This includes any sequence number.
2857
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002858ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002859 Like ch_read() but for a JS and JSON channel does not decode
2860 the message.
2861
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002862ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
2863 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01002864 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01002865 with a raw channel. See |channel-use|. *E912*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002866 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002867
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002868 {options} must be a Dictionary. The "callback" item is a
2869 Funcref or the name of a function it is invoked when the
2870 response is received. See |channel-callback|.
2871 Without "callback" the channel handler is invoked, otherwise
2872 any received message is dropped.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002873
Bram Moolenaar835dc632016-02-07 14:27:38 +01002874 {only available when compiled with the |+channel| feature}
2875
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002876ch_sendraw({handle}, {string} [, {options}]) *ch_sendraw()*
2877 Send {string} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01002878 Works like |ch_sendexpr()|, but does not encode the request or
2879 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01002880 correct contents. Also does not add a newline for a channel
2881 in NL mode, the caller must do that. The NL in the response
2882 is removed.
2883 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002884
Bram Moolenaar835dc632016-02-07 14:27:38 +01002885 {only available when compiled with the |+channel| feature}
2886
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002887ch_setoptions({handle}, {options}) *ch_setoptions()*
2888 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002889 "callback" the channel callback
2890 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002891 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002892 See |ch_open()| for more explanation.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002893 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002894
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002895 Note that changing the mode may cause queued messages to be
2896 lost.
2897
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002898 These options cannot be changed:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002899 "waittime" only applies to "ch_open()|
2900
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002901ch_status({handle}) *ch_status()*
2902 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01002903 "fail" failed to open the channel
2904 "open" channel can be used
2905 "closed" channel can not be used
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002906 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002907
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002908 *copy()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002909copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002910 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002911 When {expr} is a |List| a shallow copy is created. This means
2912 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002913 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01002914 changing an item changes the contents of both |Lists|.
2915 A |Dictionary| is copied in a similar way as a |List|.
2916 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002917
Bram Moolenaar446cb832008-06-24 21:56:24 +00002918cos({expr}) *cos()*
2919 Return the cosine of {expr}, measured in radians, as a |Float|.
2920 {expr} must evaluate to a |Float| or a |Number|.
2921 Examples: >
2922 :echo cos(100)
2923< 0.862319 >
2924 :echo cos(-4.01)
2925< -0.646043
2926 {only available when compiled with the |+float| feature}
2927
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002928
2929cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002930 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002931 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002932 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002933 Examples: >
2934 :echo cosh(0.5)
2935< 1.127626 >
2936 :echo cosh(-0.5)
2937< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02002938 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002939
Bram Moolenaar446cb832008-06-24 21:56:24 +00002940
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002941count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002942 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002943 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002944 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002945 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002946 When {ic} is given and it's non-zero then case is ignored.
2947
2948
Bram Moolenaar071d4272004-06-13 20:20:40 +00002949 *cscope_connection()*
2950cscope_connection([{num} , {dbpath} [, {prepend}]])
2951 Checks for the existence of a |cscope| connection. If no
2952 parameters are specified, then the function returns:
2953 0, if cscope was not available (not compiled in), or
2954 if there are no cscope connections;
2955 1, if there is at least one cscope connection.
2956
2957 If parameters are specified, then the value of {num}
2958 determines how existence of a cscope connection is checked:
2959
2960 {num} Description of existence check
2961 ----- ------------------------------
2962 0 Same as no parameters (e.g., "cscope_connection()").
2963 1 Ignore {prepend}, and use partial string matches for
2964 {dbpath}.
2965 2 Ignore {prepend}, and use exact string matches for
2966 {dbpath}.
2967 3 Use {prepend}, use partial string matches for both
2968 {dbpath} and {prepend}.
2969 4 Use {prepend}, use exact string matches for both
2970 {dbpath} and {prepend}.
2971
2972 Note: All string comparisons are case sensitive!
2973
2974 Examples. Suppose we had the following (from ":cs show"): >
2975
2976 # pid database name prepend path
2977 0 27664 cscope.out /usr/local
2978<
2979 Invocation Return Val ~
2980 ---------- ---------- >
2981 cscope_connection() 1
2982 cscope_connection(1, "out") 1
2983 cscope_connection(2, "out") 0
2984 cscope_connection(3, "out") 0
2985 cscope_connection(3, "out", "local") 1
2986 cscope_connection(4, "out") 0
2987 cscope_connection(4, "out", "local") 0
2988 cscope_connection(4, "cscope.out", "/usr/local") 1
2989<
Bram Moolenaar0b238792006-03-02 22:49:12 +00002990cursor({lnum}, {col} [, {off}]) *cursor()*
2991cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002992 Positions the cursor at the column (byte count) {col} in the
2993 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02002994
Bram Moolenaar0b238792006-03-02 22:49:12 +00002995 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02002996 with two, three or four item:
2997 [{lnum}, {col}, {off}]
2998 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02002999 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003000 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003001
Bram Moolenaar071d4272004-06-13 20:20:40 +00003002 Does not change the jumplist.
3003 If {lnum} is greater than the number of lines in the buffer,
3004 the cursor will be positioned at the last line in the buffer.
3005 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003006 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003007 the cursor will be positioned at the last character in the
3008 line.
3009 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003010 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003011 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003012
Bram Moolenaar0b238792006-03-02 22:49:12 +00003013 When 'virtualedit' is used {off} specifies the offset in
3014 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003015 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003016 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003017
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003018
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003019deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003020 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003021 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003022 When {expr} is a |List| a full copy is created. This means
3023 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003024 copy, and vice versa. When an item is a |List| or
3025 |Dictionary|, a copy for it is made, recursively. Thus
3026 changing an item in the copy does not change the contents of
3027 the original |List|.
3028 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003029 When {noref} is omitted or zero a contained |List| or
3030 |Dictionary| is only copied once. All references point to
3031 this single copy. With {noref} set to 1 every occurrence of a
3032 |List| or |Dictionary| results in a new copy. This also means
3033 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003034 *E724*
3035 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003036 that refers back to a higher level making a deep copy with
3037 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003038 Also see |copy()|.
3039
Bram Moolenaarda440d22016-01-16 21:27:23 +01003040delete({fname} [, {flags}]) *delete()*
3041 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003042 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003043
3044 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003045 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003046
3047 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003048 {fname} and everything in it, recursively. BE CAREFUL!
3049 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003050
3051 The result is a Number, which is 0 if the delete operation was
3052 successful and -1 when the deletion failed or partly failed.
3053
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003054 Use |remove()| to delete an item from a |List|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +01003055 To delete a line from the buffer use |:delete|. Use |:exe|
3056 when the line number is in a variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003057
3058 *did_filetype()*
3059did_filetype() Returns non-zero when autocommands are being executed and the
3060 FileType event has been triggered at least once. Can be used
3061 to avoid triggering the FileType event again in the scripts
3062 that detect the file type. |FileType|
3063 When editing another file, the counter is reset, thus this
3064 really checks if the FileType event has been triggered for the
3065 current buffer. This allows an autocommand that starts
3066 editing another buffer to set 'filetype' and load a syntax
3067 file.
3068
Bram Moolenaar47136d72004-10-12 20:02:24 +00003069diff_filler({lnum}) *diff_filler()*
3070 Returns the number of filler lines above line {lnum}.
3071 These are the lines that were inserted at this point in
3072 another diff'ed window. These filler lines are shown in the
3073 display but don't exist in the buffer.
3074 {lnum} is used like with |getline()|. Thus "." is the current
3075 line, "'m" mark m, etc.
3076 Returns 0 if the current window is not in diff mode.
3077
3078diff_hlID({lnum}, {col}) *diff_hlID()*
3079 Returns the highlight ID for diff mode at line {lnum} column
3080 {col} (byte index). When the current line does not have a
3081 diff change zero is returned.
3082 {lnum} is used like with |getline()|. Thus "." is the current
3083 line, "'m" mark m, etc.
3084 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3085 line.
3086 The highlight ID can be used with |synIDattr()| to obtain
3087 syntax information about the highlighting.
3088
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003089 *disable_char_avail_for_testing()*
3090disable_char_avail_for_testing({expr})
3091 When {expr} is 1 the internal char_avail() function will
3092 return FALSE. When {expr} is 0 the char_avail() function will
3093 function normally.
3094 Only use this for a test where typeahead causes the test not
3095 to work. E.g., to trigger the CursorMovedI autocommand event.
3096
Bram Moolenaar13065c42005-01-08 16:08:21 +00003097empty({expr}) *empty()*
3098 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003099 - A |List| or |Dictionary| is empty when it does not have any
3100 items.
3101 - A Number and Float is empty when its value is zero.
3102 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
3103 - A Job is empty when it failed to start.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003104 - A Channel is empty when it is closed.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003105
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003106 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003107 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003108
Bram Moolenaar071d4272004-06-13 20:20:40 +00003109escape({string}, {chars}) *escape()*
3110 Escape the characters in {chars} that occur in {string} with a
3111 backslash. Example: >
3112 :echo escape('c:\program files\vim', ' \')
3113< results in: >
3114 c:\\program\ files\\vim
Bram Moolenaar446cb832008-06-24 21:56:24 +00003115< Also see |shellescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003116
Bram Moolenaar446cb832008-06-24 21:56:24 +00003117 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003118eval({string}) Evaluate {string} and return the result. Especially useful to
3119 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003120 This works for Numbers, Floats, Strings and composites of
3121 them. Also works for |Funcref|s that refer to existing
3122 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003123
Bram Moolenaar071d4272004-06-13 20:20:40 +00003124eventhandler() *eventhandler()*
3125 Returns 1 when inside an event handler. That is that Vim got
3126 interrupted while waiting for the user to type a character,
3127 e.g., when dropping a file on Vim. This means interactive
3128 commands cannot be used. Otherwise zero is returned.
3129
3130executable({expr}) *executable()*
3131 This function checks if an executable with the name {expr}
3132 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003133 arguments.
3134 executable() uses the value of $PATH and/or the normal
3135 searchpath for programs. *PATHEXT*
3136 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3137 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar446cb832008-06-24 21:56:24 +00003138 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3139 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003140 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar446cb832008-06-24 21:56:24 +00003141 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003142 Unix shell, then the name is also tried without adding an
3143 extension.
3144 On MS-DOS and MS-Windows it only checks if the file exists and
3145 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003146 On MS-Windows an executable in the same directory as Vim is
3147 always found. Since this directory is added to $PATH it
3148 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003149 The result is a Number:
3150 1 exists
3151 0 does not exist
3152 -1 not implemented on this system
3153
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003154exepath({expr}) *exepath()*
3155 If {expr} is an executable and is either an absolute path, a
3156 relative path or found in $PATH, return the full path.
3157 Note that the current directory is used when {expr} starts
3158 with "./", which may be a problem for Vim: >
3159 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003160< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003161 an empty string is returned.
3162
Bram Moolenaar071d4272004-06-13 20:20:40 +00003163 *exists()*
3164exists({expr}) The result is a Number, which is non-zero if {expr} is
3165 defined, zero otherwise. The {expr} argument is a string,
3166 which contains one of these:
3167 &option-name Vim option (only checks if it exists,
3168 not if it really works)
3169 +option-name Vim option that works.
3170 $ENVNAME environment variable (could also be
3171 done by comparing with an empty
3172 string)
3173 *funcname built-in function (see |functions|)
3174 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02003175 |user-functions|). Also works for a
3176 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003177 varname internal variable (see
Bram Moolenaar446cb832008-06-24 21:56:24 +00003178 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003179 for |curly-braces-names|, |Dictionary|
3180 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00003181 that evaluating an index may cause an
3182 error message for an invalid
3183 expression. E.g.: >
3184 :let l = [1, 2, 3]
3185 :echo exists("l[5]")
3186< 0 >
3187 :echo exists("l[xx]")
3188< E121: Undefined variable: xx
3189 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00003190 :cmdname Ex command: built-in command, user
3191 command or command modifier |:command|.
3192 Returns:
3193 1 for match with start of a command
3194 2 full match with a command
3195 3 matches several user commands
3196 To check for a supported command
3197 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00003198 :2match The |:2match| command.
3199 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003200 #event autocommand defined for this event
3201 #event#pattern autocommand defined for this event and
3202 pattern (the pattern is taken
3203 literally and compared to the
3204 autocommand patterns character by
3205 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003206 #group autocommand group exists
3207 #group#event autocommand defined for this group and
3208 event.
3209 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003210 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003211 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003212 ##event autocommand for this event is
3213 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003214 For checking for a supported feature use |has()|.
3215
3216 Examples: >
3217 exists("&shortname")
3218 exists("$HOSTNAME")
3219 exists("*strftime")
3220 exists("*s:MyFunc")
3221 exists("bufcount")
3222 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003223 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003224 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003225 exists("#filetypeindent")
3226 exists("#filetypeindent#FileType")
3227 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003228 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003229< There must be no space between the symbol (&/$/*/#) and the
3230 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003231 There must be no extra characters after the name, although in
3232 a few cases this is ignored. That may become more strict in
3233 the future, thus don't count on it!
3234 Working example: >
3235 exists(":make")
3236< NOT working example: >
3237 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00003238
3239< Note that the argument must be a string, not the name of the
3240 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003241 exists(bufcount)
3242< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00003243 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003244
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003245exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003246 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003247 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003248 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003249 Examples: >
3250 :echo exp(2)
3251< 7.389056 >
3252 :echo exp(-1)
3253< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02003254 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003255
3256
Bram Moolenaar84f72352012-03-11 15:57:40 +01003257expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003258 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003259 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003260
Bram Moolenaar84f72352012-03-11 15:57:40 +01003261 If {list} is given and it is non-zero, a List will be returned.
3262 Otherwise the result is a String and when there are several
3263 matches, they are separated by <NL> characters. [Note: in
3264 version 5.0 a space was used, which caused problems when a
3265 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00003266
Bram Moolenaar446cb832008-06-24 21:56:24 +00003267 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02003268 for a non-existing file is not included, unless {expr} does
3269 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003270
3271 When {expr} starts with '%', '#' or '<', the expansion is done
3272 like for the |cmdline-special| variables with their associated
3273 modifiers. Here is a short overview:
3274
3275 % current file name
3276 # alternate file name
3277 #n alternate file name n
3278 <cfile> file name under the cursor
3279 <afile> autocmd file name
3280 <abuf> autocmd buffer number (as a String!)
3281 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01003282 <sfile> sourced script file or function name
Bram Moolenaar81af9252010-12-10 20:35:50 +01003283 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00003284 <cword> word under the cursor
3285 <cWORD> WORD under the cursor
3286 <client> the {clientid} of the last received
3287 message |server2client()|
3288 Modifiers:
3289 :p expand to full path
3290 :h head (last path component removed)
3291 :t tail (last path component only)
3292 :r root (one extension removed)
3293 :e extension only
3294
3295 Example: >
3296 :let &tags = expand("%:p:h") . "/tags"
3297< Note that when expanding a string that starts with '%', '#' or
3298 '<', any following text is ignored. This does NOT work: >
3299 :let doesntwork = expand("%:h.bak")
3300< Use this: >
3301 :let doeswork = expand("%:h") . ".bak"
3302< Also note that expanding "<cfile>" and others only returns the
3303 referenced file name without further expansion. If "<cfile>"
3304 is "~/.cshrc", you need to do another expand() to have the
3305 "~/" expanded into the path of the home directory: >
3306 :echo expand(expand("<cfile>"))
3307<
3308 There cannot be white space between the variables and the
3309 following modifier. The |fnamemodify()| function can be used
3310 to modify normal file names.
3311
3312 When using '%' or '#', and the current or alternate file name
3313 is not defined, an empty string is used. Using "%:p" in a
3314 buffer with no name, results in the current directory, with a
3315 '/' added.
3316
3317 When {expr} does not start with '%', '#' or '<', it is
3318 expanded like a file name is expanded on the command line.
3319 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaar146e9c32012-03-07 19:18:23 +01003320 {nosuf} argument is given and it is non-zero.
3321 Names for non-existing files are included. The "**" item can
3322 be used to search in a directory tree. For example, to find
3323 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00003324 :echo expand("**/README")
3325<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003326 Expand() can also be used to expand variables and environment
3327 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003328 slow, because a shell may be used to do the expansion. See
3329 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003330 The expanded variable is still handled like a list of file
Bram Moolenaar446cb832008-06-24 21:56:24 +00003331 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003332 left unchanged. Thus ":echo expand('$FOOBAR')" results in
3333 "$FOOBAR".
3334
3335 See |glob()| for finding existing files. See |system()| for
3336 getting the raw output of an external command.
3337
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003338extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003339 {expr1} and {expr2} must be both |Lists| or both
3340 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003341
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003342 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003343 If {expr3} is given insert the items of {expr2} before item
3344 {expr3} in {expr1}. When {expr3} is zero insert before the
3345 first item. When {expr3} is equal to len({expr1}) then
3346 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003347 Examples: >
3348 :echo sort(extend(mylist, [7, 5]))
3349 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00003350< When {expr1} is the same List as {expr2} then the number of
3351 items copied is equal to the original length of the List.
3352 E.g., when {expr3} is 1 you get N new copies of the first item
3353 (where N is the original length of the List).
3354 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003355 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003356 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003357<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003358 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003359 Add all entries from {expr2} to {expr1}.
3360 If a key exists in both {expr1} and {expr2} then {expr3} is
3361 used to decide what to do:
3362 {expr3} = "keep": keep the value of {expr1}
3363 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003364 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003365 When {expr3} is omitted then "force" is assumed.
3366
3367 {expr1} is changed when {expr2} is not empty. If necessary
3368 make a copy of {expr1} first.
3369 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02003370 When {expr1} is locked and {expr2} is not empty the operation
3371 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003372 Returns {expr1}.
3373
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003374
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003375feedkeys({string} [, {mode}]) *feedkeys()*
3376 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003377 come from a mapping or were typed by the user.
3378 By default the string is added to the end of the typeahead
3379 buffer, thus if a mapping is still being executed the
3380 characters come after them. Use the 'i' flag to insert before
3381 other characters, they will be executed next, before any
3382 characters from a mapping.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003383 The function does not wait for processing of keys contained in
3384 {string}.
3385 To include special keys into {string}, use double-quotes
3386 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00003387 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003388 feedkeys('\<CR>') pushes 5 characters.
3389 If {mode} is absent, keys are remapped.
3390 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003391 'm' Remap keys. This is default.
3392 'n' Do not remap keys.
3393 't' Handle keys as if typed; otherwise they are handled as
3394 if coming from a mapping. This matters for undo,
3395 opening folds, etc.
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003396 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01003397 'x' Execute commands until typeahead is empty. This is
3398 similar to using ":normal!". You can call feedkeys()
3399 several times without 'x' and then one time with 'x'
3400 (possibly with an empty {string}) to execute all the
3401 typeahead.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003402 Return value is always 0.
3403
Bram Moolenaar071d4272004-06-13 20:20:40 +00003404filereadable({file}) *filereadable()*
3405 The result is a Number, which is TRUE when a file with the
3406 name {file} exists, and can be read. If {file} doesn't exist,
3407 or is a directory, the result is FALSE. {file} is any
3408 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003409 If you don't care about the file being readable you can use
3410 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003411 *file_readable()*
3412 Obsolete name: file_readable().
3413
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003414
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003415filewritable({file}) *filewritable()*
3416 The result is a Number, which is 1 when a file with the
3417 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00003418 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003419 directory, and we can write to it, the result is 2.
3420
3421
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003422filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003423 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003424 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003425 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003426 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003427 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003428 Examples: >
3429 :call filter(mylist, 'v:val !~ "OLD"')
3430< Removes the items where "OLD" appears. >
3431 :call filter(mydict, 'v:key >= 8')
3432< Removes the items with a key below 8. >
3433 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003434< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003435
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003436 Note that {string} is the result of expression and is then
3437 used as an expression again. Often it is good to use a
3438 |literal-string| to avoid having to double backslashes.
3439
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003440 The operation is done in-place. If you want a |List| or
3441 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00003442 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003443
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003444< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00003445 When an error is encountered while evaluating {string} no
3446 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003447
3448
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003449finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00003450 Find directory {name} in {path}. Supports both downwards and
3451 upwards recursive directory searches. See |file-searching|
3452 for the syntax of {path}.
3453 Returns the path of the first found match. When the found
3454 directory is below the current directory a relative path is
3455 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003456 If {path} is omitted or empty then 'path' is used.
3457 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003458 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00003459 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003460 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003461 {only available when compiled with the |+file_in_path|
3462 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003463
3464findfile({name}[, {path}[, {count}]]) *findfile()*
3465 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003466 Uses 'suffixesadd'.
3467 Example: >
3468 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003469< Searches from the directory of the current file upwards until
3470 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003471
Bram Moolenaar446cb832008-06-24 21:56:24 +00003472float2nr({expr}) *float2nr()*
3473 Convert {expr} to a Number by omitting the part after the
3474 decimal point.
3475 {expr} must evaluate to a |Float| or a Number.
3476 When the value of {expr} is out of range for a |Number| the
3477 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
3478 in -0x80000000.
3479 Examples: >
3480 echo float2nr(3.95)
3481< 3 >
3482 echo float2nr(-23.45)
3483< -23 >
3484 echo float2nr(1.0e100)
3485< 2147483647 >
3486 echo float2nr(-1.0e150)
3487< -2147483647 >
3488 echo float2nr(1.0e-100)
3489< 0
3490 {only available when compiled with the |+float| feature}
3491
3492
3493floor({expr}) *floor()*
3494 Return the largest integral value less than or equal to
3495 {expr} as a |Float| (round down).
3496 {expr} must evaluate to a |Float| or a |Number|.
3497 Examples: >
3498 echo floor(1.856)
3499< 1.0 >
3500 echo floor(-5.456)
3501< -6.0 >
3502 echo floor(4.0)
3503< 4.0
3504 {only available when compiled with the |+float| feature}
3505
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003506
3507fmod({expr1}, {expr2}) *fmod()*
3508 Return the remainder of {expr1} / {expr2}, even if the
3509 division is not representable. Returns {expr1} - i * {expr2}
3510 for some integer i such that if {expr2} is non-zero, the
3511 result has the same sign as {expr1} and magnitude less than
3512 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003513 returned is zero. The value returned is a |Float|.
3514 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003515 Examples: >
3516 :echo fmod(12.33, 1.22)
3517< 0.13 >
3518 :echo fmod(-12.33, 1.22)
3519< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02003520 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003521
3522
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003523fnameescape({string}) *fnameescape()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003524 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003525 characters that have a special meaning, such as '%' and '|'
3526 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003527 For most systems the characters escaped are
3528 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3529 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003530 A leading '+' and '>' is also escaped (special after |:edit|
3531 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003532 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003533 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003534 :exe "edit " . fnameescape(fname)
3535< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003536 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003537
Bram Moolenaar071d4272004-06-13 20:20:40 +00003538fnamemodify({fname}, {mods}) *fnamemodify()*
3539 Modify file name {fname} according to {mods}. {mods} is a
3540 string of characters like it is used for file names on the
3541 command line. See |filename-modifiers|.
3542 Example: >
3543 :echo fnamemodify("main.c", ":p:h")
3544< results in: >
3545 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003546< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003547 |expand()| first then.
3548
3549foldclosed({lnum}) *foldclosed()*
3550 The result is a Number. If the line {lnum} is in a closed
3551 fold, the result is the number of the first line in that fold.
3552 If the line {lnum} is not in a closed fold, -1 is returned.
3553
3554foldclosedend({lnum}) *foldclosedend()*
3555 The result is a Number. If the line {lnum} is in a closed
3556 fold, the result is the number of the last line in that fold.
3557 If the line {lnum} is not in a closed fold, -1 is returned.
3558
3559foldlevel({lnum}) *foldlevel()*
3560 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003561 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003562 returned. If there is no fold at line {lnum}, zero is
3563 returned. It doesn't matter if the folds are open or closed.
3564 When used while updating folds (from 'foldexpr') -1 is
3565 returned for lines where folds are still to be updated and the
3566 foldlevel is unknown. As a special case the level of the
3567 previous line is usually available.
3568
3569 *foldtext()*
3570foldtext() Returns a String, to be displayed for a closed fold. This is
3571 the default function used for the 'foldtext' option and should
3572 only be called from evaluating 'foldtext'. It uses the
3573 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3574 The returned string looks like this: >
3575 +-- 45 lines: abcdef
Bram Moolenaar446cb832008-06-24 21:56:24 +00003576< The number of dashes depends on the foldlevel. The "45" is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003577 the number of lines in the fold. "abcdef" is the text in the
3578 first non-blank line of the fold. Leading white space, "//"
3579 or "/*" and the text from the 'foldmarker' and 'commentstring'
3580 options is removed.
3581 {not available when compiled without the |+folding| feature}
3582
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003583foldtextresult({lnum}) *foldtextresult()*
3584 Returns the text that is displayed for the closed fold at line
3585 {lnum}. Evaluates 'foldtext' in the appropriate context.
3586 When there is no closed fold at {lnum} an empty string is
3587 returned.
3588 {lnum} is used like with |getline()|. Thus "." is the current
3589 line, "'m" mark m, etc.
3590 Useful when exporting folded text, e.g., to HTML.
3591 {not available when compiled without the |+folding| feature}
3592
Bram Moolenaar071d4272004-06-13 20:20:40 +00003593 *foreground()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003594foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00003595 a client to a Vim server. |remote_send()|
3596 On Win32 systems this might not work, the OS does not always
3597 allow a window to bring itself to the foreground. Use
3598 |remote_foreground()| instead.
3599 {only in the Win32, Athena, Motif and GTK GUI versions and the
3600 Win32 console version}
3601
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003602
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003603 *function()* *E700* *E922* *E923*
3604function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003605 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01003606 {name} can be the name of a user defined function or an
3607 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003608
Bram Moolenaar975b5272016-03-15 23:10:59 +01003609 {name} can also be a Funcref, also a partial. When it is a
3610 partial the dict stored in it will be used and the {dict}
3611 argument is not allowed. E.g.: >
3612 let FuncWithArg = function(dict.Func, [arg])
3613 let Broken = function(dict.Func, [arg], dict)
3614<
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003615 When {arglist} or {dict} is present this creates a partial.
3616 That mans the argument list and/or the dictionary is stored in
3617 the Funcref and will be used when the Funcref is called.
3618
3619 The arguments are passed to the function in front of other
3620 arguments. Example: >
3621 func Callback(arg1, arg2, name)
3622 ...
3623 let Func = function('Callback', ['one', 'two'])
3624 ...
3625 call Func('name')
3626< Invokes the function as with: >
3627 call Callback('one', 'two', 'name')
3628
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003629< The function() call can be nested to add more arguments to the
3630 Funcref. The extra arguments are appended to the list of
3631 arguments. Example: >
3632 func Callback(arg1, arg2, name)
3633 ...
3634 let Func = function('Callback', ['one'])
3635 let Func2 = function(Func, ['two'])
3636 ...
3637 call Func2('name')
3638< Invokes the function as with: >
3639 call Callback('one', 'two', 'name')
3640
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003641< The Dictionary is only useful when calling a "dict" function.
3642 In that case the {dict} is passed in as "self". Example: >
3643 function Callback() dict
3644 echo "called for " . self.name
3645 endfunction
3646 ...
3647 let context = {"name": "example"}
3648 let Func = function('Callback', context)
3649 ...
3650 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01003651< The use of function() is not needed when there are no extra
3652 arguments, these two are equivalent: >
3653 let Func = function('Callback', context)
3654 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003655
3656< The argument list and the Dictionary can be combined: >
3657 function Callback(arg1, count) dict
3658 ...
3659 let context = {"name": "example"}
3660 let Func = function('Callback', ['one'], context)
3661 ...
3662 call Func(500)
3663< Invokes the function as with: >
3664 call context.Callback('one', 500)
3665
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003666
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003667garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003668 Cleanup unused |Lists| and |Dictionaries| that have circular
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003669 references. There is hardly ever a need to invoke this
3670 function, as it is automatically done when Vim runs out of
3671 memory or is waiting for the user to press a key after
3672 'updatetime'. Items without circular references are always
3673 freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003674 This is useful if you have deleted a very big |List| and/or
3675 |Dictionary| with circular references in a script that runs
3676 for a long time.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003677 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003678 collection will also be done when exiting Vim, if it wasn't
3679 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003680
Bram Moolenaar677ee682005-01-27 14:41:15 +00003681get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003682 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003683 available return {default}. Return zero when {default} is
3684 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003685get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003686 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003687 item is not available return {default}. Return zero when
3688 {default} is omitted.
3689
Bram Moolenaar45360022005-07-21 21:08:21 +00003690 *getbufline()*
3691getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003692 Return a |List| with the lines starting from {lnum} to {end}
3693 (inclusive) in the buffer {expr}. If {end} is omitted, a
3694 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003695
3696 For the use of {expr}, see |bufname()| above.
3697
Bram Moolenaar661b1822005-07-28 22:36:45 +00003698 For {lnum} and {end} "$" can be used for the last line of the
3699 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00003700
3701 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003702 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003703
3704 When {end} is greater than the number of lines in the buffer,
3705 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003706 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00003707 returned.
3708
Bram Moolenaar661b1822005-07-28 22:36:45 +00003709 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003710 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003711
3712 Example: >
3713 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003714
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003715getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003716 The result is the value of option or local buffer variable
3717 {varname} in buffer {expr}. Note that the name without "b:"
3718 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003719 When {varname} is empty returns a dictionary with all the
3720 buffer-local variables.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00003721 This also works for a global or buffer-local option, but it
3722 doesn't work for a global variable, window-local variable or
3723 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003724 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003725 When the buffer or variable doesn't exist {def} or an empty
3726 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003727 Examples: >
3728 :let bufmodified = getbufvar(1, "&mod")
3729 :echo "todo myvar = " . getbufvar("todo", "myvar")
3730<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003731getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00003732 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003733 If [expr] is omitted, wait until a character is available.
3734 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003735 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003736 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00003737 not consumed. Return zero if no character available.
3738
Bram Moolenaardfb18412013-12-11 18:53:29 +01003739 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaar91170f82006-05-05 21:15:17 +00003740 special key is returned. If it is an 8-bit character, the
3741 result is a number. Use nr2char() to convert it to a String.
3742 Otherwise a String is returned with the encoded character.
3743 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003744 (decimal: 128). This is the same value as the string
3745 "\<Key>", e.g., "\<Left>". The returned value is also a
3746 String when a modifier (shift, control, alt) was used that is
3747 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003748
Bram Moolenaar822ff862014-06-12 21:46:14 +02003749 When [expr] is 0 and Esc is typed, there will be a short delay
3750 while Vim waits to see if this is the start of an escape
3751 sequence.
3752
Bram Moolenaardfb18412013-12-11 18:53:29 +01003753 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003754 one-byte character it is the character itself as a number.
3755 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003756
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003757 Use getcharmod() to obtain any additional modifiers.
3758
Bram Moolenaar219b8702006-11-01 14:32:36 +00003759 When the user clicks a mouse button, the mouse event will be
3760 returned. The position can then be found in |v:mouse_col|,
3761 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3762 mouse as it would normally happen: >
3763 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003764 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00003765 exe v:mouse_win . "wincmd w"
3766 exe v:mouse_lnum
3767 exe "normal " . v:mouse_col . "|"
3768 endif
3769<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003770 There is no prompt, you will somehow have to make clear to the
3771 user that a character has to be typed.
3772 There is no mapping for the character.
3773 Key codes are replaced, thus when the user presses the <Del>
3774 key you get the code for the <Del> key, not the raw character
3775 sequence. Examples: >
3776 getchar() == "\<Del>"
3777 getchar() == "\<S-Left>"
3778< This example redefines "f" to ignore case: >
3779 :nmap f :call FindChar()<CR>
3780 :function FindChar()
3781 : let c = nr2char(getchar())
3782 : while col('.') < col('$') - 1
3783 : normal l
3784 : if getline('.')[col('.') - 1] ==? c
3785 : break
3786 : endif
3787 : endwhile
3788 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01003789<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003790 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01003791 |<CursorHold>|. Often you will want to ignore this and get
3792 another character: >
3793 :function GetKey()
3794 : let c = getchar()
3795 : while c == "\<CursorHold>"
3796 : let c = getchar()
3797 : endwhile
3798 : return c
3799 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00003800
3801getcharmod() *getcharmod()*
3802 The result is a Number which is the state of the modifiers for
3803 the last obtained character with getchar() or in another way.
3804 These values are added together:
3805 2 shift
3806 4 control
3807 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003808 16 meta (when it's different from ALT)
3809 32 mouse double click
3810 64 mouse triple click
3811 96 mouse quadruple click (== 32 + 64)
3812 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003813 Only the modifiers that have not been included in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003814 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003815 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003816
Bram Moolenaardbd24b52015-08-11 14:26:19 +02003817getcharsearch() *getcharsearch()*
3818 Return the current character search information as a {dict}
3819 with the following entries:
3820
3821 char character previously used for a character
3822 search (|t|, |f|, |T|, or |F|); empty string
3823 if no character search has been performed
3824 forward direction of character search; 1 for forward,
3825 0 for backward
3826 until type of character search; 1 for a |t| or |T|
3827 character search, 0 for an |f| or |F|
3828 character search
3829
3830 This can be useful to always have |;| and |,| search
3831 forward/backward regardless of the direction of the previous
3832 character search: >
3833 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3834 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3835< Also see |setcharsearch()|.
3836
Bram Moolenaar071d4272004-06-13 20:20:40 +00003837getcmdline() *getcmdline()*
3838 Return the current command-line. Only works when the command
3839 line is being edited, thus requires use of |c_CTRL-\_e| or
3840 |c_CTRL-R_=|.
3841 Example: >
3842 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003843< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003844
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003845getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003846 Return the position of the cursor in the command line as a
3847 byte count. The first column is 1.
3848 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003849 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3850 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003851 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3852
3853getcmdtype() *getcmdtype()*
3854 Return the current command-line type. Possible return values
3855 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00003856 : normal Ex command
3857 > debug mode command |debug-mode|
3858 / forward search command
3859 ? backward search command
3860 @ |input()| command
3861 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02003862 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003863 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003864 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3865 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003866 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003867
Bram Moolenaarfb539272014-08-22 19:21:47 +02003868getcmdwintype() *getcmdwintype()*
3869 Return the current |command-line-window| type. Possible return
3870 values are the same as |getcmdtype()|. Returns an empty string
3871 when not in the command-line window.
3872
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003873 *getcurpos()*
3874getcurpos() Get the position of the cursor. This is like getpos('.'), but
3875 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01003876 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003877 The "curswant" number is the preferred column when moving the
3878 cursor vertically.
3879 This can be used to save and restore the cursor position: >
3880 let save_cursor = getcurpos()
3881 MoveTheCursorAround
3882 call setpos('.', save_cursor)
Bram Moolenaarfb539272014-08-22 19:21:47 +02003883<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003884 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01003885getcwd([{winnr} [, {tabnr}]])
3886 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00003887 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01003888 Without arguments, for the current window.
3889
3890 With {winnr} return the local current directory of this window
3891 in the current tab page.
3892 With {winnr} and {tabnr} return the local current directory of
3893 the window in the specified tab page.
3894 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003895
3896getfsize({fname}) *getfsize()*
3897 The result is a Number, which is the size in bytes of the
3898 given file {fname}.
3899 If {fname} is a directory, 0 is returned.
3900 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00003901 If the size of {fname} is too big to fit in a Number then -2
3902 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003903
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003904getfontname([{name}]) *getfontname()*
3905 Without an argument returns the name of the normal font being
3906 used. Like what is used for the Normal highlight group
3907 |hl-Normal|.
3908 With an argument a check is done whether {name} is a valid
3909 font name. If not then an empty string is returned.
3910 Otherwise the actual font name is returned, or {name} if the
3911 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00003912 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003913 gvimrc file. Use the |GUIEnter| autocommand to use this
3914 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003915 Note that the GTK 2 GUI accepts any font name, thus checking
3916 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003917
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003918getfperm({fname}) *getfperm()*
3919 The result is a String, which is the read, write, and execute
3920 permissions of the given file {fname}.
3921 If {fname} does not exist or its directory cannot be read, an
3922 empty string is returned.
3923 The result is of the form "rwxrwxrwx", where each group of
3924 "rwx" flags represent, in turn, the permissions of the owner
3925 of the file, the group the file belongs to, and other users.
3926 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02003927 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003928 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02003929 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003930< This will hopefully (from a security point of view) display
3931 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003932
Bram Moolenaar80492532016-03-08 17:08:53 +01003933 For setting permissins use |setfperm()|.
3934
Bram Moolenaar071d4272004-06-13 20:20:40 +00003935getftime({fname}) *getftime()*
3936 The result is a Number, which is the last modification time of
3937 the given file {fname}. The value is measured as seconds
3938 since 1st Jan 1970, and may be passed to strftime(). See also
3939 |localtime()| and |strftime()|.
3940 If the file {fname} can't be found -1 is returned.
3941
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003942getftype({fname}) *getftype()*
3943 The result is a String, which is a description of the kind of
3944 file of the given file {fname}.
3945 If {fname} does not exist an empty string is returned.
3946 Here is a table over different kinds of files and their
3947 results:
3948 Normal file "file"
3949 Directory "dir"
3950 Symbolic link "link"
3951 Block device "bdev"
3952 Character device "cdev"
3953 Socket "socket"
3954 FIFO "fifo"
3955 All other "other"
3956 Example: >
3957 getftype("/home")
3958< Note that a type such as "link" will only be returned on
3959 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01003960 "file" are returned. On MS-Windows a symbolic link to a
3961 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003962
Bram Moolenaar071d4272004-06-13 20:20:40 +00003963 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003964getline({lnum} [, {end}])
3965 Without {end} the result is a String, which is line {lnum}
3966 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003967 getline(1)
3968< When {lnum} is a String that doesn't start with a
3969 digit, line() is called to translate the String into a Number.
3970 To get the line under the cursor: >
3971 getline(".")
3972< When {lnum} is smaller than 1 or bigger than the number of
3973 lines in the buffer, an empty string is returned.
3974
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003975 When {end} is given the result is a |List| where each item is
3976 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003977 including line {end}.
3978 {end} is used in the same way as {lnum}.
3979 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003980 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003981 Example: >
3982 :let start = line('.')
3983 :let end = search("^$") - 1
3984 :let lines = getline(start, end)
3985
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003986< To get lines from another buffer see |getbufline()|
3987
Bram Moolenaar17c7c012006-01-26 22:25:15 +00003988getloclist({nr}) *getloclist()*
3989 Returns a list with all the entries in the location list for
3990 window {nr}. When {nr} is zero the current window is used.
3991 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00003992 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003993 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003994
Bram Moolenaar6ee10162007-07-26 20:58:42 +00003995getmatches() *getmatches()*
3996 Returns a |List| with all matches previously defined by
3997 |matchadd()| and the |:match| commands. |getmatches()| is
3998 useful in combination with |setmatches()|, as |setmatches()|
3999 can restore a list of matches saved by |getmatches()|.
4000 Example: >
4001 :echo getmatches()
4002< [{'group': 'MyGroup1', 'pattern': 'TODO',
4003 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4004 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4005 :let m = getmatches()
4006 :call clearmatches()
4007 :echo getmatches()
4008< [] >
4009 :call setmatches(m)
4010 :echo getmatches()
4011< [{'group': 'MyGroup1', 'pattern': 'TODO',
4012 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4013 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4014 :unlet m
4015<
Bram Moolenaar822ff862014-06-12 21:46:14 +02004016 *getpid()*
4017getpid() Return a Number which is the process ID of the Vim process.
4018 On Unix and MS-Windows this is a unique number, until Vim
4019 exits. On MS-DOS it's always zero.
4020
4021 *getpos()*
4022getpos({expr}) Get the position for {expr}. For possible values of {expr}
4023 see |line()|. For getting the cursor position see
4024 |getcurpos()|.
4025 The result is a |List| with four numbers:
4026 [bufnum, lnum, col, off]
4027 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4028 is the buffer number of the mark.
4029 "lnum" and "col" are the position in the buffer. The first
4030 column is 1.
4031 The "off" number is zero, unless 'virtualedit' is used. Then
4032 it is the offset in screen columns from the start of the
4033 character. E.g., a position within a <Tab> or after the last
4034 character.
4035 Note that for '< and '> Visual mode matters: when it is "V"
4036 (visual line mode) the column of '< is zero and the column of
4037 '> is a large number.
4038 This can be used to save and restore the position of a mark: >
4039 let save_a_mark = getpos("'a")
4040 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01004041 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02004042< Also see |getcurpos()| and |setpos()|.
4043
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004044
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004045getqflist() *getqflist()*
4046 Returns a list with all the current quickfix errors. Each
4047 list item is a dictionary with these entries:
4048 bufnr number of buffer that has the file name, use
4049 bufname() to get the name
4050 lnum line number in the buffer (first line is 1)
4051 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00004052 vcol non-zero: "col" is visual column
4053 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004054 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004055 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004056 text description of the error
4057 type type of the error, 'E', '1', etc.
4058 valid non-zero: recognized error message
4059
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004060 When there is no error list or it's empty an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004061 returned. Quickfix list entries with non-existing buffer
4062 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004063
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004064 Useful application: Find pattern matches in multiple files and
4065 do something with them: >
4066 :vimgrep /theword/jg *.c
4067 :for d in getqflist()
4068 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4069 :endfor
4070
4071
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004072getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004073 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004074 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004075 :let cliptext = getreg('*')
4076< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004077 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004078 getreg('=', 1) returns the expression itself, so that it can
4079 be restored with |setreg()|. For other registers the extra
4080 argument is ignored, thus you can always give it.
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004081 If {list} is present and non-zero result type is changed to
4082 |List|. Each list item is one text line. Use it if you care
4083 about zero bytes possibly present inside register: without
4084 third argument both NLs and zero bytes are represented as NLs
4085 (see |NL-used-for-Nul|).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004086 If {regname} is not specified, |v:register| is used.
4087
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004088
Bram Moolenaar071d4272004-06-13 20:20:40 +00004089getregtype([{regname}]) *getregtype()*
4090 The result is a String, which is type of register {regname}.
4091 The value will be one of:
4092 "v" for |characterwise| text
4093 "V" for |linewise| text
4094 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01004095 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00004096 <CTRL-V> is one character with value 0x16.
4097 If {regname} is not specified, |v:register| is used.
4098
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004099gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004100 Get the value of a tab-local variable {varname} in tab page
4101 {tabnr}. |t:var|
4102 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02004103 When {varname} is empty a dictionary with all tab-local
4104 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004105 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004106 When the tab or variable doesn't exist {def} or an empty
4107 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004108
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004109gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004110 Get the value of window-local variable {varname} in window
4111 {winnr} in tab page {tabnr}.
4112 When {varname} starts with "&" get the value of a window-local
4113 option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004114 When {varname} is empty a dictionary with all window-local
4115 variables is returned.
4116 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004117 Tabs are numbered starting with one. For the current tabpage
4118 use |getwinvar()|.
4119 When {winnr} is zero the current window is used.
4120 This also works for a global option, buffer-local option and
4121 window-local option, but it doesn't work for a global variable
4122 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004123 When the tab, window or variable doesn't exist {def} or an
4124 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004125 Examples: >
4126 :let list_is_on = gettabwinvar(1, 2, '&list')
4127 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004128<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004129 *getwinposx()*
4130getwinposx() The result is a Number, which is the X coordinate in pixels of
4131 the left hand side of the GUI Vim window. The result will be
4132 -1 if the information is not available.
4133
4134 *getwinposy()*
4135getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar446cb832008-06-24 21:56:24 +00004136 the top of the GUI Vim window. The result will be -1 if the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004137 information is not available.
4138
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004139getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004140 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004141 Examples: >
4142 :let list_is_on = getwinvar(2, '&list')
4143 :echo "myvar = " . getwinvar(1, 'myvar')
4144<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004145glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004146 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004147 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004148
4149 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004150 the 'suffixes' and 'wildignore' options apply: Names matching
4151 one of the patterns in 'wildignore' will be skipped and
4152 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01004153 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004154
4155 When {list} is present and it is non-zero the result is a List
4156 with all matching files. The advantage of using a List is,
4157 you also get filenames containing newlines correctly.
4158 Otherwise the result is a String and when there are several
4159 matches, they are separated by <NL> characters.
4160
4161 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004162
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02004163 A name for a non-existing file is not included. A symbolic
4164 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004165 However, when the {alllinks} argument is present and it is
4166 non-zero then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004167
4168 For most systems backticks can be used to get files names from
4169 any external command. Example: >
4170 :let tagfiles = glob("`find . -name tags -print`")
4171 :let &tags = substitute(tagfiles, "\n", ",", "g")
4172< The result of the program inside the backticks should be one
Bram Moolenaar446cb832008-06-24 21:56:24 +00004173 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004174
4175 See |expand()| for expanding special Vim variables. See
4176 |system()| for getting the raw output of an external command.
4177
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01004178glob2regpat({expr}) *glob2regpat()*
4179 Convert a file pattern, as used by glob(), into a search
4180 pattern. The result can be used to match with a string that
4181 is a file name. E.g. >
4182 if filename =~ glob2regpat('Make*.mak')
4183< This is equivalent to: >
4184 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01004185< When {expr} is an empty string the result is "^$", match an
4186 empty string.
4187
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004188 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004189globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004190 Perform glob() on all directories in {path} and concatenate
4191 the results. Example: >
4192 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004193<
4194 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00004195 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004196 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004197 To add a comma inside a directory name escape it with a
4198 backslash. Note that on MS-Windows a directory may have a
4199 trailing backslash, remove it if you put a comma after it.
4200 If the expansion fails for one of the directories, there is no
4201 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004202
4203 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004204 the 'suffixes' and 'wildignore' options apply: Names matching
4205 one of the patterns in 'wildignore' will be skipped and
4206 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004207
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004208 When {list} is present and it is non-zero the result is a List
4209 with all matching files. The advantage of using a List is, you
4210 also get filenames containing newlines correctly. Otherwise
4211 the result is a String and when there are several matches,
4212 they are separated by <NL> characters. Example: >
4213 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4214<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004215 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004216
Bram Moolenaar02743632005-07-25 20:42:36 +00004217 The "**" item can be used to search in a directory tree.
4218 For example, to find all "README.txt" files in the directories
4219 in 'runtimepath' and below: >
4220 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00004221< Upwards search and limiting the depth of "**" is not
4222 supported, thus using 'path' will not always work properly.
4223
Bram Moolenaar071d4272004-06-13 20:20:40 +00004224 *has()*
4225has({feature}) The result is a Number, which is 1 if the feature {feature} is
4226 supported, zero otherwise. The {feature} argument is a
4227 string. See |feature-list| below.
4228 Also see |exists()|.
4229
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004230
4231has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004232 The result is a Number, which is 1 if |Dictionary| {dict} has
4233 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004234
Bram Moolenaarc9703302016-01-17 21:49:33 +01004235haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4236 The result is a Number, which is 1 when the window has set a
4237 local path via |:lcd|, and 0 otherwise.
4238
4239 Without arguments use the current window.
4240 With {winnr} use this window in the current tab page.
4241 With {winnr} and {tabnr} use the window in the specified tab
4242 page.
4243 Return 0 if the arguments are invalid.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004244
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004245hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004246 The result is a Number, which is 1 if there is a mapping that
4247 contains {what} in somewhere in the rhs (what it is mapped to)
4248 and this mapping exists in one of the modes indicated by
4249 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004250 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00004251 instead of mappings. Don't forget to specify Insert and/or
4252 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004253 Both the global mappings and the mappings local to the current
4254 buffer are checked for a match.
4255 If no matching mapping is found 0 is returned.
4256 The following characters are recognized in {mode}:
4257 n Normal mode
4258 v Visual mode
4259 o Operator-pending mode
4260 i Insert mode
4261 l Language-Argument ("r", "f", "t", etc.)
4262 c Command-line mode
4263 When {mode} is omitted, "nvo" is used.
4264
4265 This function is useful to check if a mapping already exists
Bram Moolenaar446cb832008-06-24 21:56:24 +00004266 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004267 :if !hasmapto('\ABCdoit')
4268 : map <Leader>d \ABCdoit
4269 :endif
4270< This installs the mapping to "\ABCdoit" only if there isn't
4271 already a mapping to "\ABCdoit".
4272
4273histadd({history}, {item}) *histadd()*
4274 Add the String {item} to the history {history} which can be
4275 one of: *hist-names*
4276 "cmd" or ":" command line history
4277 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00004278 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00004279 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02004280 "debug" or ">" debug command history
4281 The {history} string does not need to be the whole name, one
4282 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004283 If {item} does already exist in the history, it will be
4284 shifted to become the newest entry.
4285 The result is a Number: 1 if the operation was successful,
4286 otherwise 0 is returned.
4287
4288 Example: >
4289 :call histadd("input", strftime("%Y %b %d"))
4290 :let date=input("Enter date: ")
4291< This function is not available in the |sandbox|.
4292
4293histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004294 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004295 for the possible values of {history}.
4296
Bram Moolenaarc236c162008-07-13 17:41:49 +00004297 If the parameter {item} evaluates to a String, it is used as a
4298 regular expression. All entries matching that expression will
4299 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004300 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004301 If {item} evaluates to a Number, it will be interpreted as
4302 an index, see |:history-indexing|. The respective entry will
4303 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004304
4305 The result is a Number: 1 for a successful operation,
4306 otherwise 0 is returned.
4307
4308 Examples:
4309 Clear expression register history: >
4310 :call histdel("expr")
4311<
4312 Remove all entries starting with "*" from the search history: >
4313 :call histdel("/", '^\*')
4314<
4315 The following three are equivalent: >
4316 :call histdel("search", histnr("search"))
4317 :call histdel("search", -1)
4318 :call histdel("search", '^'.histget("search", -1).'$')
4319<
4320 To delete the last search pattern and use the last-but-one for
4321 the "n" command and 'hlsearch': >
4322 :call histdel("search", -1)
4323 :let @/ = histget("search", -1)
4324
4325histget({history} [, {index}]) *histget()*
4326 The result is a String, the entry with Number {index} from
4327 {history}. See |hist-names| for the possible values of
4328 {history}, and |:history-indexing| for {index}. If there is
4329 no such entry, an empty String is returned. When {index} is
4330 omitted, the most recent item from the history is used.
4331
4332 Examples:
4333 Redo the second last search from history. >
4334 :execute '/' . histget("search", -2)
4335
4336< Define an Ex command ":H {num}" that supports re-execution of
4337 the {num}th entry from the output of |:history|. >
4338 :command -nargs=1 H execute histget("cmd", 0+<args>)
4339<
4340histnr({history}) *histnr()*
4341 The result is the Number of the current entry in {history}.
4342 See |hist-names| for the possible values of {history}.
4343 If an error occurred, -1 is returned.
4344
4345 Example: >
4346 :let inp_index = histnr("expr")
4347<
4348hlexists({name}) *hlexists()*
4349 The result is a Number, which is non-zero if a highlight group
4350 called {name} exists. This is when the group has been
4351 defined in some way. Not necessarily when highlighting has
4352 been defined for it, it may also have been used for a syntax
4353 item.
4354 *highlight_exists()*
4355 Obsolete name: highlight_exists().
4356
4357 *hlID()*
4358hlID({name}) The result is a Number, which is the ID of the highlight group
4359 with name {name}. When the highlight group doesn't exist,
4360 zero is returned.
4361 This can be used to retrieve information about the highlight
Bram Moolenaar446cb832008-06-24 21:56:24 +00004362 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004363 "Comment" group: >
4364 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4365< *highlightID()*
4366 Obsolete name: highlightID().
4367
4368hostname() *hostname()*
4369 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004370 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00004371 256 characters long are truncated.
4372
4373iconv({expr}, {from}, {to}) *iconv()*
4374 The result is a String, which is the text {expr} converted
4375 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004376 When the conversion completely fails an empty string is
4377 returned. When some characters could not be converted they
4378 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004379 The encoding names are whatever the iconv() library function
4380 can accept, see ":!man 3 iconv".
4381 Most conversions require Vim to be compiled with the |+iconv|
4382 feature. Otherwise only UTF-8 to latin1 conversion and back
4383 can be done.
4384 This can be used to display messages with special characters,
4385 no matter what 'encoding' is set to. Write the message in
4386 UTF-8 and use: >
4387 echo iconv(utf8_str, "utf-8", &enc)
4388< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4389 from/to UCS-2 is automatically changed to use UTF-8. You
4390 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004391 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004392
4393 *indent()*
4394indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4395 current buffer. The indent is counted in spaces, the value
4396 of 'tabstop' is relevant. {lnum} is used just like in
4397 |getline()|.
4398 When {lnum} is invalid -1 is returned.
4399
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004400
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004401index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004402 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004403 value equal to {expr}. There is no automatic conversion, so
4404 the String "4" is different from the Number 4. And the number
4405 4 is different from the Float 4.0. The value of 'ignorecase'
4406 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00004407 If {start} is given then start looking at the item with index
4408 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004409 When {ic} is given and it is non-zero, ignore case. Otherwise
4410 case must match.
4411 -1 is returned when {expr} is not found in {list}.
4412 Example: >
4413 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004414 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004415
4416
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004417input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004418 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004419 the command-line. The {prompt} argument is either a prompt
4420 string, or a blank string (for no prompt). A '\n' can be used
4421 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004422 The highlighting set with |:echohl| is used for the prompt.
4423 The input is entered just like a command-line, with the same
Bram Moolenaar446cb832008-06-24 21:56:24 +00004424 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004425 for lines typed for input().
4426 Example: >
4427 :if input("Coffee or beer? ") == "beer"
4428 : echo "Cheers!"
4429 :endif
4430<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004431 If the optional {text} argument is present and not empty, this
4432 is used for the default reply, as if the user typed this.
4433 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004434 :let color = input("Color? ", "white")
4435
4436< The optional {completion} argument specifies the type of
4437 completion supported for the input. Without it completion is
Bram Moolenaar446cb832008-06-24 21:56:24 +00004438 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004439 that can be supplied to a user-defined command using the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004440 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004441 more information. Example: >
4442 let fname = input("File: ", "", "file")
4443<
4444 NOTE: This function must not be used in a startup file, for
4445 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004446 Note: When input() is called from within a mapping it will
4447 consume remaining characters from that mapping, because a
4448 mapping is handled like the characters were typed.
4449 Use |inputsave()| before input() and |inputrestore()|
4450 after input() to avoid that. Another solution is to avoid
4451 that further characters follow in the mapping, e.g., by using
4452 |:execute| or |:normal|.
4453
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004454 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004455 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
4456 :function GetFoo()
4457 : call inputsave()
4458 : let g:Foo = input("enter search pattern: ")
4459 : call inputrestore()
4460 :endfunction
4461
4462inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004463 Like |input()|, but when the GUI is running and text dialogs
4464 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004465 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02004466 :let n = inputdialog("value for shiftwidth", shiftwidth())
4467 :if n != ""
4468 : let &sw = n
4469 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00004470< When the dialog is cancelled {cancelreturn} is returned. When
4471 omitted an empty string is returned.
4472 Hitting <Enter> works like pressing the OK button. Hitting
4473 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004474 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004475
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004476inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004477 {textlist} must be a |List| of strings. This |List| is
4478 displayed, one string per line. The user will be prompted to
4479 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004480 The user can also select an item by clicking on it with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004481 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004482 above the first item a negative number is returned. When
4483 clicking on the prompt one more than the length of {textlist}
4484 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004485 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +00004486 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004487 the start of the string. And put a prompt in the first item.
4488 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004489 let color = inputlist(['Select color:', '1. red',
4490 \ '2. green', '3. blue'])
4491
Bram Moolenaar071d4272004-06-13 20:20:40 +00004492inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004493 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004494 Should be called the same number of times inputsave() is
4495 called. Calling it more often is harmless though.
4496 Returns 1 when there is nothing to restore, 0 otherwise.
4497
4498inputsave() *inputsave()*
4499 Preserve typeahead (also from mappings) and clear it, so that
4500 a following prompt gets input from the user. Should be
4501 followed by a matching inputrestore() after the prompt. Can
4502 be used several times, in which case there must be just as
4503 many inputrestore() calls.
4504 Returns 1 when out of memory, 0 otherwise.
4505
4506inputsecret({prompt} [, {text}]) *inputsecret()*
4507 This function acts much like the |input()| function with but
4508 two exceptions:
4509 a) the user's response will be displayed as a sequence of
4510 asterisks ("*") thereby keeping the entry secret, and
4511 b) the user's response will not be recorded on the input
4512 |history| stack.
4513 The result is a String, which is whatever the user actually
4514 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004515 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004516
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004517insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004518 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004519 If {idx} is specified insert {item} before the item with index
Bram Moolenaar446cb832008-06-24 21:56:24 +00004520 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004521 like omitting {idx}. A negative {idx} is also possible, see
4522 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004523 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004524 :let mylist = insert([2, 3, 5], 1)
4525 :call insert(mylist, 4, -1)
4526 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004527< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004528 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004529 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004530
Bram Moolenaard6e256c2011-12-14 15:32:50 +01004531invert({expr}) *invert()*
4532 Bitwise invert. The argument is converted to a number. A
4533 List, Dict or Float argument causes an error. Example: >
4534 :let bits = invert(bits)
4535
Bram Moolenaar071d4272004-06-13 20:20:40 +00004536isdirectory({directory}) *isdirectory()*
4537 The result is a Number, which is non-zero when a directory
4538 with the name {directory} exists. If {directory} doesn't
4539 exist, or isn't a directory, the result is FALSE. {directory}
4540 is any expression, which is used as a String.
4541
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004542islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004543 The result is a Number, which is non-zero when {expr} is the
4544 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004545 {expr} must be the name of a variable, |List| item or
4546 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004547 :let alist = [0, ['a', 'b'], 2, 3]
4548 :lockvar 1 alist
4549 :echo islocked('alist') " 1
4550 :echo islocked('alist[1]') " 0
4551
4552< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004553 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004554
Bram Moolenaarf3913272016-02-25 00:00:01 +01004555isnan({expr}) *isnan()*
4556 Return non-zero if {expr} is a float with value NaN. >
4557 echo isnan(0.0 / 0.0)
4558< 1 ~
4559
4560 {only available when compiled with the |+float| feature}
4561
Bram Moolenaar677ee682005-01-27 14:41:15 +00004562items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004563 Return a |List| with all the key-value pairs of {dict}. Each
4564 |List| item is a list with two items: the key of a {dict}
4565 entry and the value of this entry. The |List| is in arbitrary
4566 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004567
Bram Moolenaar38a55632016-02-15 22:07:32 +01004568job_getchannel({job}) *job_getchannel()*
4569 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01004570 To check if the job has no channel: >
4571 if string(job_getchannel()) == 'channel fail'
4572<
Bram Moolenaar38a55632016-02-15 22:07:32 +01004573 {only available when compiled with the |+job| feature}
4574
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004575job_info({job}) *job_info()*
4576 Returns a Dictionary with information about {job}:
4577 "status" what |job_status()| returns
4578 "channel" what |job_getchannel()| returns
4579 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01004580 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004581 "stoponexit" |job-stoponexit|
4582
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004583job_setoptions({job}, {options}) *job_setoptions()*
4584 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004585 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01004586 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004587
Bram Moolenaar38a55632016-02-15 22:07:32 +01004588job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01004589 Start a job and return a Job object. Unlike |system()| and
4590 |:!cmd| this does not wait for the job to finish.
4591
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004592 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01004593 Unix it is split up in white-separated parts to be passed to
4594 execvp(). Arguments in double quotes can contain white space.
4595
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004596 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01004597 and further items are the arguments. All items are converted
4598 to String. This works best on Unix.
4599
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004600 On MS-Windows, job_start() makes a GUI application hidden. If
4601 want to show it, Use |:!start| instead.
4602
Bram Moolenaar835dc632016-02-07 14:27:38 +01004603 The command is executed directly, not through a shell, the
4604 'shell' option is not used. To use the shell: >
4605 let job = job_start(["/bin/sh", "-c", "echo hello"])
4606< Or: >
4607 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004608< Note that this will start two processes, the shell and the
4609 command it executes. If you don't want this use the "exec"
4610 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004611
4612 On Unix $PATH is used to search for the executable only when
4613 the command does not contain a slash.
4614
4615 The job will use the same terminal as Vim. If it reads from
4616 stdin the job and Vim will be fighting over input, that
4617 doesn't work. Redirect stdin and stdout to avoid problems: >
4618 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
4619<
4620 The returned Job object can be used to get the status with
4621 |job_status()| and stop the job with |job_stop()|.
4622
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004623 {options} must be a Dictionary. It can contain many optional
4624 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004625
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004626 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004627
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004628job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01004629 Returns a String with the status of {job}:
4630 "run" job is running
4631 "fail" job failed to start
4632 "dead" job died or was stopped after running
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004633
4634 If an exit callback was set with the "exit-cb" option and the
4635 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004636
Bram Moolenaar8950a562016-03-12 15:22:55 +01004637 For more information see |job_info()|.
4638
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004639 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004640
4641job_stop({job} [, {how}]) *job_stop()*
4642 Stop the {job}. This can also be used to signal the job.
4643
Bram Moolenaar923d9262016-02-25 20:56:01 +01004644 When {how} is omitted or is "term" the job will be terminated.
4645 For Unix SIGTERM is sent. On MS-Windows the job will be
4646 terminated forcedly (there is no "gentle" way).
4647 This goes to the process group, thus children may also be
4648 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004649
Bram Moolenaar923d9262016-02-25 20:56:01 +01004650 Effect for Unix:
4651 "term" SIGTERM (default)
4652 "hup" SIGHUP
4653 "quit" SIGQUIT
4654 "int" SIGINT
4655 "kill" SIGKILL (strongest way to stop)
4656 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01004657
Bram Moolenaar923d9262016-02-25 20:56:01 +01004658 Effect for MS-Windows:
4659 "term" terminate process forcedly (default)
4660 "hup" CTRL_BREAK
4661 "quit" CTRL_BREAK
4662 "int" CTRL_C
4663 "kill" terminate process forcedly
4664 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004665
4666 On Unix the signal is sent to the process group. This means
4667 that when the job is "sh -c command" it affects both the shell
4668 and the command.
4669
Bram Moolenaar835dc632016-02-07 14:27:38 +01004670 The result is a Number: 1 if the operation could be executed,
4671 0 if "how" is not supported on the system.
4672 Note that even when the operation was executed, whether the
4673 job was actually stopped needs to be checked with
4674 job_status().
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004675 The status of the job isn't checked, the operation will even
4676 be done when Vim thinks the job isn't running.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004677
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004678 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004679
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004680join({list} [, {sep}]) *join()*
4681 Join the items in {list} together into one String.
4682 When {sep} is specified it is put in between the items. If
4683 {sep} is omitted a single space is used.
4684 Note that {sep} is not added at the end. You might want to
4685 add it there too: >
4686 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004687< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004688 converted into a string like with |string()|.
4689 The opposite function is |split()|.
4690
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004691js_decode({string}) *js_decode()*
4692 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004693 - Object key names do not have to be in quotes.
4694 - Empty items in an array (between two commas) are allowed and
4695 result in v:none items.
4696
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004697js_encode({expr}) *js_encode()*
4698 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004699 - Object key names are not in quotes.
4700 - v:none items in an array result in an empty item between
4701 commas.
4702 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004703 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004704 Will be encoded as:
4705 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004706 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004707 [1,null,{"one":1},null] ~
4708 This encoding is valid for JavaScript. It is more efficient
4709 than JSON, especially when using an array with optional items.
4710
4711
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004712json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01004713 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004714 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01004715 JSON and Vim values.
4716 The decoding is permissive:
4717 - A trailing comma in an array and object is ignored.
Bram Moolenaar705ada12016-01-24 17:56:50 +01004718 - More floating point numbers are recognized, e.g. "1." for
4719 "1.0".
Bram Moolenaar009d84a2016-01-28 14:12:00 +01004720 The result must be a valid Vim type:
4721 - An empty object member name is not allowed.
4722 - Duplicate object member names are not allowed.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004723
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004724json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01004725 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004726 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01004727 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004728 Vim values are converted as follows:
4729 Number decimal number
4730 Float floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01004731 Float nan "NaN"
4732 Float inf "Infinity"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004733 String in double quotes (possibly null)
Bram Moolenaar705ada12016-01-24 17:56:50 +01004734 Funcref not possible, error
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004735 List as an array (possibly null); when
4736 used recursively: []
4737 Dict as an object (possibly null); when
4738 used recursively: {}
4739 v:false "false"
4740 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004741 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004742 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01004743 Note that NaN and Infinity are passed on as values. This is
4744 missing in the JSON standard, but several implementations do
4745 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004746
Bram Moolenaard8b02732005-01-14 21:48:43 +00004747keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004748 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00004749 arbitrary order.
4750
Bram Moolenaar13065c42005-01-08 16:08:21 +00004751 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004752len({expr}) The result is a Number, which is the length of the argument.
4753 When {expr} is a String or a Number the length in bytes is
4754 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004755 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004756 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004757 When {expr} is a |Dictionary| the number of entries in the
4758 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004759 Otherwise an error is given.
4760
Bram Moolenaar071d4272004-06-13 20:20:40 +00004761 *libcall()* *E364* *E368*
4762libcall({libname}, {funcname}, {argument})
4763 Call function {funcname} in the run-time library {libname}
4764 with single argument {argument}.
4765 This is useful to call functions in a library that you
4766 especially made to be used with Vim. Since only one argument
4767 is possible, calling standard library functions is rather
4768 limited.
4769 The result is the String returned by the function. If the
4770 function returns NULL, this will appear as an empty string ""
4771 to Vim.
4772 If the function returns a number, use libcallnr()!
4773 If {argument} is a number, it is passed to the function as an
4774 int; if {argument} is a string, it is passed as a
4775 null-terminated string.
4776 This function will fail in |restricted-mode|.
4777
4778 libcall() allows you to write your own 'plug-in' extensions to
4779 Vim without having to recompile the program. It is NOT a
4780 means to call system functions! If you try to do so Vim will
4781 very probably crash.
4782
4783 For Win32, the functions you write must be placed in a DLL
4784 and use the normal C calling convention (NOT Pascal which is
4785 used in Windows System DLLs). The function must take exactly
4786 one parameter, either a character pointer or a long integer,
4787 and must return a character pointer or NULL. The character
4788 pointer returned must point to memory that will remain valid
4789 after the function has returned (e.g. in static data in the
4790 DLL). If it points to allocated memory, that memory will
4791 leak away. Using a static buffer in the function should work,
4792 it's then freed when the DLL is unloaded.
4793
4794 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00004795 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00004796 because Vim thinks it's a pointer.
4797 For Win32 systems, {libname} should be the filename of the DLL
4798 without the ".DLL" suffix. A full path is only required if
4799 the DLL is not in the usual places.
4800 For Unix: When compiling your own plugins, remember that the
4801 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004802 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004803 feature is present}
4804 Examples: >
4805 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004806<
4807 *libcallnr()*
4808libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004809 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004810 int instead of a string.
4811 {only in Win32 on some Unix versions, when the |+libcall|
4812 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00004813 Examples: >
4814 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004815 :call libcallnr("libc.so", "printf", "Hello World!\n")
4816 :call libcallnr("libc.so", "sleep", 10)
4817<
4818 *line()*
4819line({expr}) The result is a Number, which is the line number of the file
4820 position given with {expr}. The accepted positions are:
4821 . the cursor position
4822 $ the last line in the current buffer
4823 'x position of mark x (if the mark is not set, 0 is
4824 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00004825 w0 first line visible in current window
4826 w$ last line visible in current window
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00004827 v In Visual mode: the start of the Visual area (the
4828 cursor is the end). When not in Visual mode
4829 returns the cursor position. Differs from |'<| in
4830 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004831 Note that a mark in another file can be used. The line number
4832 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004833 To get the column number use |col()|. To get both use
4834 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004835 Examples: >
4836 line(".") line number of the cursor
4837 line("'t") line number of mark t
4838 line("'" . marker) line number of mark marker
4839< *last-position-jump*
4840 This autocommand jumps to the last known position in a file
4841 just after opening it, if the '" mark is set: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004842 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004843
Bram Moolenaar071d4272004-06-13 20:20:40 +00004844line2byte({lnum}) *line2byte()*
4845 Return the byte count from the start of the buffer for line
4846 {lnum}. This includes the end-of-line character, depending on
4847 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004848 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004849 This can also be used to get the byte count for the line just
4850 below the last line: >
4851 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004852< This is the buffer size plus one. If 'fileencoding' is empty
4853 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004854 When {lnum} is invalid, or the |+byte_offset| feature has been
4855 disabled at compile time, -1 is returned.
4856 Also see |byte2line()|, |go| and |:goto|.
4857
4858lispindent({lnum}) *lispindent()*
4859 Get the amount of indent for line {lnum} according the lisp
4860 indenting rules, as with 'lisp'.
4861 The indent is counted in spaces, the value of 'tabstop' is
4862 relevant. {lnum} is used just like in |getline()|.
4863 When {lnum} is invalid or Vim was not compiled the
4864 |+lispindent| feature, -1 is returned.
4865
4866localtime() *localtime()*
4867 Return the current time, measured as seconds since 1st Jan
4868 1970. See also |strftime()| and |getftime()|.
4869
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004870
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004871log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004872 Return the natural logarithm (base e) of {expr} as a |Float|.
4873 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004874 (0, inf].
4875 Examples: >
4876 :echo log(10)
4877< 2.302585 >
4878 :echo log(exp(5))
4879< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02004880 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004881
4882
Bram Moolenaar446cb832008-06-24 21:56:24 +00004883log10({expr}) *log10()*
4884 Return the logarithm of Float {expr} to base 10 as a |Float|.
4885 {expr} must evaluate to a |Float| or a |Number|.
4886 Examples: >
4887 :echo log10(1000)
4888< 3.0 >
4889 :echo log10(0.01)
4890< -2.0
4891 {only available when compiled with the |+float| feature}
4892
Bram Moolenaard38b0552012-04-25 19:07:41 +02004893luaeval({expr}[, {expr}]) *luaeval()*
4894 Evaluate Lua expression {expr} and return its result converted
4895 to Vim data structures. Second {expr} may hold additional
4896 argument accessible as _A inside first {expr}.
4897 Strings are returned as they are.
4898 Boolean objects are converted to numbers.
4899 Numbers are converted to |Float| values if vim was compiled
4900 with |+float| and to numbers otherwise.
4901 Dictionaries and lists obtained by vim.eval() are returned
4902 as-is.
4903 Other objects are returned as zero without any errors.
4904 See |lua-luaeval| for more details.
4905 {only available when compiled with the |+lua| feature}
4906
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004907map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004908 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004909 Replace each item in {expr} with the result of evaluating
4910 {string}.
4911 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar627b1d32009-11-17 11:20:35 +00004912 For a |Dictionary| |v:key| has the key of the current item
4913 and for a |List| |v:key| has the index of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004914 Example: >
4915 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004916< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004917
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004918 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004919 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004920 |literal-string| to avoid having to double backslashes. You
4921 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004922
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004923 The operation is done in-place. If you want a |List| or
4924 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02004925 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004926
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004927< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004928 When an error is encountered while evaluating {string} no
4929 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004930
4931
Bram Moolenaarbd743252010-10-20 21:23:33 +02004932maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
4933 When {dict} is omitted or zero: Return the rhs of mapping
4934 {name} in mode {mode}. The returned String has special
4935 characters translated like in the output of the ":map" command
4936 listing.
4937
4938 When there is no mapping for {name}, an empty String is
4939 returned.
4940
4941 The {name} can have special key names, like in the ":map"
4942 command.
4943
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004944 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004945 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02004946 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004947 "o" Operator-pending
4948 "i" Insert
4949 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02004950 "s" Select
4951 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00004952 "l" langmap |language-mapping|
4953 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004954 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004955
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004956 When {abbr} is there and it is non-zero use abbreviations
4957 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004958
4959 When {dict} is there and it is non-zero return a dictionary
4960 containing all the information of the mapping with the
4961 following items:
4962 "lhs" The {lhs} of the mapping.
4963 "rhs" The {rhs} of the mapping as typed.
4964 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02004965 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004966 "expr" 1 for an expression mapping (|:map-<expr>|).
4967 "buffer" 1 for a buffer local mapping (|:map-local|).
4968 "mode" Modes for which the mapping is defined. In
4969 addition to the modes mentioned above, these
4970 characters will be used:
4971 " " Normal, Visual and Operator-pending
4972 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01004973 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02004974 "sid" The script local ID, used for <sid> mappings
4975 (|<SID>|).
Bram Moolenaardfb18412013-12-11 18:53:29 +01004976 "nowait" Do not wait for other, longer mappings.
4977 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02004978
Bram Moolenaar071d4272004-06-13 20:20:40 +00004979 The mappings local to the current buffer are checked first,
4980 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00004981 This function can be used to map a key even when it's already
4982 mapped, and have it do the original mapping too. Sketch: >
4983 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
4984
Bram Moolenaar071d4272004-06-13 20:20:40 +00004985
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004986mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004987 Check if there is a mapping that matches with {name} in mode
4988 {mode}. See |maparg()| for {mode} and special names in
4989 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004990 When {abbr} is there and it is non-zero use abbreviations
4991 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004992 A match happens with a mapping that starts with {name} and
4993 with a mapping which is equal to the start of {name}.
4994
Bram Moolenaar446cb832008-06-24 21:56:24 +00004995 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004996 mapcheck("a") yes yes yes
4997 mapcheck("abc") yes yes yes
4998 mapcheck("ax") yes no no
4999 mapcheck("b") no no no
5000
5001 The difference with maparg() is that mapcheck() finds a
5002 mapping that matches with {name}, while maparg() only finds a
5003 mapping for {name} exactly.
5004 When there is no mapping that starts with {name}, an empty
5005 String is returned. If there is one, the rhs of that mapping
5006 is returned. If there are several mappings that start with
5007 {name}, the rhs of one of them is returned.
5008 The mappings local to the current buffer are checked first,
5009 then the global mappings.
5010 This function can be used to check if a mapping can be added
5011 without being ambiguous. Example: >
5012 :if mapcheck("_vv") == ""
5013 : map _vv :set guifont=7x13<CR>
5014 :endif
5015< This avoids adding the "_vv" mapping when there already is a
5016 mapping for "_v" or for "_vvv".
5017
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005018match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005019 When {expr} is a |List| then this returns the index of the
5020 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005021 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005022 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005023 Number, which gives the index (byte offset) in {expr} where
5024 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005025 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005026 If there is no match -1 is returned.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02005027 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005028 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005029 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005030 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005031< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00005032 *strpbrk()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005033 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00005034 :let sepidx = match(line, '[.,;: \t]')
5035< *strcasestr()*
5036 Vim doesn't have a strcasestr() function. But you can add
5037 "\c" to the pattern to ignore case: >
5038 :let idx = match(haystack, '\cneedle')
5039<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005040 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005041 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005042 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005043 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005044 :echo match("testing", "ing", 2)
5045< result is again "4". >
5046 :echo match("testing", "ing", 4)
5047< result is again "4". >
5048 :echo match("testing", "t", 2)
5049< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005050 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00005051 {start} bytes later, thus "^" will match at {start}. Except
5052 when {count} is given, then it's like matches before the
5053 {start} byte are ignored (this is a bit complicated to keep it
5054 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005055 For a String, if {start} < 0, it will be set to 0. For a list
5056 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005057 If {start} is out of range ({start} > strlen({expr}) for a
5058 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005059
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005060 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005061 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005062 character further. Thus this example results in 1: >
5063 echo match("testing", "..", 0, 2)
5064< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00005065 Note that when {count} is added the way {start} works changes,
5066 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005067
Bram Moolenaar071d4272004-06-13 20:20:40 +00005068 See |pattern| for the patterns that are accepted.
5069 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar446cb832008-06-24 21:56:24 +00005070 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00005071 done like 'magic' is set and 'cpoptions' is empty.
5072
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005073 *matchadd()* *E798* *E799* *E801*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005074matchadd({group}, {pattern}[, {priority}[, {id}[, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005075 Defines a pattern to be highlighted in the current window (a
5076 "match"). It will be highlighted with {group}. Returns an
5077 identification number (ID), which can be used to delete the
5078 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01005079 Matching is case sensitive and magic, unless case sensitivity
5080 or magicness are explicitly overridden in {pattern}. The
5081 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02005082 The "Conceal" value is special, it causes the match to be
5083 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005084
5085 The optional {priority} argument assigns a priority to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005086 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005087 highlighting overrule that of a match with a lower priority.
5088 A priority is specified as an integer (negative numbers are no
5089 exception). If the {priority} argument is not specified, the
5090 default priority is 10. The priority of 'hlsearch' is zero,
5091 hence all matches with a priority greater than zero will
5092 overrule it. Syntax highlighting (see 'syntax') is a separate
5093 mechanism, and regardless of the chosen priority a match will
5094 always overrule syntax highlighting.
5095
5096 The optional {id} argument allows the request for a specific
5097 match ID. If a specified ID is already taken, an error
5098 message will appear and the match will not be added. An ID
5099 is specified as a positive integer (zero excluded). IDs 1, 2
5100 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02005101 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005102 |matchadd()| automatically chooses a free ID.
5103
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005104 The optional {dict} argument allows for further custom
5105 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02005106 conceal character that will be shown for |hl-Conceal|
5107 highlighted matches. The dict can have the following members:
5108
5109 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005110 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02005111 matches, see |:syn-cchar|)
5112
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005113 The number of matches is not limited, as it is the case with
5114 the |:match| commands.
5115
5116 Example: >
5117 :highlight MyGroup ctermbg=green guibg=green
5118 :let m = matchadd("MyGroup", "TODO")
5119< Deletion of the pattern: >
5120 :call matchdelete(m)
5121
5122< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar446cb832008-06-24 21:56:24 +00005123 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005124 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005125
Bram Moolenaar6561d522015-07-21 15:48:27 +02005126matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()*
Bram Moolenaarb3414592014-06-17 17:48:32 +02005127 Same as |matchadd()|, but requires a list of positions {pos}
5128 instead of a pattern. This command is faster than |matchadd()|
5129 because it does not require to handle regular expressions and
5130 sets buffer line boundaries to redraw screen. It is supposed
5131 to be used when fast match additions and deletions are
5132 required, for example to highlight matching parentheses.
5133
5134 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005135 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02005136 line has number 1.
5137 - A list with one number, e.g., [23]. The whole line with this
5138 number will be highlighted.
5139 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005140 the line number, the second one is the column number (first
5141 column is 1, the value must correspond to the byte index as
5142 |col()| would return). The character at this position will
5143 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005144 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005145 the third number gives the length of the highlight in bytes.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005146
5147 The maximum number of positions is 8.
5148
5149 Example: >
5150 :highlight MyGroup ctermbg=green guibg=green
5151 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5152< Deletion of the pattern: >
5153 :call matchdelete(m)
5154
5155< Matches added by |matchaddpos()| are returned by
5156 |getmatches()| with an entry "pos1", "pos2", etc., with the
5157 value a list like the {pos} item.
5158 These matches cannot be set via |setmatches()|, however they
5159 can still be deleted by |clearmatches()|.
5160
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005161matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005162 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005163 |:2match| or |:3match| command.
5164 Return a |List| with two elements:
5165 The name of the highlight group used
5166 The pattern used.
5167 When {nr} is not 1, 2 or 3 returns an empty |List|.
5168 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005169 This is useful to save and restore a |:match|.
5170 Highlighting matches using the |:match| commands are limited
5171 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005172
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005173matchdelete({id}) *matchdelete()* *E802* *E803*
5174 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00005175 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005176 otherwise -1. See example for |matchadd()|. All matches can
5177 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005178
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005179matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005180 Same as |match()|, but return the index of first character
5181 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005182 :echo matchend("testing", "ing")
5183< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00005184 *strspn()* *strcspn()*
5185 Vim doesn't have a strspn() or strcspn() function, but you can
5186 do it with matchend(): >
5187 :let span = matchend(line, '[a-zA-Z]')
5188 :let span = matchend(line, '[^a-zA-Z]')
5189< Except that -1 is returned when there are no matches.
5190
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005191 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005192 :echo matchend("testing", "ing", 2)
5193< results in "7". >
5194 :echo matchend("testing", "ing", 5)
5195< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005196 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005197
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005198matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005199 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005200 list is the matched string, same as what matchstr() would
5201 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00005202 in |:substitute|. When an optional submatch didn't match an
5203 empty string is used. Example: >
5204 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5205< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005206 When there is no match an empty list is returned.
5207
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005208matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005209 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005210 :echo matchstr("testing", "ing")
5211< results in "ing".
5212 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005213 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005214 :echo matchstr("testing", "ing", 2)
5215< results in "ing". >
5216 :echo matchstr("testing", "ing", 5)
5217< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005218 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005219 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005220
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005221 *max()*
5222max({list}) Return the maximum value of all items in {list}.
5223 If {list} is not a list or one of the items in {list} cannot
5224 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005225 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005226
5227 *min()*
Bram Moolenaar79166c42007-05-10 18:29:51 +00005228min({list}) Return the minimum value of all items in {list}.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005229 If {list} is not a list or one of the items in {list} cannot
5230 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005231 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005232
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005233 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005234mkdir({name} [, {path} [, {prot}]])
5235 Create directory {name}.
5236 If {path} is "p" then intermediate directories are created as
5237 necessary. Otherwise it must be "".
5238 If {prot} is given it is used to set the protection bits of
5239 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar446cb832008-06-24 21:56:24 +00005240 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00005241 for others. This is only used for the last part of {name}.
5242 Thus if you create /tmp/foo/bar then /tmp/foo will be created
5243 with 0755.
5244 Example: >
5245 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
5246< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005247 Not available on all systems. To check use: >
5248 :if exists("*mkdir")
5249<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005250 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005251mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005252 If [expr] is supplied and it evaluates to a non-zero Number or
5253 a non-empty String (|non-zero-arg|), then the full mode is
5254 returned, otherwise only the first letter is returned. Note
5255 that " " and "0" are also non-empty strings.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005256
Bram Moolenaar071d4272004-06-13 20:20:40 +00005257 n Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00005258 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00005259 v Visual by character
5260 V Visual by line
5261 CTRL-V Visual blockwise
5262 s Select by character
5263 S Select by line
5264 CTRL-S Select blockwise
5265 i Insert
Bram Moolenaar446cb832008-06-24 21:56:24 +00005266 R Replace |R|
5267 Rv Virtual Replace |gR|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005268 c Command-line
Bram Moolenaar446cb832008-06-24 21:56:24 +00005269 cv Vim Ex mode |gQ|
5270 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005271 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00005272 rm The -- more -- prompt
5273 r? A |:confirm| query of some sort
5274 ! Shell or external command is executing
5275 This is useful in the 'statusline' option or when used
5276 with |remote_expr()| In most other places it always returns
5277 "c" or "n".
5278 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005279
Bram Moolenaar7e506b62010-01-19 15:55:06 +01005280mzeval({expr}) *mzeval()*
5281 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02005282 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01005283 Numbers and strings are returned as they are.
5284 Pairs (including lists and improper lists) and vectors are
5285 returned as Vim |Lists|.
5286 Hash tables are represented as Vim |Dictionary| type with keys
5287 converted to strings.
5288 All other types are converted to string with display function.
5289 Examples: >
5290 :mz (define l (list 1 2 3))
5291 :mz (define h (make-hash)) (hash-set! h "list" l)
5292 :echo mzeval("l")
5293 :echo mzeval("h")
5294<
5295 {only available when compiled with the |+mzscheme| feature}
5296
Bram Moolenaar071d4272004-06-13 20:20:40 +00005297nextnonblank({lnum}) *nextnonblank()*
5298 Return the line number of the first line at or below {lnum}
5299 that is not blank. Example: >
5300 if getline(nextnonblank(1)) =~ "Java"
5301< When {lnum} is invalid or there is no non-blank line at or
5302 below it, zero is returned.
5303 See also |prevnonblank()|.
5304
Bram Moolenaard35d7842013-01-23 17:17:10 +01005305nr2char({expr}[, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005306 Return a string with a single character, which has the number
5307 value {expr}. Examples: >
5308 nr2char(64) returns "@"
5309 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01005310< When {utf8} is omitted or zero, the current 'encoding' is used.
5311 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005312 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01005313< With {utf8} set to 1, always return utf-8 characters.
5314 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00005315 nr2char(10), because NULs are represented with newline
5316 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00005317 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005318
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005319or({expr}, {expr}) *or()*
5320 Bitwise OR on the two arguments. The arguments are converted
5321 to a number. A List, Dict or Float argument causes an error.
5322 Example: >
5323 :let bits = or(bits, 0x80)
5324
5325
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005326pathshorten({expr}) *pathshorten()*
5327 Shorten directory names in the path {expr} and return the
5328 result. The tail, the file name, is kept as-is. The other
5329 components in the path are reduced to single letters. Leading
5330 '~' and '.' characters are kept. Example: >
5331 :echo pathshorten('~/.vim/autoload/myfile.vim')
5332< ~/.v/a/myfile.vim ~
5333 It doesn't matter if the path exists or not.
5334
Bram Moolenaare9b892e2016-01-17 21:15:58 +01005335perleval({expr}) *perleval()*
5336 Evaluate Perl expression {expr} in scalar context and return
5337 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005338 converted, it is returned as a string Perl representation.
5339 Note: If you want an array or hash, {expr} must return a
5340 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01005341 Example: >
5342 :echo perleval('[1 .. 4]')
5343< [1, 2, 3, 4]
5344 {only available when compiled with the |+perl| feature}
5345
Bram Moolenaar446cb832008-06-24 21:56:24 +00005346pow({x}, {y}) *pow()*
5347 Return the power of {x} to the exponent {y} as a |Float|.
5348 {x} and {y} must evaluate to a |Float| or a |Number|.
5349 Examples: >
5350 :echo pow(3, 3)
5351< 27.0 >
5352 :echo pow(2, 16)
5353< 65536.0 >
5354 :echo pow(32, 0.20)
5355< 2.0
5356 {only available when compiled with the |+float| feature}
5357
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005358prevnonblank({lnum}) *prevnonblank()*
5359 Return the line number of the first line at or above {lnum}
5360 that is not blank. Example: >
5361 let ind = indent(prevnonblank(v:lnum - 1))
5362< When {lnum} is invalid or there is no non-blank line at or
5363 above it, zero is returned.
5364 Also see |nextnonblank()|.
5365
5366
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005367printf({fmt}, {expr1} ...) *printf()*
5368 Return a String with {fmt}, where "%" items are replaced by
5369 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005370 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005371< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005372 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005373
5374 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005375 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01005376 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00005377 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00005378 %.9s string truncated to 9 bytes
5379 %c single byte
5380 %d decimal number
5381 %5d decimal number padded with spaces to 5 characters
5382 %x hex number
5383 %04x hex number padded with zeros to at least 4 characters
5384 %X hex number using upper case letters
5385 %o octal number
5386 %f floating point number in the form 123.456
5387 %e floating point number in the form 1.234e3
5388 %E floating point number in the form 1.234E3
5389 %g floating point number, as %f or %e depending on value
5390 %G floating point number, as %f or %E depending on value
5391 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005392
5393 Conversion specifications start with '%' and end with the
5394 conversion type. All other characters are copied unchanged to
5395 the result.
5396
5397 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005398 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005399
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005400 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005401
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005402 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005403 Zero or more of the following flags:
5404
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005405 # The value should be converted to an "alternate
5406 form". For c, d, and s conversions, this option
5407 has no effect. For o conversions, the precision
5408 of the number is increased to force the first
5409 character of the output string to a zero (except
5410 if a zero value is printed with an explicit
5411 precision of zero).
5412 For x and X conversions, a non-zero result has
5413 the string "0x" (or "0X" for X conversions)
5414 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005415
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005416 0 (zero) Zero padding. For all conversions the converted
5417 value is padded on the left with zeros rather
5418 than blanks. If a precision is given with a
5419 numeric conversion (d, o, x, and X), the 0 flag
5420 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005421
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005422 - A negative field width flag; the converted value
5423 is to be left adjusted on the field boundary.
5424 The converted value is padded on the right with
5425 blanks, rather than on the left with blanks or
5426 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005427
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005428 ' ' (space) A blank should be left before a positive
5429 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005430
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005431 + A sign must always be placed before a number
Bram Moolenaar446cb832008-06-24 21:56:24 +00005432 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005433 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005434
5435 field-width
5436 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00005437 field width. If the converted value has fewer bytes
5438 than the field width, it will be padded with spaces on
5439 the left (or right, if the left-adjustment flag has
5440 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005441
5442 .precision
5443 An optional precision, in the form of a period '.'
5444 followed by an optional digit string. If the digit
5445 string is omitted, the precision is taken as zero.
5446 This gives the minimum number of digits to appear for
5447 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00005448 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005449 For floating point it is the number of digits after
5450 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005451
5452 type
5453 A character that specifies the type of conversion to
5454 be applied, see below.
5455
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005456 A field width or precision, or both, may be indicated by an
5457 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar446cb832008-06-24 21:56:24 +00005458 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005459 negative field width is treated as a left adjustment flag
5460 followed by a positive field width; a negative precision is
5461 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005462 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005463< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005464 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005465
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005466 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005467
Bram Moolenaar446cb832008-06-24 21:56:24 +00005468 *printf-d* *printf-o* *printf-x* *printf-X*
5469 doxX The Number argument is converted to signed decimal
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005470 (d), unsigned octal (o), or unsigned hexadecimal (x
5471 and X) notation. The letters "abcdef" are used for
5472 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005473 conversions.
5474 The precision, if any, gives the minimum number of
5475 digits that must appear; if the converted value
5476 requires fewer digits, it is padded on the left with
5477 zeros.
5478 In no case does a non-existent or small field width
5479 cause truncation of a numeric field; if the result of
5480 a conversion is wider than the field width, the field
5481 is expanded to contain the conversion result.
5482
Bram Moolenaar446cb832008-06-24 21:56:24 +00005483 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005484 c The Number argument is converted to a byte, and the
5485 resulting character is written.
5486
Bram Moolenaar446cb832008-06-24 21:56:24 +00005487 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005488 s The text of the String argument is used. If a
5489 precision is specified, no more bytes than the number
5490 specified are used.
Bram Moolenaar0122c402015-02-03 19:13:34 +01005491 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01005492 S The text of the String argument is used. If a
5493 precision is specified, no more display cells than the
5494 number specified are used. Without the |+multi_byte|
5495 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005496
Bram Moolenaar446cb832008-06-24 21:56:24 +00005497 *printf-f* *E807*
5498 f The Float argument is converted into a string of the
5499 form 123.456. The precision specifies the number of
5500 digits after the decimal point. When the precision is
5501 zero the decimal point is omitted. When the precision
5502 is not specified 6 is used. A really big number
5503 (out of range or dividing by zero) results in "inf".
5504 "0.0 / 0.0" results in "nan".
5505 Example: >
5506 echo printf("%.2f", 12.115)
5507< 12.12
5508 Note that roundoff depends on the system libraries.
5509 Use |round()| when in doubt.
5510
5511 *printf-e* *printf-E*
5512 e E The Float argument is converted into a string of the
5513 form 1.234e+03 or 1.234E+03 when using 'E'. The
5514 precision specifies the number of digits after the
5515 decimal point, like with 'f'.
5516
5517 *printf-g* *printf-G*
5518 g G The Float argument is converted like with 'f' if the
5519 value is between 0.001 (inclusive) and 10000000.0
5520 (exclusive). Otherwise 'e' is used for 'g' and 'E'
5521 for 'G'. When no precision is specified superfluous
5522 zeroes and '+' signs are removed, except for the zero
5523 immediately after the decimal point. Thus 10000000.0
5524 results in 1.0e7.
5525
5526 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005527 % A '%' is written. No argument is converted. The
5528 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005529
Bram Moolenaarc236c162008-07-13 17:41:49 +00005530 When a Number argument is expected a String argument is also
5531 accepted and automatically converted.
5532 When a Float or String argument is expected a Number argument
5533 is also accepted and automatically converted.
5534 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005535
Bram Moolenaar83bab712005-08-01 21:58:57 +00005536 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005537 The number of {exprN} arguments must exactly match the number
5538 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005539 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005540
5541
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005542pumvisible() *pumvisible()*
5543 Returns non-zero when the popup menu is visible, zero
5544 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005545 This can be used to avoid some things that would remove the
5546 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005547
Bram Moolenaare6ae6222013-05-21 21:01:10 +02005548 *E860*
Bram Moolenaar30b65812012-07-12 22:01:11 +02005549py3eval({expr}) *py3eval()*
5550 Evaluate Python expression {expr} and return its result
5551 converted to Vim data structures.
5552 Numbers and strings are returned as they are (strings are
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01005553 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02005554 'encoding').
5555 Lists are represented as Vim |List| type.
5556 Dictionaries are represented as Vim |Dictionary| type with
5557 keys converted to strings.
5558 {only available when compiled with the |+python3| feature}
5559
5560 *E858* *E859*
5561pyeval({expr}) *pyeval()*
5562 Evaluate Python expression {expr} and return its result
5563 converted to Vim data structures.
5564 Numbers and strings are returned as they are (strings are
5565 copied though).
5566 Lists are represented as Vim |List| type.
Bram Moolenaard09acef2012-09-21 14:54:30 +02005567 Dictionaries are represented as Vim |Dictionary| type,
5568 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02005569 {only available when compiled with the |+python| feature}
5570
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005571 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00005572range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005573 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00005574 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
5575 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
5576 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
5577 {max}] (increasing {expr} with {stride} each time, not
5578 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00005579 When the maximum is one before the start the result is an
5580 empty list. When the maximum is more than one before the
5581 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00005582 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005583 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00005584 range(2, 4) " [2, 3, 4]
5585 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005586 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00005587 range(0) " []
5588 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00005589<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005590 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005591readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005592 Read file {fname} and return a |List|, each line of the file
5593 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005594 separated with CR will result in a single long line (unless a
5595 NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02005596 All NUL characters are replaced with a NL character.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02005597 When {binary} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005598 - When the last line ends in a NL an extra empty list item is
5599 added.
5600 - No CR characters are removed.
5601 Otherwise:
5602 - CR characters that appear before a NL are removed.
5603 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02005604 - When 'encoding' is Unicode any UTF-8 byte order mark is
5605 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005606 When {max} is given this specifies the maximum number of lines
5607 to be read. Useful if you only want to check the first ten
5608 lines of a file: >
5609 :for line in readfile(fname, '', 10)
5610 : if line =~ 'Date' | echo line | endif
5611 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00005612< When {max} is negative -{max} lines from the end of the file
5613 are returned, or as many as there are.
5614 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005615 Note that without {max} the whole file is read into memory.
5616 Also note that there is no recognition of encoding. Read a
5617 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005618 When the file can't be opened an error message is given and
5619 the result is an empty list.
5620 Also see |writefile()|.
5621
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005622reltime([{start} [, {end}]]) *reltime()*
5623 Return an item that represents a time value. The format of
5624 the item depends on the system. It can be passed to
5625 |reltimestr()| to convert it to a string.
5626 Without an argument it returns the current time.
5627 With one argument is returns the time passed since the time
5628 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005629 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005630 and {end}.
5631 The {start} and {end} arguments must be values returned by
5632 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02005633 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005634
5635reltimestr({time}) *reltimestr()*
5636 Return a String that represents the time value of {time}.
5637 This is the number of seconds, a dot and the number of
5638 microseconds. Example: >
5639 let start = reltime()
5640 call MyFunction()
5641 echo reltimestr(reltime(start))
5642< Note that overhead for the commands will be added to the time.
5643 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005644 Leading spaces are used to make the string align nicely. You
5645 can use split() to remove it. >
5646 echo split(reltimestr(reltime(start)))[0]
5647< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005648 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005649
Bram Moolenaar071d4272004-06-13 20:20:40 +00005650 *remote_expr()* *E449*
5651remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005652 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005653 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005654 The result must be a String or a |List|. A |List| is turned
5655 into a String by joining the items with a line break in
5656 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00005657 If {idvar} is present, it is taken as the name of a
5658 variable and a {serverid} for later use with
5659 remote_read() is stored there.
5660 See also |clientserver| |RemoteReply|.
5661 This function is not available in the |sandbox|.
5662 {only available when compiled with the |+clientserver| feature}
5663 Note: Any errors will cause a local error message to be issued
5664 and the result will be the empty string.
5665 Examples: >
5666 :echo remote_expr("gvim", "2+2")
5667 :echo remote_expr("gvim1", "b:current_syntax")
5668<
5669
5670remote_foreground({server}) *remote_foreground()*
5671 Move the Vim server with the name {server} to the foreground.
5672 This works like: >
5673 remote_expr({server}, "foreground()")
5674< Except that on Win32 systems the client does the work, to work
5675 around the problem that the OS doesn't always allow the server
5676 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00005677 Note: This does not restore the window if it was minimized,
5678 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005679 This function is not available in the |sandbox|.
5680 {only in the Win32, Athena, Motif and GTK GUI versions and the
5681 Win32 console version}
5682
5683
5684remote_peek({serverid} [, {retvar}]) *remote_peek()*
5685 Returns a positive number if there are available strings
5686 from {serverid}. Copies any reply string into the variable
Bram Moolenaar446cb832008-06-24 21:56:24 +00005687 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005688 name of a variable.
5689 Returns zero if none are available.
5690 Returns -1 if something is wrong.
5691 See also |clientserver|.
5692 This function is not available in the |sandbox|.
5693 {only available when compiled with the |+clientserver| feature}
5694 Examples: >
5695 :let repl = ""
5696 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
5697
5698remote_read({serverid}) *remote_read()*
5699 Return the oldest available reply from {serverid} and consume
5700 it. It blocks until a reply is available.
5701 See also |clientserver|.
5702 This function is not available in the |sandbox|.
5703 {only available when compiled with the |+clientserver| feature}
5704 Example: >
5705 :echo remote_read(id)
5706<
5707 *remote_send()* *E241*
5708remote_send({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005709 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00005710 keys and the function returns immediately. At the Vim server
5711 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005712 If {idvar} is present, it is taken as the name of a variable
5713 and a {serverid} for later use with remote_read() is stored
5714 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005715 See also |clientserver| |RemoteReply|.
5716 This function is not available in the |sandbox|.
5717 {only available when compiled with the |+clientserver| feature}
5718 Note: Any errors will be reported in the server and may mess
5719 up the display.
5720 Examples: >
5721 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
5722 \ remote_read(serverid)
5723
5724 :autocmd NONE RemoteReply *
5725 \ echo remote_read(expand("<amatch>"))
5726 :echo remote_send("gvim", ":sleep 10 | echo ".
5727 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005728<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005729remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005730 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005731 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005732 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005733 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005734 item as {end} a list with one item is returned. When {end}
5735 points to an item before {idx} this is an error.
5736 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005737 Example: >
5738 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005739 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00005740remove({dict}, {key})
5741 Remove the entry from {dict} with key {key}. Example: >
5742 :echo "removed " . remove(dict, "one")
5743< If there is no {key} in {dict} this is an error.
5744
5745 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005746
Bram Moolenaar071d4272004-06-13 20:20:40 +00005747rename({from}, {to}) *rename()*
5748 Rename the file by the name {from} to the name {to}. This
5749 should also work to move files across file systems. The
5750 result is a Number, which is 0 if the file was renamed
5751 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00005752 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005753 This function is not available in the |sandbox|.
5754
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005755repeat({expr}, {count}) *repeat()*
5756 Repeat {expr} {count} times and return the concatenated
5757 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005758 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005759< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005760 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar446cb832008-06-24 21:56:24 +00005761 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005762 :let longlist = repeat(['a', 'b'], 3)
5763< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005764
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005765
Bram Moolenaar071d4272004-06-13 20:20:40 +00005766resolve({filename}) *resolve()* *E655*
5767 On MS-Windows, when {filename} is a shortcut (a .lnk file),
5768 returns the path the shortcut points to in a simplified form.
5769 On Unix, repeat resolving symbolic links in all path
5770 components of {filename} and return the simplified result.
5771 To cope with link cycles, resolving of symbolic links is
5772 stopped after 100 iterations.
5773 On other systems, return the simplified {filename}.
5774 The simplification step is done as by |simplify()|.
5775 resolve() keeps a leading path component specifying the
5776 current directory (provided the result is still a relative
5777 path name) and also keeps a trailing path separator.
5778
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005779 *reverse()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005780reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005781 {list}.
5782 If you want a list to remain unmodified make a copy first: >
5783 :let revlist = reverse(copy(mylist))
5784
Bram Moolenaar446cb832008-06-24 21:56:24 +00005785round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00005786 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00005787 as a |Float|. If {expr} lies halfway between two integral
5788 values, then use the larger one (away from zero).
5789 {expr} must evaluate to a |Float| or a |Number|.
5790 Examples: >
5791 echo round(0.456)
5792< 0.0 >
5793 echo round(4.5)
5794< 5.0 >
5795 echo round(-4.5)
5796< -5.0
5797 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005798
Bram Moolenaar9a773482013-06-11 18:40:13 +02005799screenattr(row, col) *screenattr()*
5800 Like screenchar(), but return the attribute. This is a rather
5801 arbitrary number that can only be used to compare to the
5802 attribute at other positions.
5803
5804screenchar(row, col) *screenchar()*
5805 The result is a Number, which is the character at position
5806 [row, col] on the screen. This works for every possible
5807 screen position, also status lines, window separators and the
5808 command line. The top left position is row one, column one
5809 The character excludes composing characters. For double-byte
5810 encodings it may only be the first byte.
5811 This is mainly to be used for testing.
5812 Returns -1 when row or col is out of range.
5813
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005814screencol() *screencol()*
5815 The result is a Number, which is the current screen column of
5816 the cursor. The leftmost column has number 1.
5817 This function is mainly used for testing.
5818
5819 Note: Always returns the current screen column, thus if used
5820 in a command (e.g. ":echo screencol()") it will return the
5821 column inside the command line, which is 1 when the command is
5822 executed. To get the cursor position in the file use one of
5823 the following mappings: >
5824 nnoremap <expr> GG ":echom ".screencol()."\n"
5825 nnoremap <silent> GG :echom screencol()<CR>
5826<
5827screenrow() *screenrow()*
5828 The result is a Number, which is the current screen row of the
5829 cursor. The top line has number one.
5830 This function is mainly used for testing.
5831
5832 Note: Same restrictions as with |screencol()|.
5833
Bram Moolenaar76929292008-01-06 19:07:36 +00005834search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005835 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00005836 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005837
Bram Moolenaar2df58b42012-11-28 18:21:11 +01005838 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005839 If there is no match a 0 is returned and the cursor doesn't
5840 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005841
Bram Moolenaar071d4272004-06-13 20:20:40 +00005842 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005843 'b' search Backward instead of forward
5844 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005845 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005846 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005847 'p' return number of matching sub-Pattern (see below)
5848 's' Set the ' mark at the previous location of the cursor
5849 'w' Wrap around the end of the file
5850 'W' don't Wrap around the end of the file
5851 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00005852 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
5853
Bram Moolenaar02743632005-07-25 20:42:36 +00005854 If the 's' flag is supplied, the ' mark is set, only if the
5855 cursor is moved. The 's' flag cannot be combined with the 'n'
5856 flag.
5857
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005858 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005859
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005860 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005861 column zero and then matches before the cursor are skipped.
5862 When the 'c' flag is present in 'cpo' the next search starts
5863 after the match. Without the 'c' flag the next search starts
5864 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005865
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005866 When the {stopline} argument is given then the search stops
5867 after searching this line. This is useful to restrict the
5868 search to a range of lines. Examples: >
5869 let match = search('(', 'b', line("w0"))
5870 let end = search('END', '', line("w$"))
5871< When {stopline} is used and it is not zero this also implies
5872 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00005873 A zero value is equal to not giving the argument.
5874
5875 When the {timeout} argument is given the search stops when
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02005876 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00005877 {timeout} is 500 the search stops after half a second.
5878 The value must not be negative. A zero value is like not
5879 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005880 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005881
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005882 *search()-sub-match*
5883 With the 'p' flag the returned value is one more than the
5884 first sub-match in \(\). One if none of them matched but the
5885 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005886 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005887
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005888 The cursor will be positioned at the match, unless the 'n'
5889 flag is used.
5890
Bram Moolenaar071d4272004-06-13 20:20:40 +00005891 Example (goes over all files in the argument list): >
5892 :let n = 1
5893 :while n <= argc() " loop over all files in arglist
5894 : exe "argument " . n
5895 : " start at the last char in the file and wrap for the
5896 : " first search to find match at start of file
5897 : normal G$
5898 : let flags = "w"
5899 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005900 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00005901 : let flags = "W"
5902 : endwhile
5903 : update " write the file if modified
5904 : let n = n + 1
5905 :endwhile
5906<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005907 Example for using some flags: >
5908 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
5909< This will search for the keywords "if", "else", and "endif"
5910 under or after the cursor. Because of the 'p' flag, it
5911 returns 1, 2, or 3 depending on which keyword is found, or 0
5912 if the search fails. With the cursor on the first word of the
5913 line:
5914 if (foo == 0) | let foo = foo + 1 | endif ~
5915 the function returns 1. Without the 'c' flag, the function
5916 finds the "endif" and returns 3. The same thing happens
5917 without the 'e' flag if the cursor is on the "f" of "if".
5918 The 'n' flag tells the function not to move the cursor.
5919
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005920
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005921searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
5922 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005923
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005924 With a non-zero {global} argument it works like |gD|, find
5925 first match in the file. Otherwise it works like |gd|, find
5926 first match in the function.
5927
5928 With a non-zero {thisblock} argument matches in a {} block
5929 that ends before the cursor position are ignored. Avoids
5930 finding variable declarations only valid in another scope.
5931
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005932 Moves the cursor to the found match.
5933 Returns zero for success, non-zero for failure.
5934 Example: >
5935 if searchdecl('myvar') == 0
5936 echo getline('.')
5937 endif
5938<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005939 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00005940searchpair({start}, {middle}, {end} [, {flags} [, {skip}
5941 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00005942 Search for the match of a nested start-end pair. This can be
5943 used to find the "endif" that matches an "if", while other
5944 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005945 The search starts at the cursor. The default is to search
5946 forward, include 'b' in {flags} to search backward.
5947 If a match is found, the cursor is positioned at it and the
5948 line number is returned. If no match is found 0 or -1 is
5949 returned and the cursor doesn't move. No error message is
5950 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005951
5952 {start}, {middle} and {end} are patterns, see |pattern|. They
5953 must not contain \( \) pairs. Use of \%( \) is allowed. When
5954 {middle} is not empty, it is found when searching from either
5955 direction, but only when not in a nested start-end pair. A
5956 typical use is: >
5957 searchpair('\<if\>', '\<else\>', '\<endif\>')
5958< By leaving {middle} empty the "else" is skipped.
5959
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005960 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
5961 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005962 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005963 outer pair. Implies the 'W' flag.
5964 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005965 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005966 Note: it's nearly always a good idea to use the 'W' flag, to
5967 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005968
5969 When a match for {start}, {middle} or {end} is found, the
5970 {skip} expression is evaluated with the cursor positioned on
5971 the start of the match. It should return non-zero if this
5972 match is to be skipped. E.g., because it is inside a comment
5973 or a string.
5974 When {skip} is omitted or empty, every match is accepted.
5975 When evaluating {skip} causes an error the search is aborted
5976 and -1 returned.
5977
Bram Moolenaar76929292008-01-06 19:07:36 +00005978 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005979
Bram Moolenaar071d4272004-06-13 20:20:40 +00005980 The value of 'ignorecase' is used. 'magic' is ignored, the
5981 patterns are used like it's on.
5982
5983 The search starts exactly at the cursor. A match with
5984 {start}, {middle} or {end} at the next character, in the
5985 direction of searching, is the first one found. Example: >
5986 if 1
5987 if 2
5988 endif 2
5989 endif 1
5990< When starting at the "if 2", with the cursor on the "i", and
5991 searching forwards, the "endif 2" is found. When starting on
5992 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar446cb832008-06-24 21:56:24 +00005993 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00005994 then this is considered to be a nested if/endif from "if 2" to
5995 "endif 2".
5996 When searching backwards and {end} is more than one character,
5997 it may be useful to put "\zs" at the end of the pattern, so
5998 that when the cursor is inside a match with the end it finds
5999 the matching start.
6000
6001 Example, to find the "endif" command in a Vim script: >
6002
6003 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
6004 \ 'getline(".") =~ "^\\s*\""')
6005
6006< The cursor must be at or after the "if" for which a match is
6007 to be found. Note that single-quote strings are used to avoid
6008 having to double the backslashes. The skip expression only
6009 catches comments at the start of a line, not after a command.
6010 Also, a word "en" or "if" halfway a line is considered a
6011 match.
6012 Another example, to search for the matching "{" of a "}": >
6013
6014 :echo searchpair('{', '', '}', 'bW')
6015
6016< This works when the cursor is at or before the "}" for which a
6017 match is to be found. To reject matches that syntax
6018 highlighting recognized as strings: >
6019
6020 :echo searchpair('{', '', '}', 'bW',
6021 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
6022<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006023 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006024searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
6025 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006026 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006027 column position of the match. The first element of the |List|
6028 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006029 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006030 returns [0, 0]. >
6031
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006032 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
6033<
6034 See |match-parens| for a bigger and more useful example.
6035
Bram Moolenaar76929292008-01-06 19:07:36 +00006036searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006037 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006038 column position of the match. The first element of the |List|
6039 is the line number and the second element is the byte index of
6040 the column position of the match. If no match is found,
6041 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006042 Example: >
6043 :let [lnum, col] = searchpos('mypattern', 'n')
6044
6045< When the 'p' flag is given then there is an extra item with
6046 the sub-pattern match number |search()-sub-match|. Example: >
6047 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
6048< In this example "submatch" is 2 when a lowercase letter is
6049 found |/\l|, 3 when an uppercase letter is found |/\u|.
6050
Bram Moolenaar071d4272004-06-13 20:20:40 +00006051server2client( {clientid}, {string}) *server2client()*
6052 Send a reply string to {clientid}. The most recent {clientid}
6053 that sent a string can be retrieved with expand("<client>").
6054 {only available when compiled with the |+clientserver| feature}
6055 Note:
6056 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006057 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006058 before calling any commands that waits for input.
6059 See also |clientserver|.
6060 Example: >
6061 :echo server2client(expand("<client>"), "HELLO")
6062<
6063serverlist() *serverlist()*
6064 Return a list of available server names, one per line.
6065 When there are no servers or the information is not available
6066 an empty string is returned. See also |clientserver|.
6067 {only available when compiled with the |+clientserver| feature}
6068 Example: >
6069 :echo serverlist()
6070<
6071setbufvar({expr}, {varname}, {val}) *setbufvar()*
6072 Set option or local variable {varname} in buffer {expr} to
6073 {val}.
6074 This also works for a global or local window option, but it
6075 doesn't work for a global or local window variable.
6076 For a local window option the global value is unchanged.
6077 For the use of {expr}, see |bufname()| above.
6078 Note that the variable name without "b:" must be used.
6079 Examples: >
6080 :call setbufvar(1, "&mod", 1)
6081 :call setbufvar("todo", "myvar", "foobar")
6082< This function is not available in the |sandbox|.
6083
Bram Moolenaar12969c02015-09-08 23:36:10 +02006084setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02006085 Set the current character search information to {dict},
6086 which contains one or more of the following entries:
6087
6088 char character which will be used for a subsequent
6089 |,| or |;| command; an empty string clears the
6090 character search
6091 forward direction of character search; 1 for forward,
6092 0 for backward
6093 until type of character search; 1 for a |t| or |T|
6094 character search, 0 for an |f| or |F|
6095 character search
6096
6097 This can be useful to save/restore a user's character search
6098 from a script: >
6099 :let prevsearch = getcharsearch()
6100 :" Perform a command which clobbers user's search
6101 :call setcharsearch(prevsearch)
6102< Also see |getcharsearch()|.
6103
Bram Moolenaar071d4272004-06-13 20:20:40 +00006104setcmdpos({pos}) *setcmdpos()*
6105 Set the cursor position in the command line to byte position
Bram Moolenaar446cb832008-06-24 21:56:24 +00006106 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006107 Use |getcmdpos()| to obtain the current position.
6108 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00006109 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
6110 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
6111 set after the command line is set to the expression. For
6112 |c_CTRL-R_=| it is set after evaluating the expression but
6113 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006114 When the number is too big the cursor is put at the end of the
6115 line. A number smaller than one has undefined results.
6116 Returns 0 when successful, 1 when not editing the command
6117 line.
6118
Bram Moolenaar80492532016-03-08 17:08:53 +01006119setfperm({fname}, {mode}) *setfperm()* *chmod*
6120 Set the file permissions for {fname} to {mode}.
6121 {mode} must be a string with 9 characters. It is of the form
6122 "rwxrwxrwx", where each group of "rwx" flags represent, in
6123 turn, the permissions of the owner of the file, the group the
6124 file belongs to, and other users. A '-' character means the
6125 permission is off, any other character means on. Multi-byte
6126 characters are not supported.
6127
6128 For example "rw-r-----" means read-write for the user,
6129 readable by the group, not accessible by others. "xx-x-----"
6130 would do the same thing.
6131
6132 Returns non-zero for success, zero for failure.
6133
6134 To read permissions see |getfperm()|.
6135
6136
Bram Moolenaar446cb832008-06-24 21:56:24 +00006137setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006138 Set line {lnum} of the current buffer to {text}. To insert
6139 lines use |append()|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006140 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006141 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006142 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006143 If this succeeds, 0 is returned. If this fails (most likely
6144 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006145 :call setline(5, strftime("%c"))
Bram Moolenaar446cb832008-06-24 21:56:24 +00006146< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006147 will be set to the items in the list. Example: >
6148 :call setline(5, ['aaa', 'bbb', 'ccc'])
6149< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02006150 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006151 : call setline(n, l)
6152 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00006153< Note: The '[ and '] marks are not set.
6154
Bram Moolenaar17c7c012006-01-26 22:25:15 +00006155setloclist({nr}, {list} [, {action}]) *setloclist()*
6156 Create or replace or add to the location list for window {nr}.
6157 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00006158 list window, the displayed location list is modified. For an
6159 invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006160 Otherwise, same as |setqflist()|.
6161 Also see |location-list|.
6162
6163setmatches({list}) *setmatches()*
6164 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00006165 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006166 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006167
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006168 *setpos()*
6169setpos({expr}, {list})
6170 Set the position for {expr}. Possible values:
6171 . the cursor
6172 'x mark x
6173
Bram Moolenaar493c1782014-05-28 14:34:46 +02006174 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006175 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02006176 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006177
Bram Moolenaar446cb832008-06-24 21:56:24 +00006178 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006179 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006180 the current buffer. To set a mark in another buffer you can
6181 use the |bufnr()| function to turn a file name into a buffer
6182 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00006183 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006184
6185 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006186 column is 1. Use a zero "lnum" to delete a mark. If "col" is
6187 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006188
6189 The "off" number is only used when 'virtualedit' is set. Then
6190 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006191 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006192 character.
6193
Bram Moolenaar493c1782014-05-28 14:34:46 +02006194 The "curswant" number is only used when setting the cursor
6195 position. It sets the preferred column for when moving the
6196 cursor vertically. When the "curswant" number is missing the
6197 preferred column is not set. When it is present and setting a
6198 mark position it is not used.
6199
Bram Moolenaardfb18412013-12-11 18:53:29 +01006200 Note that for '< and '> changing the line number may result in
6201 the marks to be effectively be swapped, so that '< is always
6202 before '>.
6203
Bram Moolenaar08250432008-02-13 11:42:46 +00006204 Returns 0 when the position could be set, -1 otherwise.
6205 An error message is given if {expr} is invalid.
6206
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02006207 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006208
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006209 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02006210 vertically; if you set the cursor position with this, |j| and
6211 |k| motions will jump to previous columns! Use |cursor()| to
6212 also set the preferred column. Also see the "curswant" key in
6213 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006214
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006215
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006216setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00006217 Create or replace or add to the quickfix list using the items
6218 in {list}. Each item in {list} is a dictionary.
6219 Non-dictionary items in {list} are ignored. Each dictionary
6220 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006221
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006222 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00006223 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006224 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00006225 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006226 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006227 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00006228 col column number
6229 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006230 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00006231 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006232 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00006233 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006234
Bram Moolenaar582fd852005-03-28 20:58:01 +00006235 The "col", "vcol", "nr", "type" and "text" entries are
6236 optional. Either "lnum" or "pattern" entry can be used to
6237 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006238 If the "filename" and "bufnr" entries are not present or
6239 neither the "lnum" or "pattern" entries are present, then the
6240 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006241 If both "pattern" and "lnum" are present then "pattern" will
6242 be used.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02006243 If you supply an empty {list}, the quickfix list will be
6244 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006245 Note that the list is not exactly the same as what
6246 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006247
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006248 If {action} is set to 'a', then the items from {list} are
6249 added to the existing quickfix list. If there is no existing
6250 list, then a new list is created. If {action} is set to 'r',
6251 then the items from the current quickfix list are replaced
6252 with the items from {list}. If {action} is not present or is
6253 set to ' ', then a new list is created.
6254
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006255 Returns zero for success, -1 for failure.
6256
6257 This function can be used to create a quickfix list
6258 independent of the 'errorformat' setting. Use a command like
6259 ":cc 1" to jump to the first position.
6260
6261
Bram Moolenaar071d4272004-06-13 20:20:40 +00006262 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01006263setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00006264 Set the register {regname} to {value}.
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006265 {value} may be any value returned by |getreg()|, including
6266 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006267 If {options} contains "a" or {regname} is upper case,
6268 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02006269 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006270 "c" or "v" |characterwise| mode
6271 "l" or "V" |linewise| mode
6272 "b" or "<CTRL-V>" |blockwise-visual| mode
6273 If a number immediately follows "b" or "<CTRL-V>" then this is
6274 used as the width of the selection - if it is not specified
6275 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006276 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006277
6278 If {options} contains no register settings, then the default
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006279 is to use character mode unless {value} ends in a <NL> for
6280 string {value} and linewise mode for list {value}. Blockwise
6281 mode is never selected automatically.
6282 Returns zero for success, non-zero for failure.
6283
6284 *E883*
Bram Moolenaar34401cc2014-08-29 15:12:19 +02006285 Note: you may not use |List| containing more than one item to
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006286 set search and expression registers. Lists containing no
6287 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006288
6289 Examples: >
6290 :call setreg(v:register, @*)
6291 :call setreg('*', @%, 'ac')
6292 :call setreg('a', "1\n2\n3", 'b5')
6293
6294< This example shows using the functions to save and restore a
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006295 register (note: you may not reliably restore register value
6296 without using the third argument to |getreg()| as without it
6297 newlines are represented as newlines AND Nul bytes are
6298 represented as newlines as well, see |NL-used-for-Nul|). >
6299 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006300 :let var_amode = getregtype('a')
6301 ....
6302 :call setreg('a', var_a, var_amode)
6303
6304< You can also change the type of a register by appending
6305 nothing: >
6306 :call setreg('a', '', 'al')
6307
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006308settabvar({tabnr}, {varname}, {val}) *settabvar()*
6309 Set tab-local variable {varname} to {val} in tab page {tabnr}.
6310 |t:var|
6311 Note that the variable name without "t:" must be used.
6312 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006313 This function is not available in the |sandbox|.
6314
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006315settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
6316 Set option or local variable {varname} in window {winnr} to
6317 {val}.
6318 Tabs are numbered starting with one. For the current tabpage
6319 use |setwinvar()|.
6320 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006321 This also works for a global or local buffer option, but it
6322 doesn't work for a global or local buffer variable.
6323 For a local buffer option the global value is unchanged.
6324 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006325 Examples: >
6326 :call settabwinvar(1, 1, "&list", 0)
6327 :call settabwinvar(3, 2, "myvar", "foobar")
6328< This function is not available in the |sandbox|.
6329
6330setwinvar({nr}, {varname}, {val}) *setwinvar()*
6331 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006332 Examples: >
6333 :call setwinvar(1, "&list", 0)
6334 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006335
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01006336sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01006337 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01006338 checksum of {string}.
6339 {only available when compiled with the |+cryptv| feature}
6340
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006341shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006342 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006343 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006344 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006345 quotes within {string}.
6346 For other systems, it will enclose {string} in single quotes
6347 and replace all "'" with "'\''".
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006348 When the {special} argument is present and it's a non-zero
6349 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006350 items such as "!", "%", "#" and "<cword>" will be preceded by
6351 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006352 command.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006353 The "!" character will be escaped (again with a |non-zero-arg|
6354 {special}) when 'shell' contains "csh" in the tail. That is
6355 because for csh and tcsh "!" is used for history replacement
6356 even when inside single quotes.
6357 The <NL> character is also escaped. With a |non-zero-arg|
6358 {special} and 'shell' containing "csh" in the tail it's
6359 escaped a second time.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006360 Example of use with a |:!| command: >
6361 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
6362< This results in a directory listing for the file under the
6363 cursor. Example of use with |system()|: >
6364 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01006365< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006366
6367
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006368shiftwidth() *shiftwidth()*
6369 Returns the effective value of 'shiftwidth'. This is the
6370 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006371 'tabstop' value. This function was introduced with patch
6372 7.3.694 in 2012, everybody should have it by now.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006373
6374
Bram Moolenaar071d4272004-06-13 20:20:40 +00006375simplify({filename}) *simplify()*
6376 Simplify the file name as much as possible without changing
6377 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
6378 Unix) are not resolved. If the first path component in
6379 {filename} designates the current directory, this will be
6380 valid for the result as well. A trailing path separator is
6381 not removed either.
6382 Example: >
6383 simplify("./dir/.././/file/") == "./file/"
6384< Note: The combination "dir/.." is only removed if "dir" is
6385 a searchable directory or does not exist. On Unix, it is also
6386 removed when "dir" is a symbolic link within the same
6387 directory. In order to resolve all the involved symbolic
6388 links before simplifying the path name, use |resolve()|.
6389
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006390
Bram Moolenaar446cb832008-06-24 21:56:24 +00006391sin({expr}) *sin()*
6392 Return the sine of {expr}, measured in radians, as a |Float|.
6393 {expr} must evaluate to a |Float| or a |Number|.
6394 Examples: >
6395 :echo sin(100)
6396< -0.506366 >
6397 :echo sin(-4.01)
6398< 0.763301
6399 {only available when compiled with the |+float| feature}
6400
6401
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006402sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006403 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006404 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006405 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006406 Examples: >
6407 :echo sinh(0.5)
6408< 0.521095 >
6409 :echo sinh(-0.9)
6410< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02006411 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006412
6413
Bram Moolenaar5f894962011-06-19 02:55:37 +02006414sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01006415 Sort the items in {list} in-place. Returns {list}.
6416
6417 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006418 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02006419
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006420< When {func} is omitted, is empty or zero, then sort() uses the
6421 string representation of each item to sort on. Numbers sort
6422 after Strings, |Lists| after Numbers. For sorting text in the
6423 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01006424
Bram Moolenaar34401cc2014-08-29 15:12:19 +02006425 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006426 ignored.
6427
6428 When {func} is given and it is 'n' then all items will be
6429 sorted numerical (Implementation detail: This uses the
6430 strtod() function to parse numbers, Strings, Lists, Dicts and
6431 Funcrefs will be considered as being 0).
6432
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01006433 When {func} is given and it is 'N' then all items will be
6434 sorted numerical. This is like 'n' but a string containing
6435 digits will be used as the number they represent.
6436
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01006437 When {func} is given and it is 'f' then all items will be
6438 sorted numerical. All values must be a Number or a Float.
6439
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006440 When {func} is a |Funcref| or a function name, this function
6441 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006442 items as argument and must return zero if they are equal, 1 or
6443 bigger if the first one sorts after the second one, -1 or
6444 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01006445
6446 {dict} is for functions with the "dict" attribute. It will be
6447 used to set the local variable "self". |Dictionary-function|
6448
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02006449 The sort is stable, items which compare equal (as number or as
6450 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02006451 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02006452 same order as they were originally.
6453
Bram Moolenaar327aa022014-03-25 18:24:23 +01006454 Also see |uniq()|.
6455
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006456 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006457 func MyCompare(i1, i2)
6458 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
6459 endfunc
6460 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006461< A shorter compare version for this specific simple case, which
6462 ignores overflow: >
6463 func MyCompare(i1, i2)
6464 return a:i1 - a:i2
6465 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006466<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00006467 *soundfold()*
6468soundfold({word})
6469 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00006470 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00006471 soundfolding. 'spell' must be set. When no sound folding is
6472 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00006473 This can be used for making spelling suggestions. Note that
6474 the method can be quite slow.
6475
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006476 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00006477spellbadword([{sentence}])
6478 Without argument: The result is the badly spelled word under
6479 or after the cursor. The cursor is moved to the start of the
6480 bad word. When no bad word is found in the cursor line the
6481 result is an empty string and the cursor doesn't move.
6482
6483 With argument: The result is the first word in {sentence} that
6484 is badly spelled. If there are no spelling mistakes the
6485 result is an empty string.
6486
6487 The return value is a list with two items:
6488 - The badly spelled word or an empty string.
6489 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006490 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00006491 "rare" rare word
6492 "local" word only valid in another region
6493 "caps" word should start with Capital
6494 Example: >
6495 echo spellbadword("the quik brown fox")
6496< ['quik', 'bad'] ~
6497
6498 The spelling information for the current window is used. The
6499 'spell' option must be set and the value of 'spelllang' is
6500 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006501
6502 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006503spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006504 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006505 When {max} is given up to this number of suggestions are
6506 returned. Otherwise up to 25 suggestions are returned.
6507
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006508 When the {capital} argument is given and it's non-zero only
6509 suggestions with a leading capital will be given. Use this
6510 after a match with 'spellcapcheck'.
6511
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006512 {word} can be a badly spelled word followed by other text.
6513 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00006514 suggestions also include the following text, thus you can
6515 replace a line.
6516
6517 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006518 returned. {word} itself is not included in the suggestions,
6519 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006520
6521 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00006522 'spell' option must be set and the values of 'spelllang' and
6523 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006524
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006525
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006526split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006527 Make a |List| out of {expr}. When {pattern} is omitted or
6528 empty each white-separated sequence of characters becomes an
6529 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006530 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01006531 removing the matched characters. 'ignorecase' is not used
6532 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006533 When the first or last item is empty it is omitted, unless the
6534 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00006535 Other empty items are kept when {pattern} matches at least one
6536 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006537 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006538 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006539< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006540 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02006541< If you want to keep the separator you can also use '\zs' at
6542 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00006543 :echo split('abc:def:ghi', ':\zs')
6544< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006545 Splitting a table where the first element can be empty: >
6546 :let items = split(line, ':', 1)
6547< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006548
6549
Bram Moolenaar446cb832008-06-24 21:56:24 +00006550sqrt({expr}) *sqrt()*
6551 Return the non-negative square root of Float {expr} as a
6552 |Float|.
6553 {expr} must evaluate to a |Float| or a |Number|. When {expr}
6554 is negative the result is NaN (Not a Number).
6555 Examples: >
6556 :echo sqrt(100)
6557< 10.0 >
6558 :echo sqrt(-4.01)
6559< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00006560 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006561 {only available when compiled with the |+float| feature}
6562
6563
6564str2float( {expr}) *str2float()*
6565 Convert String {expr} to a Float. This mostly works the same
6566 as when using a floating point number in an expression, see
6567 |floating-point-format|. But it's a bit more permissive.
6568 E.g., "1e40" is accepted, while in an expression you need to
6569 write "1.0e40".
6570 Text after the number is silently ignored.
6571 The decimal point is always '.', no matter what the locale is
6572 set to. A comma ends the number: "12,345.67" is converted to
6573 12.0. You can strip out thousands separators with
6574 |substitute()|: >
6575 let f = str2float(substitute(text, ',', '', 'g'))
6576< {only available when compiled with the |+float| feature}
6577
6578
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006579str2nr( {expr} [, {base}]) *str2nr()*
6580 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01006581 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006582 When {base} is omitted base 10 is used. This also means that
6583 a leading zero doesn't cause octal conversion to be used, as
6584 with the default String to Number conversion.
6585 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01006586 different base the result will be zero. Similarly, when
6587 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
6588 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006589 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006590
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006591
Bram Moolenaar979243b2015-06-26 19:35:49 +02006592strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02006593 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02006594 in String {expr}.
6595 When {skipcc} is omitted or zero, composing characters are
6596 counted separately.
6597 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02006598 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
6599
Bram Moolenaar86ae7202015-07-10 19:31:35 +02006600
6601 {skipcc} is only available after 7.4.755. For backward
6602 compatibility, you can define a wrapper function: >
6603 if has("patch-7.4.755")
6604 function s:strchars(str, skipcc)
6605 return strchars(a:str, a:skipcc)
6606 endfunction
6607 else
6608 function s:strchars(str, skipcc)
6609 if a:skipcc
6610 return strlen(substitute(a:str, ".", "x", "g"))
6611 else
6612 return strchars(a:str)
6613 endif
6614 endfunction
6615 endif
6616<
6617
Bram Moolenaardc536092010-07-18 15:45:49 +02006618strdisplaywidth({expr}[, {col}]) *strdisplaywidth()*
6619 The result is a Number, which is the number of display cells
Bram Moolenaar979243b2015-06-26 19:35:49 +02006620 String {expr} occupies on the screen when it starts at {col}.
Bram Moolenaardc536092010-07-18 15:45:49 +02006621 When {col} is omitted zero is used. Otherwise it is the
6622 screen column where to start. This matters for Tab
6623 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02006624 The option settings of the current window are used. This
6625 matters for anything that's displayed differently, such as
6626 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006627 When {expr} contains characters with East Asian Width Class
6628 Ambiguous, this function's return value depends on 'ambiwidth'.
6629 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006630
Bram Moolenaar071d4272004-06-13 20:20:40 +00006631strftime({format} [, {time}]) *strftime()*
6632 The result is a String, which is a formatted date and time, as
6633 specified by the {format} string. The given {time} is used,
6634 or the current time if no time is given. The accepted
6635 {format} depends on your system, thus this is not portable!
6636 See the manual page of the C function strftime() for the
6637 format. The maximum length of the result is 80 characters.
6638 See also |localtime()| and |getftime()|.
6639 The language can be changed with the |:language| command.
6640 Examples: >
6641 :echo strftime("%c") Sun Apr 27 11:49:23 1997
6642 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
6643 :echo strftime("%y%m%d %T") 970427 11:53:55
6644 :echo strftime("%H:%M") 11:55
6645 :echo strftime("%c", getftime("file.c"))
6646 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006647< Not available on all systems. To check use: >
6648 :if exists("*strftime")
6649
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006650stridx({haystack}, {needle} [, {start}]) *stridx()*
6651 The result is a Number, which gives the byte index in
6652 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006653 If {start} is specified, the search starts at index {start}.
6654 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01006655 :let colon1 = stridx(line, ":")
6656 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00006657< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006658 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006659 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006660 See also |strridx()|.
6661 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006662 :echo stridx("An Example", "Example") 3
6663 :echo stridx("Starting point", "Start") 0
6664 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006665< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006666 stridx() works similar to the C function strstr(). When used
6667 with a single character it works similar to strchr().
6668
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006669 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006670string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00006671 Float, String or a composition of them, then the result can be
6672 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006673 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00006674 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006675 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00006676 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00006677 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006678 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00006679 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00006680 Note that in String values the ' character is doubled.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006681 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006682
Bram Moolenaar071d4272004-06-13 20:20:40 +00006683 *strlen()*
6684strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00006685 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006686 If the argument is a Number it is first converted to a String.
6687 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02006688 If you want to count the number of multi-byte characters use
6689 |strchars()|.
6690 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006691
6692strpart({src}, {start}[, {len}]) *strpart()*
6693 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00006694 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006695 When non-existing bytes are included, this doesn't result in
6696 an error, the bytes are simply omitted.
6697 If {len} is missing, the copy continues from {start} till the
6698 end of the {src}. >
6699 strpart("abcdefg", 3, 2) == "de"
6700 strpart("abcdefg", -2, 4) == "ab"
6701 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00006702 strpart("abcdefg", 3) == "defg"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006703< Note: To get the first character, {start} must be 0. For
6704 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00006705 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006706<
Bram Moolenaar677ee682005-01-27 14:41:15 +00006707strridx({haystack}, {needle} [, {start}]) *strridx()*
6708 The result is a Number, which gives the byte index in
6709 {haystack} of the last occurrence of the String {needle}.
6710 When {start} is specified, matches beyond this index are
6711 ignored. This can be used to find a match before a previous
6712 match: >
6713 :let lastcomma = strridx(line, ",")
6714 :let comma2 = strridx(line, ",", lastcomma - 1)
6715< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006716 For pattern searches use |match()|.
6717 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00006718 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006719 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006720 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006721< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006722 When used with a single character it works similar to the C
6723 function strrchr().
6724
Bram Moolenaar071d4272004-06-13 20:20:40 +00006725strtrans({expr}) *strtrans()*
6726 The result is a String, which is {expr} with all unprintable
6727 characters translated into printable characters |'isprint'|.
6728 Like they are shown in a window. Example: >
6729 echo strtrans(@a)
6730< This displays a newline in register a as "^@" instead of
6731 starting a new line.
6732
Bram Moolenaar72597a52010-07-18 15:31:08 +02006733strwidth({expr}) *strwidth()*
6734 The result is a Number, which is the number of display cells
6735 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02006736 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006737 When {expr} contains characters with East Asian Width Class
6738 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006739 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006740
Bram Moolenaar41571762014-04-02 19:00:58 +02006741submatch({nr}[, {list}]) *submatch()*
Bram Moolenaar251e1912011-06-19 05:09:16 +02006742 Only for an expression in a |:substitute| command or
6743 substitute() function.
6744 Returns the {nr}'th submatch of the matched text. When {nr}
6745 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02006746 Note that a NL in the string can stand for a line break of a
6747 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006748 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02006749
6750 If {list} is present and non-zero then submatch() returns
6751 a list of strings, similar to |getline()| with two arguments.
6752 NL characters in the text represent NUL characters in the
6753 text.
6754 Only returns more than one item for |:substitute|, inside
6755 |substitute()| this list will always contain one or zero
6756 items, since there are no real line breaks.
6757
Bram Moolenaar071d4272004-06-13 20:20:40 +00006758 Example: >
6759 :s/\d\+/\=submatch(0) + 1/
6760< This finds the first number in the line and adds one to it.
6761 A line break is included as a newline character.
6762
6763substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
6764 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02006765 the first match of {pat} is replaced with {sub}.
6766 When {flags} is "g", all matches of {pat} in {expr} are
6767 replaced. Otherwise {flags} should be "".
6768
6769 This works like the ":substitute" command (without any flags).
6770 But the matching with {pat} is always done like the 'magic'
6771 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006772 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
6773 if you want to ignore or match case and ignore 'ignorecase'.
6774 'smartcase' is not used. See |string-match| for how {pat} is
6775 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006776
6777 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006778 Note that some codes in {sub} have a special meaning
Bram Moolenaar446cb832008-06-24 21:56:24 +00006779 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006780 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006781
Bram Moolenaar071d4272004-06-13 20:20:40 +00006782 When {pat} does not match in {expr}, {expr} is returned
6783 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006784
Bram Moolenaar071d4272004-06-13 20:20:40 +00006785 Example: >
6786 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
6787< This removes the last component of the 'path' option. >
6788 :echo substitute("testing", ".*", "\\U\\0", "")
6789< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02006790
6791 When {sub} starts with "\=", the remainder is interpreted as
6792 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006793 :echo substitute(s, '%\(\x\x\)',
6794 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00006795
Bram Moolenaar47136d72004-10-12 20:02:24 +00006796synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006797 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00006798 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006799 The syntax ID can be used with |synIDattr()| and
6800 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006801
Bram Moolenaar47136d72004-10-12 20:02:24 +00006802 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006803 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02006804 Note that when the position is after the last character,
6805 that's where the cursor can be in Insert mode, synID() returns
6806 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006807
Bram Moolenaar071d4272004-06-13 20:20:40 +00006808 When {trans} is non-zero, transparent items are reduced to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006809 item that they reveal. This is useful when wanting to know
Bram Moolenaar071d4272004-06-13 20:20:40 +00006810 the effective color. When {trans} is zero, the transparent
6811 item is returned. This is useful when wanting to know which
6812 syntax item is effective (e.g. inside parens).
6813 Warning: This function can be very slow. Best speed is
6814 obtained by going through the file in forward direction.
6815
6816 Example (echoes the name of the syntax item under the cursor): >
6817 :echo synIDattr(synID(line("."), col("."), 1), "name")
6818<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02006819
Bram Moolenaar071d4272004-06-13 20:20:40 +00006820synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
6821 The result is a String, which is the {what} attribute of
6822 syntax ID {synID}. This can be used to obtain information
6823 about a syntax item.
6824 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006825 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00006826 used, the attributes for the currently active highlighting are
6827 used (GUI, cterm or term).
6828 Use synIDtrans() to follow linked highlight groups.
6829 {what} result
6830 "name" the name of the syntax item
6831 "fg" foreground color (GUI: color name used to set
6832 the color, cterm: color number as a string,
6833 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006834 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01006835 "font" font name (only available in the GUI)
6836 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006837 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006838 "fg#" like "fg", but for the GUI and the GUI is
6839 running the name in "#RRGGBB" form
6840 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006841 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006842 "bold" "1" if bold
6843 "italic" "1" if italic
6844 "reverse" "1" if reverse
6845 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01006846 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00006847 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006848 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00006849
6850 Example (echoes the color of the syntax item under the
6851 cursor): >
6852 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
6853<
6854synIDtrans({synID}) *synIDtrans()*
6855 The result is a Number, which is the translated syntax ID of
6856 {synID}. This is the syntax group ID of what is being used to
6857 highlight the character. Highlight links given with
6858 ":highlight link" are followed.
6859
Bram Moolenaar483c5d82010-10-20 18:45:33 +02006860synconcealed({lnum}, {col}) *synconcealed()*
6861 The result is a List. The first item in the list is 0 if the
6862 character at the position {lnum} and {col} is not part of a
6863 concealable region, 1 if it is. The second item in the list is
6864 a string. If the first item is 1, the second item contains the
6865 text which will be displayed in place of the concealed text,
6866 depending on the current setting of 'conceallevel'. The third
6867 and final item in the list is a unique number representing the
6868 specific syntax region matched. This allows detection of the
6869 beginning of a new concealable region if there are two
6870 consecutive regions with the same replacement character.
6871 For an example use see $VIMRUNTIME/syntax/2html.vim .
6872
6873
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006874synstack({lnum}, {col}) *synstack()*
6875 Return a |List|, which is the stack of syntax items at the
6876 position {lnum} and {col} in the current window. Each item in
6877 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006878 The first item in the List is the outer region, following are
6879 items contained in that one. The last one is what |synID()|
6880 returns, unless not the whole item is highlighted or it is a
6881 transparent item.
6882 This function is useful for debugging a syntax file.
6883 Example that shows the syntax stack under the cursor: >
6884 for id in synstack(line("."), col("."))
6885 echo synIDattr(id, "name")
6886 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02006887< When the position specified with {lnum} and {col} is invalid
6888 nothing is returned. The position just after the last
6889 character in a line and the first column in an empty line are
6890 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006891
Bram Moolenaarc0197e22004-09-13 20:26:32 +00006892system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02006893 Get the output of the shell command {expr} as a string. See
6894 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02006895
6896 When {input} is given and is a string this string is written
6897 to a file and passed as stdin to the command. The string is
6898 written as-is, you need to take care of using the correct line
6899 separators yourself.
6900 If {input} is given and is a |List| it is written to the file
6901 in a way |writefile()| does with {binary} set to "b" (i.e.
6902 with a newline between each list item with newlines inside
6903 list items converted to NULs).
6904 Pipes are not used.
6905
Bram Moolenaar52a72462014-08-29 15:53:52 +02006906 When prepended by |:silent| the shell will not be set to
6907 cooked mode. This is meant to be used for commands that do
6908 not need the user to type. It avoids stray characters showing
6909 up on the screen which require |CTRL-L| to remove. >
6910 :silent let f = system('ls *.vim')
6911<
Bram Moolenaar26df0922014-02-23 23:39:13 +01006912 Note: Use |shellescape()| or |::S| with |expand()| or
6913 |fnamemodify()| to escape special characters in a command
6914 argument. Newlines in {expr} may cause the command to fail.
6915 The characters in 'shellquote' and 'shellxquote' may also
6916 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006917 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006918
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006919 The result is a String. Example: >
6920 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01006921 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00006922
6923< To make the result more system-independent, the shell output
6924 is filtered to replace <CR> with <NL> for Macintosh, and
6925 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02006926 To avoid the string being truncated at a NUL, all NUL
6927 characters are replaced with SOH (0x01).
6928
Bram Moolenaar071d4272004-06-13 20:20:40 +00006929 The command executed is constructed using several options:
6930 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
6931 ({tmp} is an automatically generated file name).
6932 For Unix and OS/2 braces are put around {expr} to allow for
6933 concatenated commands.
6934
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006935 The command will be executed in "cooked" mode, so that a
6936 CTRL-C will interrupt the command (on Unix at least).
6937
Bram Moolenaar071d4272004-06-13 20:20:40 +00006938 The resulting error code can be found in |v:shell_error|.
6939 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00006940
6941 Note that any wrong value in the options mentioned above may
6942 make the function fail. It has also been reported to fail
6943 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006944 Unlike ":!cmd" there is no automatic check for changed files.
6945 Use |:checktime| to force a check.
6946
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006947
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02006948systemlist({expr} [, {input}]) *systemlist()*
6949 Same as |system()|, but returns a |List| with lines (parts of
6950 output separated by NL) with NULs transformed into NLs. Output
6951 is the same as |readfile()| will output with {binary} argument
6952 set to "b".
6953
Bram Moolenaar975b5272016-03-15 23:10:59 +01006954 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02006955
6956
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006957tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006958 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006959 buffer associated with each window in the current tab page.
6960 {arg} specifies the number of tab page to be used. When
6961 omitted the current tab page is used.
6962 When {arg} is invalid the number zero is returned.
6963 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006964 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006965 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006966 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006967 endfor
6968< Note that a buffer may appear in more than one window.
6969
6970
6971tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00006972 The result is a Number, which is the number of the current
6973 tab page. The first tab page has number 1.
6974 When the optional argument is "$", the number of the last tab
6975 page is returned (the tab page count).
6976 The number can be used with the |:tab| command.
6977
6978
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01006979tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02006980 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006981 {tabarg} specifies the number of tab page to be used.
6982 {arg} is used like with |winnr()|:
6983 - When omitted the current window number is returned. This is
6984 the window which will be used when going to this tab page.
6985 - When "$" the number of windows is returned.
6986 - When "#" the previous window nr is returned.
6987 Useful examples: >
6988 tabpagewinnr(1) " current window of tab page 1
6989 tabpagewinnr(4, '$') " number of windows in tab page 4
6990< When {tabarg} is invalid zero is returned.
6991
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00006992 *tagfiles()*
6993tagfiles() Returns a |List| with the file names used to search for tags
6994 for the current buffer. This is the 'tags' option expanded.
6995
6996
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006997taglist({expr}) *taglist()*
6998 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00006999 Each list item is a dictionary with at least the following
7000 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00007001 name Name of the tag.
7002 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007003 defined. It is either relative to the
7004 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007005 cmd Ex command used to locate the tag in
7006 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007007 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007008 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007009 kind values. Only available when
7010 using a tags file generated by
7011 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007012 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007013 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007014 More entries may be present, depending on the content of the
7015 tags file: access, implementation, inherits and signature.
7016 Refer to the ctags documentation for information about these
7017 fields. For C code the fields "struct", "class" and "enum"
7018 may appear, they give the name of the entity the tag is
7019 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007020
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00007021 The ex-command 'cmd' can be either an ex search pattern, a
7022 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007023
7024 If there are no matching tags, then an empty list is returned.
7025
7026 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01007027 used in {expr}. This also make the function work faster.
7028 Refer to |tag-regexp| for more information about the tag
7029 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007030
7031 Refer to |'tags'| for information about how the tags file is
7032 located by Vim. Refer to |tags-file-format| for the format of
7033 the tags file generated by the different ctags tools.
7034
Bram Moolenaar071d4272004-06-13 20:20:40 +00007035tempname() *tempname()* *temp-file-name*
7036 The result is a String, which is the name of a file that
Bram Moolenaar446cb832008-06-24 21:56:24 +00007037 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar071d4272004-06-13 20:20:40 +00007038 is different for at least 26 consecutive calls. Example: >
7039 :let tmpfile = tempname()
7040 :exe "redir > " . tmpfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007041< For Unix, the file will be in a private directory |tempfile|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007042 For MS-Windows forward slashes are used when the 'shellslash'
7043 option is set or when 'shellcmdflag' starts with '-'.
7044
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007045
7046tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007047 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007048 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007049 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007050 Examples: >
7051 :echo tan(10)
7052< 0.648361 >
7053 :echo tan(-4.01)
7054< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02007055 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007056
7057
7058tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007059 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007060 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007061 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007062 Examples: >
7063 :echo tanh(0.5)
7064< 0.462117 >
7065 :echo tanh(-1)
7066< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02007067 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007068
7069
Bram Moolenaar975b5272016-03-15 23:10:59 +01007070 *timer_start()*
7071timer_start({time}, {callback} [, {options}])
7072 Create a timer and return the timer ID.
7073
7074 {time} is the waiting time in milliseconds. This is the
7075 minimum time before invoking the callback. When the system is
7076 busy or Vim is not waiting for input the time will be longer.
7077
7078 {callback} is the function to call. It can be the name of a
7079 function or a Funcref. It is called with one argument, which
7080 is the timer ID. The callback is only invoked when Vim is
7081 waiting for input.
7082
7083 {options} is a dictionary. Supported entries:
7084 "repeat" Number of times to repeat calling the
7085 callback. -1 means forever.
7086
7087 Example: >
7088 func MyHandler(timer)
7089 echo 'Handler called'
7090 endfunc
7091 let timer = timer_start(500, 'MyHandler',
7092 \ {'repeat': 3})
7093< This will invoke MyHandler() three times at 500 msec
7094 intervals.
7095 {only available when compiled with the |+timers| feature}
7096
Bram Moolenaar03602ec2016-03-20 20:57:45 +01007097timer_stop({timer}) *timer_stop()*
7098 Stop a timer. {timer} is an ID returned by timer_start().
7099 The timer callback will no longer be invoked.
7100
Bram Moolenaar071d4272004-06-13 20:20:40 +00007101tolower({expr}) *tolower()*
7102 The result is a copy of the String given, with all uppercase
7103 characters turned into lowercase (just like applying |gu| to
7104 the string).
7105
7106toupper({expr}) *toupper()*
7107 The result is a copy of the String given, with all lowercase
7108 characters turned into uppercase (just like applying |gU| to
7109 the string).
7110
Bram Moolenaar8299df92004-07-10 09:47:34 +00007111tr({src}, {fromstr}, {tostr}) *tr()*
7112 The result is a copy of the {src} string with all characters
7113 which appear in {fromstr} replaced by the character in that
7114 position in the {tostr} string. Thus the first character in
7115 {fromstr} is translated into the first character in {tostr}
7116 and so on. Exactly like the unix "tr" command.
7117 This code also deals with multibyte characters properly.
7118
7119 Examples: >
7120 echo tr("hello there", "ht", "HT")
7121< returns "Hello THere" >
7122 echo tr("<blob>", "<>", "{}")
7123< returns "{blob}"
7124
Bram Moolenaar446cb832008-06-24 21:56:24 +00007125trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007126 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00007127 equal to {expr} as a |Float| (truncate towards zero).
7128 {expr} must evaluate to a |Float| or a |Number|.
7129 Examples: >
7130 echo trunc(1.456)
7131< 1.0 >
7132 echo trunc(-5.456)
7133< -5.0 >
7134 echo trunc(4.0)
7135< 4.0
7136 {only available when compiled with the |+float| feature}
7137
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007138 *type()*
7139type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00007140 Number: 0
7141 String: 1
7142 Funcref: 2
7143 List: 3
7144 Dictionary: 4
Bram Moolenaar446cb832008-06-24 21:56:24 +00007145 Float: 5
Bram Moolenaar705ada12016-01-24 17:56:50 +01007146 Boolean: 6 (v:false and v:true)
7147 None 7 (v:null and v:none)
Bram Moolenaar835dc632016-02-07 14:27:38 +01007148 Job 8
Bram Moolenaar38a55632016-02-15 22:07:32 +01007149 Channel 9
Bram Moolenaar748bf032005-02-02 23:04:36 +00007150 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007151 :if type(myvar) == type(0)
7152 :if type(myvar) == type("")
7153 :if type(myvar) == type(function("tr"))
7154 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00007155 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00007156 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +01007157 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +01007158 :if type(myvar) == type(v:none)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007159
Bram Moolenaara17d4c12010-05-30 18:30:36 +02007160undofile({name}) *undofile()*
7161 Return the name of the undo file that would be used for a file
7162 with name {name} when writing. This uses the 'undodir'
7163 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02007164 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02007165 {name} is always expanded to the full path, since that is what
7166 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02007167 If {name} is empty undofile() returns an empty string, since a
7168 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02007169 Useful in combination with |:wundo| and |:rundo|.
7170 When compiled without the +persistent_undo option this always
7171 returns an empty string.
7172
Bram Moolenaara800b422010-06-27 01:15:55 +02007173undotree() *undotree()*
7174 Return the current state of the undo tree in a dictionary with
7175 the following items:
7176 "seq_last" The highest undo sequence number used.
7177 "seq_cur" The sequence number of the current position in
7178 the undo tree. This differs from "seq_last"
7179 when some changes were undone.
7180 "time_cur" Time last used for |:earlier| and related
7181 commands. Use |strftime()| to convert to
7182 something readable.
7183 "save_last" Number of the last file write. Zero when no
7184 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02007185 "save_cur" Number of the current position in the undo
7186 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02007187 "synced" Non-zero when the last undo block was synced.
7188 This happens when waiting from input from the
7189 user. See |undo-blocks|.
7190 "entries" A list of dictionaries with information about
7191 undo blocks.
7192
7193 The first item in the "entries" list is the oldest undo item.
7194 Each List item is a Dictionary with these items:
7195 "seq" Undo sequence number. Same as what appears in
7196 |:undolist|.
7197 "time" Timestamp when the change happened. Use
7198 |strftime()| to convert to something readable.
7199 "newhead" Only appears in the item that is the last one
7200 that was added. This marks the last change
7201 and where further changes will be added.
7202 "curhead" Only appears in the item that is the last one
7203 that was undone. This marks the current
7204 position in the undo tree, the block that will
7205 be used by a redo command. When nothing was
7206 undone after the last change this item will
7207 not appear anywhere.
7208 "save" Only appears on the last block before a file
7209 write. The number is the write count. The
7210 first write has number 1, the last one the
7211 "save_last" mentioned above.
7212 "alt" Alternate entry. This is again a List of undo
7213 blocks. Each item may again have an "alt"
7214 item.
7215
Bram Moolenaar327aa022014-03-25 18:24:23 +01007216uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
7217 Remove second and succeeding copies of repeated adjacent
7218 {list} items in-place. Returns {list}. If you want a list
7219 to remain unmodified make a copy first: >
7220 :let newlist = uniq(copy(mylist))
7221< The default compare function uses the string representation of
7222 each item. For the use of {func} and {dict} see |sort()|.
7223
Bram Moolenaar677ee682005-01-27 14:41:15 +00007224values({dict}) *values()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007225 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007226 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00007227
7228
Bram Moolenaar071d4272004-06-13 20:20:40 +00007229virtcol({expr}) *virtcol()*
7230 The result is a Number, which is the screen column of the file
7231 position given with {expr}. That is, the last screen position
7232 occupied by the character at that position, when the screen
7233 would be of unlimited width. When there is a <Tab> at the
7234 position, the returned Number will be the column at the end of
7235 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007236 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00007237 For the byte position use |col()|.
7238 For the use of {expr} see |col()|.
7239 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00007240 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007241 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02007242 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007243 When Virtual editing is active in the current mode, a position
7244 beyond the end of the line can be returned. |'virtualedit'|
7245 The accepted positions are:
7246 . the cursor position
7247 $ the end of the cursor line (the result is the
7248 number of displayed characters in the cursor line
7249 plus one)
7250 'x position of mark x (if the mark is not set, 0 is
7251 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01007252 v In Visual mode: the start of the Visual area (the
7253 cursor is the end). When not in Visual mode
7254 returns the cursor position. Differs from |'<| in
7255 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007256 Note that only marks in the current file can be used.
7257 Examples: >
7258 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
7259 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00007260 virtcol("'t") with text " there", with 't at 'h', returns 6
7261< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007262 A more advanced example that echoes the maximum length of
7263 all lines: >
7264 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
7265
Bram Moolenaar071d4272004-06-13 20:20:40 +00007266
7267visualmode([expr]) *visualmode()*
7268 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007269 used in the current buffer. Initially it returns an empty
7270 string, but once Visual mode has been used, it returns "v",
7271 "V", or "<CTRL-V>" (a single CTRL-V character) for
7272 character-wise, line-wise, or block-wise Visual mode
7273 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007274 Example: >
7275 :exe "normal " . visualmode()
7276< This enters the same Visual mode as before. It is also useful
7277 in scripts if you wish to act differently depending on the
7278 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007279 If Visual mode is active, use |mode()| to get the Visual mode
7280 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007281 *non-zero-arg*
7282 If [expr] is supplied and it evaluates to a non-zero Number or
7283 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaar446cb832008-06-24 21:56:24 +00007284 the old value is returned. Note that " " and "0" are also
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007285 non-empty strings, thus cause the mode to be cleared. A List,
7286 Dictionary or Float is not a Number or String, thus does not
7287 cause the mode to be cleared.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007288
Bram Moolenaar8738fc12013-02-20 17:59:11 +01007289wildmenumode() *wildmenumode()*
7290 Returns non-zero when the wildmenu is active and zero
7291 otherwise. See 'wildmenu' and 'wildmode'.
7292 This can be used in mappings to handle the 'wildcharm' option
7293 gracefully. (Makes only sense with |mapmode-c| mappings).
7294
7295 For example to make <c-j> work like <down> in wildmode, use: >
7296 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
7297<
7298 (Note, this needs the 'wildcharm' option set appropriately).
7299
7300
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01007301win_findbuf({bufnr}) *win_findbuf()*
7302 Returns a list with window IDs for windows that contain buffer
7303 {bufnr}. When there is none the list is empty.
7304
Bram Moolenaar86edef62016-03-13 18:07:30 +01007305win_getid([{win} [, {tab}]]) *win_getid()*
7306 Get the window ID for the specified window.
7307 When {win} is missing use the current window.
7308 With {win} this is the window number. The top window has
7309 number 1.
7310 Without {tab} use the current tab, otherwise the tab with
7311 number {tab}. The first tab has number one.
7312 Return zero if the window cannot be found.
7313
7314win_gotoid({expr}) *win_gotoid()*
7315 Go to window with ID {expr}. This may also change the current
7316 tabpage.
7317 Return 1 if successful, 0 if the window cannot be found.
7318
7319win_id2tabwin({expr} *win_id2tabwin()*
7320 Return a list with the tab number and window number of window
7321 with ID {expr}: [tabnr, winnr].
7322 Return [0, 0] if the window cannot be found.
7323
7324win_id2win({expr}) *win_id2win()*
7325 Return the window number of window with ID {expr}.
7326 Return 0 if the window cannot be found in the current tabpage.
7327
Bram Moolenaar071d4272004-06-13 20:20:40 +00007328 *winbufnr()*
7329winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007330 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007331 the buffer in the current window is returned. When window
7332 {nr} doesn't exist, -1 is returned.
7333 Example: >
7334 :echo "The file in the current window is " . bufname(winbufnr(0))
7335<
7336 *wincol()*
7337wincol() The result is a Number, which is the virtual column of the
7338 cursor in the window. This is counting screen cells from the
7339 left side of the window. The leftmost column is one.
7340
7341winheight({nr}) *winheight()*
7342 The result is a Number, which is the height of window {nr}.
7343 When {nr} is zero, the height of the current window is
7344 returned. When window {nr} doesn't exist, -1 is returned.
7345 An existing window always has a height of zero or more.
7346 Examples: >
7347 :echo "The current window has " . winheight(0) . " lines."
7348<
7349 *winline()*
7350winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar446cb832008-06-24 21:56:24 +00007351 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007352 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00007353 If the cursor was moved the view on the file will be updated
7354 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007355
7356 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007357winnr([{arg}]) The result is a Number, which is the number of the current
7358 window. The top window has number 1.
7359 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007360 last window is returned (the window count). >
7361 let window_count = winnr('$')
7362< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007363 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007364 If there is no previous window or it is in another tab page 0
7365 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007366 The number can be used with |CTRL-W_w| and ":wincmd w"
7367 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007368 Also see |tabpagewinnr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007369
7370 *winrestcmd()*
7371winrestcmd() Returns a sequence of |:resize| commands that should restore
7372 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007373 are opened or closed and the current window and tab page is
7374 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007375 Example: >
7376 :let cmd = winrestcmd()
7377 :call MessWithWindowSizes()
7378 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007379<
7380 *winrestview()*
7381winrestview({dict})
7382 Uses the |Dictionary| returned by |winsaveview()| to restore
7383 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +02007384 Note: The {dict} does not have to contain all values, that are
7385 returned by |winsaveview()|. If values are missing, those
7386 settings won't be restored. So you can use: >
7387 :call winrestview({'curswant': 4})
7388<
7389 This will only set the curswant value (the column the cursor
7390 wants to move on vertical movements) of the cursor to column 5
7391 (yes, that is 5), while all other settings will remain the
7392 same. This is useful, if you set the cursor position manually.
7393
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007394 If you have changed the values the result is unpredictable.
7395 If the window size changed the result won't be the same.
7396
7397 *winsaveview()*
7398winsaveview() Returns a |Dictionary| that contains information to restore
7399 the view of the current window. Use |winrestview()| to
7400 restore the view.
7401 This is useful if you have a mapping that jumps around in the
7402 buffer and you want to go back to the original view.
7403 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00007404 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +02007405 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007406 The return value includes:
7407 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +02007408 col cursor column (Note: the first column
7409 zero, as opposed to what getpos()
7410 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007411 coladd cursor column offset for 'virtualedit'
7412 curswant column for vertical movement
7413 topline first line in the window
7414 topfill filler lines, only in diff mode
7415 leftcol first column displayed
7416 skipcol columns skipped
7417 Note that no option values are saved.
7418
Bram Moolenaar071d4272004-06-13 20:20:40 +00007419
7420winwidth({nr}) *winwidth()*
7421 The result is a Number, which is the width of window {nr}.
7422 When {nr} is zero, the width of the current window is
7423 returned. When window {nr} doesn't exist, -1 is returned.
7424 An existing window always has a width of zero or more.
7425 Examples: >
7426 :echo "The current window has " . winwidth(0) . " columns."
7427 :if winwidth(0) <= 50
7428 : exe "normal 50\<C-W>|"
7429 :endif
7430<
Bram Moolenaared767a22016-01-03 22:49:16 +01007431wordcount() *wordcount()*
7432 The result is a dictionary of byte/chars/word statistics for
7433 the current buffer. This is the same info as provided by
7434 |g_CTRL-G|
7435 The return value includes:
7436 bytes Number of bytes in the buffer
7437 chars Number of chars in the buffer
7438 words Number of words in the buffer
7439 cursor_bytes Number of bytes before cursor position
7440 (not in Visual mode)
7441 cursor_chars Number of chars before cursor position
7442 (not in Visual mode)
7443 cursor_words Number of words before cursor position
7444 (not in Visual mode)
7445 visual_bytes Number of bytes visually selected
7446 (only in Visual mode)
7447 visual_chars Number of chars visually selected
7448 (only in Visual mode)
7449 visual_words Number of chars visually selected
7450 (only in Visual mode)
7451
7452
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007453 *writefile()*
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007454writefile({list}, {fname} [, {flags}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007455 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007456 separated with a NL. Each list item must be a String or
7457 Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007458 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007459 not be a NL after the last list item. An empty item at the
7460 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007461
7462 When {flags} contains "a" then append mode is used, lines are
7463 append to the file: >
7464 :call writefile(["foo"], "event.log", "a")
7465 :call writefile(["bar"], "event.log", "a")
7466>
7467< All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007468 Inserting CR characters needs to be done before passing {list}
7469 to writefile().
7470 An existing file is overwritten, if possible.
7471 When the write fails -1 is returned, otherwise 0. There is an
7472 error message if the file can't be created or when writing
7473 fails.
7474 Also see |readfile()|.
7475 To copy a file byte for byte: >
7476 :let fl = readfile("foo", "b")
7477 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007478
7479
7480xor({expr}, {expr}) *xor()*
7481 Bitwise XOR on the two arguments. The arguments are converted
7482 to a number. A List, Dict or Float argument causes an error.
7483 Example: >
7484 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +01007485<
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007486
Bram Moolenaar071d4272004-06-13 20:20:40 +00007487
7488 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02007489There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +000074901. Features that are only supported when they have been enabled when Vim
7491 was compiled |+feature-list|. Example: >
7492 :if has("cindent")
74932. Features that are only supported when certain conditions have been met.
7494 Example: >
7495 :if has("gui_running")
7496< *has-patch*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020074973. Included patches. The "patch123" feature means that patch 123 has been
7498 included. Note that this form does not check the version of Vim, you need
7499 to inspect |v:version| for that.
7500 Example (checking version 6.2.148 or later): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007501 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007502< Note that it's possible for patch 147 to be omitted even though 148 is
7503 included.
7504
75054. Beyond a certain version or at a certain version and including a specific
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007506 patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or
7507 later, or it is version 7.4 and patch 237 was included.
7508 Note that this only works for patch 7.4.237 and later, before that you
7509 need to use the example above that checks v:version. Example: >
7510 :if has("patch-7.4.248")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007511< Note that it's possible for patch 147 to be omitted even though 148 is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007512 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007513
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02007514acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007515all_builtin_terms Compiled with all builtin terminals enabled.
7516amiga Amiga version of Vim.
7517arabic Compiled with Arabic support |Arabic|.
7518arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00007519autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007520balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00007521balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007522beos BeOS version of Vim.
7523browse Compiled with |:browse| support, and browse() will
7524 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +02007525browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007526builtin_terms Compiled with some builtin terminals.
7527byte_offset Compiled with support for 'o' in 'statusline'
7528cindent Compiled with 'cindent' support.
7529clientserver Compiled with remote invocation support |clientserver|.
7530clipboard Compiled with 'clipboard' support.
7531cmdline_compl Compiled with |cmdline-completion| support.
7532cmdline_hist Compiled with |cmdline-history| support.
7533cmdline_info Compiled with 'showcmd' and 'ruler' support.
7534comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007535compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007536cryptv Compiled with encryption support |encryption|.
7537cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007538debug Compiled with "DEBUG" defined.
7539dialog_con Compiled with console dialog support.
7540dialog_gui Compiled with GUI dialog support.
7541diff Compiled with |vimdiff| and 'diff' support.
7542digraphs Compiled with support for digraphs.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02007543directx Compiled with support for Direct-X and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007544dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007545dos16 16 bits DOS version of Vim.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007546dos32 32 bits DOS (DJGPP) version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007547ebcdic Compiled on a machine with ebcdic character set.
7548emacs_tags Compiled with support for Emacs tags.
7549eval Compiled with expression evaluation support. Always
7550 true, of course!
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01007551ex_extra |+ex_extra|, always true now
Bram Moolenaar071d4272004-06-13 20:20:40 +00007552extra_search Compiled with support for |'incsearch'| and
7553 |'hlsearch'|
7554farsi Compiled with Farsi support |farsi|.
7555file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007556filterpipe When 'shelltemp' is off pipes are used for shell
7557 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00007558find_in_path Compiled with support for include file searches
7559 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007560float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007561fname_case Case in file names matters (for Amiga, MS-DOS, and
7562 Windows this is not present).
7563folding Compiled with |folding| support.
7564footer Compiled with GUI footer support. |gui-footer|
7565fork Compiled to use fork()/exec() instead of system().
7566gettext Compiled with message translation |multi-lang|
7567gui Compiled with GUI enabled.
7568gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007569gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007570gui_gtk Compiled with GTK+ GUI (any version).
7571gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +01007572gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007573gui_mac Compiled with Macintosh GUI.
7574gui_motif Compiled with Motif GUI.
7575gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007576gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007577gui_win32 Compiled with MS Windows Win32 GUI.
7578gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007579hangul_input Compiled with Hangul input support. |hangul|
7580iconv Can use iconv() for conversion.
7581insert_expand Compiled with support for CTRL-X expansion commands in
7582 Insert mode.
7583jumplist Compiled with |jumplist| support.
7584keymap Compiled with 'keymap' support.
7585langmap Compiled with 'langmap' support.
7586libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +02007587linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
7588 'breakindent' support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007589lispindent Compiled with support for lisp indenting.
7590listcmds Compiled with commands for the buffer list |:files|
7591 and the argument list |arglist|.
7592localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02007593lua Compiled with Lua interface |Lua|.
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01007594mac Any Macintosh version of Vim.
Bram Moolenaarf8df7ad2016-02-16 14:07:40 +01007595macunix Compiled for OS X, with darwin
7596osx Compiled for OS X, with or without darwin
Bram Moolenaar071d4272004-06-13 20:20:40 +00007597menu Compiled with support for |:menu|.
7598mksession Compiled with support for |:mksession|.
7599modify_fname Compiled with file name modifiers. |filename-modifiers|
7600mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007601mouse_dec Compiled with support for Dec terminal mouse.
7602mouse_gpm Compiled with support for gpm (Linux console mouse)
7603mouse_netterm Compiled with support for netterm mouse.
7604mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007605mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +02007606mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01007607mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007608mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007609mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00007610multi_byte Compiled with support for 'encoding'
7611multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007612multi_byte_ime Compiled with support for IME input method.
7613multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00007614mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02007615netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007616netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007617ole Compiled with OLE automation support for Win32.
7618os2 OS/2 version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007619path_extra Compiled with up/downwards search in 'path' and 'tags'
7620perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02007621persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007622postscript Compiled with PostScript file printing.
7623printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00007624profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02007625python Compiled with Python 2.x interface. |has-python|
7626python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007627qnx QNX version of Vim.
7628quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00007629reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007630rightleft Compiled with 'rightleft' support.
7631ruby Compiled with Ruby interface |ruby|.
7632scrollbind Compiled with 'scrollbind' support.
7633showcmd Compiled with 'showcmd' support.
7634signs Compiled with |:sign| support.
7635smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007636spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00007637startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007638statusline Compiled with support for 'statusline', 'rulerformat'
7639 and special formats of 'titlestring' and 'iconstring'.
7640sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007641syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007642syntax_items There are active syntax highlighting items for the
7643 current buffer.
7644system Compiled to use system() instead of fork()/exec().
7645tag_binary Compiled with binary searching in tags files
7646 |tag-binary-search|.
7647tag_old_static Compiled with support for old static tags
7648 |tag-old-static|.
7649tag_any_white Compiled with support for any white characters in tags
7650 files |tag-any-white|.
7651tcl Compiled with Tcl interface.
7652terminfo Compiled with terminfo instead of termcap.
7653termresponse Compiled with support for |t_RV| and |v:termresponse|.
7654textobjects Compiled with support for |text-objects|.
7655tgetent Compiled with tgetent support, able to use a termcap
7656 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +01007657timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007658title Compiled with window title support |'title'|.
7659toolbar Compiled with support for |gui-toolbar|.
7660unix Unix version of Vim.
7661user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007662vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007663vim_starting True while initial source'ing takes place. |startup|
7664viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007665virtualedit Compiled with 'virtualedit' option.
7666visual Compiled with Visual mode.
7667visualextra Compiled with extra Visual mode commands.
7668 |blockwise-operators|.
7669vms VMS version of Vim.
7670vreplace Compiled with |gR| and |gr| commands.
7671wildignore Compiled with 'wildignore' option.
7672wildmenu Compiled with 'wildmenu' option.
Bram Moolenaard58e9292011-02-09 17:07:58 +01007673win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
7674 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007675win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007676win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007677win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007678winaltkeys Compiled with 'winaltkeys' option.
7679windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007680writebackup Compiled with 'writebackup' default on.
7681xfontset Compiled with X fontset support |xfontset|.
7682xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02007683xpm Compiled with pixmap support.
7684xpm_w32 Compiled with pixmap support for Win32. (Only for
7685 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007686xsmp Compiled with X session management support.
7687xsmp_interact Compiled with interactive X session management support.
7688xterm_clipboard Compiled with support for xterm clipboard.
7689xterm_save Compiled with support for saving and restoring the
7690 xterm screen.
7691x11 Compiled with X11 support.
7692
7693 *string-match*
7694Matching a pattern in a String
7695
7696A regexp pattern as explained at |pattern| is normally used to find a match in
7697the buffer lines. When a pattern is used to find a match in a String, almost
7698everything works in the same way. The difference is that a String is handled
7699like it is one line. When it contains a "\n" character, this is not seen as a
7700line break for the pattern. It can be matched with a "\n" in the pattern, or
7701with ".". Example: >
7702 :let a = "aaaa\nxxxx"
7703 :echo matchstr(a, "..\n..")
7704 aa
7705 xx
7706 :echo matchstr(a, "a.x")
7707 a
7708 x
7709
7710Don't forget that "^" will only match at the first character of the String and
7711"$" at the last character of the string. They don't match after or before a
7712"\n".
7713
7714==============================================================================
77155. Defining functions *user-functions*
7716
7717New functions can be defined. These can be called just like builtin
7718functions. The function executes a sequence of Ex commands. Normal mode
7719commands can be executed with the |:normal| command.
7720
7721The function name must start with an uppercase letter, to avoid confusion with
7722builtin functions. To prevent from using the same name in different scripts
7723avoid obvious, short names. A good habit is to start the function name with
7724the name of the script, e.g., "HTMLcolor()".
7725
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007726It's also possible to use curly braces, see |curly-braces-names|. And the
7727|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007728
7729 *local-function*
7730A function local to a script must start with "s:". A local script function
7731can only be called from within the script and from functions, user commands
7732and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007733function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00007734instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007735There are only script-local functions, no buffer-local or window-local
7736functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007737
7738 *:fu* *:function* *E128* *E129* *E123*
7739:fu[nction] List all functions and their arguments.
7740
7741:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007742 {name} can also be a |Dictionary| entry that is a
7743 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007744 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007745
7746:fu[nction] /{pattern} List functions with a name matching {pattern}.
7747 Example that lists all functions ending with "File": >
7748 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00007749<
7750 *:function-verbose*
7751When 'verbose' is non-zero, listing a function will also display where it was
7752last defined. Example: >
7753
7754 :verbose function SetFileTypeSH
7755 function SetFileTypeSH(name)
7756 Last set from /usr/share/vim/vim-7.0/filetype.vim
7757<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007758See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00007759
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007760 *E124* *E125* *E853* *E884*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007761:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007762 Define a new function by the name {name}. The name
7763 must be made of alphanumeric characters and '_', and
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007764 must start with a capital or "s:" (see above). Note
7765 that using "b:" or "g:" is not allowed. (since patch
7766 7.4.260 E884 is given if the function name has a colon
7767 in the name, e.g. for "foo:bar()". Before that patch
7768 no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007769
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007770 {name} can also be a |Dictionary| entry that is a
7771 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007772 :function dict.init(arg)
Bram Moolenaar446cb832008-06-24 21:56:24 +00007773< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007774 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar446cb832008-06-24 21:56:24 +00007775 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007776 result is a |Funcref| to a numbered function. The
7777 function can only be used with a |Funcref| and will be
7778 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007779 *E127* *E122*
7780 When a function by this name already exists and [!] is
7781 not used an error message is given. When [!] is used,
7782 an existing function is silently replaced. Unless it
7783 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007784
7785 For the {arguments} see |function-argument|.
7786
Bram Moolenaar8d043172014-01-23 14:24:41 +01007787 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007788 When the [range] argument is added, the function is
7789 expected to take care of a range itself. The range is
7790 passed as "a:firstline" and "a:lastline". If [range]
7791 is excluded, ":{range}call" will call the function for
7792 each line in the range, with the cursor on the start
7793 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007794 The cursor is still moved to the first line of the
7795 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +01007796 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007797 When the [abort] argument is added, the function will
7798 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +01007799 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007800 When the [dict] argument is added, the function must
Bram Moolenaar446cb832008-06-24 21:56:24 +00007801 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007802 local variable "self" will then be set to the
7803 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007804
Bram Moolenaar446cb832008-06-24 21:56:24 +00007805 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00007806 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00007807 will not be changed by the function. This also
7808 implies that the effect of |:nohlsearch| is undone
7809 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00007810
Bram Moolenaar071d4272004-06-13 20:20:40 +00007811 *:endf* *:endfunction* *E126* *E193*
7812:endf[unction] The end of a function definition. Must be on a line
7813 by its own, without other commands.
7814
7815 *:delf* *:delfunction* *E130* *E131*
7816:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007817 {name} can also be a |Dictionary| entry that is a
7818 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007819 :delfunc dict.init
Bram Moolenaar446cb832008-06-24 21:56:24 +00007820< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007821 function is deleted if there are no more references to
7822 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007823 *:retu* *:return* *E133*
7824:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
7825 evaluated and returned as the result of the function.
7826 If "[expr]" is not given, the number 0 is returned.
7827 When a function ends without an explicit ":return",
7828 the number 0 is returned.
7829 Note that there is no check for unreachable lines,
7830 thus there is no warning if commands follow ":return".
7831
7832 If the ":return" is used after a |:try| but before the
7833 matching |:finally| (if present), the commands
7834 following the ":finally" up to the matching |:endtry|
7835 are executed first. This process applies to all
7836 nested ":try"s inside the function. The function
7837 returns at the outermost ":endtry".
7838
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007839 *function-argument* *a:var*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007840An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007841be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007842 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007843Up to 20 arguments can be given, separated by commas. After the named
7844arguments an argument "..." can be specified, which means that more arguments
7845may optionally be following. In the function the extra arguments can be used
7846as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007847can be 0). "a:000" is set to a |List| that contains these arguments. Note
7848that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007849 *E742*
7850The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007851However, if a |List| or |Dictionary| is used, you can change their contents.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007852Thus you can pass a |List| to a function and have the function add an item to
7853it. If you want to make sure the function cannot change a |List| or
7854|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007855
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007856When not using "...", the number of arguments in a function call must be equal
7857to the number of named arguments. When using "...", the number of arguments
7858may be larger.
7859
7860It is also possible to define a function without any arguments. You must
7861still supply the () then. The body of the function follows in the next lines,
7862until the matching |:endfunction|. It is allowed to define another function
7863inside a function body.
7864
7865 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007866Inside a function variables can be used. These are local variables, which
7867will disappear when the function returns. Global variables need to be
7868accessed with "g:".
7869
7870Example: >
7871 :function Table(title, ...)
7872 : echohl Title
7873 : echo a:title
7874 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00007875 : echo a:0 . " items:"
7876 : for s in a:000
7877 : echon ' ' . s
7878 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00007879 :endfunction
7880
7881This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00007882 call Table("Table", "line1", "line2")
7883 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007884
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007885To return more than one value, return a |List|: >
7886 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007887 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007888 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007889 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007890 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007891 :endfunction
7892
7893This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007894 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007895 :if success == "ok"
7896 : echo div
7897 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007898<
Bram Moolenaar39f05632006-03-19 22:15:26 +00007899 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007900:[range]cal[l] {name}([arguments])
7901 Call a function. The name of the function and its arguments
7902 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007903 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007904 Without a range and for functions that accept a range, the
7905 function is called once. When a range is given the cursor is
7906 positioned at the start of the first line before executing the
7907 function.
7908 When a range is given and the function doesn't handle it
7909 itself, the function is executed for each line in the range,
7910 with the cursor in the first column of that line. The cursor
7911 is left at the last line (possibly moved by the last function
Bram Moolenaar446cb832008-06-24 21:56:24 +00007912 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00007913 this works:
7914 *function-range-example* >
7915 :function Mynumber(arg)
7916 : echo line(".") . " " . a:arg
7917 :endfunction
7918 :1,5call Mynumber(getline("."))
7919<
7920 The "a:firstline" and "a:lastline" are defined anyway, they
7921 can be used to do something different at the start or end of
7922 the range.
7923
7924 Example of a function that handles the range itself: >
7925
7926 :function Cont() range
7927 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
7928 :endfunction
7929 :4,8call Cont()
7930<
7931 This function inserts the continuation character "\" in front
7932 of all the lines in the range, except the first one.
7933
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007934 When the function returns a composite value it can be further
7935 dereferenced, but the range will not be used then. Example: >
7936 :4,8call GetDict().method()
7937< Here GetDict() gets the range but method() does not.
7938
Bram Moolenaar071d4272004-06-13 20:20:40 +00007939 *E132*
7940The recursiveness of user functions is restricted with the |'maxfuncdepth'|
7941option.
7942
Bram Moolenaar7c626922005-02-07 22:01:03 +00007943
7944AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00007945 *autoload-functions*
7946When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00007947only when they are used. There are two methods: with an autocommand and with
7948the "autoload" directory in 'runtimepath'.
7949
7950
7951Using an autocommand ~
7952
Bram Moolenaar05159a02005-02-26 23:04:13 +00007953This is introduced in the user manual, section |41.14|.
7954
Bram Moolenaar7c626922005-02-07 22:01:03 +00007955The autocommand is useful if you have a plugin that is a long Vim script file.
7956You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007957That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00007958again, setting a variable to skip the |:finish| command.
7959
7960Use the FuncUndefined autocommand event with a pattern that matches the
7961function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007962
7963 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
7964
7965The file "~/vim/bufnetfuncs.vim" should then define functions that start with
7966"BufNet". Also see |FuncUndefined|.
7967
Bram Moolenaar7c626922005-02-07 22:01:03 +00007968
7969Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007970 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00007971This is introduced in the user manual, section |41.15|.
7972
Bram Moolenaar7c626922005-02-07 22:01:03 +00007973Using a script in the "autoload" directory is simpler, but requires using
7974exactly the right file name. A function that can be autoloaded has a name
7975like this: >
7976
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007977 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00007978
7979When such a function is called, and it is not defined yet, Vim will search the
7980"autoload" directories in 'runtimepath' for a script file called
7981"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
7982then define the function like this: >
7983
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007984 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00007985 echo "Done!"
7986 endfunction
7987
Bram Moolenaar60a795a2005-09-16 21:55:43 +00007988The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00007989exactly, and the defined function must have the name exactly as it will be
7990called.
7991
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007992It is possible to use subdirectories. Every # in the function name works like
7993a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00007994
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007995 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00007996
7997Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
7998
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007999This also works when reading a variable that has not been set yet: >
8000
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008001 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008002
Bram Moolenaara5792f52005-11-23 21:25:05 +00008003However, when the autoload script was already loaded it won't be loaded again
8004for an unknown variable.
8005
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008006When assigning a value to such a variable nothing special happens. This can
8007be used to pass settings to the autoload script before it's loaded: >
8008
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008009 :let foo#bar#toggle = 1
8010 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008011
Bram Moolenaar4399ef42005-02-12 14:29:27 +00008012Note that when you make a mistake and call a function that is supposed to be
8013defined in an autoload script, but the script doesn't actually define the
8014function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008015And you will get an error message every time.
8016
8017Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008018other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008019Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00008020
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008021Hint: If you distribute a bunch of scripts you can pack them together with the
8022|vimball| utility. Also read the user manual |distribute-script|.
8023
Bram Moolenaar071d4272004-06-13 20:20:40 +00008024==============================================================================
80256. Curly braces names *curly-braces-names*
8026
Bram Moolenaar84f72352012-03-11 15:57:40 +01008027In most places where you can use a variable, you can use a "curly braces name"
8028variable. This is a regular variable name with one or more expressions
8029wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008030 my_{adjective}_variable
8031
8032When Vim encounters this, it evaluates the expression inside the braces, puts
8033that in place of the expression, and re-interprets the whole as a variable
8034name. So in the above example, if the variable "adjective" was set to
8035"noisy", then the reference would be to "my_noisy_variable", whereas if
8036"adjective" was set to "quiet", then it would be to "my_quiet_variable".
8037
8038One application for this is to create a set of variables governed by an option
Bram Moolenaar446cb832008-06-24 21:56:24 +00008039value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008040 echo my_{&background}_message
8041
8042would output the contents of "my_dark_message" or "my_light_message" depending
8043on the current value of 'background'.
8044
8045You can use multiple brace pairs: >
8046 echo my_{adverb}_{adjective}_message
8047..or even nest them: >
8048 echo my_{ad{end_of_word}}_message
8049where "end_of_word" is either "verb" or "jective".
8050
8051However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008052variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008053 :let foo='a + b'
8054 :echo c{foo}d
8055.. since the result of expansion is "ca + bd", which is not a variable name.
8056
8057 *curly-braces-function-names*
8058You can call and define functions by an evaluated name in a similar way.
8059Example: >
8060 :let func_end='whizz'
8061 :call my_func_{func_end}(parameter)
8062
8063This would call the function "my_func_whizz(parameter)".
8064
Bram Moolenaar84f72352012-03-11 15:57:40 +01008065This does NOT work: >
8066 :let i = 3
8067 :let @{i} = '' " error
8068 :echo @{i} " error
8069
Bram Moolenaar071d4272004-06-13 20:20:40 +00008070==============================================================================
80717. Commands *expression-commands*
8072
8073:let {var-name} = {expr1} *:let* *E18*
8074 Set internal variable {var-name} to the result of the
8075 expression {expr1}. The variable will get the type
8076 from the {expr}. If {var-name} didn't exist yet, it
8077 is created.
8078
Bram Moolenaar13065c42005-01-08 16:08:21 +00008079:let {var-name}[{idx}] = {expr1} *E689*
8080 Set a list item to the result of the expression
8081 {expr1}. {var-name} must refer to a list and {idx}
8082 must be a valid index in that list. For nested list
8083 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008084 This cannot be used to add an item to a |List|.
8085 This cannot be used to set a byte in a String. You
8086 can do that like this: >
8087 :let var = var[0:2] . 'X' . var[4:]
8088<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008089 *E711* *E719*
8090:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008091 Set a sequence of items in a |List| to the result of
8092 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008093 correct number of items.
8094 {idx1} can be omitted, zero is used instead.
8095 {idx2} can be omitted, meaning the end of the list.
8096 When the selected range of items is partly past the
8097 end of the list, items will be added.
8098
Bram Moolenaar748bf032005-02-02 23:04:36 +00008099 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008100:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
8101:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
8102:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
8103 These fail if {var} was not set yet and when the type
8104 of {var} and {expr1} don't fit the operator.
8105
8106
Bram Moolenaar071d4272004-06-13 20:20:40 +00008107:let ${env-name} = {expr1} *:let-environment* *:let-$*
8108 Set environment variable {env-name} to the result of
8109 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008110:let ${env-name} .= {expr1}
8111 Append {expr1} to the environment variable {env-name}.
8112 If the environment variable didn't exist yet this
8113 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00008114
8115:let @{reg-name} = {expr1} *:let-register* *:let-@*
8116 Write the result of the expression {expr1} in register
8117 {reg-name}. {reg-name} must be a single letter, and
8118 must be the name of a writable register (see
8119 |registers|). "@@" can be used for the unnamed
8120 register, "@/" for the search pattern.
8121 If the result of {expr1} ends in a <CR> or <NL>, the
8122 register will be linewise, otherwise it will be set to
8123 characterwise.
8124 This can be used to clear the last search pattern: >
8125 :let @/ = ""
8126< This is different from searching for an empty string,
8127 that would match everywhere.
8128
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008129:let @{reg-name} .= {expr1}
Bram Moolenaar446cb832008-06-24 21:56:24 +00008130 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008131 register was empty it's like setting it to {expr1}.
8132
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008133:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008134 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008135 expression {expr1}. A String or Number value is
8136 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008137 For an option local to a window or buffer the effect
8138 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00008139 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008140 Example: >
8141 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00008142
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008143:let &{option-name} .= {expr1}
8144 For a string option: Append {expr1} to the value.
8145 Does not insert a comma like |:set+=|.
8146
8147:let &{option-name} += {expr1}
8148:let &{option-name} -= {expr1}
8149 For a number or boolean option: Add or subtract
8150 {expr1}.
8151
Bram Moolenaar071d4272004-06-13 20:20:40 +00008152:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008153:let &l:{option-name} .= {expr1}
8154:let &l:{option-name} += {expr1}
8155:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008156 Like above, but only set the local value of an option
8157 (if there is one). Works like |:setlocal|.
8158
8159:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008160:let &g:{option-name} .= {expr1}
8161:let &g:{option-name} += {expr1}
8162:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008163 Like above, but only set the global value of an option
8164 (if there is one). Works like |:setglobal|.
8165
Bram Moolenaar13065c42005-01-08 16:08:21 +00008166:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008167 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008168 the list is assigned to {name1}, the second item to
8169 {name2}, etc.
8170 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008171 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008172 Each name can be one of the items of the ":let"
8173 command as mentioned above.
8174 Example: >
8175 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008176< Detail: {expr1} is evaluated first, then the
8177 assignments are done in sequence. This matters if
8178 {name2} depends on {name1}. Example: >
8179 :let x = [0, 1]
8180 :let i = 0
8181 :let [i, x[i]] = [1, 2]
8182 :echo x
8183< The result is [0, 2].
8184
8185:let [{name1}, {name2}, ...] .= {expr1}
8186:let [{name1}, {name2}, ...] += {expr1}
8187:let [{name1}, {name2}, ...] -= {expr1}
8188 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008189 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008190
8191:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008192 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008193 items than there are names. A list of the remaining
8194 items is assigned to {lastname}. If there are no
8195 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008196 Example: >
8197 :let [a, b; rest] = ["aval", "bval", 3, 4]
8198<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008199:let [{name}, ..., ; {lastname}] .= {expr1}
8200:let [{name}, ..., ; {lastname}] += {expr1}
8201:let [{name}, ..., ; {lastname}] -= {expr1}
8202 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008203 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02008204
8205 *E121*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008206:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00008207 variable names may be given. Special names recognized
8208 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00008209 g: global variables
8210 b: local buffer variables
8211 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00008212 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00008213 s: script-local variables
8214 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00008215 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008216
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008217:let List the values of all variables. The type of the
8218 variable is indicated before the value:
8219 <nothing> String
8220 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008221 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00008222
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008223
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008224:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008225 Remove the internal variable {name}. Several variable
8226 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008227 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008228 With [!] no error message is given for non-existing
8229 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008230 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00008231 :unlet list[3] " remove fourth item
8232 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008233< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00008234 :unlet dict['two']
8235 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00008236< This is especially useful to clean up used global
8237 variables and script-local variables (these are not
8238 deleted when the script ends). Function-local
8239 variables are automatically deleted when the function
8240 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008241
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008242:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
8243 Lock the internal variable {name}. Locking means that
8244 it can no longer be changed (until it is unlocked).
8245 A locked variable can be deleted: >
8246 :lockvar v
8247 :let v = 'asdf' " fails!
8248 :unlet v
8249< *E741*
8250 If you try to change a locked variable you get an
Bram Moolenaar8a94d872015-01-25 13:02:57 +01008251 error message: "E741: Value is locked: {name}"
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008252
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008253 [depth] is relevant when locking a |List| or
8254 |Dictionary|. It specifies how deep the locking goes:
8255 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008256 cannot add or remove items, but can
8257 still change their values.
8258 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008259 the items. If an item is a |List| or
8260 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008261 items, but can still change the
8262 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008263 3 Like 2 but for the |List| /
8264 |Dictionary| in the |List| /
8265 |Dictionary|, one level deeper.
8266 The default [depth] is 2, thus when {name} is a |List|
8267 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008268 *E743*
8269 For unlimited depth use [!] and omit [depth].
8270 However, there is a maximum depth of 100 to catch
8271 loops.
8272
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008273 Note that when two variables refer to the same |List|
8274 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00008275 locked when used through the other variable.
8276 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008277 :let l = [0, 1, 2, 3]
8278 :let cl = l
8279 :lockvar l
8280 :let cl[1] = 99 " won't work!
8281< You may want to make a copy of a list to avoid this.
8282 See |deepcopy()|.
8283
8284
8285:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
8286 Unlock the internal variable {name}. Does the
8287 opposite of |:lockvar|.
8288
8289
Bram Moolenaar071d4272004-06-13 20:20:40 +00008290:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
8291:en[dif] Execute the commands until the next matching ":else"
8292 or ":endif" if {expr1} evaluates to non-zero.
8293
8294 From Vim version 4.5 until 5.0, every Ex command in
8295 between the ":if" and ":endif" is ignored. These two
8296 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +01008297 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00008298 that any ":else" or ":elseif" was ignored, the "else"
8299 part was not executed either.
8300
8301 You can use this to remain compatible with older
8302 versions: >
8303 :if version >= 500
8304 : version-5-specific-commands
8305 :endif
8306< The commands still need to be parsed to find the
8307 "endif". Sometimes an older Vim has a problem with a
8308 new command. For example, ":silent" is recognized as
8309 a ":substitute" command. In that case ":execute" can
8310 avoid problems: >
8311 :if version >= 600
8312 : execute "silent 1,$delete"
8313 :endif
8314<
8315 NOTE: The ":append" and ":insert" commands don't work
8316 properly in between ":if" and ":endif".
8317
8318 *:else* *:el* *E581* *E583*
8319:el[se] Execute the commands until the next matching ":else"
8320 or ":endif" if they previously were not being
8321 executed.
8322
8323 *:elseif* *:elsei* *E582* *E584*
8324:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
8325 is no extra ":endif".
8326
8327:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008328 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008329:endw[hile] Repeat the commands between ":while" and ":endwhile",
8330 as long as {expr1} evaluates to non-zero.
8331 When an error is detected from a command inside the
8332 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00008333 Example: >
8334 :let lnum = 1
8335 :while lnum <= line("$")
8336 :call FixLine(lnum)
8337 :let lnum = lnum + 1
8338 :endwhile
8339<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008340 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00008341 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008342
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008343:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00008344:endfo[r] *:endfo* *:endfor*
8345 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008346 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008347 value of each item.
8348 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00008349 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00008350 Changing {list} inside the loop affects what items are
8351 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008352 :for item in copy(mylist)
8353< When not making a copy, Vim stores a reference to the
8354 next item in the list, before executing the commands
Bram Moolenaar446cb832008-06-24 21:56:24 +00008355 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008356 removed without effect. Removing any later item means
8357 it will not be found. Thus the following example
8358 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008359 for item in mylist
8360 call remove(mylist, 0)
8361 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008362< Note that reordering the list (e.g., with sort() or
8363 reverse()) may have unexpected effects.
8364 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00008365 identical to avoid errors for the type of {var}
8366 changing. Unlet the variable at the end of the loop
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008367 to allow multiple item types: >
8368 for item in ["foo", ["bar"]]
8369 echo item
8370 unlet item " E706 without this
8371 endfor
Bram Moolenaar12805862005-01-05 22:16:17 +00008372
Bram Moolenaar12805862005-01-05 22:16:17 +00008373:for [{var1}, {var2}, ...] in {listlist}
8374:endfo[r]
8375 Like ":for" above, but each item in {listlist} must be
8376 a list, of which each item is assigned to {var1},
8377 {var2}, etc. Example: >
8378 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
8379 :echo getline(lnum)[col]
8380 :endfor
8381<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008382 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00008383:con[tinue] When used inside a ":while" or ":for" loop, jumps back
8384 to the start of the loop.
8385 If it is used after a |:try| inside the loop but
8386 before the matching |:finally| (if present), the
8387 commands following the ":finally" up to the matching
8388 |:endtry| are executed first. This process applies to
8389 all nested ":try"s inside the loop. The outermost
8390 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008391
8392 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00008393:brea[k] When used inside a ":while" or ":for" loop, skips to
8394 the command after the matching ":endwhile" or
8395 ":endfor".
8396 If it is used after a |:try| inside the loop but
8397 before the matching |:finally| (if present), the
8398 commands following the ":finally" up to the matching
8399 |:endtry| are executed first. This process applies to
8400 all nested ":try"s inside the loop. The outermost
8401 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008402
8403:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
8404:endt[ry] Change the error handling for the commands between
8405 ":try" and ":endtry" including everything being
8406 executed across ":source" commands, function calls,
8407 or autocommand invocations.
8408
8409 When an error or interrupt is detected and there is
8410 a |:finally| command following, execution continues
8411 after the ":finally". Otherwise, or when the
8412 ":endtry" is reached thereafter, the next
8413 (dynamically) surrounding ":try" is checked for
8414 a corresponding ":finally" etc. Then the script
8415 processing is terminated. (Whether a function
8416 definition has an "abort" argument does not matter.)
8417 Example: >
8418 :try | edit too much | finally | echo "cleanup" | endtry
8419 :echo "impossible" " not reached, script terminated above
8420<
8421 Moreover, an error or interrupt (dynamically) inside
8422 ":try" and ":endtry" is converted to an exception. It
8423 can be caught as if it were thrown by a |:throw|
8424 command (see |:catch|). In this case, the script
8425 processing is not terminated.
8426
8427 The value "Vim:Interrupt" is used for an interrupt
8428 exception. An error in a Vim command is converted
8429 to a value of the form "Vim({command}):{errmsg}",
8430 other errors are converted to a value of the form
8431 "Vim:{errmsg}". {command} is the full command name,
8432 and {errmsg} is the message that is displayed if the
8433 error exception is not caught, always beginning with
8434 the error number.
8435 Examples: >
8436 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
8437 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
8438<
8439 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008440:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008441 |:finally|, or |:endtry| that belongs to the same
8442 |:try| as the ":catch" are executed when an exception
8443 matching {pattern} is being thrown and has not yet
8444 been caught by a previous ":catch". Otherwise, these
8445 commands are skipped.
8446 When {pattern} is omitted all errors are caught.
8447 Examples: >
8448 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
8449 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
8450 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
8451 :catch /^Vim(write):/ " catch all errors in :write
8452 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
8453 :catch /my-exception/ " catch user exception
8454 :catch /.*/ " catch everything
8455 :catch " same as /.*/
8456<
8457 Another character can be used instead of / around the
8458 {pattern}, so long as it does not have a special
8459 meaning (e.g., '|' or '"') and doesn't occur inside
8460 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02008461 Information about the exception is available in
8462 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008463 NOTE: It is not reliable to ":catch" the TEXT of
8464 an error message because it may vary in different
8465 locales.
8466
8467 *:fina* *:finally* *E606* *E607*
8468:fina[lly] The following commands until the matching |:endtry|
8469 are executed whenever the part between the matching
8470 |:try| and the ":finally" is left: either by falling
8471 through to the ":finally" or by a |:continue|,
8472 |:break|, |:finish|, or |:return|, or by an error or
8473 interrupt or exception (see |:throw|).
8474
8475 *:th* *:throw* *E608*
8476:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
8477 If the ":throw" is used after a |:try| but before the
8478 first corresponding |:catch|, commands are skipped
8479 until the first ":catch" matching {expr1} is reached.
8480 If there is no such ":catch" or if the ":throw" is
8481 used after a ":catch" but before the |:finally|, the
8482 commands following the ":finally" (if present) up to
8483 the matching |:endtry| are executed. If the ":throw"
8484 is after the ":finally", commands up to the ":endtry"
8485 are skipped. At the ":endtry", this process applies
8486 again for the next dynamically surrounding ":try"
8487 (which may be found in a calling function or sourcing
8488 script), until a matching ":catch" has been found.
8489 If the exception is not caught, the command processing
8490 is terminated.
8491 Example: >
8492 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01008493< Note that "catch" may need to be on a separate line
8494 for when an error causes the parsing to skip the whole
8495 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008496
8497 *:ec* *:echo*
8498:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
8499 first {expr1} starts on a new line.
8500 Also see |:comment|.
8501 Use "\n" to start a new line. Use "\r" to move the
8502 cursor to the first column.
8503 Uses the highlighting set by the |:echohl| command.
8504 Cannot be followed by a comment.
8505 Example: >
8506 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008507< *:echo-redraw*
8508 A later redraw may make the message disappear again.
8509 And since Vim mostly postpones redrawing until it's
8510 finished with a sequence of commands this happens
8511 quite often. To avoid that a command from before the
8512 ":echo" causes a redraw afterwards (redraws are often
8513 postponed until you type something), force a redraw
8514 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008515 :new | redraw | echo "there is a new window"
8516<
8517 *:echon*
8518:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
8519 |:comment|.
8520 Uses the highlighting set by the |:echohl| command.
8521 Cannot be followed by a comment.
8522 Example: >
8523 :echon "the value of 'shell' is " &shell
8524<
8525 Note the difference between using ":echo", which is a
8526 Vim command, and ":!echo", which is an external shell
8527 command: >
8528 :!echo % --> filename
8529< The arguments of ":!" are expanded, see |:_%|. >
8530 :!echo "%" --> filename or "filename"
8531< Like the previous example. Whether you see the double
8532 quotes or not depends on your 'shell'. >
8533 :echo % --> nothing
8534< The '%' is an illegal character in an expression. >
8535 :echo "%" --> %
8536< This just echoes the '%' character. >
8537 :echo expand("%") --> filename
8538< This calls the expand() function to expand the '%'.
8539
8540 *:echoh* *:echohl*
8541:echoh[l] {name} Use the highlight group {name} for the following
8542 |:echo|, |:echon| and |:echomsg| commands. Also used
8543 for the |input()| prompt. Example: >
8544 :echohl WarningMsg | echo "Don't panic!" | echohl None
8545< Don't forget to set the group back to "None",
8546 otherwise all following echo's will be highlighted.
8547
8548 *:echom* *:echomsg*
8549:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
8550 message in the |message-history|.
8551 Spaces are placed between the arguments as with the
8552 |:echo| command. But unprintable characters are
8553 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008554 The parsing works slightly different from |:echo|,
8555 more like |:execute|. All the expressions are first
8556 evaluated and concatenated before echoing anything.
8557 The expressions must evaluate to a Number or String, a
8558 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008559 Uses the highlighting set by the |:echohl| command.
8560 Example: >
8561 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008562< See |:echo-redraw| to avoid the message disappearing
8563 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008564 *:echoe* *:echoerr*
8565:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
8566 message in the |message-history|. When used in a
8567 script or function the line number will be added.
8568 Spaces are placed between the arguments as with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008569 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008570 the message is raised as an error exception instead
8571 (see |try-echoerr|).
8572 Example: >
8573 :echoerr "This script just failed!"
8574< If you just want a highlighted message use |:echohl|.
8575 And to get a beep: >
8576 :exe "normal \<Esc>"
8577<
8578 *:exe* *:execute*
8579:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008580 of {expr1} as an Ex command.
8581 Multiple arguments are concatenated, with a space in
8582 between. To avoid the extra space use the "."
8583 operator to concatenate strings into one argument.
8584 {expr1} is used as the processed command, command line
8585 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008586 Cannot be followed by a comment.
8587 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008588 :execute "buffer" nextbuf
8589 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008590<
8591 ":execute" can be used to append a command to commands
8592 that don't accept a '|'. Example: >
8593 :execute '!ls' | echo "theend"
8594
8595< ":execute" is also a nice way to avoid having to type
8596 control characters in a Vim script for a ":normal"
8597 command: >
8598 :execute "normal ixxx\<Esc>"
8599< This has an <Esc> character, see |expr-string|.
8600
Bram Moolenaar446cb832008-06-24 21:56:24 +00008601 Be careful to correctly escape special characters in
8602 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008603 for Vim commands, |shellescape()| for |:!| commands.
8604 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00008605 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +01008606 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00008607<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008608 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01008609 starting or ending "if", "while" and "for" does not
8610 always work, because when commands are skipped the
8611 ":execute" is not evaluated and Vim loses track of
8612 where blocks start and end. Also "break" and
8613 "continue" should not be inside ":execute".
8614 This example does not work, because the ":execute" is
8615 not evaluated and Vim does not see the "while", and
8616 gives an error for finding an ":endwhile": >
8617 :if 0
8618 : execute 'while i > 5'
8619 : echo "test"
8620 : endwhile
8621 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00008622<
8623 It is allowed to have a "while" or "if" command
8624 completely in the executed string: >
8625 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
8626<
8627
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008628 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008629 ":execute", ":echo" and ":echon" cannot be followed by
8630 a comment directly, because they see the '"' as the
8631 start of a string. But, you can use '|' followed by a
8632 comment. Example: >
8633 :echo "foo" | "this is a comment
8634
8635==============================================================================
86368. Exception handling *exception-handling*
8637
8638The Vim script language comprises an exception handling feature. This section
8639explains how it can be used in a Vim script.
8640
8641Exceptions may be raised by Vim on an error or on interrupt, see
8642|catch-errors| and |catch-interrupt|. You can also explicitly throw an
8643exception by using the ":throw" command, see |throw-catch|.
8644
8645
8646TRY CONDITIONALS *try-conditionals*
8647
8648Exceptions can be caught or can cause cleanup code to be executed. You can
8649use a try conditional to specify catch clauses (that catch exceptions) and/or
8650a finally clause (to be executed for cleanup).
8651 A try conditional begins with a |:try| command and ends at the matching
8652|:endtry| command. In between, you can use a |:catch| command to start
8653a catch clause, or a |:finally| command to start a finally clause. There may
8654be none or multiple catch clauses, but there is at most one finally clause,
8655which must not be followed by any catch clauses. The lines before the catch
8656clauses and the finally clause is called a try block. >
8657
8658 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008659 : ...
8660 : ... TRY BLOCK
8661 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008662 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00008663 : ...
8664 : ... CATCH CLAUSE
8665 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008666 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00008667 : ...
8668 : ... CATCH CLAUSE
8669 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008670 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00008671 : ...
8672 : ... FINALLY CLAUSE
8673 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008674 :endtry
8675
8676The try conditional allows to watch code for exceptions and to take the
8677appropriate actions. Exceptions from the try block may be caught. Exceptions
8678from the try block and also the catch clauses may cause cleanup actions.
8679 When no exception is thrown during execution of the try block, the control
8680is transferred to the finally clause, if present. After its execution, the
8681script continues with the line following the ":endtry".
8682 When an exception occurs during execution of the try block, the remaining
8683lines in the try block are skipped. The exception is matched against the
8684patterns specified as arguments to the ":catch" commands. The catch clause
8685after the first matching ":catch" is taken, other catch clauses are not
8686executed. The catch clause ends when the next ":catch", ":finally", or
8687":endtry" command is reached - whatever is first. Then, the finally clause
8688(if present) is executed. When the ":endtry" is reached, the script execution
8689continues in the following line as usual.
8690 When an exception that does not match any of the patterns specified by the
8691":catch" commands is thrown in the try block, the exception is not caught by
8692that try conditional and none of the catch clauses is executed. Only the
8693finally clause, if present, is taken. The exception pends during execution of
8694the finally clause. It is resumed at the ":endtry", so that commands after
8695the ":endtry" are not executed and the exception might be caught elsewhere,
8696see |try-nesting|.
8697 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008698remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00008699not matched against the patterns in any of the ":catch" commands of the same
8700try conditional and none of its catch clauses is taken. If there is, however,
8701a finally clause, it is executed, and the exception pends during its
8702execution. The commands following the ":endtry" are not executed. The new
8703exception might, however, be caught elsewhere, see |try-nesting|.
8704 When during execution of the finally clause (if present) an exception is
Bram Moolenaar446cb832008-06-24 21:56:24 +00008705thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00008706clause has been taken because of an exception from the try block or one of the
8707catch clauses, the original (pending) exception is discarded. The commands
8708following the ":endtry" are not executed, and the exception from the finally
8709clause is propagated and can be caught elsewhere, see |try-nesting|.
8710
8711The finally clause is also executed, when a ":break" or ":continue" for
8712a ":while" loop enclosing the complete try conditional is executed from the
8713try block or a catch clause. Or when a ":return" or ":finish" is executed
8714from the try block or a catch clause of a try conditional in a function or
8715sourced script, respectively. The ":break", ":continue", ":return", or
8716":finish" pends during execution of the finally clause and is resumed when the
8717":endtry" is reached. It is, however, discarded when an exception is thrown
8718from the finally clause.
8719 When a ":break" or ":continue" for a ":while" loop enclosing the complete
8720try conditional or when a ":return" or ":finish" is encountered in the finally
8721clause, the rest of the finally clause is skipped, and the ":break",
8722":continue", ":return" or ":finish" is executed as usual. If the finally
8723clause has been taken because of an exception or an earlier ":break",
8724":continue", ":return", or ":finish" from the try block or a catch clause,
8725this pending exception or command is discarded.
8726
8727For examples see |throw-catch| and |try-finally|.
8728
8729
8730NESTING OF TRY CONDITIONALS *try-nesting*
8731
8732Try conditionals can be nested arbitrarily. That is, a complete try
8733conditional can be put into the try block, a catch clause, or the finally
8734clause of another try conditional. If the inner try conditional does not
8735catch an exception thrown in its try block or throws a new exception from one
8736of its catch clauses or its finally clause, the outer try conditional is
8737checked according to the rules above. If the inner try conditional is in the
8738try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar446cb832008-06-24 21:56:24 +00008739otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00008740nesting, whether the inner try conditional is directly contained in the outer
8741one, or whether the outer one sources a script or calls a function containing
8742the inner try conditional.
8743
8744When none of the active try conditionals catches an exception, just their
8745finally clauses are executed. Thereafter, the script processing terminates.
8746An error message is displayed in case of an uncaught exception explicitly
8747thrown by a ":throw" command. For uncaught error and interrupt exceptions
8748implicitly raised by Vim, the error message(s) or interrupt message are shown
8749as usual.
8750
8751For examples see |throw-catch|.
8752
8753
8754EXAMINING EXCEPTION HANDLING CODE *except-examine*
8755
8756Exception handling code can get tricky. If you are in doubt what happens, set
8757'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
8758script file. Then you see when an exception is thrown, discarded, caught, or
8759finished. When using a verbosity level of at least 14, things pending in
8760a finally clause are also shown. This information is also given in debug mode
8761(see |debug-scripts|).
8762
8763
8764THROWING AND CATCHING EXCEPTIONS *throw-catch*
8765
8766You can throw any number or string as an exception. Use the |:throw| command
8767and pass the value to be thrown as argument: >
8768 :throw 4711
8769 :throw "string"
8770< *throw-expression*
8771You can also specify an expression argument. The expression is then evaluated
8772first, and the result is thrown: >
8773 :throw 4705 + strlen("string")
8774 :throw strpart("strings", 0, 6)
8775
8776An exception might be thrown during evaluation of the argument of the ":throw"
8777command. Unless it is caught there, the expression evaluation is abandoned.
8778The ":throw" command then does not throw a new exception.
8779 Example: >
8780
8781 :function! Foo(arg)
8782 : try
8783 : throw a:arg
8784 : catch /foo/
8785 : endtry
8786 : return 1
8787 :endfunction
8788 :
8789 :function! Bar()
8790 : echo "in Bar"
8791 : return 4710
8792 :endfunction
8793 :
8794 :throw Foo("arrgh") + Bar()
8795
8796This throws "arrgh", and "in Bar" is not displayed since Bar() is not
8797executed. >
8798 :throw Foo("foo") + Bar()
8799however displays "in Bar" and throws 4711.
8800
8801Any other command that takes an expression as argument might also be
Bram Moolenaar446cb832008-06-24 21:56:24 +00008802abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008803exception is then propagated to the caller of the command.
8804 Example: >
8805
8806 :if Foo("arrgh")
8807 : echo "then"
8808 :else
8809 : echo "else"
8810 :endif
8811
8812Here neither of "then" or "else" is displayed.
8813
8814 *catch-order*
8815Exceptions can be caught by a try conditional with one or more |:catch|
8816commands, see |try-conditionals|. The values to be caught by each ":catch"
8817command can be specified as a pattern argument. The subsequent catch clause
8818gets executed when a matching exception is caught.
8819 Example: >
8820
8821 :function! Foo(value)
8822 : try
8823 : throw a:value
8824 : catch /^\d\+$/
8825 : echo "Number thrown"
8826 : catch /.*/
8827 : echo "String thrown"
8828 : endtry
8829 :endfunction
8830 :
8831 :call Foo(0x1267)
8832 :call Foo('string')
8833
8834The first call to Foo() displays "Number thrown", the second "String thrown".
8835An exception is matched against the ":catch" commands in the order they are
8836specified. Only the first match counts. So you should place the more
8837specific ":catch" first. The following order does not make sense: >
8838
8839 : catch /.*/
8840 : echo "String thrown"
8841 : catch /^\d\+$/
8842 : echo "Number thrown"
8843
8844The first ":catch" here matches always, so that the second catch clause is
8845never taken.
8846
8847 *throw-variables*
8848If you catch an exception by a general pattern, you may access the exact value
8849in the variable |v:exception|: >
8850
8851 : catch /^\d\+$/
8852 : echo "Number thrown. Value is" v:exception
8853
8854You may also be interested where an exception was thrown. This is stored in
8855|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
8856exception most recently caught as long it is not finished.
8857 Example: >
8858
8859 :function! Caught()
8860 : if v:exception != ""
8861 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
8862 : else
8863 : echo 'Nothing caught'
8864 : endif
8865 :endfunction
8866 :
8867 :function! Foo()
8868 : try
8869 : try
8870 : try
8871 : throw 4711
8872 : finally
8873 : call Caught()
8874 : endtry
8875 : catch /.*/
8876 : call Caught()
8877 : throw "oops"
8878 : endtry
8879 : catch /.*/
8880 : call Caught()
8881 : finally
8882 : call Caught()
8883 : endtry
8884 :endfunction
8885 :
8886 :call Foo()
8887
8888This displays >
8889
8890 Nothing caught
8891 Caught "4711" in function Foo, line 4
8892 Caught "oops" in function Foo, line 10
8893 Nothing caught
8894
8895A practical example: The following command ":LineNumber" displays the line
8896number in the script or function where it has been used: >
8897
8898 :function! LineNumber()
8899 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
8900 :endfunction
8901 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
8902<
8903 *try-nested*
8904An exception that is not caught by a try conditional can be caught by
8905a surrounding try conditional: >
8906
8907 :try
8908 : try
8909 : throw "foo"
8910 : catch /foobar/
8911 : echo "foobar"
8912 : finally
8913 : echo "inner finally"
8914 : endtry
8915 :catch /foo/
8916 : echo "foo"
8917 :endtry
8918
8919The inner try conditional does not catch the exception, just its finally
8920clause is executed. The exception is then caught by the outer try
8921conditional. The example displays "inner finally" and then "foo".
8922
8923 *throw-from-catch*
8924You can catch an exception and throw a new one to be caught elsewhere from the
8925catch clause: >
8926
8927 :function! Foo()
8928 : throw "foo"
8929 :endfunction
8930 :
8931 :function! Bar()
8932 : try
8933 : call Foo()
8934 : catch /foo/
8935 : echo "Caught foo, throw bar"
8936 : throw "bar"
8937 : endtry
8938 :endfunction
8939 :
8940 :try
8941 : call Bar()
8942 :catch /.*/
8943 : echo "Caught" v:exception
8944 :endtry
8945
8946This displays "Caught foo, throw bar" and then "Caught bar".
8947
8948 *rethrow*
8949There is no real rethrow in the Vim script language, but you may throw
8950"v:exception" instead: >
8951
8952 :function! Bar()
8953 : try
8954 : call Foo()
8955 : catch /.*/
8956 : echo "Rethrow" v:exception
8957 : throw v:exception
8958 : endtry
8959 :endfunction
8960< *try-echoerr*
8961Note that this method cannot be used to "rethrow" Vim error or interrupt
8962exceptions, because it is not possible to fake Vim internal exceptions.
8963Trying so causes an error exception. You should throw your own exception
8964denoting the situation. If you want to cause a Vim error exception containing
8965the original error exception value, you can use the |:echoerr| command: >
8966
8967 :try
8968 : try
8969 : asdf
8970 : catch /.*/
8971 : echoerr v:exception
8972 : endtry
8973 :catch /.*/
8974 : echo v:exception
8975 :endtry
8976
8977This code displays
8978
Bram Moolenaar446cb832008-06-24 21:56:24 +00008979 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008980
8981
8982CLEANUP CODE *try-finally*
8983
8984Scripts often change global settings and restore them at their end. If the
8985user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar446cb832008-06-24 21:56:24 +00008986an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00008987a script when an error occurs or you explicitly throw an exception without
8988catching it. You can solve these problems by using a try conditional with
8989a finally clause for restoring the settings. Its execution is guaranteed on
8990normal control flow, on error, on an explicit ":throw", and on interrupt.
8991(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar446cb832008-06-24 21:56:24 +00008992to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00008993clause has been executed.)
8994Example: >
8995
8996 :try
8997 : let s:saved_ts = &ts
8998 : set ts=17
8999 :
9000 : " Do the hard work here.
9001 :
9002 :finally
9003 : let &ts = s:saved_ts
9004 : unlet s:saved_ts
9005 :endtry
9006
9007This method should be used locally whenever a function or part of a script
9008changes global settings which need to be restored on failure or normal exit of
9009that function or script part.
9010
9011 *break-finally*
9012Cleanup code works also when the try block or a catch clause is left by
9013a ":continue", ":break", ":return", or ":finish".
9014 Example: >
9015
9016 :let first = 1
9017 :while 1
9018 : try
9019 : if first
9020 : echo "first"
9021 : let first = 0
9022 : continue
9023 : else
9024 : throw "second"
9025 : endif
9026 : catch /.*/
9027 : echo v:exception
9028 : break
9029 : finally
9030 : echo "cleanup"
9031 : endtry
9032 : echo "still in while"
9033 :endwhile
9034 :echo "end"
9035
9036This displays "first", "cleanup", "second", "cleanup", and "end". >
9037
9038 :function! Foo()
9039 : try
9040 : return 4711
9041 : finally
9042 : echo "cleanup\n"
9043 : endtry
9044 : echo "Foo still active"
9045 :endfunction
9046 :
9047 :echo Foo() "returned by Foo"
9048
9049This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar446cb832008-06-24 21:56:24 +00009050extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009051return value.)
9052
9053 *except-from-finally*
9054Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
9055a finally clause is possible, but not recommended since it abandons the
9056cleanup actions for the try conditional. But, of course, interrupt and error
9057exceptions might get raised from a finally clause.
9058 Example where an error in the finally clause stops an interrupt from
9059working correctly: >
9060
9061 :try
9062 : try
9063 : echo "Press CTRL-C for interrupt"
9064 : while 1
9065 : endwhile
9066 : finally
9067 : unlet novar
9068 : endtry
9069 :catch /novar/
9070 :endtry
9071 :echo "Script still running"
9072 :sleep 1
9073
9074If you need to put commands that could fail into a finally clause, you should
9075think about catching or ignoring the errors in these commands, see
9076|catch-errors| and |ignore-errors|.
9077
9078
9079CATCHING ERRORS *catch-errors*
9080
9081If you want to catch specific errors, you just have to put the code to be
9082watched in a try block and add a catch clause for the error message. The
9083presence of the try conditional causes all errors to be converted to an
9084exception. No message is displayed and |v:errmsg| is not set then. To find
9085the right pattern for the ":catch" command, you have to know how the format of
9086the error exception is.
9087 Error exceptions have the following format: >
9088
9089 Vim({cmdname}):{errmsg}
9090or >
9091 Vim:{errmsg}
9092
9093{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar446cb832008-06-24 21:56:24 +00009094the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00009095when the error occurs outside try conditionals. It always begins with
9096a capital "E", followed by a two or three-digit error number, a colon, and
9097a space.
9098
9099Examples:
9100
9101The command >
9102 :unlet novar
9103normally produces the error message >
9104 E108: No such variable: "novar"
9105which is converted inside try conditionals to an exception >
9106 Vim(unlet):E108: No such variable: "novar"
9107
9108The command >
9109 :dwim
9110normally produces the error message >
9111 E492: Not an editor command: dwim
9112which is converted inside try conditionals to an exception >
9113 Vim:E492: Not an editor command: dwim
9114
9115You can catch all ":unlet" errors by a >
9116 :catch /^Vim(unlet):/
9117or all errors for misspelled command names by a >
9118 :catch /^Vim:E492:/
9119
9120Some error messages may be produced by different commands: >
9121 :function nofunc
9122and >
9123 :delfunction nofunc
9124both produce the error message >
9125 E128: Function name must start with a capital: nofunc
9126which is converted inside try conditionals to an exception >
9127 Vim(function):E128: Function name must start with a capital: nofunc
9128or >
9129 Vim(delfunction):E128: Function name must start with a capital: nofunc
9130respectively. You can catch the error by its number independently on the
9131command that caused it if you use the following pattern: >
9132 :catch /^Vim(\a\+):E128:/
9133
9134Some commands like >
9135 :let x = novar
9136produce multiple error messages, here: >
9137 E121: Undefined variable: novar
9138 E15: Invalid expression: novar
9139Only the first is used for the exception value, since it is the most specific
9140one (see |except-several-errors|). So you can catch it by >
9141 :catch /^Vim(\a\+):E121:/
9142
9143You can catch all errors related to the name "nofunc" by >
9144 :catch /\<nofunc\>/
9145
9146You can catch all Vim errors in the ":write" and ":read" commands by >
9147 :catch /^Vim(\(write\|read\)):E\d\+:/
9148
9149You can catch all Vim errors by the pattern >
9150 :catch /^Vim\((\a\+)\)\=:E\d\+:/
9151<
9152 *catch-text*
9153NOTE: You should never catch the error message text itself: >
9154 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01009155only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +00009156a different language by the |:language| command. It is however helpful to
9157cite the message text in a comment: >
9158 :catch /^Vim(\a\+):E108:/ " No such variable
9159
9160
9161IGNORING ERRORS *ignore-errors*
9162
9163You can ignore errors in a specific Vim command by catching them locally: >
9164
9165 :try
9166 : write
9167 :catch
9168 :endtry
9169
9170But you are strongly recommended NOT to use this simple form, since it could
9171catch more than you want. With the ":write" command, some autocommands could
9172be executed and cause errors not related to writing, for instance: >
9173
9174 :au BufWritePre * unlet novar
9175
9176There could even be such errors you are not responsible for as a script
9177writer: a user of your script might have defined such autocommands. You would
9178then hide the error from the user.
9179 It is much better to use >
9180
9181 :try
9182 : write
9183 :catch /^Vim(write):/
9184 :endtry
9185
9186which only catches real write errors. So catch only what you'd like to ignore
9187intentionally.
9188
9189For a single command that does not cause execution of autocommands, you could
9190even suppress the conversion of errors to exceptions by the ":silent!"
9191command: >
9192 :silent! nunmap k
9193This works also when a try conditional is active.
9194
9195
9196CATCHING INTERRUPTS *catch-interrupt*
9197
9198When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar446cb832008-06-24 21:56:24 +00009199the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00009200script is not terminated, then.
9201 Example: >
9202
9203 :function! TASK1()
9204 : sleep 10
9205 :endfunction
9206
9207 :function! TASK2()
9208 : sleep 20
9209 :endfunction
9210
9211 :while 1
9212 : let command = input("Type a command: ")
9213 : try
9214 : if command == ""
9215 : continue
9216 : elseif command == "END"
9217 : break
9218 : elseif command == "TASK1"
9219 : call TASK1()
9220 : elseif command == "TASK2"
9221 : call TASK2()
9222 : else
9223 : echo "\nIllegal command:" command
9224 : continue
9225 : endif
9226 : catch /^Vim:Interrupt$/
9227 : echo "\nCommand interrupted"
9228 : " Caught the interrupt. Continue with next prompt.
9229 : endtry
9230 :endwhile
9231
9232You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar446cb832008-06-24 21:56:24 +00009233a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009234
9235For testing what happens when CTRL-C would be pressed on a specific line in
9236your script, use the debug mode and execute the |>quit| or |>interrupt|
9237command on that line. See |debug-scripts|.
9238
9239
9240CATCHING ALL *catch-all*
9241
9242The commands >
9243
9244 :catch /.*/
9245 :catch //
9246 :catch
9247
9248catch everything, error exceptions, interrupt exceptions and exceptions
9249explicitly thrown by the |:throw| command. This is useful at the top level of
9250a script in order to catch unexpected things.
9251 Example: >
9252
9253 :try
9254 :
9255 : " do the hard work here
9256 :
9257 :catch /MyException/
9258 :
9259 : " handle known problem
9260 :
9261 :catch /^Vim:Interrupt$/
9262 : echo "Script interrupted"
9263 :catch /.*/
9264 : echo "Internal error (" . v:exception . ")"
9265 : echo " - occurred at " . v:throwpoint
9266 :endtry
9267 :" end of script
9268
9269Note: Catching all might catch more things than you want. Thus, you are
9270strongly encouraged to catch only for problems that you can really handle by
9271specifying a pattern argument to the ":catch".
9272 Example: Catching all could make it nearly impossible to interrupt a script
9273by pressing CTRL-C: >
9274
9275 :while 1
9276 : try
9277 : sleep 1
9278 : catch
9279 : endtry
9280 :endwhile
9281
9282
9283EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
9284
9285Exceptions may be used during execution of autocommands. Example: >
9286
9287 :autocmd User x try
9288 :autocmd User x throw "Oops!"
9289 :autocmd User x catch
9290 :autocmd User x echo v:exception
9291 :autocmd User x endtry
9292 :autocmd User x throw "Arrgh!"
9293 :autocmd User x echo "Should not be displayed"
9294 :
9295 :try
9296 : doautocmd User x
9297 :catch
9298 : echo v:exception
9299 :endtry
9300
9301This displays "Oops!" and "Arrgh!".
9302
9303 *except-autocmd-Pre*
9304For some commands, autocommands get executed before the main action of the
9305command takes place. If an exception is thrown and not caught in the sequence
9306of autocommands, the sequence and the command that caused its execution are
9307abandoned and the exception is propagated to the caller of the command.
9308 Example: >
9309
9310 :autocmd BufWritePre * throw "FAIL"
9311 :autocmd BufWritePre * echo "Should not be displayed"
9312 :
9313 :try
9314 : write
9315 :catch
9316 : echo "Caught:" v:exception "from" v:throwpoint
9317 :endtry
9318
9319Here, the ":write" command does not write the file currently being edited (as
9320you can see by checking 'modified'), since the exception from the BufWritePre
9321autocommand abandons the ":write". The exception is then caught and the
9322script displays: >
9323
9324 Caught: FAIL from BufWrite Auto commands for "*"
9325<
9326 *except-autocmd-Post*
9327For some commands, autocommands get executed after the main action of the
9328command has taken place. If this main action fails and the command is inside
9329an active try conditional, the autocommands are skipped and an error exception
9330is thrown that can be caught by the caller of the command.
9331 Example: >
9332
9333 :autocmd BufWritePost * echo "File successfully written!"
9334 :
9335 :try
9336 : write /i/m/p/o/s/s/i/b/l/e
9337 :catch
9338 : echo v:exception
9339 :endtry
9340
9341This just displays: >
9342
9343 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
9344
9345If you really need to execute the autocommands even when the main action
9346fails, trigger the event from the catch clause.
9347 Example: >
9348
9349 :autocmd BufWritePre * set noreadonly
9350 :autocmd BufWritePost * set readonly
9351 :
9352 :try
9353 : write /i/m/p/o/s/s/i/b/l/e
9354 :catch
9355 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
9356 :endtry
9357<
9358You can also use ":silent!": >
9359
9360 :let x = "ok"
9361 :let v:errmsg = ""
9362 :autocmd BufWritePost * if v:errmsg != ""
9363 :autocmd BufWritePost * let x = "after fail"
9364 :autocmd BufWritePost * endif
9365 :try
9366 : silent! write /i/m/p/o/s/s/i/b/l/e
9367 :catch
9368 :endtry
9369 :echo x
9370
9371This displays "after fail".
9372
9373If the main action of the command does not fail, exceptions from the
9374autocommands will be catchable by the caller of the command: >
9375
9376 :autocmd BufWritePost * throw ":-("
9377 :autocmd BufWritePost * echo "Should not be displayed"
9378 :
9379 :try
9380 : write
9381 :catch
9382 : echo v:exception
9383 :endtry
9384<
9385 *except-autocmd-Cmd*
9386For some commands, the normal action can be replaced by a sequence of
9387autocommands. Exceptions from that sequence will be catchable by the caller
9388of the command.
9389 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar446cb832008-06-24 21:56:24 +00009390had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00009391some way. >
9392
9393 :if !exists("cnt")
9394 : let cnt = 0
9395 :
9396 : autocmd BufWriteCmd * if &modified
9397 : autocmd BufWriteCmd * let cnt = cnt + 1
9398 : autocmd BufWriteCmd * if cnt % 3 == 2
9399 : autocmd BufWriteCmd * throw "BufWriteCmdError"
9400 : autocmd BufWriteCmd * endif
9401 : autocmd BufWriteCmd * write | set nomodified
9402 : autocmd BufWriteCmd * if cnt % 3 == 0
9403 : autocmd BufWriteCmd * throw "BufWriteCmdError"
9404 : autocmd BufWriteCmd * endif
9405 : autocmd BufWriteCmd * echo "File successfully written!"
9406 : autocmd BufWriteCmd * endif
9407 :endif
9408 :
9409 :try
9410 : write
9411 :catch /^BufWriteCmdError$/
9412 : if &modified
9413 : echo "Error on writing (file contents not changed)"
9414 : else
9415 : echo "Error after writing"
9416 : endif
9417 :catch /^Vim(write):/
9418 : echo "Error on writing"
9419 :endtry
9420
9421When this script is sourced several times after making changes, it displays
9422first >
9423 File successfully written!
9424then >
9425 Error on writing (file contents not changed)
9426then >
9427 Error after writing
9428etc.
9429
9430 *except-autocmd-ill*
9431You cannot spread a try conditional over autocommands for different events.
9432The following code is ill-formed: >
9433
9434 :autocmd BufWritePre * try
9435 :
9436 :autocmd BufWritePost * catch
9437 :autocmd BufWritePost * echo v:exception
9438 :autocmd BufWritePost * endtry
9439 :
9440 :write
9441
9442
9443EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
9444
9445Some programming languages allow to use hierarchies of exception classes or to
9446pass additional information with the object of an exception class. You can do
9447similar things in Vim.
9448 In order to throw an exception from a hierarchy, just throw the complete
9449class name with the components separated by a colon, for instance throw the
9450string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
9451 When you want to pass additional information with your exception class, add
9452it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
9453for an error when writing "myfile".
9454 With the appropriate patterns in the ":catch" command, you can catch for
9455base classes or derived classes of your hierarchy. Additional information in
9456parentheses can be cut out from |v:exception| with the ":substitute" command.
9457 Example: >
9458
9459 :function! CheckRange(a, func)
9460 : if a:a < 0
9461 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
9462 : endif
9463 :endfunction
9464 :
9465 :function! Add(a, b)
9466 : call CheckRange(a:a, "Add")
9467 : call CheckRange(a:b, "Add")
9468 : let c = a:a + a:b
9469 : if c < 0
9470 : throw "EXCEPT:MATHERR:OVERFLOW"
9471 : endif
9472 : return c
9473 :endfunction
9474 :
9475 :function! Div(a, b)
9476 : call CheckRange(a:a, "Div")
9477 : call CheckRange(a:b, "Div")
9478 : if (a:b == 0)
9479 : throw "EXCEPT:MATHERR:ZERODIV"
9480 : endif
9481 : return a:a / a:b
9482 :endfunction
9483 :
9484 :function! Write(file)
9485 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00009486 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009487 : catch /^Vim(write):/
9488 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
9489 : endtry
9490 :endfunction
9491 :
9492 :try
9493 :
9494 : " something with arithmetics and I/O
9495 :
9496 :catch /^EXCEPT:MATHERR:RANGE/
9497 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
9498 : echo "Range error in" function
9499 :
9500 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
9501 : echo "Math error"
9502 :
9503 :catch /^EXCEPT:IO/
9504 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
9505 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
9506 : if file !~ '^/'
9507 : let file = dir . "/" . file
9508 : endif
9509 : echo 'I/O error for "' . file . '"'
9510 :
9511 :catch /^EXCEPT/
9512 : echo "Unspecified error"
9513 :
9514 :endtry
9515
9516The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
9517a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
9518exceptions with the "Vim" prefix; they are reserved for Vim.
9519 Vim error exceptions are parameterized with the name of the command that
9520failed, if known. See |catch-errors|.
9521
9522
9523PECULIARITIES
9524 *except-compat*
9525The exception handling concept requires that the command sequence causing the
9526exception is aborted immediately and control is transferred to finally clauses
9527and/or a catch clause.
9528
9529In the Vim script language there are cases where scripts and functions
9530continue after an error: in functions without the "abort" flag or in a command
9531after ":silent!", control flow goes to the following line, and outside
9532functions, control flow goes to the line following the outermost ":endwhile"
9533or ":endif". On the other hand, errors should be catchable as exceptions
9534(thus, requiring the immediate abortion).
9535
9536This problem has been solved by converting errors to exceptions and using
9537immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar446cb832008-06-24 21:56:24 +00009538conditional is active. This is no restriction since an (error) exception can
9539be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00009540termination without catching the error, just use a try conditional without
9541catch clause. (You can cause cleanup code being executed before termination
9542by specifying a finally clause.)
9543
9544When no try conditional is active, the usual abortion and continuation
9545behavior is used instead of immediate abortion. This ensures compatibility of
9546scripts written for Vim 6.1 and earlier.
9547
9548However, when sourcing an existing script that does not use exception handling
9549commands (or when calling one of its functions) from inside an active try
9550conditional of a new script, you might change the control flow of the existing
9551script on error. You get the immediate abortion on error and can catch the
9552error in the new script. If however the sourced script suppresses error
9553messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar446cb832008-06-24 21:56:24 +00009554|v:errmsg| if appropriate), its execution path is not changed. The error is
9555not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00009556where this happens is for scripts that don't care about errors and produce
9557error messages. You probably won't want to use such code from your new
9558scripts.
9559
9560 *except-syntax-err*
9561Syntax errors in the exception handling commands are never caught by any of
9562the ":catch" commands of the try conditional they belong to. Its finally
9563clauses, however, is executed.
9564 Example: >
9565
9566 :try
9567 : try
9568 : throw 4711
9569 : catch /\(/
9570 : echo "in catch with syntax error"
9571 : catch
9572 : echo "inner catch-all"
9573 : finally
9574 : echo "inner finally"
9575 : endtry
9576 :catch
9577 : echo 'outer catch-all caught "' . v:exception . '"'
9578 : finally
9579 : echo "outer finally"
9580 :endtry
9581
9582This displays: >
9583 inner finally
9584 outer catch-all caught "Vim(catch):E54: Unmatched \("
9585 outer finally
9586The original exception is discarded and an error exception is raised, instead.
9587
9588 *except-single-line*
9589The ":try", ":catch", ":finally", and ":endtry" commands can be put on
9590a single line, but then syntax errors may make it difficult to recognize the
9591"catch" line, thus you better avoid this.
9592 Example: >
9593 :try | unlet! foo # | catch | endtry
9594raises an error exception for the trailing characters after the ":unlet!"
9595argument, but does not see the ":catch" and ":endtry" commands, so that the
9596error exception is discarded and the "E488: Trailing characters" message gets
9597displayed.
9598
9599 *except-several-errors*
9600When several errors appear in a single command, the first error message is
9601usually the most specific one and therefor converted to the error exception.
9602 Example: >
9603 echo novar
9604causes >
9605 E121: Undefined variable: novar
9606 E15: Invalid expression: novar
9607The value of the error exception inside try conditionals is: >
9608 Vim(echo):E121: Undefined variable: novar
9609< *except-syntax-error*
9610But when a syntax error is detected after a normal error in the same command,
9611the syntax error is used for the exception being thrown.
9612 Example: >
9613 unlet novar #
9614causes >
9615 E108: No such variable: "novar"
9616 E488: Trailing characters
9617The value of the error exception inside try conditionals is: >
9618 Vim(unlet):E488: Trailing characters
9619This is done because the syntax error might change the execution path in a way
9620not intended by the user. Example: >
9621 try
9622 try | unlet novar # | catch | echo v:exception | endtry
9623 catch /.*/
9624 echo "outer catch:" v:exception
9625 endtry
9626This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
9627a "E600: Missing :endtry" error message is given, see |except-single-line|.
9628
9629==============================================================================
96309. Examples *eval-examples*
9631
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009632Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009633>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009634 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009635 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009636 : let n = a:nr
9637 : let r = ""
9638 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009639 : let r = '01'[n % 2] . r
9640 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00009641 : endwhile
9642 : return r
9643 :endfunc
9644
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009645 :" The function String2Bin() converts each character in a string to a
9646 :" binary string, separated with dashes.
9647 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009648 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009649 : for ix in range(strlen(a:str))
9650 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
9651 : endfor
9652 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00009653 :endfunc
9654
9655Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009656 :echo Nr2Bin(32)
9657result: "100000" >
9658 :echo String2Bin("32")
9659result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009660
9661
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009662Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009663
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009664This example sorts lines with a specific compare function. >
9665
9666 :func SortBuffer()
9667 : let lines = getline(1, '$')
9668 : call sort(lines, function("Strcmp"))
9669 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009670 :endfunction
9671
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009672As a one-liner: >
9673 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00009674
Bram Moolenaar071d4272004-06-13 20:20:40 +00009675
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009676scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009677 *sscanf*
9678There is no sscanf() function in Vim. If you need to extract parts from a
9679line, you can use matchstr() and substitute() to do it. This example shows
9680how to get the file name, line number and column number out of a line like
9681"foobar.txt, 123, 45". >
9682 :" Set up the match bit
9683 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
9684 :"get the part matching the whole expression
9685 :let l = matchstr(line, mx)
9686 :"get each item out of the match
9687 :let file = substitute(l, mx, '\1', '')
9688 :let lnum = substitute(l, mx, '\2', '')
9689 :let col = substitute(l, mx, '\3', '')
9690
9691The input is in the variable "line", the results in the variables "file",
9692"lnum" and "col". (idea from Michael Geddes)
9693
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009694
9695getting the scriptnames in a Dictionary ~
9696 *scriptnames-dictionary*
9697The |:scriptnames| command can be used to get a list of all script files that
9698have been sourced. There is no equivalent function or variable for this
9699(because it's rarely needed). In case you need to manipulate the list this
9700code can be used: >
9701 " Get the output of ":scriptnames" in the scriptnames_output variable.
9702 let scriptnames_output = ''
9703 redir => scriptnames_output
9704 silent scriptnames
9705 redir END
9706
Bram Moolenaar446cb832008-06-24 21:56:24 +00009707 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009708 " "scripts" dictionary.
9709 let scripts = {}
9710 for line in split(scriptnames_output, "\n")
9711 " Only do non-blank lines.
9712 if line =~ '\S'
9713 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009714 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009715 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00009716 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009717 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00009718 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009719 endif
9720 endfor
9721 unlet scriptnames_output
9722
Bram Moolenaar071d4272004-06-13 20:20:40 +00009723==============================================================================
972410. No +eval feature *no-eval-feature*
9725
9726When the |+eval| feature was disabled at compile time, none of the expression
9727evaluation commands are available. To prevent this from causing Vim scripts
9728to generate all kinds of errors, the ":if" and ":endif" commands are still
9729recognized, though the argument of the ":if" and everything between the ":if"
9730and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
9731only if the commands are at the start of the line. The ":else" command is not
9732recognized.
9733
9734Example of how to avoid executing commands when the |+eval| feature is
9735missing: >
9736
9737 :if 1
9738 : echo "Expression evaluation is compiled in"
9739 :else
9740 : echo "You will _never_ see this message"
9741 :endif
9742
9743==============================================================================
974411. The sandbox *eval-sandbox* *sandbox* *E48*
9745
Bram Moolenaar368373e2010-07-19 20:46:22 +02009746The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
9747'foldtext' options may be evaluated in a sandbox. This means that you are
9748protected from these expressions having nasty side effects. This gives some
9749safety for when these options are set from a modeline. It is also used when
9750the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009751The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009752
9753These items are not allowed in the sandbox:
9754 - changing the buffer text
9755 - defining or changing mapping, autocommands, functions, user commands
9756 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009757 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009758 - executing a shell command
9759 - reading or writing a file
9760 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00009761 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009762This is not guaranteed 100% secure, but it should block most attacks.
9763
9764 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00009765:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009766 option that may have been set from a modeline, e.g.
9767 'foldexpr'.
9768
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009769 *sandbox-option*
9770A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00009771have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009772restrictive, thus this only happens when the option was set from an insecure
9773location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00009774- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009775- while executing in the sandbox
9776- value coming from a modeline
9777
9778Note that when in the sandbox and saving an option value and restoring it, the
9779option will still be marked as it was set in the sandbox.
9780
9781==============================================================================
978212. Textlock *textlock*
9783
9784In a few situations it is not allowed to change the text in the buffer, jump
9785to another window and some other things that might confuse or break what Vim
9786is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar446cb832008-06-24 21:56:24 +00009787actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009788happen any moment the mouse cursor is resting at some position.
9789
9790This is not allowed when the textlock is active:
9791 - changing the buffer text
9792 - jumping to another buffer or window
9793 - editing another file
9794 - closing a window or quitting Vim
9795 - etc.
9796
Bram Moolenaar071d4272004-06-13 20:20:40 +00009797
9798 vim:tw=78:ts=8:ft=help:norl: