blob: be0e667b7c70a6fdb6f7cbdc067c567b2571f4bd [file] [log] [blame]
Bram Moolenaardfb18412013-12-11 18:53:29 +01001*eval.txt* For Vim version 7.4. Last change: 2013 Dec 08
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 Moolenaar446cb832008-06-24 21:56:24 +000040There are six 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
52Funcref A reference to a function |Funcref|.
53 Example: function("strlen")
54
55List An ordered sequence of items |List|.
56 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000057
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000058Dictionary An associative, unordered array: Each entry has a key and a
59 value. |Dictionary|
60 Example: {'blue': "#0000ff", 'red': "#ff0000"}
61
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000062The Number and String types are converted automatically, depending on how they
63are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000064
65Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020066the Number. Examples:
67 Number 123 --> String "123" ~
68 Number 0 --> String "0" ~
69 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020070 *octal*
Bram Moolenaar071d4272004-06-13 20:20:40 +000071Conversion from a String to a Number is done by converting the first digits
72to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020073the String doesn't start with digits, the result is zero. Examples:
74 String "456" --> Number 456 ~
75 String "6bar" --> Number 6 ~
76 String "foo" --> Number 0 ~
77 String "0xf1" --> Number 241 ~
78 String "0100" --> Number 64 ~
79 String "-8" --> Number -8 ~
80 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000081
82To force conversion from String to Number, add zero to it: >
83 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000084< 64 ~
85
86To avoid a leading zero to cause octal conversion, or for using a different
87base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000088
89For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
90
91Note that in the command >
92 :if "foo"
93"foo" is converted to 0, which means FALSE. To test for a non-empty string,
Bram Moolenaar3a0d8092012-10-21 03:02:54 +020094use empty(): >
95 :if !empty("foo")
Bram Moolenaar748bf032005-02-02 23:04:36 +000096< *E745* *E728* *E703* *E729* *E730* *E731*
97List, Dictionary and Funcref types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000098
Bram Moolenaar446cb832008-06-24 21:56:24 +000099 *E805* *E806* *E808*
100When mixing Number and Float the Number is converted to Float. Otherwise
101there is no automatic conversion of Float. You can use str2float() for String
102to Float, printf() for Float to String and float2nr() for Float to Number.
103
104 *E706* *sticky-type-checking*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000105You will get an error if you try to change the type of a variable. You need
106to |:unlet| it first to avoid this error. String and Number are considered
Bram Moolenaar446cb832008-06-24 21:56:24 +0000107equivalent though, as well are Float and Number. Consider this sequence of
108commands: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000109 :let l = "string"
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000110 :let l = 44 " changes type from String to Number
Bram Moolenaar446cb832008-06-24 21:56:24 +0000111 :let l = [1, 2, 3] " error! l is still a Number
112 :let l = 4.4 " changes type from Number to Float
113 :let l = "string" " error!
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000114
Bram Moolenaar13065c42005-01-08 16:08:21 +0000115
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001161.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000117 *Funcref* *E695* *E718*
Bram Moolenaar446cb832008-06-24 21:56:24 +0000118A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000119in an expression in the place of a function name, before the parenthesis
120around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000121
122 :let Fn = function("MyFunc")
123 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000124< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000125A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200126can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000127cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000128
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000129A special case is defining a function and directly assigning its Funcref to a
130Dictionary entry. Example: >
131 :function dict.init() dict
132 : let self.val = 0
133 :endfunction
134
135The key of the Dictionary can start with a lower case letter. The actual
136function name is not used here. Also see |numbered-function|.
137
138A Funcref can also be used with the |:call| command: >
139 :call Fn()
140 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000141
142The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000143 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000144
145You can use |call()| to invoke a Funcref and use a list variable for the
146arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000147 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000148
149
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001501.3 Lists ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000151 *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000152A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar446cb832008-06-24 21:56:24 +0000153can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000154position in the sequence.
155
Bram Moolenaar13065c42005-01-08 16:08:21 +0000156
157List creation ~
158 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000159A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000160Examples: >
161 :let mylist = [1, two, 3, "four"]
162 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000163
Bram Moolenaar446cb832008-06-24 21:56:24 +0000164An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000165List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000166 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000167
168An extra comma after the last item is ignored.
169
Bram Moolenaar13065c42005-01-08 16:08:21 +0000170
171List index ~
172 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000173An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000174after the List. Indexes are zero-based, thus the first item has index zero. >
175 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000176 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000177
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000178When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000179 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000180<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000181A negative index is counted from the end. Index -1 refers to the last item in
182the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000183 :let last = mylist[-1] " get the last item: "four"
184
Bram Moolenaar13065c42005-01-08 16:08:21 +0000185To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000186is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000187 :echo get(mylist, idx)
188 :echo get(mylist, idx, "NONE")
189
190
191List concatenation ~
192
193Two lists can be concatenated with the "+" operator: >
194 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000195 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000196
197To prepend or append an item turn the item into a list by putting [] around
198it. To change a list in-place see |list-modification| below.
199
200
201Sublist ~
202
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000203A part of the List can be obtained by specifying the first and last index,
204separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000205 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000206
207Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000208similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000209 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
210 :let shortlist = mylist[2:2] " List with one item: [3]
211 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000212
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000213If the first index is beyond the last item of the List or the second item is
214before the first item, the result is an empty list. There is no error
215message.
216
217If the second index is equal to or greater than the length of the list the
218length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000219 :let mylist = [0, 1, 2, 3]
220 :echo mylist[2:8] " result: [2, 3]
221
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000222NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar446cb832008-06-24 21:56:24 +0000223using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000224mylist[s : e].
225
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000226
Bram Moolenaar13065c42005-01-08 16:08:21 +0000227List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000228 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000229When variable "aa" is a list and you assign it to another variable "bb", both
230variables refer to the same list. Thus changing the list "aa" will also
231change "bb": >
232 :let aa = [1, 2, 3]
233 :let bb = aa
234 :call add(aa, 4)
235 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000236< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000237
238Making a copy of a list is done with the |copy()| function. Using [:] also
239works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000240a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241 :let aa = [[1, 'a'], 2, 3]
242 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000243 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000244 :let aa[0][1] = 'aaa'
245 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000246< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000247 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000248< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000249
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000250To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000251copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000252
253The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000254List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000255the same value. >
256 :let alist = [1, 2, 3]
257 :let blist = [1, 2, 3]
258 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000259< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000260 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000261< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000262
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000263Note about comparing lists: Two lists are considered equal if they have the
264same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000265exception: When comparing a number with a string they are considered
266different. There is no automatic type conversion, as with using "==" on
267variables. Example: >
268 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000269< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000270 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000271< 0
272
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000273Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000274can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000275
276 :let a = 5
277 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000278 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000279< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000280 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000281< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000282
Bram Moolenaar13065c42005-01-08 16:08:21 +0000283
284List unpack ~
285
286To unpack the items in a list to individual variables, put the variables in
287square brackets, like list items: >
288 :let [var1, var2] = mylist
289
290When the number of variables does not match the number of items in the list
291this produces an error. To handle any extra items from the list append ";"
292and a variable name: >
293 :let [var1, var2; rest] = mylist
294
295This works like: >
296 :let var1 = mylist[0]
297 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000298 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000299
300Except that there is no error if there are only two items. "rest" will be an
301empty list then.
302
303
304List modification ~
305 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000306To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000307 :let list[4] = "four"
308 :let listlist[0][3] = item
309
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000310To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000311modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000312 :let list[3:5] = [3, 4, 5]
313
Bram Moolenaar13065c42005-01-08 16:08:21 +0000314Adding and removing items from a list is done with functions. Here are a few
315examples: >
316 :call insert(list, 'a') " prepend item 'a'
317 :call insert(list, 'a', 3) " insert item 'a' before list[3]
318 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000319 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000320 :call extend(list, [1, 2]) " extend the list with two more items
321 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000322 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000323 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000324 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000325 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000326
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000327Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000328 :call sort(list) " sort a list alphabetically
329 :call reverse(list) " reverse the order of items
330
Bram Moolenaar13065c42005-01-08 16:08:21 +0000331
332For loop ~
333
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000334The |:for| loop executes commands for each item in a list. A variable is set
335to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000336 :for item in mylist
337 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000338 :endfor
339
340This works like: >
341 :let index = 0
342 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000343 : let item = mylist[index]
344 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000345 : let index = index + 1
346 :endwhile
347
348Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000349results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000350the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000351
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000352If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000353function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000354
Bram Moolenaar446cb832008-06-24 21:56:24 +0000355Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000356requires the argument to be a list of lists. >
357 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
358 : call Doit(lnum, col)
359 :endfor
360
361This works like a |:let| command is done for each list item. Again, the types
362must remain the same to avoid an error.
363
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000364It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000365 :for [i, j; rest] in listlist
366 : call Doit(i, j)
367 : if !empty(rest)
368 : echo "remainder: " . string(rest)
369 : endif
370 :endfor
371
372
373List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000374 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000375Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000376 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000377 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000378 :let l = len(list) " number of items in list
379 :let big = max(list) " maximum value in list
380 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000381 :let xs = count(list, 'x') " count nr of times 'x' appears in list
382 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000383 :let lines = getline(1, 10) " get ten text lines from buffer
384 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000385 :let list = split("a b c") " create list from items in a string
386 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000387 :let s = string(list) " String representation of list
388 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000389
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000390Don't forget that a combination of features can make things simple. For
391example, to add up all the numbers in a list: >
392 :exe 'let sum = ' . join(nrlist, '+')
393
Bram Moolenaar13065c42005-01-08 16:08:21 +0000394
Bram Moolenaard8b02732005-01-14 21:48:43 +00003951.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000396 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000397A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000398entry can be located with the key. The entries are stored without a specific
399ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000400
401
402Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000403 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000404A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000405braces. Each entry has a key and a value, separated by a colon. Each key can
406only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000407 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
408 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000409< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000410A key is always a String. You can use a Number, it will be converted to a
411String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar446cb832008-06-24 21:56:24 +0000412entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000413Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000414
Bram Moolenaar446cb832008-06-24 21:56:24 +0000415A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000416nested Dictionary: >
417 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
418
419An extra comma after the last entry is ignored.
420
421
422Accessing entries ~
423
424The normal way to access an entry is by putting the key in square brackets: >
425 :let val = mydict["one"]
426 :let mydict["four"] = 4
427
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000428You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000429
430For keys that consist entirely of letters, digits and underscore the following
431form can be used |expr-entry|: >
432 :let val = mydict.one
433 :let mydict.four = 4
434
435Since an entry can be any type, also a List and a Dictionary, the indexing and
436key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000437 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000438
439
440Dictionary to List conversion ~
441
Bram Moolenaar446cb832008-06-24 21:56:24 +0000442You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000443turn the Dictionary into a List and pass it to |:for|.
444
445Most often you want to loop over the keys, using the |keys()| function: >
446 :for key in keys(mydict)
447 : echo key . ': ' . mydict[key]
448 :endfor
449
450The List of keys is unsorted. You may want to sort them first: >
451 :for key in sort(keys(mydict))
452
453To loop over the values use the |values()| function: >
454 :for v in values(mydict)
455 : echo "value: " . v
456 :endfor
457
458If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000459a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000460 :for [key, value] in items(mydict)
461 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000462 :endfor
463
464
465Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000466 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000467Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
468Dictionary. Otherwise, assignment results in referring to the same
469Dictionary: >
470 :let onedict = {'a': 1, 'b': 2}
471 :let adict = onedict
472 :let adict['a'] = 11
473 :echo onedict['a']
474 11
475
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000476Two Dictionaries compare equal if all the key-value pairs compare equal. For
477more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000478
479
480Dictionary modification ~
481 *dict-modification*
482To change an already existing entry of a Dictionary, or to add a new entry,
483use |:let| this way: >
484 :let dict[4] = "four"
485 :let dict['one'] = item
486
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000487Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
488Three ways to remove the entry with key "aaa" from dict: >
489 :let i = remove(dict, 'aaa')
490 :unlet dict.aaa
491 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000492
493Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000494 :call extend(adict, bdict)
495This extends adict with all entries from bdict. Duplicate keys cause entries
496in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000497Note that the order of entries in a Dictionary is irrelevant, thus don't
498expect ":echo adict" to show the items from bdict after the older entries in
499adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000500
501Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000502 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000503This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000504
505
506Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100507 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000508When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000509special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000510 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000511 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000512 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000513 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
514 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000515
516This is like a method in object oriented programming. The entry in the
517Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
518the function was invoked from.
519
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000520It is also possible to add a function without the "dict" attribute as a
521Funcref to a Dictionary, but the "self" variable is not available then.
522
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000523 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000524To avoid the extra name for the function it can be defined and directly
525assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000526 :let mydict = {'data': [0, 1, 2, 3]}
527 :function mydict.len() dict
528 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000529 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000530 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000531
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000532The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar446cb832008-06-24 21:56:24 +0000533that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000534|Funcref|. It will automatically be deleted when there is no |Funcref|
535remaining that refers to it.
536
537It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000538
Bram Moolenaar1affd722010-08-04 17:49:30 +0200539If you get an error for a numbered function, you can find out what it is with
540a trick. Assuming the function is 42, the command is: >
541 :function {42}
542
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000543
544Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000545 *E715*
546Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000547 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
548 :if empty(dict) " TRUE if dict is empty
549 :let l = len(dict) " number of items in dict
550 :let big = max(dict) " maximum value in dict
551 :let small = min(dict) " minimum value in dict
552 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
553 :let s = string(dict) " String representation of dict
554 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000555
556
5571.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000558 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000559If you need to know the type of a variable or expression, use the |type()|
560function.
561
562When the '!' flag is included in the 'viminfo' option, global variables that
563start with an uppercase letter, and don't contain a lowercase letter, are
564stored in the viminfo file |viminfo-file|.
565
566When the 'sessionoptions' option contains "global", global variables that
567start with an uppercase letter and contain at least one lowercase letter are
568stored in the session file |session-file|.
569
570variable name can be stored where ~
571my_var_6 not
572My_Var_6 session file
573MY_VAR_6 viminfo file
574
575
576It's possible to form a variable name with curly braces, see
577|curly-braces-names|.
578
579==============================================================================
5802. Expression syntax *expression-syntax*
581
582Expression syntax summary, from least to most significant:
583
584|expr1| expr2 ? expr1 : expr1 if-then-else
585
586|expr2| expr3 || expr3 .. logical OR
587
588|expr3| expr4 && expr4 .. logical AND
589
590|expr4| expr5 == expr5 equal
591 expr5 != expr5 not equal
592 expr5 > expr5 greater than
593 expr5 >= expr5 greater than or equal
594 expr5 < expr5 smaller than
595 expr5 <= expr5 smaller than or equal
596 expr5 =~ expr5 regexp matches
597 expr5 !~ expr5 regexp doesn't match
598
599 expr5 ==? expr5 equal, ignoring case
600 expr5 ==# expr5 equal, match case
601 etc. As above, append ? for ignoring case, # for
602 matching case
603
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000604 expr5 is expr5 same |List| instance
605 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000606
607|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000608 expr6 - expr6 .. number subtraction
609 expr6 . expr6 .. string concatenation
610
611|expr6| expr7 * expr7 .. number multiplication
612 expr7 / expr7 .. number division
613 expr7 % expr7 .. number modulo
614
615|expr7| ! expr7 logical NOT
616 - expr7 unary minus
617 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000619|expr8| expr8[expr1] byte of a String or item of a |List|
620 expr8[expr1 : expr1] substring of a String or sublist of a |List|
621 expr8.name entry in a |Dictionary|
622 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000623
624|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000625 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000626 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000627 [expr1, ...] |List|
628 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000629 &option option value
630 (expr1) nested expression
631 variable internal variable
632 va{ria}ble internal variable with curly braces
633 $VAR environment variable
634 @r contents of register 'r'
635 function(expr1, ...) function call
636 func{ti}on(expr1, ...) function call with curly braces
637
638
639".." indicates that the operations in this level can be concatenated.
640Example: >
641 &nu || &list && &shell == "csh"
642
643All expressions within one level are parsed from left to right.
644
645
646expr1 *expr1* *E109*
647-----
648
649expr2 ? expr1 : expr1
650
651The expression before the '?' is evaluated to a number. If it evaluates to
652non-zero, the result is the value of the expression between the '?' and ':',
653otherwise the result is the value of the expression after the ':'.
654Example: >
655 :echo lnum == 1 ? "top" : lnum
656
657Since the first expression is an "expr2", it cannot contain another ?:. The
658other two expressions can, thus allow for recursive use of ?:.
659Example: >
660 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
661
662To keep this readable, using |line-continuation| is suggested: >
663 :echo lnum == 1
664 :\ ? "top"
665 :\ : lnum == 1000
666 :\ ? "last"
667 :\ : lnum
668
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000669You should always put a space before the ':', otherwise it can be mistaken for
670use in a variable such as "a:1".
671
Bram Moolenaar071d4272004-06-13 20:20:40 +0000672
673expr2 and expr3 *expr2* *expr3*
674---------------
675
676 *expr-barbar* *expr-&&*
677The "||" and "&&" operators take one argument on each side. The arguments
678are (converted to) Numbers. The result is:
679
680 input output ~
681n1 n2 n1 || n2 n1 && n2 ~
682zero zero zero zero
683zero non-zero non-zero zero
684non-zero zero non-zero zero
685non-zero non-zero non-zero non-zero
686
687The operators can be concatenated, for example: >
688
689 &nu || &list && &shell == "csh"
690
691Note that "&&" takes precedence over "||", so this has the meaning of: >
692
693 &nu || (&list && &shell == "csh")
694
695Once the result is known, the expression "short-circuits", that is, further
696arguments are not evaluated. This is like what happens in C. For example: >
697
698 let a = 1
699 echo a || b
700
701This is valid even if there is no variable called "b" because "a" is non-zero,
702so the result must be non-zero. Similarly below: >
703
704 echo exists("b") && b == "yes"
705
706This is valid whether "b" has been defined or not. The second clause will
707only be evaluated if "b" has been defined.
708
709
710expr4 *expr4*
711-----
712
713expr5 {cmp} expr5
714
715Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
716if it evaluates to true.
717
Bram Moolenaar446cb832008-06-24 21:56:24 +0000718 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000719 *expr-<* *expr-<=* *expr-=~* *expr-!~*
720 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
721 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
722 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
723 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200724 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
725 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000726 use 'ignorecase' match case ignore case ~
727equal == ==# ==?
728not equal != !=# !=?
729greater than > ># >?
730greater than or equal >= >=# >=?
731smaller than < <# <?
732smaller than or equal <= <=# <=?
733regexp matches =~ =~# =~?
734regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200735same instance is is# is?
736different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000737
738Examples:
739"abc" ==# "Abc" evaluates to 0
740"abc" ==? "Abc" evaluates to 1
741"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
742
Bram Moolenaar13065c42005-01-08 16:08:21 +0000743 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000744A |List| can only be compared with a |List| and only "equal", "not equal" and
745"is" can be used. This compares the values of the list, recursively.
746Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000747
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000748 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000749A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
750equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000751recursively. Ignoring case means case is ignored when comparing item values.
752
Bram Moolenaar13065c42005-01-08 16:08:21 +0000753 *E693* *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000754A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
755equal" can be used. Case is never ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000756
Bram Moolenaar251e1912011-06-19 05:09:16 +0200757When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the
758expressions are referring to the same |List| or |Dictionary| instance. A copy
759of a |List| is different from the original |List|. When using "is" without
760a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot"
761equivalent to using "not equal". Except that a different type means the
762values are different: "4 == '4'" is true, "4 is '4'" is false and "0 is []" is
Bram Moolenaard09acef2012-09-21 14:54:30 +0200763false and not an error. "is#"/"isnot#" and "is?"/"isnot?" can be used to match
Bram Moolenaar251e1912011-06-19 05:09:16 +0200764and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000765
Bram Moolenaar071d4272004-06-13 20:20:40 +0000766When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +0000767and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
Bram Moolenaar071d4272004-06-13 20:20:40 +0000768because 'x' converted to a Number is zero.
769
770When comparing two Strings, this is done with strcmp() or stricmp(). This
771results in the mathematical difference (comparing byte values), not
772necessarily the alphabetical difference in the local language.
773
Bram Moolenaar446cb832008-06-24 21:56:24 +0000774When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000775'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000776
777When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000778'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
779
780'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000781
782The "=~" and "!~" operators match the lefthand argument with the righthand
783argument, which is used as a pattern. See |pattern| for what a pattern is.
784This matching is always done like 'magic' was set and 'cpoptions' is empty, no
785matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
786portable. To avoid backslashes in the regexp pattern to be doubled, use a
787single-quote string, see |literal-string|.
788Since a string is considered to be a single line, a multi-line pattern
789(containing \n, backslash-n) will not match. However, a literal NL character
790can be matched like an ordinary character. Examples:
791 "foo\nbar" =~ "\n" evaluates to 1
792 "foo\nbar" =~ "\\n" evaluates to 0
793
794
795expr5 and expr6 *expr5* *expr6*
796---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000797expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000798expr6 - expr6 .. Number subtraction *expr--*
799expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000800
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000801For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000802result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000803
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100804expr7 * expr7 .. Number multiplication *expr-star*
805expr7 / expr7 .. Number division *expr-/*
806expr7 % expr7 .. Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000807
808For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100809For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000810
811Note the difference between "+" and ".":
812 "123" + "456" = 579
813 "123" . "456" = "123456"
814
Bram Moolenaar446cb832008-06-24 21:56:24 +0000815Since '.' has the same precedence as '+' and '-', you need to read: >
816 1 . 90 + 90.0
817As: >
818 (1 . 90) + 90.0
819That works, since the String "190" is automatically converted to the Number
820190, which can be added to the Float 90.0. However: >
821 1 . 90 * 90.0
822Should be read as: >
823 1 . (90 * 90.0)
824Since '.' has lower precedence than '*'. This does NOT work, since this
825attempts to concatenate a Float and a String.
826
827When dividing a Number by zero the result depends on the value:
828 0 / 0 = -0x80000000 (like NaN for Float)
829 >0 / 0 = 0x7fffffff (like positive infinity)
830 <0 / 0 = -0x7fffffff (like negative infinity)
831 (before Vim 7.2 it was always 0x7fffffff)
832
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833When the righthand side of '%' is zero, the result is 0.
834
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000835None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000836
Bram Moolenaar446cb832008-06-24 21:56:24 +0000837. and % do not work for Float. *E804*
838
Bram Moolenaar071d4272004-06-13 20:20:40 +0000839
840expr7 *expr7*
841-----
842! expr7 logical NOT *expr-!*
843- expr7 unary minus *expr-unary--*
844+ expr7 unary plus *expr-unary-+*
845
846For '!' non-zero becomes zero, zero becomes one.
847For '-' the sign of the number is changed.
848For '+' the number is unchanged.
849
850A String will be converted to a Number first.
851
Bram Moolenaar446cb832008-06-24 21:56:24 +0000852These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000853 !-1 == 0
854 !!8 == 1
855 --9 == 9
856
857
858expr8 *expr8*
859-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000860expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000862If expr8 is a Number or String this results in a String that contains the
863expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100864Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
865an alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000866
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000867Index zero gives the first character. This is like it works in C. Careful:
868text column numbers start with one! Example, to get the character under the
869cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000870 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000871
872If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000873String. A negative index always results in an empty string (reason: backwards
874compatibility). Use [-1:] to get the last byte.
875
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000876If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000877for possible index values. If the index is out of range this results in an
Bram Moolenaar446cb832008-06-24 21:56:24 +0000878error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000879 :let item = mylist[-1] " get last item
880
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000881Generally, if a |List| index is equal to or higher than the length of the
882|List|, or more negative than the length of the |List|, this results in an
883error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000884
Bram Moolenaard8b02732005-01-14 21:48:43 +0000885
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000886expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000887
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000888If expr8 is a Number or String this results in the substring with the bytes
889from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100890expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
891|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000892
893If expr1a is omitted zero is used. If expr1b is omitted the length of the
894string minus one is used.
895
896A negative number can be used to measure from the end of the string. -1 is
897the last character, -2 the last but one, etc.
898
899If an index goes out of range for the string characters are omitted. If
900expr1b is smaller than expr1a the result is an empty string.
901
902Examples: >
903 :let c = name[-1:] " last byte of a string
904 :let c = name[-2:-2] " last but one byte of a string
905 :let s = line(".")[4:] " from the fifth byte to the end
906 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100907<
908 *sublist* *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000909If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar446cb832008-06-24 21:56:24 +0000910the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000911just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000912 :let l = mylist[:3] " first four items
913 :let l = mylist[4:4] " List with one item
914 :let l = mylist[:] " shallow copy of a List
915
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000916Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
917error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000918
Bram Moolenaard8b02732005-01-14 21:48:43 +0000919
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000920expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000921
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000922If expr8 is a |Dictionary| and it is followed by a dot, then the following
923name will be used as a key in the |Dictionary|. This is just like:
924expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000925
926The name must consist of alphanumeric characters, just like a variable name,
927but it may start with a number. Curly braces cannot be used.
928
929There must not be white space before or after the dot.
930
931Examples: >
932 :let dict = {"one": 1, 2: "two"}
933 :echo dict.one
934 :echo dict .2
935
936Note that the dot is also used for String concatenation. To avoid confusion
937always put spaces around the dot for String concatenation.
938
939
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000940expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000941
942When expr8 is a |Funcref| type variable, invoke the function it refers to.
943
944
945
946 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000947number
948------
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100949number number constant *expr-number*
950 *hex-number* *octal-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000951
952Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
953
Bram Moolenaar446cb832008-06-24 21:56:24 +0000954 *floating-point-format*
955Floating point numbers can be written in two forms:
956
957 [-+]{N}.{M}
958 [-+]{N}.{M}e[-+]{exp}
959
960{N} and {M} are numbers. Both {N} and {M} must be present and can only
961contain digits.
962[-+] means there is an optional plus or minus sign.
963{exp} is the exponent, power of 10.
964Only a decimal point is accepted, not a comma. No matter what the current
965locale is.
966{only when compiled with the |+float| feature}
967
968Examples:
969 123.456
970 +0.0001
971 55.0
972 -0.123
973 1.234e03
974 1.0E-6
975 -3.1416e+88
976
977These are INVALID:
978 3. empty {M}
979 1e40 missing .{M}
980
Bram Moolenaare37d50a2008-08-06 17:06:04 +0000981 *float-pi* *float-e*
982A few useful values to copy&paste: >
983 :let pi = 3.14159265359
984 :let e = 2.71828182846
985
Bram Moolenaar446cb832008-06-24 21:56:24 +0000986Rationale:
987Before floating point was introduced, the text "123.456" was interpreted as
988the two numbers "123" and "456", both converted to a string and concatenated,
989resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +0000990could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +0000991incompatibility was accepted in favor of being able to use the normal notation
992for floating point numbers.
993
994 *floating-point-precision*
995The precision and range of floating points numbers depends on what "double"
996means in the library Vim was compiled with. There is no way to change this at
997runtime.
998
999The default for displaying a |Float| is to use 6 decimal places, like using
1000printf("%g", f). You can select something else when using the |printf()|
1001function. Example: >
1002 :echo printf('%.15e', atan(1))
1003< 7.853981633974483e-01
1004
1005
Bram Moolenaar071d4272004-06-13 20:20:40 +00001006
1007string *expr-string* *E114*
1008------
1009"string" string constant *expr-quote*
1010
1011Note that double quotes are used.
1012
1013A string constant accepts these special characters:
1014\... three-digit octal number (e.g., "\316")
1015\.. two-digit octal number (must be followed by non-digit)
1016\. one-digit octal number (must be followed by non-digit)
1017\x.. byte specified with two hex numbers (e.g., "\x1f")
1018\x. byte specified with one hex number (must be followed by non-hex char)
1019\X.. same as \x..
1020\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001021\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001022 current value of 'encoding' (e.g., "\u02a4")
1023\U.... same as \u....
1024\b backspace <BS>
1025\e escape <Esc>
1026\f formfeed <FF>
1027\n newline <NL>
1028\r return <CR>
1029\t tab <Tab>
1030\\ backslash
1031\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001032\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
1033 in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a
1034 utf-8 character, use \uxxxx as mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001035
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001036Note that "\xff" is stored as the byte 255, which may be invalid in some
1037encodings. Use "\u00ff" to store character 255 according to the current value
1038of 'encoding'.
1039
Bram Moolenaar071d4272004-06-13 20:20:40 +00001040Note that "\000" and "\x00" force the end of the string.
1041
1042
1043literal-string *literal-string* *E115*
1044---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001045'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001046
1047Note that single quotes are used.
1048
Bram Moolenaar446cb832008-06-24 21:56:24 +00001049This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001050meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001051
1052Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar446cb832008-06-24 21:56:24 +00001053to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001054 if a =~ "\\s*"
1055 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001056
1057
1058option *expr-option* *E112* *E113*
1059------
1060&option option value, local value if possible
1061&g:option global option value
1062&l:option local option value
1063
1064Examples: >
1065 echo "tabstop is " . &tabstop
1066 if &insertmode
1067
1068Any option name can be used here. See |options|. When using the local value
1069and there is no buffer-local or window-local value, the global value is used
1070anyway.
1071
1072
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001073register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001074--------
1075@r contents of register 'r'
1076
1077The result is the contents of the named register, as a single string.
1078Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar446cb832008-06-24 21:56:24 +00001079register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001080registers.
1081
1082When using the '=' register you get the expression itself, not what it
1083evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001084
1085
1086nesting *expr-nesting* *E110*
1087-------
1088(expr1) nested expression
1089
1090
1091environment variable *expr-env*
1092--------------------
1093$VAR environment variable
1094
1095The String value of any environment variable. When it is not defined, the
1096result is an empty string.
1097 *expr-env-expand*
1098Note that there is a difference between using $VAR directly and using
1099expand("$VAR"). Using it directly will only expand environment variables that
1100are known inside the current Vim session. Using expand() will first try using
1101the environment variables known inside the current Vim session. If that
1102fails, a shell will be used to expand the variable. This can be slow, but it
1103does expand all variables that the shell knows about. Example: >
1104 :echo $version
1105 :echo expand("$version")
1106The first one probably doesn't echo anything, the second echoes the $version
1107variable (if your shell supports it).
1108
1109
1110internal variable *expr-variable*
1111-----------------
1112variable internal variable
1113See below |internal-variables|.
1114
1115
Bram Moolenaar05159a02005-02-26 23:04:13 +00001116function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001117-------------
1118function(expr1, ...) function call
1119See below |functions|.
1120
1121
1122==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020011233. Internal variable *internal-variables* *E461*
1124
Bram Moolenaar071d4272004-06-13 20:20:40 +00001125An internal variable name can be made up of letters, digits and '_'. But it
1126cannot start with a digit. It's also possible to use curly braces, see
1127|curly-braces-names|.
1128
1129An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001130An internal variable is explicitly destroyed with the ":unlet" command
1131|:unlet|.
1132Using a name that is not an internal variable or refers to a variable that has
1133been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001134
1135There are several name spaces for variables. Which one is to be used is
1136specified by what is prepended:
1137
1138 (nothing) In a function: local to a function; otherwise: global
1139|buffer-variable| b: Local to the current buffer.
1140|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001141|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001142|global-variable| g: Global.
1143|local-variable| l: Local to a function.
1144|script-variable| s: Local to a |:source|'ed Vim script.
1145|function-argument| a: Function argument (only inside a function).
Bram Moolenaar446cb832008-06-24 21:56:24 +00001146|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001147
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001148The scope name by itself can be used as a |Dictionary|. For example, to
1149delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001150 :for k in keys(s:)
1151 : unlet s:[k]
1152 :endfor
1153<
Bram Moolenaar531da592013-05-06 05:58:55 +02001154 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001155A variable name that is preceded with "b:" is local to the current buffer.
1156Thus you can have several "b:foo" variables, one for each buffer.
1157This kind of variable is deleted when the buffer is wiped out or deleted with
1158|:bdelete|.
1159
1160One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001161 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001162b:changedtick The total number of changes to the current buffer. It is
1163 incremented for each change. An undo command is also a change
1164 in this case. This can be used to perform an action only when
1165 the buffer has changed. Example: >
1166 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001167 : let my_changedtick = b:changedtick
1168 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169 :endif
1170<
Bram Moolenaar531da592013-05-06 05:58:55 +02001171 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001172A variable name that is preceded with "w:" is local to the current window. It
1173is deleted when the window is closed.
1174
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001175 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001176A variable name that is preceded with "t:" is local to the current tab page,
1177It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001178without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001179
Bram Moolenaar531da592013-05-06 05:58:55 +02001180 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001181Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar446cb832008-06-24 21:56:24 +00001182access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001183place if you like.
1184
Bram Moolenaar531da592013-05-06 05:58:55 +02001185 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001186Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001187But you can also prepend "l:" if you like. However, without prepending "l:"
1188you may run into reserved variable names. For example "count". By itself it
1189refers to "v:count". Using "l:count" you can have a local variable with the
1190same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001191
1192 *script-variable* *s:var*
1193In a Vim script variables starting with "s:" can be used. They cannot be
1194accessed from outside of the scripts, thus are local to the script.
1195
1196They can be used in:
1197- commands executed while the script is sourced
1198- functions defined in the script
1199- autocommands defined in the script
1200- functions and autocommands defined in functions and autocommands which were
1201 defined in the script (recursively)
1202- user defined commands defined in the script
1203Thus not in:
1204- other scripts sourced from this one
1205- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001206- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207- etc.
1208
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001209Script variables can be used to avoid conflicts with global variable names.
1210Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001211
1212 let s:counter = 0
1213 function MyCounter()
1214 let s:counter = s:counter + 1
1215 echo s:counter
1216 endfunction
1217 command Tick call MyCounter()
1218
1219You can now invoke "Tick" from any script, and the "s:counter" variable in
1220that script will not be changed, only the "s:counter" in the script where
1221"Tick" was defined is used.
1222
1223Another example that does the same: >
1224
1225 let s:counter = 0
1226 command Tick let s:counter = s:counter + 1 | echo s:counter
1227
1228When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001229script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001230defined.
1231
1232The script variables are also available when a function is defined inside a
1233function that is defined in a script. Example: >
1234
1235 let s:counter = 0
1236 function StartCounting(incr)
1237 if a:incr
1238 function MyCounter()
1239 let s:counter = s:counter + 1
1240 endfunction
1241 else
1242 function MyCounter()
1243 let s:counter = s:counter - 1
1244 endfunction
1245 endif
1246 endfunction
1247
1248This defines the MyCounter() function either for counting up or counting down
1249when calling StartCounting(). It doesn't matter from where StartCounting() is
1250called, the s:counter variable will be accessible in MyCounter().
1251
1252When the same script is sourced again it will use the same script variables.
1253They will remain valid as long as Vim is running. This can be used to
1254maintain a counter: >
1255
1256 if !exists("s:counter")
1257 let s:counter = 1
1258 echo "script executed for the first time"
1259 else
1260 let s:counter = s:counter + 1
1261 echo "script executed " . s:counter . " times now"
1262 endif
1263
1264Note that this means that filetype plugins don't get a different set of script
1265variables for each buffer. Use local buffer variables instead |b:var|.
1266
1267
Bram Moolenaar531da592013-05-06 05:58:55 +02001268Predefined Vim variables: *vim-variable* *v:var* *v:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001269
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001270 *v:beval_col* *beval_col-variable*
1271v:beval_col The number of the column, over which the mouse pointer is.
1272 This is the byte index in the |v:beval_lnum| line.
1273 Only valid while evaluating the 'balloonexpr' option.
1274
1275 *v:beval_bufnr* *beval_bufnr-variable*
1276v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1277 valid while evaluating the 'balloonexpr' option.
1278
1279 *v:beval_lnum* *beval_lnum-variable*
1280v:beval_lnum The number of the line, over which the mouse pointer is. Only
1281 valid while evaluating the 'balloonexpr' option.
1282
1283 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001284v:beval_text The text under or after the mouse pointer. Usually a word as
1285 it is useful for debugging a C program. 'iskeyword' applies,
1286 but a dot and "->" before the position is included. When on a
1287 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001288 word before it. When on a Visual area within one line the
1289 highlighted text is used.
1290 Only valid while evaluating the 'balloonexpr' option.
1291
1292 *v:beval_winnr* *beval_winnr-variable*
1293v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001294 valid while evaluating the 'balloonexpr' option. The first
1295 window has number zero (unlike most other places where a
1296 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001297
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001298 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001299v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001300 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001301 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001302
Bram Moolenaar071d4272004-06-13 20:20:40 +00001303 *v:charconvert_from* *charconvert_from-variable*
1304v:charconvert_from
1305 The name of the character encoding of a file to be converted.
1306 Only valid while evaluating the 'charconvert' option.
1307
1308 *v:charconvert_to* *charconvert_to-variable*
1309v:charconvert_to
1310 The name of the character encoding of a file after conversion.
1311 Only valid while evaluating the 'charconvert' option.
1312
1313 *v:cmdarg* *cmdarg-variable*
1314v:cmdarg This variable is used for two purposes:
1315 1. The extra arguments given to a file read/write command.
1316 Currently these are "++enc=" and "++ff=". This variable is
1317 set before an autocommand event for a file read/write
1318 command is triggered. There is a leading space to make it
1319 possible to append this variable directly after the
Bram Moolenaar446cb832008-06-24 21:56:24 +00001320 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001321 included here, because it will be executed anyway.
1322 2. When printing a PostScript file with ":hardcopy" this is
1323 the argument for the ":hardcopy" command. This can be used
1324 in 'printexpr'.
1325
1326 *v:cmdbang* *cmdbang-variable*
1327v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1328 was used the value is 1, otherwise it is 0. Note that this
1329 can only be used in autocommands. For user commands |<bang>|
1330 can be used.
1331
1332 *v:count* *count-variable*
1333v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar446cb832008-06-24 21:56:24 +00001334 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001335 :map _x :<C-U>echo "the count is " . v:count<CR>
1336< Note: The <C-U> is required to remove the line range that you
1337 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001338 When there are two counts, as in "3d2w", they are multiplied,
1339 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001340 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001341 "count" also works, for backwards compatibility.
1342
1343 *v:count1* *count1-variable*
1344v:count1 Just like "v:count", but defaults to one when no count is
1345 used.
1346
1347 *v:ctype* *ctype-variable*
1348v:ctype The current locale setting for characters of the runtime
1349 environment. This allows Vim scripts to be aware of the
1350 current locale encoding. Technical: it's the value of
1351 LC_CTYPE. When not using a locale the value is "C".
1352 This variable can not be set directly, use the |:language|
1353 command.
1354 See |multi-lang|.
1355
1356 *v:dying* *dying-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001357v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001358 one. When multiple signals are caught the number increases.
1359 Can be used in an autocommand to check if Vim didn't
1360 terminate normally. {only works on Unix}
1361 Example: >
1362 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001363< Note: if another deadly signal is caught when v:dying is one,
1364 VimLeave autocommands will not be executed.
1365
Bram Moolenaar071d4272004-06-13 20:20:40 +00001366 *v:errmsg* *errmsg-variable*
1367v:errmsg Last given error message. It's allowed to set this variable.
1368 Example: >
1369 :let v:errmsg = ""
1370 :silent! next
1371 :if v:errmsg != ""
1372 : ... handle error
1373< "errmsg" also works, for backwards compatibility.
1374
1375 *v:exception* *exception-variable*
1376v:exception The value of the exception most recently caught and not
1377 finished. See also |v:throwpoint| and |throw-variables|.
1378 Example: >
1379 :try
1380 : throw "oops"
1381 :catch /.*/
1382 : echo "caught" v:exception
1383 :endtry
1384< Output: "caught oops".
1385
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001386 *v:fcs_reason* *fcs_reason-variable*
1387v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1388 Can be used in an autocommand to decide what to do and/or what
1389 to set v:fcs_choice to. Possible values:
1390 deleted file no longer exists
1391 conflict file contents, mode or timestamp was
1392 changed and buffer is modified
1393 changed file contents has changed
1394 mode mode of file changed
1395 time only file timestamp changed
1396
1397 *v:fcs_choice* *fcs_choice-variable*
1398v:fcs_choice What should happen after a |FileChangedShell| event was
1399 triggered. Can be used in an autocommand to tell Vim what to
1400 do with the affected buffer:
1401 reload Reload the buffer (does not work if
1402 the file was deleted).
1403 ask Ask the user what to do, as if there
1404 was no autocommand. Except that when
1405 only the timestamp changed nothing
1406 will happen.
1407 <empty> Nothing, the autocommand should do
1408 everything that needs to be done.
1409 The default is empty. If another (invalid) value is used then
1410 Vim behaves like it is empty, there is no warning message.
1411
Bram Moolenaar071d4272004-06-13 20:20:40 +00001412 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001413v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001414 option used for ~
1415 'charconvert' file to be converted
1416 'diffexpr' original file
1417 'patchexpr' original file
1418 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001419 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001420
1421 *v:fname_out* *fname_out-variable*
1422v:fname_out The name of the output file. Only valid while
1423 evaluating:
1424 option used for ~
1425 'charconvert' resulting converted file (*)
1426 'diffexpr' output of diff
1427 'patchexpr' resulting patched file
1428 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar446cb832008-06-24 21:56:24 +00001429 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001430 for a read command (e.g., ":e file") it will be a temporary
1431 file and different from v:fname_in.
1432
1433 *v:fname_new* *fname_new-variable*
1434v:fname_new The name of the new version of the file. Only valid while
1435 evaluating 'diffexpr'.
1436
1437 *v:fname_diff* *fname_diff-variable*
1438v:fname_diff The name of the diff (patch) file. Only valid while
1439 evaluating 'patchexpr'.
1440
1441 *v:folddashes* *folddashes-variable*
1442v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1443 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001444 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001445
1446 *v:foldlevel* *foldlevel-variable*
1447v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001448 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001449
1450 *v:foldend* *foldend-variable*
1451v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001452 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001453
1454 *v:foldstart* *foldstart-variable*
1455v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001456 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001457
Bram Moolenaar817a8802013-11-09 01:44:43 +01001458 *v:hlsearch* *hlsearch-variable*
1459v:hlsearch Variable that determines whether search highlighting is on.
1460 Makes sense only if 'hlsearch' is enabled which requires
1461 |+extra_search|. Setting this variable to zero acts the like
1462 |:nohlsearch| command, setting it to one acts like >
1463 let &hlsearch = &hlsearch
1464<
Bram Moolenaar843ee412004-06-30 16:16:41 +00001465 *v:insertmode* *insertmode-variable*
1466v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1467 events. Values:
1468 i Insert mode
1469 r Replace mode
1470 v Virtual Replace mode
1471
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001472 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001473v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001474 evaluating the expression used with |map()| and |filter()|.
1475 Read-only.
1476
Bram Moolenaar071d4272004-06-13 20:20:40 +00001477 *v:lang* *lang-variable*
1478v:lang The current locale setting for messages of the runtime
1479 environment. This allows Vim scripts to be aware of the
1480 current language. Technical: it's the value of LC_MESSAGES.
1481 The value is system dependent.
1482 This variable can not be set directly, use the |:language|
1483 command.
1484 It can be different from |v:ctype| when messages are desired
1485 in a different language than what is used for character
1486 encoding. See |multi-lang|.
1487
1488 *v:lc_time* *lc_time-variable*
1489v:lc_time The current locale setting for time messages of the runtime
1490 environment. This allows Vim scripts to be aware of the
1491 current language. Technical: it's the value of LC_TIME.
1492 This variable can not be set directly, use the |:language|
1493 command. See |multi-lang|.
1494
1495 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001496v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1497 'indentexpr' expressions, tab page number for 'guitablabel'
1498 and 'guitabtooltip'. Only valid while one of these
1499 expressions is being evaluated. Read-only when in the
1500 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001501
Bram Moolenaar219b8702006-11-01 14:32:36 +00001502 *v:mouse_win* *mouse_win-variable*
1503v:mouse_win Window number for a mouse click obtained with |getchar()|.
1504 First window has number 1, like with |winnr()|. The value is
1505 zero when there was no mouse button click.
1506
1507 *v:mouse_lnum* *mouse_lnum-variable*
1508v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1509 This is the text line number, not the screen line number. The
1510 value is zero when there was no mouse button click.
1511
1512 *v:mouse_col* *mouse_col-variable*
1513v:mouse_col Column number for a mouse click obtained with |getchar()|.
1514 This is the screen column number, like with |virtcol()|. The
1515 value is zero when there was no mouse button click.
1516
Bram Moolenaard812df62008-11-09 12:46:09 +00001517 *v:oldfiles* *oldfiles-variable*
1518v:oldfiles List of file names that is loaded from the |viminfo| file on
1519 startup. These are the files that Vim remembers marks for.
1520 The length of the List is limited by the ' argument of the
1521 'viminfo' option (default is 100).
1522 Also see |:oldfiles| and |c_#<|.
1523 The List can be modified, but this has no effect on what is
1524 stored in the |viminfo| file later. If you use values other
1525 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001526 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001527
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001528 *v:operator* *operator-variable*
1529v:operator The last operator given in Normal mode. This is a single
1530 character except for commands starting with <g> or <z>,
1531 in which case it is two characters. Best used alongside
1532 |v:prevcount| and |v:register|. Useful if you want to cancel
1533 Operator-pending mode and then use the operator, e.g.: >
1534 :omap O <Esc>:call MyMotion(v:operator)<CR>
1535< The value remains set until another operator is entered, thus
1536 don't expect it to be empty.
1537 v:operator is not set for |:delete|, |:yank| or other Ex
1538 commands.
1539 Read-only.
1540
Bram Moolenaar071d4272004-06-13 20:20:40 +00001541 *v:prevcount* *prevcount-variable*
1542v:prevcount The count given for the last but one Normal mode command.
1543 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001544 you want to cancel Visual or Operator-pending mode and then
1545 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001546 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1547< Read-only.
1548
Bram Moolenaar05159a02005-02-26 23:04:13 +00001549 *v:profiling* *profiling-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001550v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001551 See |profiling|.
1552
Bram Moolenaar071d4272004-06-13 20:20:40 +00001553 *v:progname* *progname-variable*
1554v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001555 invoked. Allows you to do special initialisations for |view|,
1556 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001557 Read-only.
1558
1559 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001560v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001561 command (regardless of whether that command actually used a
1562 register). Or for the currently executing normal mode mapping
1563 (use this in custom commands that take a register).
1564 If none is supplied it is the default register '"', unless
1565 'clipboard' contains "unnamed" or "unnamedplus", then it is
1566 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001567 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001568
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001569 *v:scrollstart* *scrollstart-variable*
1570v:scrollstart String describing the script or function that caused the
1571 screen to scroll up. It's only set when it is empty, thus the
1572 first reason is remembered. It is set to "Unknown" for a
1573 typed command.
1574 This can be used to find out why your script causes the
1575 hit-enter prompt.
1576
Bram Moolenaar071d4272004-06-13 20:20:40 +00001577 *v:servername* *servername-variable*
1578v:servername The resulting registered |x11-clientserver| name if any.
1579 Read-only.
1580
Bram Moolenaar446cb832008-06-24 21:56:24 +00001581
1582v:searchforward *v:searchforward* *searchforward-variable*
1583 Search direction: 1 after a forward search, 0 after a
1584 backward search. It is reset to forward when directly setting
1585 the last search pattern, see |quote/|.
1586 Note that the value is restored when returning from a
1587 function. |function-search-undo|.
1588 Read-write.
1589
Bram Moolenaar071d4272004-06-13 20:20:40 +00001590 *v:shell_error* *shell_error-variable*
1591v:shell_error Result of the last shell command. When non-zero, the last
1592 shell command had an error. When zero, there was no problem.
1593 This only works when the shell returns the error code to Vim.
1594 The value -1 is often used when the command could not be
1595 executed. Read-only.
1596 Example: >
1597 :!mv foo bar
1598 :if v:shell_error
1599 : echo 'could not rename "foo" to "bar"!'
1600 :endif
1601< "shell_error" also works, for backwards compatibility.
1602
1603 *v:statusmsg* *statusmsg-variable*
1604v:statusmsg Last given status message. It's allowed to set this variable.
1605
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001606 *v:swapname* *swapname-variable*
1607v:swapname Only valid when executing |SwapExists| autocommands: Name of
1608 the swap file found. Read-only.
1609
1610 *v:swapchoice* *swapchoice-variable*
1611v:swapchoice |SwapExists| autocommands can set this to the selected choice
1612 for handling an existing swap file:
1613 'o' Open read-only
1614 'e' Edit anyway
1615 'r' Recover
1616 'd' Delete swapfile
1617 'q' Quit
1618 'a' Abort
Bram Moolenaar446cb832008-06-24 21:56:24 +00001619 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001620 results in the user being asked, as would happen when there is
1621 no SwapExists autocommand. The default is empty.
1622
Bram Moolenaarb3480382005-12-11 21:33:32 +00001623 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001624v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001625 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar446cb832008-06-24 21:56:24 +00001626 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001627 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001628 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001629
Bram Moolenaar071d4272004-06-13 20:20:40 +00001630 *v:termresponse* *termresponse-variable*
1631v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar446cb832008-06-24 21:56:24 +00001632 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001633 that starts with ESC [ or CSI and ends in a 'c', with only
1634 digits, ';' and '.' in between.
1635 When this option is set, the TermResponse autocommand event is
1636 fired, so that you can react to the response from the
1637 terminal.
1638 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1639 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1640 patch level (since this was introduced in patch 95, it's
1641 always 95 or bigger). Pc is always zero.
1642 {only when compiled with |+termresponse| feature}
1643
1644 *v:this_session* *this_session-variable*
1645v:this_session Full filename of the last loaded or saved session file. See
1646 |:mksession|. It is allowed to set this variable. When no
1647 session file has been saved, this variable is empty.
1648 "this_session" also works, for backwards compatibility.
1649
1650 *v:throwpoint* *throwpoint-variable*
1651v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001652 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001653 also |v:exception| and |throw-variables|.
1654 Example: >
1655 :try
1656 : throw "oops"
1657 :catch /.*/
1658 : echo "Exception from" v:throwpoint
1659 :endtry
1660< Output: "Exception from test.vim, line 2"
1661
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001662 *v:val* *val-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001663v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001664 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001665 |filter()|. Read-only.
1666
Bram Moolenaar071d4272004-06-13 20:20:40 +00001667 *v:version* *version-variable*
1668v:version Version number of Vim: Major version number times 100 plus
1669 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1670 is 501. Read-only. "version" also works, for backwards
1671 compatibility.
1672 Use |has()| to check if a certain patch was included, e.g.: >
1673 if has("patch123")
1674< Note that patch numbers are specific to the version, thus both
1675 version 5.0 and 5.1 may have a patch 123, but these are
1676 completely different.
1677
1678 *v:warningmsg* *warningmsg-variable*
1679v:warningmsg Last given warning message. It's allowed to set this variable.
1680
Bram Moolenaar727c8762010-10-20 19:17:48 +02001681 *v:windowid* *windowid-variable*
1682v:windowid When any X11 based GUI is running or when running in a
1683 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001684 set to the window ID.
1685 When an MS-Windows GUI is running this will be set to the
1686 window handle.
1687 Otherwise the value is zero.
1688 Note: for windows inside Vim use |winnr()|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001689
Bram Moolenaar071d4272004-06-13 20:20:40 +00001690==============================================================================
16914. Builtin Functions *functions*
1692
1693See |function-list| for a list grouped by what the function is used for.
1694
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001695(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001696
1697USAGE RESULT DESCRIPTION ~
1698
Bram Moolenaar446cb832008-06-24 21:56:24 +00001699abs( {expr}) Float or Number absolute value of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001700acos( {expr}) Float arc cosine of {expr}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001701add( {list}, {item}) List append {item} to |List| {list}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001702and( {expr}, {expr}) Number bitwise AND
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001703append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001704append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001705argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001706argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001707argv( {nr}) String {nr} entry of the argument list
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001708argv( ) List the argument list
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001709asin( {expr}) Float arc sine of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001710atan( {expr}) Float arc tangent of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001711atan2( {expr}, {expr}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001712browse( {save}, {title}, {initdir}, {default})
1713 String put up a file requester
Bram Moolenaar446cb832008-06-24 21:56:24 +00001714browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001715bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001716buflisted( {expr}) Number TRUE if buffer {expr} is listed
1717bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001718bufname( {expr}) String Name of the buffer {expr}
1719bufnr( {expr}) Number Number of the buffer {expr}
1720bufwinnr( {expr}) Number window number of buffer {expr}
1721byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001722byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01001723byteidxcomp( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001724call( {func}, {arglist} [, {dict}])
1725 any call {func} with arguments {arglist}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001726ceil( {expr}) Float round {expr} up
1727changenr() Number current change number
Bram Moolenaard35d7842013-01-23 17:17:10 +01001728char2nr( {expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001729cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001730clearmatches() none clear all matches
Bram Moolenaar071d4272004-06-13 20:20:40 +00001731col( {expr}) Number column nr of cursor or mark
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001732complete( {startcol}, {matches}) none set Insert mode completion
Bram Moolenaar572cb562005-08-05 21:35:02 +00001733complete_add( {expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00001734complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001735confirm( {msg} [, {choices} [, {default} [, {type}]]])
1736 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001737copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001738cos( {expr}) Float cosine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001739cosh( {expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001740count( {list}, {expr} [, {start} [, {ic}]])
1741 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001742cscope_connection( [{num} , {dbpath} [, {prepend}]])
1743 Number checks existence of cscope connection
Bram Moolenaar0b238792006-03-02 22:49:12 +00001744cursor( {lnum}, {col} [, {coladd}])
1745 Number move cursor to {lnum}, {col}, {coladd}
1746cursor( {list}) Number move cursor to position in {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001747deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001748delete( {fname}) Number delete file {fname}
1749did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001750diff_filler( {lnum}) Number diff filler lines about {lnum}
1751diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001752empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001753escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001754eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001755eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001756executable( {expr}) Number 1 if executable {expr} exists
1757exists( {expr}) Number TRUE if {expr} exists
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001758extend( {expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001759 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001760exp( {expr}) Float exponential of {expr}
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001761expand( {expr} [, {nosuf} [, {list}]])
1762 any expand special keywords in {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001763feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001764filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001765filewritable( {file}) Number TRUE if {file} is a writable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001766filter( {expr}, {string}) List/Dict remove items from {expr} where
1767 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001768finddir( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001769 String find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001770findfile( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001771 String find file {name} in {path}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001772float2nr( {expr}) Number convert Float {expr} to a Number
1773floor( {expr}) Float round {expr} down
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001774fmod( {expr1}, {expr2}) Float remainder of {expr1} / {expr2}
Bram Moolenaaraebaf892008-05-28 14:49:58 +00001775fnameescape( {fname}) String escape special characters in {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001776fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001777foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1778foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001779foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001780foldtext( ) String line displayed for closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001781foldtextresult( {lnum}) String text for closed fold at {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001782foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001783function( {name}) Funcref reference to function {name}
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001784garbagecollect( [{atexit}]) none free memory, breaking cyclic references
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001785get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001786get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001787getbufline( {expr}, {lnum} [, {end}])
1788 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001789getbufvar( {expr}, {varname} [, {def}])
1790 any variable {varname} in buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001791getchar( [expr]) Number get one character from the user
1792getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001793getcmdline() String return the current command-line
1794getcmdpos() Number return cursor position in command-line
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001795getcmdtype() String return the current command-line type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001796getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001797getfperm( {fname}) String file permissions of file {fname}
1798getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001799getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001800getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001801getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001802getline( {lnum}) String line {lnum} of current buffer
1803getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001804getloclist( {nr}) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001805getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00001806getpid() Number process ID of Vim
Bram Moolenaar0b238792006-03-02 22:49:12 +00001807getpos( {expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001808getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001809getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001810getregtype( [{regname}]) String type of register
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001811gettabvar( {nr}, {varname} [, {def}])
1812 any variable {varname} in tab {nr} or {def}
1813gettabwinvar( {tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001814 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001815getwinposx() Number X coord in pixels of GUI Vim window
1816getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001817getwinvar( {nr}, {varname} [, {def}])
1818 any variable {varname} in window {nr}
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001819glob( {expr} [, {nosuf} [, {list}]])
1820 any expand file wildcards in {expr}
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00001821globpath( {path}, {expr} [, {flag}])
1822 String do glob({expr}) for all dirs in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001823has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001824has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaard267b9c2007-04-26 15:06:45 +00001825haslocaldir() Number TRUE if current window executed |:lcd|
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001826hasmapto( {what} [, {mode} [, {abbr}]])
1827 Number TRUE if mapping to {what} exists
Bram Moolenaar071d4272004-06-13 20:20:40 +00001828histadd( {history},{item}) String add an item to a history
1829histdel( {history} [, {item}]) String remove an item from a history
1830histget( {history} [, {index}]) String get the item {index} from a history
1831histnr( {history}) Number highest index of a history
1832hlexists( {name}) Number TRUE if highlight group {name} exists
1833hlID( {name}) Number syntax ID of highlight group {name}
1834hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001835iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1836indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001837index( {list}, {expr} [, {start} [, {ic}]])
1838 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001839input( {prompt} [, {text} [, {completion}]])
1840 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001841inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001842inputlist( {textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001843inputrestore() Number restore typeahead
1844inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001845inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001846insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001847invert( {expr}) Number bitwise invert
Bram Moolenaar071d4272004-06-13 20:20:40 +00001848isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001849islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001850items( {dict}) List key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001851join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001852keys( {dict}) List keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001853len( {expr}) Number the length of {expr}
1854libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001855libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1856line( {expr}) Number line nr of cursor, last line or mark
1857line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001858lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001859localtime() Number current time
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001860log( {expr}) Float natural logarithm (base e) of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001861log10( {expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaard38b0552012-04-25 19:07:41 +02001862luaeval( {expr}[, {expr}]) any evaluate |Lua| expression
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001863map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaarbd743252010-10-20 21:23:33 +02001864maparg( {name}[, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001865 String or Dict
1866 rhs of mapping {name} in mode {mode}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001867mapcheck( {name}[, {mode} [, {abbr}]])
1868 String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001869match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001870 Number position where {pat} matches in {expr}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001871matchadd( {group}, {pattern}[, {priority}[, {id}]])
1872 Number highlight {pattern} with {group}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001873matcharg( {nr}) List arguments of |:match|
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001874matchdelete( {id}) Number delete match identified by {id}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001875matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001876 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001877matchlist( {expr}, {pat}[, {start}[, {count}]])
1878 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001879matchstr( {expr}, {pat}[, {start}[, {count}]])
1880 String {count}'th match of {pat} in {expr}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001881max( {list}) Number maximum value of items in {list}
1882min( {list}) Number minimum value of items in {list}
1883mkdir( {name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001884 Number create directory {name}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001885mode( [expr]) String current editing mode
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001886mzeval( {expr}) any evaluate |MzScheme| expression
Bram Moolenaar071d4272004-06-13 20:20:40 +00001887nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaard35d7842013-01-23 17:17:10 +01001888nr2char( {expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001889or( {expr}, {expr}) Number bitwise OR
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001890pathshorten( {expr}) String shorten directory names in a path
Bram Moolenaar446cb832008-06-24 21:56:24 +00001891pow( {x}, {y}) Float {x} to the power of {y}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001892prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001893printf( {fmt}, {expr1}...) String format text
1894pumvisible() Number whether popup menu is visible
Bram Moolenaar30b65812012-07-12 22:01:11 +02001895pyeval( {expr}) any evaluate |Python| expression
1896py3eval( {expr}) any evaluate |python3| expression
Bram Moolenaard8b02732005-01-14 21:48:43 +00001897range( {expr} [, {max} [, {stride}]])
1898 List items from {expr} to {max}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001899readfile( {fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001900 List get list of lines from file {fname}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001901reltime( [{start} [, {end}]]) List get time value
1902reltimestr( {time}) String turn time value into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00001903remote_expr( {server}, {string} [, {idvar}])
1904 String send expression
1905remote_foreground( {server}) Number bring Vim server to the foreground
1906remote_peek( {serverid} [, {retvar}])
1907 Number check for reply string
1908remote_read( {serverid}) String read reply string
1909remote_send( {server}, {string} [, {idvar}])
1910 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001911remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001912remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001913rename( {from}, {to}) Number rename (move) file from {from} to {to}
1914repeat( {expr}, {count}) String repeat {expr} {count} times
1915resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001916reverse( {list}) List reverse {list} in-place
Bram Moolenaar446cb832008-06-24 21:56:24 +00001917round( {expr}) Float round off {expr}
Bram Moolenaar9a773482013-06-11 18:40:13 +02001918screenattr( {row}, {col}) Number attribute at screen position
1919screenchar( {row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01001920screencol() Number current cursor column
1921screenrow() Number current cursor row
Bram Moolenaar76929292008-01-06 19:07:36 +00001922search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1923 Number search for {pattern}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001924searchdecl( {name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00001925 Number search for variable declaration
Bram Moolenaar76929292008-01-06 19:07:36 +00001926searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001927 Number search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00001928searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001929 List search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00001930searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001931 List search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001932server2client( {clientid}, {string})
1933 Number send reply string
1934serverlist() String get a list of available servers
1935setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1936setcmdpos( {pos}) Number set cursor position in command-line
1937setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001938setloclist( {nr}, {list}[, {action}])
1939 Number modify location list using {list}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001940setmatches( {list}) Number restore a list of matches
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001941setpos( {expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001942setqflist( {list}[, {action}]) Number modify quickfix list using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001943setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001944settabvar( {nr}, {varname}, {val}) set {varname} in tab page {nr} to {val}
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001945settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1946 {winnr} in tab page {tabnr} to {val}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001947setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01001948sha256( {string}) String SHA256 checksum of {string}
Bram Moolenaar05bb9532008-07-04 09:44:11 +00001949shellescape( {string} [, {special}])
1950 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00001951 command argument
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02001952shiftwidth() Number effective value of 'shiftwidth'
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001953simplify( {filename}) String simplify filename as much as possible
Bram Moolenaar446cb832008-06-24 21:56:24 +00001954sin( {expr}) Float sine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001955sinh( {expr}) Float hyperbolic sine of {expr}
Bram Moolenaar5f894962011-06-19 02:55:37 +02001956sort( {list} [, {func} [, {dict}]])
1957 List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001958soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001959spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00001960spellsuggest( {word} [, {max} [, {capital}]])
1961 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001962split( {expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001963 List make |List| from {pat} separated {expr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01001964sqrt( {expr}) Float square root of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001965str2float( {expr}) Float convert String to Float
1966str2nr( {expr} [, {base}]) Number convert String to Number
Bram Moolenaar72597a52010-07-18 15:31:08 +02001967strchars( {expr}) Number character length of the String {expr}
Bram Moolenaardc536092010-07-18 15:45:49 +02001968strdisplaywidth( {expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001969strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001970stridx( {haystack}, {needle}[, {start}])
1971 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001972string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001973strlen( {expr}) Number length of the String {expr}
1974strpart( {src}, {start}[, {len}])
1975 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001976strridx( {haystack}, {needle} [, {start}])
1977 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001978strtrans( {expr}) String translate string to make it printable
Bram Moolenaar72597a52010-07-18 15:31:08 +02001979strwidth( {expr}) Number display cell length of the String {expr}
Bram Moolenaar251e1912011-06-19 05:09:16 +02001980submatch( {nr}) String specific match in ":s" or substitute()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001981substitute( {expr}, {pat}, {sub}, {flags})
1982 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001983synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001984synIDattr( {synID}, {what} [, {mode}])
1985 String attribute {what} of syntax ID {synID}
1986synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001987synconcealed( {lnum}, {col}) List info about concealing
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001988synstack( {lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001989system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001990tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1991tabpagenr( [{arg}]) Number number of current or last tab page
1992tabpagewinnr( {tabarg}[, {arg}])
1993 Number number of current window in tab page
1994taglist( {expr}) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001995tagfiles() List tags files used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001996tempname() String name for a temporary file
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001997tan( {expr}) Float tangent of {expr}
1998tanh( {expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001999tolower( {expr}) String the String {expr} switched to lowercase
2000toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00002001tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
2002 to chars in {tostr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01002003trunc( {expr}) Float truncate Float {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002004type( {name}) Number type of variable {name}
Bram Moolenaara17d4c12010-05-30 18:30:36 +02002005undofile( {name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002006undotree() List undo file tree
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002007values( {dict}) List values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002008virtcol( {expr}) Number screen column of cursor or mark
2009visualmode( [expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002010wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar071d4272004-06-13 20:20:40 +00002011winbufnr( {nr}) Number buffer number of window {nr}
2012wincol() Number window column of the cursor
2013winheight( {nr}) Number height of window {nr}
2014winline() Number window line of the cursor
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00002015winnr( [{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002016winrestcmd() String returns command to restore window sizes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002017winrestview( {dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002018winsaveview() Dict save view of current window
Bram Moolenaar071d4272004-06-13 20:20:40 +00002019winwidth( {nr}) Number width of window {nr}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002020writefile( {list}, {fname} [, {binary}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002021 Number write list of lines to file {fname}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002022xor( {expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002023
Bram Moolenaar446cb832008-06-24 21:56:24 +00002024abs({expr}) *abs()*
2025 Return the absolute value of {expr}. When {expr} evaluates to
2026 a |Float| abs() returns a |Float|. When {expr} can be
2027 converted to a |Number| abs() returns a |Number|. Otherwise
2028 abs() gives an error message and returns -1.
2029 Examples: >
2030 echo abs(1.456)
2031< 1.456 >
2032 echo abs(-5.456)
2033< 5.456 >
2034 echo abs(-4)
2035< 4
2036 {only available when compiled with the |+float| feature}
2037
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002038
2039acos({expr}) *acos()*
2040 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002041 |Float| in the range of [0, pi].
2042 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002043 [-1, 1].
2044 Examples: >
2045 :echo acos(0)
2046< 1.570796 >
2047 :echo acos(-0.5)
2048< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002049 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002050
2051
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002052add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002053 Append the item {expr} to |List| {list}. Returns the
2054 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002055 :let alist = add([1, 2, 3], item)
2056 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002057< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002058 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002059 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002060
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002061
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002062and({expr}, {expr}) *and()*
2063 Bitwise AND on the two arguments. The arguments are converted
2064 to a number. A List, Dict or Float argument causes an error.
2065 Example: >
2066 :let flag = and(bits, 0x80)
2067
2068
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002069append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002070 When {expr} is a |List|: Append each item of the |List| as a
2071 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002072 Otherwise append {expr} as one text line below line {lnum} in
2073 the current buffer.
2074 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002075 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar446cb832008-06-24 21:56:24 +00002076 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002077 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002078 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002079<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002080 *argc()*
2081argc() The result is the number of files in the argument list of the
2082 current window. See |arglist|.
2083
2084 *argidx()*
2085argidx() The result is the current index in the argument list. 0 is
2086 the first file. argc() - 1 is the last one. See |arglist|.
2087
2088 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002089argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002090 current window. See |arglist|. "argv(0)" is the first one.
2091 Example: >
2092 :let i = 0
2093 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002094 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002095 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2096 : let i = i + 1
2097 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002098< Without the {nr} argument a |List| with the whole |arglist| is
2099 returned.
2100
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002101asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002102 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002103 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002104 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002105 [-1, 1].
2106 Examples: >
2107 :echo asin(0.8)
2108< 0.927295 >
2109 :echo asin(-0.5)
2110< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002111 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002112
2113
Bram Moolenaar446cb832008-06-24 21:56:24 +00002114atan({expr}) *atan()*
2115 Return the principal value of the arc tangent of {expr}, in
2116 the range [-pi/2, +pi/2] radians, as a |Float|.
2117 {expr} must evaluate to a |Float| or a |Number|.
2118 Examples: >
2119 :echo atan(100)
2120< 1.560797 >
2121 :echo atan(-4.01)
2122< -1.326405
2123 {only available when compiled with the |+float| feature}
2124
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002125
2126atan2({expr1}, {expr2}) *atan2()*
2127 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002128 radians, as a |Float| in the range [-pi, pi].
2129 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002130 Examples: >
2131 :echo atan2(-1, 1)
2132< -0.785398 >
2133 :echo atan2(1, -1)
2134< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002135 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002136
2137
Bram Moolenaar071d4272004-06-13 20:20:40 +00002138 *browse()*
2139browse({save}, {title}, {initdir}, {default})
2140 Put up a file requester. This only works when "has("browse")"
2141 returns non-zero (only in some GUI versions).
2142 The input fields are:
2143 {save} when non-zero, select file to write
2144 {title} title for the requester
2145 {initdir} directory to start browsing in
2146 {default} default file name
2147 When the "Cancel" button is hit, something went wrong, or
2148 browsing is not possible, an empty string is returned.
2149
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002150 *browsedir()*
2151browsedir({title}, {initdir})
2152 Put up a directory requester. This only works when
2153 "has("browse")" returns non-zero (only in some GUI versions).
2154 On systems where a directory browser is not supported a file
2155 browser is used. In that case: select a file in the directory
2156 to be used.
2157 The input fields are:
2158 {title} title for the requester
2159 {initdir} directory to start browsing in
2160 When the "Cancel" button is hit, something went wrong, or
2161 browsing is not possible, an empty string is returned.
2162
Bram Moolenaar071d4272004-06-13 20:20:40 +00002163bufexists({expr}) *bufexists()*
2164 The result is a Number, which is non-zero if a buffer called
2165 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002166 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002167 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002168 exactly. The name can be:
2169 - Relative to the current directory.
2170 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002171 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002172 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002173 Unlisted buffers will be found.
2174 Note that help files are listed by their short name in the
2175 output of |:buffers|, but bufexists() requires using their
2176 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002177 bufexists() may report a buffer exists, but to use the name
2178 with a |:buffer| command you may need to use |expand()|. Esp
2179 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002180 Use "bufexists(0)" to test for the existence of an alternate
2181 file name.
2182 *buffer_exists()*
2183 Obsolete name: buffer_exists().
2184
2185buflisted({expr}) *buflisted()*
2186 The result is a Number, which is non-zero if a buffer called
2187 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002188 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002189
2190bufloaded({expr}) *bufloaded()*
2191 The result is a Number, which is non-zero if a buffer called
2192 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002193 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002194
2195bufname({expr}) *bufname()*
2196 The result is the name of a buffer, as it is displayed by the
2197 ":ls" command.
2198 If {expr} is a Number, that buffer number's name is given.
2199 Number zero is the alternate buffer for the current window.
2200 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002201 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002202 set and 'cpoptions' is empty. When there is more than one
2203 match an empty string is returned.
2204 "" or "%" can be used for the current buffer, "#" for the
2205 alternate buffer.
2206 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002207 or middle of the buffer name is accepted. If you only want a
2208 full match then put "^" at the start and "$" at the end of the
2209 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002210 Listed buffers are found first. If there is a single match
2211 with a listed buffer, that one is returned. Next unlisted
2212 buffers are searched for.
2213 If the {expr} is a String, but you want to use it as a buffer
2214 number, force it to be a Number by adding zero to it: >
2215 :echo bufname("3" + 0)
2216< If the buffer doesn't exist, or doesn't have a name, an empty
2217 string is returned. >
2218 bufname("#") alternate buffer name
2219 bufname(3) name of buffer 3
2220 bufname("%") name of current buffer
2221 bufname("file2") name of buffer where "file2" matches.
2222< *buffer_name()*
2223 Obsolete name: buffer_name().
2224
2225 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002226bufnr({expr} [, {create}])
2227 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002228 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002229 above.
2230 If the buffer doesn't exist, -1 is returned. Or, if the
2231 {create} argument is present and not zero, a new, unlisted,
2232 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002233 bufnr("$") is the last buffer: >
2234 :let last_buffer = bufnr("$")
2235< The result is a Number, which is the highest buffer number
2236 of existing buffers. Note that not all buffers with a smaller
2237 number necessarily exist, because ":bwipeout" may have removed
2238 them. Use bufexists() to test for the existence of a buffer.
2239 *buffer_number()*
2240 Obsolete name: buffer_number().
2241 *last_buffer_nr()*
2242 Obsolete name for bufnr("$"): last_buffer_nr().
2243
2244bufwinnr({expr}) *bufwinnr()*
2245 The result is a Number, which is the number of the first
2246 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar446cb832008-06-24 21:56:24 +00002247 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002248 there is no such window, -1 is returned. Example: >
2249
2250 echo "A window containing buffer 1 is " . (bufwinnr(1))
2251
2252< The number can be used with |CTRL-W_w| and ":wincmd w"
2253 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002254 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002255
2256
2257byte2line({byte}) *byte2line()*
2258 Return the line number that contains the character at byte
2259 count {byte} in the current buffer. This includes the
2260 end-of-line character, depending on the 'fileformat' option
2261 for the current buffer. The first character has byte count
2262 one.
2263 Also see |line2byte()|, |go| and |:goto|.
2264 {not available when compiled without the |+byte_offset|
2265 feature}
2266
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002267byteidx({expr}, {nr}) *byteidx()*
2268 Return byte index of the {nr}'th character in the string
2269 {expr}. Use zero for the first character, it returns zero.
2270 This function is only useful when there are multibyte
2271 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002272 Composing characters are not counted separately, their byte
2273 length is added to the preceding base character. See
2274 |byteidxcomp()| below for counting composing characters
2275 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002276 Example : >
2277 echo matchstr(str, ".", byteidx(str, 3))
2278< will display the fourth character. Another way to do the
2279 same: >
2280 let s = strpart(str, byteidx(str, 3))
2281 echo strpart(s, 0, byteidx(s, 1))
2282< If there are less than {nr} characters -1 is returned.
2283 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002284 in bytes is returned.
2285
2286byteidxcomp({expr}, {nr}) *byteidxcomp()*
2287 Like byteidx(), except that a composing character is counted
2288 as a separate character. Example: >
2289 let s = 'e' . nr2char(0x301)
2290 echo byteidx(s, 1)
2291 echo byteidxcomp(s, 1)
2292 echo byteidxcomp(s, 2)
2293< The first and third echo result in 3 ('e' plus composing
2294 character is 3 bytes), the second echo results in 1 ('e' is
2295 one byte).
2296 Only works different from byteidx() when 'encoding' is set to
2297 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002298
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002299call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002300 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002301 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002302 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002303 a:firstline and a:lastline are set to the cursor line.
2304 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002305 {dict} is for functions with the "dict" attribute. It will be
2306 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002307
Bram Moolenaar446cb832008-06-24 21:56:24 +00002308ceil({expr}) *ceil()*
2309 Return the smallest integral value greater than or equal to
2310 {expr} as a |Float| (round up).
2311 {expr} must evaluate to a |Float| or a |Number|.
2312 Examples: >
2313 echo ceil(1.456)
2314< 2.0 >
2315 echo ceil(-5.456)
2316< -5.0 >
2317 echo ceil(4.0)
2318< 4.0
2319 {only available when compiled with the |+float| feature}
2320
Bram Moolenaarca003e12006-03-17 23:19:38 +00002321changenr() *changenr()*
2322 Return the number of the most recent change. This is the same
2323 number as what is displayed with |:undolist| and can be used
2324 with the |:undo| command.
2325 When a change was made it is the number of that change. After
2326 redo it is the number of the redone change. After undo it is
2327 one less than the number of the undone change.
2328
Bram Moolenaard35d7842013-01-23 17:17:10 +01002329char2nr({expr}[, {utf8}]) *char2nr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002330 Return number value of the first char in {expr}. Examples: >
2331 char2nr(" ") returns 32
2332 char2nr("ABC") returns 65
Bram Moolenaard35d7842013-01-23 17:17:10 +01002333< When {utf8} is omitted or zero, the current 'encoding' is used.
2334 Example for "utf-8": >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002335 char2nr("á") returns 225
2336 char2nr("á"[0]) returns 195
Bram Moolenaard35d7842013-01-23 17:17:10 +01002337< With {utf8} set to 1, always treat as utf-8 characters.
2338 A combining character is a separate character.
Bram Moolenaar97293012011-07-18 19:40:27 +02002339 |nr2char()| does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002340
2341cindent({lnum}) *cindent()*
2342 Get the amount of indent for line {lnum} according the C
2343 indenting rules, as with 'cindent'.
2344 The indent is counted in spaces, the value of 'tabstop' is
2345 relevant. {lnum} is used just like in |getline()|.
2346 When {lnum} is invalid or Vim was not compiled the |+cindent|
2347 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00002348 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002349
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002350clearmatches() *clearmatches()*
2351 Clears all matches previously defined by |matchadd()| and the
2352 |:match| commands.
2353
Bram Moolenaar071d4272004-06-13 20:20:40 +00002354 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002355col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00002356 position given with {expr}. The accepted positions are:
2357 . the cursor position
2358 $ the end of the cursor line (the result is the
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02002359 number of bytes in the cursor line plus one)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002360 'x position of mark x (if the mark is not set, 0 is
2361 returned)
Bram Moolenaar477933c2007-07-17 14:32:23 +00002362 Additionally {expr} can be [lnum, col]: a |List| with the line
2363 and column number. Most useful when the column is "$", to get
Bram Moolenaar446cb832008-06-24 21:56:24 +00002364 the last column of a specific line. When "lnum" or "col" is
Bram Moolenaar477933c2007-07-17 14:32:23 +00002365 out of range then col() returns zero.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002366 To get the line number use |line()|. To get both use
Bram Moolenaar0b238792006-03-02 22:49:12 +00002367 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002368 For the screen column position use |virtcol()|.
2369 Note that only marks in the current file can be used.
2370 Examples: >
2371 col(".") column of cursor
2372 col("$") length of cursor line plus one
2373 col("'t") column of mark t
2374 col("'" . markname) column of mark markname
Bram Moolenaar446cb832008-06-24 21:56:24 +00002375< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002376 For an uppercase mark the column may actually be in another
2377 buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002378 For the cursor position, when 'virtualedit' is active, the
2379 column is one higher if the cursor is after the end of the
2380 line. This can be used to obtain the column in Insert mode: >
2381 :imap <F2> <C-O>:let save_ve = &ve<CR>
2382 \<C-O>:set ve=all<CR>
2383 \<C-O>:echo col(".") . "\n" <Bar>
2384 \let &ve = save_ve<CR>
2385<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002386
Bram Moolenaara94bc432006-03-10 21:42:59 +00002387complete({startcol}, {matches}) *complete()* *E785*
2388 Set the matches for Insert mode completion.
2389 Can only be used in Insert mode. You need to use a mapping
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002390 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2391 with an expression mapping.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002392 {startcol} is the byte offset in the line where the completed
2393 text start. The text up to the cursor is the original text
2394 that will be replaced by the matches. Use col('.') for an
2395 empty string. "col('.') - 1" will replace one character by a
2396 match.
2397 {matches} must be a |List|. Each |List| item is one match.
2398 See |complete-items| for the kind of items that are possible.
2399 Note that the after calling this function you need to avoid
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002400 inserting anything that would cause completion to stop.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002401 The match can be selected with CTRL-N and CTRL-P as usual with
2402 Insert mode completion. The popup menu will appear if
2403 specified, see |ins-completion-menu|.
2404 Example: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002405 inoremap <F5> <C-R>=ListMonths()<CR>
Bram Moolenaara94bc432006-03-10 21:42:59 +00002406
2407 func! ListMonths()
2408 call complete(col('.'), ['January', 'February', 'March',
2409 \ 'April', 'May', 'June', 'July', 'August', 'September',
2410 \ 'October', 'November', 'December'])
2411 return ''
2412 endfunc
2413< This isn't very useful, but it shows how it works. Note that
2414 an empty string is returned to avoid a zero being inserted.
2415
Bram Moolenaar572cb562005-08-05 21:35:02 +00002416complete_add({expr}) *complete_add()*
2417 Add {expr} to the list of matches. Only to be used by the
2418 function specified with the 'completefunc' option.
2419 Returns 0 for failure (empty string or out of memory),
2420 1 when the match was added, 2 when the match was already in
2421 the list.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002422 See |complete-functions| for an explanation of {expr}. It is
Bram Moolenaar39f05632006-03-19 22:15:26 +00002423 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002424
2425complete_check() *complete_check()*
2426 Check for a key typed while looking for completion matches.
2427 This is to be used when looking for matches takes some time.
2428 Returns non-zero when searching for matches is to be aborted,
2429 zero otherwise.
2430 Only to be used by the function specified with the
2431 'completefunc' option.
2432
Bram Moolenaar071d4272004-06-13 20:20:40 +00002433 *confirm()*
2434confirm({msg} [, {choices} [, {default} [, {type}]]])
2435 Confirm() offers the user a dialog, from which a choice can be
2436 made. It returns the number of the choice. For the first
2437 choice this is 1.
2438 Note: confirm() is only supported when compiled with dialog
2439 support, see |+dialog_con| and |+dialog_gui|.
Bram Moolenaara800b422010-06-27 01:15:55 +02002440
Bram Moolenaar071d4272004-06-13 20:20:40 +00002441 {msg} is displayed in a |dialog| with {choices} as the
2442 alternatives. When {choices} is missing or empty, "&OK" is
2443 used (and translated).
2444 {msg} is a String, use '\n' to include a newline. Only on
2445 some systems the string is wrapped when it doesn't fit.
Bram Moolenaara800b422010-06-27 01:15:55 +02002446
Bram Moolenaar071d4272004-06-13 20:20:40 +00002447 {choices} is a String, with the individual choices separated
2448 by '\n', e.g. >
2449 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2450< The letter after the '&' is the shortcut key for that choice.
2451 Thus you can type 'c' to select "Cancel". The shortcut does
2452 not need to be the first letter: >
2453 confirm("file has been modified", "&Save\nSave &All")
2454< For the console, the first letter of each choice is used as
2455 the default shortcut key.
Bram Moolenaara800b422010-06-27 01:15:55 +02002456
Bram Moolenaar071d4272004-06-13 20:20:40 +00002457 The optional {default} argument is the number of the choice
2458 that is made if the user hits <CR>. Use 1 to make the first
2459 choice the default one. Use 0 to not set a default. If
2460 {default} is omitted, 1 is used.
Bram Moolenaara800b422010-06-27 01:15:55 +02002461
2462 The optional {type} argument gives the type of dialog. This
2463 is only used for the icon of the GTK, Mac, Motif and Win32
2464 GUI. It can be one of these values: "Error", "Question",
2465 "Info", "Warning" or "Generic". Only the first character is
2466 relevant. When {type} is omitted, "Generic" is used.
2467
Bram Moolenaar071d4272004-06-13 20:20:40 +00002468 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2469 or another valid interrupt key, confirm() returns 0.
2470
2471 An example: >
2472 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2473 :if choice == 0
2474 : echo "make up your mind!"
2475 :elseif choice == 3
2476 : echo "tasteful"
2477 :else
2478 : echo "I prefer bananas myself."
2479 :endif
2480< In a GUI dialog, buttons are used. The layout of the buttons
2481 depends on the 'v' flag in 'guioptions'. If it is included,
Bram Moolenaar446cb832008-06-24 21:56:24 +00002482 the buttons are always put vertically. Otherwise, confirm()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002483 tries to put the buttons in one horizontal line. If they
2484 don't fit, a vertical layout is used anyway. For some systems
2485 the horizontal layout is always used.
2486
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002487 *copy()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002488copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002489 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002490 When {expr} is a |List| a shallow copy is created. This means
2491 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002492 copy, and vice versa. But the items are identical, thus
2493 changing an item changes the contents of both |Lists|. Also
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002494 see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002495
Bram Moolenaar446cb832008-06-24 21:56:24 +00002496cos({expr}) *cos()*
2497 Return the cosine of {expr}, measured in radians, as a |Float|.
2498 {expr} must evaluate to a |Float| or a |Number|.
2499 Examples: >
2500 :echo cos(100)
2501< 0.862319 >
2502 :echo cos(-4.01)
2503< -0.646043
2504 {only available when compiled with the |+float| feature}
2505
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002506
2507cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002508 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002509 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002510 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002511 Examples: >
2512 :echo cosh(0.5)
2513< 1.127626 >
2514 :echo cosh(-0.5)
2515< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02002516 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002517
Bram Moolenaar446cb832008-06-24 21:56:24 +00002518
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002519count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002520 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002521 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002522 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002523 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002524 When {ic} is given and it's non-zero then case is ignored.
2525
2526
Bram Moolenaar071d4272004-06-13 20:20:40 +00002527 *cscope_connection()*
2528cscope_connection([{num} , {dbpath} [, {prepend}]])
2529 Checks for the existence of a |cscope| connection. If no
2530 parameters are specified, then the function returns:
2531 0, if cscope was not available (not compiled in), or
2532 if there are no cscope connections;
2533 1, if there is at least one cscope connection.
2534
2535 If parameters are specified, then the value of {num}
2536 determines how existence of a cscope connection is checked:
2537
2538 {num} Description of existence check
2539 ----- ------------------------------
2540 0 Same as no parameters (e.g., "cscope_connection()").
2541 1 Ignore {prepend}, and use partial string matches for
2542 {dbpath}.
2543 2 Ignore {prepend}, and use exact string matches for
2544 {dbpath}.
2545 3 Use {prepend}, use partial string matches for both
2546 {dbpath} and {prepend}.
2547 4 Use {prepend}, use exact string matches for both
2548 {dbpath} and {prepend}.
2549
2550 Note: All string comparisons are case sensitive!
2551
2552 Examples. Suppose we had the following (from ":cs show"): >
2553
2554 # pid database name prepend path
2555 0 27664 cscope.out /usr/local
2556<
2557 Invocation Return Val ~
2558 ---------- ---------- >
2559 cscope_connection() 1
2560 cscope_connection(1, "out") 1
2561 cscope_connection(2, "out") 0
2562 cscope_connection(3, "out") 0
2563 cscope_connection(3, "out", "local") 1
2564 cscope_connection(4, "out") 0
2565 cscope_connection(4, "out", "local") 0
2566 cscope_connection(4, "cscope.out", "/usr/local") 1
2567<
Bram Moolenaar0b238792006-03-02 22:49:12 +00002568cursor({lnum}, {col} [, {off}]) *cursor()*
2569cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002570 Positions the cursor at the column (byte count) {col} in the
2571 line {lnum}. The first column is one.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002572 When there is one argument {list} this is used as a |List|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002573 with two or three items {lnum}, {col} and {off}. This is like
2574 the return value of |getpos()|, but without the first item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002575 Does not change the jumplist.
2576 If {lnum} is greater than the number of lines in the buffer,
2577 the cursor will be positioned at the last line in the buffer.
2578 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002579 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002580 the cursor will be positioned at the last character in the
2581 line.
2582 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002583 When 'virtualedit' is used {off} specifies the offset in
2584 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00002585 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00002586 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002587
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002588
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002589deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002590 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002591 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002592 When {expr} is a |List| a full copy is created. This means
2593 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002594 copy, and vice versa. When an item is a |List|, a copy for it
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002595 is made, recursively. Thus changing an item in the copy does
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002596 not change the contents of the original |List|.
2597 When {noref} is omitted or zero a contained |List| or
2598 |Dictionary| is only copied once. All references point to
2599 this single copy. With {noref} set to 1 every occurrence of a
2600 |List| or |Dictionary| results in a new copy. This also means
2601 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002602 *E724*
2603 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002604 that refers back to a higher level making a deep copy with
2605 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002606 Also see |copy()|.
2607
2608delete({fname}) *delete()*
2609 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002610 which is 0 if the file was deleted successfully, and non-zero
2611 when the deletion failed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002612 Use |remove()| to delete an item from a |List|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +01002613 To delete a line from the buffer use |:delete|. Use |:exe|
2614 when the line number is in a variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002615
2616 *did_filetype()*
2617did_filetype() Returns non-zero when autocommands are being executed and the
2618 FileType event has been triggered at least once. Can be used
2619 to avoid triggering the FileType event again in the scripts
2620 that detect the file type. |FileType|
2621 When editing another file, the counter is reset, thus this
2622 really checks if the FileType event has been triggered for the
2623 current buffer. This allows an autocommand that starts
2624 editing another buffer to set 'filetype' and load a syntax
2625 file.
2626
Bram Moolenaar47136d72004-10-12 20:02:24 +00002627diff_filler({lnum}) *diff_filler()*
2628 Returns the number of filler lines above line {lnum}.
2629 These are the lines that were inserted at this point in
2630 another diff'ed window. These filler lines are shown in the
2631 display but don't exist in the buffer.
2632 {lnum} is used like with |getline()|. Thus "." is the current
2633 line, "'m" mark m, etc.
2634 Returns 0 if the current window is not in diff mode.
2635
2636diff_hlID({lnum}, {col}) *diff_hlID()*
2637 Returns the highlight ID for diff mode at line {lnum} column
2638 {col} (byte index). When the current line does not have a
2639 diff change zero is returned.
2640 {lnum} is used like with |getline()|. Thus "." is the current
2641 line, "'m" mark m, etc.
2642 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2643 line.
2644 The highlight ID can be used with |synIDattr()| to obtain
2645 syntax information about the highlighting.
2646
Bram Moolenaar13065c42005-01-08 16:08:21 +00002647empty({expr}) *empty()*
2648 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002649 A |List| or |Dictionary| is empty when it does not have any
Bram Moolenaar446cb832008-06-24 21:56:24 +00002650 items. A Number is empty when its value is zero.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002651 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002652 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002653
Bram Moolenaar071d4272004-06-13 20:20:40 +00002654escape({string}, {chars}) *escape()*
2655 Escape the characters in {chars} that occur in {string} with a
2656 backslash. Example: >
2657 :echo escape('c:\program files\vim', ' \')
2658< results in: >
2659 c:\\program\ files\\vim
Bram Moolenaar446cb832008-06-24 21:56:24 +00002660< Also see |shellescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002661
Bram Moolenaar446cb832008-06-24 21:56:24 +00002662 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002663eval({string}) Evaluate {string} and return the result. Especially useful to
2664 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002665 This works for Numbers, Floats, Strings and composites of
2666 them. Also works for |Funcref|s that refer to existing
2667 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002668
Bram Moolenaar071d4272004-06-13 20:20:40 +00002669eventhandler() *eventhandler()*
2670 Returns 1 when inside an event handler. That is that Vim got
2671 interrupted while waiting for the user to type a character,
2672 e.g., when dropping a file on Vim. This means interactive
2673 commands cannot be used. Otherwise zero is returned.
2674
2675executable({expr}) *executable()*
2676 This function checks if an executable with the name {expr}
2677 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002678 arguments.
2679 executable() uses the value of $PATH and/or the normal
2680 searchpath for programs. *PATHEXT*
2681 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2682 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar446cb832008-06-24 21:56:24 +00002683 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2684 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002685 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar446cb832008-06-24 21:56:24 +00002686 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002687 Unix shell, then the name is also tried without adding an
2688 extension.
2689 On MS-DOS and MS-Windows it only checks if the file exists and
2690 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002691 On MS-Windows an executable in the same directory as Vim is
2692 always found. Since this directory is added to $PATH it
2693 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002694 The result is a Number:
2695 1 exists
2696 0 does not exist
2697 -1 not implemented on this system
2698
2699 *exists()*
2700exists({expr}) The result is a Number, which is non-zero if {expr} is
2701 defined, zero otherwise. The {expr} argument is a string,
2702 which contains one of these:
2703 &option-name Vim option (only checks if it exists,
2704 not if it really works)
2705 +option-name Vim option that works.
2706 $ENVNAME environment variable (could also be
2707 done by comparing with an empty
2708 string)
2709 *funcname built-in function (see |functions|)
2710 or user defined function (see
2711 |user-functions|).
2712 varname internal variable (see
Bram Moolenaar446cb832008-06-24 21:56:24 +00002713 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002714 for |curly-braces-names|, |Dictionary|
2715 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00002716 that evaluating an index may cause an
2717 error message for an invalid
2718 expression. E.g.: >
2719 :let l = [1, 2, 3]
2720 :echo exists("l[5]")
2721< 0 >
2722 :echo exists("l[xx]")
2723< E121: Undefined variable: xx
2724 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00002725 :cmdname Ex command: built-in command, user
2726 command or command modifier |:command|.
2727 Returns:
2728 1 for match with start of a command
2729 2 full match with a command
2730 3 matches several user commands
2731 To check for a supported command
2732 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00002733 :2match The |:2match| command.
2734 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002735 #event autocommand defined for this event
2736 #event#pattern autocommand defined for this event and
2737 pattern (the pattern is taken
2738 literally and compared to the
2739 autocommand patterns character by
2740 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002741 #group autocommand group exists
2742 #group#event autocommand defined for this group and
2743 event.
2744 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002745 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002746 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002747 ##event autocommand for this event is
2748 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002749 For checking for a supported feature use |has()|.
2750
2751 Examples: >
2752 exists("&shortname")
2753 exists("$HOSTNAME")
2754 exists("*strftime")
2755 exists("*s:MyFunc")
2756 exists("bufcount")
2757 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002758 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002759 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002760 exists("#filetypeindent")
2761 exists("#filetypeindent#FileType")
2762 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002763 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002764< There must be no space between the symbol (&/$/*/#) and the
2765 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002766 There must be no extra characters after the name, although in
2767 a few cases this is ignored. That may become more strict in
2768 the future, thus don't count on it!
2769 Working example: >
2770 exists(":make")
2771< NOT working example: >
2772 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00002773
2774< Note that the argument must be a string, not the name of the
2775 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002776 exists(bufcount)
2777< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00002778 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002779
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002780exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002781 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002782 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002783 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002784 Examples: >
2785 :echo exp(2)
2786< 7.389056 >
2787 :echo exp(-1)
2788< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02002789 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002790
2791
Bram Moolenaar84f72352012-03-11 15:57:40 +01002792expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002793 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01002794 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002795
Bram Moolenaar84f72352012-03-11 15:57:40 +01002796 If {list} is given and it is non-zero, a List will be returned.
2797 Otherwise the result is a String and when there are several
2798 matches, they are separated by <NL> characters. [Note: in
2799 version 5.0 a space was used, which caused problems when a
2800 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00002801
Bram Moolenaar446cb832008-06-24 21:56:24 +00002802 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02002803 for a non-existing file is not included, unless {expr} does
2804 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002805
2806 When {expr} starts with '%', '#' or '<', the expansion is done
2807 like for the |cmdline-special| variables with their associated
2808 modifiers. Here is a short overview:
2809
2810 % current file name
2811 # alternate file name
2812 #n alternate file name n
2813 <cfile> file name under the cursor
2814 <afile> autocmd file name
2815 <abuf> autocmd buffer number (as a String!)
2816 <amatch> autocmd matched name
2817 <sfile> sourced script file name
Bram Moolenaar81af9252010-12-10 20:35:50 +01002818 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00002819 <cword> word under the cursor
2820 <cWORD> WORD under the cursor
2821 <client> the {clientid} of the last received
2822 message |server2client()|
2823 Modifiers:
2824 :p expand to full path
2825 :h head (last path component removed)
2826 :t tail (last path component only)
2827 :r root (one extension removed)
2828 :e extension only
2829
2830 Example: >
2831 :let &tags = expand("%:p:h") . "/tags"
2832< Note that when expanding a string that starts with '%', '#' or
2833 '<', any following text is ignored. This does NOT work: >
2834 :let doesntwork = expand("%:h.bak")
2835< Use this: >
2836 :let doeswork = expand("%:h") . ".bak"
2837< Also note that expanding "<cfile>" and others only returns the
2838 referenced file name without further expansion. If "<cfile>"
2839 is "~/.cshrc", you need to do another expand() to have the
2840 "~/" expanded into the path of the home directory: >
2841 :echo expand(expand("<cfile>"))
2842<
2843 There cannot be white space between the variables and the
2844 following modifier. The |fnamemodify()| function can be used
2845 to modify normal file names.
2846
2847 When using '%' or '#', and the current or alternate file name
2848 is not defined, an empty string is used. Using "%:p" in a
2849 buffer with no name, results in the current directory, with a
2850 '/' added.
2851
2852 When {expr} does not start with '%', '#' or '<', it is
2853 expanded like a file name is expanded on the command line.
2854 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002855 {nosuf} argument is given and it is non-zero.
2856 Names for non-existing files are included. The "**" item can
2857 be used to search in a directory tree. For example, to find
2858 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00002859 :echo expand("**/README")
2860<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002861 Expand() can also be used to expand variables and environment
2862 variables that are only known in a shell. But this can be
Bram Moolenaar446cb832008-06-24 21:56:24 +00002863 slow, because a shell must be started. See |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002864 The expanded variable is still handled like a list of file
Bram Moolenaar446cb832008-06-24 21:56:24 +00002865 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002866 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2867 "$FOOBAR".
2868
2869 See |glob()| for finding existing files. See |system()| for
2870 getting the raw output of an external command.
2871
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002872extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002873 {expr1} and {expr2} must be both |Lists| or both
2874 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002875
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002876 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002877 If {expr3} is given insert the items of {expr2} before item
2878 {expr3} in {expr1}. When {expr3} is zero insert before the
2879 first item. When {expr3} is equal to len({expr1}) then
2880 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002881 Examples: >
2882 :echo sort(extend(mylist, [7, 5]))
2883 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00002884< When {expr1} is the same List as {expr2} then the number of
2885 items copied is equal to the original length of the List.
2886 E.g., when {expr3} is 1 you get N new copies of the first item
2887 (where N is the original length of the List).
2888 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002889 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002890 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002891<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002892 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002893 Add all entries from {expr2} to {expr1}.
2894 If a key exists in both {expr1} and {expr2} then {expr3} is
2895 used to decide what to do:
2896 {expr3} = "keep": keep the value of {expr1}
2897 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002898 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002899 When {expr3} is omitted then "force" is assumed.
2900
2901 {expr1} is changed when {expr2} is not empty. If necessary
2902 make a copy of {expr1} first.
2903 {expr2} remains unchanged.
2904 Returns {expr1}.
2905
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002906
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002907feedkeys({string} [, {mode}]) *feedkeys()*
2908 Characters in {string} are queued for processing as if they
Bram Moolenaar446cb832008-06-24 21:56:24 +00002909 come from a mapping or were typed by the user. They are added
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002910 to the end of the typeahead buffer, thus if a mapping is still
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002911 being executed these characters come after them.
2912 The function does not wait for processing of keys contained in
2913 {string}.
2914 To include special keys into {string}, use double-quotes
2915 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00002916 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002917 feedkeys('\<CR>') pushes 5 characters.
2918 If {mode} is absent, keys are remapped.
2919 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00002920 'm' Remap keys. This is default.
2921 'n' Do not remap keys.
2922 't' Handle keys as if typed; otherwise they are handled as
2923 if coming from a mapping. This matters for undo,
2924 opening folds, etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002925 Return value is always 0.
2926
Bram Moolenaar071d4272004-06-13 20:20:40 +00002927filereadable({file}) *filereadable()*
2928 The result is a Number, which is TRUE when a file with the
2929 name {file} exists, and can be read. If {file} doesn't exist,
2930 or is a directory, the result is FALSE. {file} is any
2931 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002932 If you don't care about the file being readable you can use
2933 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002934 *file_readable()*
2935 Obsolete name: file_readable().
2936
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002937
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002938filewritable({file}) *filewritable()*
2939 The result is a Number, which is 1 when a file with the
2940 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00002941 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002942 directory, and we can write to it, the result is 2.
2943
2944
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002945filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002946 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002947 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002948 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002949 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002950 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002951 Examples: >
2952 :call filter(mylist, 'v:val !~ "OLD"')
2953< Removes the items where "OLD" appears. >
2954 :call filter(mydict, 'v:key >= 8')
2955< Removes the items with a key below 8. >
2956 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002957< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002958
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002959 Note that {string} is the result of expression and is then
2960 used as an expression again. Often it is good to use a
2961 |literal-string| to avoid having to double backslashes.
2962
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002963 The operation is done in-place. If you want a |List| or
2964 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00002965 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002966
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002967< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00002968 When an error is encountered while evaluating {string} no
2969 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002970
2971
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002972finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00002973 Find directory {name} in {path}. Supports both downwards and
2974 upwards recursive directory searches. See |file-searching|
2975 for the syntax of {path}.
2976 Returns the path of the first found match. When the found
2977 directory is below the current directory a relative path is
2978 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002979 If {path} is omitted or empty then 'path' is used.
2980 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002981 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00002982 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002983 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02002984 {only available when compiled with the |+file_in_path|
2985 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002986
2987findfile({name}[, {path}[, {count}]]) *findfile()*
2988 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002989 Uses 'suffixesadd'.
2990 Example: >
2991 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002992< Searches from the directory of the current file upwards until
2993 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00002994
Bram Moolenaar446cb832008-06-24 21:56:24 +00002995float2nr({expr}) *float2nr()*
2996 Convert {expr} to a Number by omitting the part after the
2997 decimal point.
2998 {expr} must evaluate to a |Float| or a Number.
2999 When the value of {expr} is out of range for a |Number| the
3000 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
3001 in -0x80000000.
3002 Examples: >
3003 echo float2nr(3.95)
3004< 3 >
3005 echo float2nr(-23.45)
3006< -23 >
3007 echo float2nr(1.0e100)
3008< 2147483647 >
3009 echo float2nr(-1.0e150)
3010< -2147483647 >
3011 echo float2nr(1.0e-100)
3012< 0
3013 {only available when compiled with the |+float| feature}
3014
3015
3016floor({expr}) *floor()*
3017 Return the largest integral value less than or equal to
3018 {expr} as a |Float| (round down).
3019 {expr} must evaluate to a |Float| or a |Number|.
3020 Examples: >
3021 echo floor(1.856)
3022< 1.0 >
3023 echo floor(-5.456)
3024< -6.0 >
3025 echo floor(4.0)
3026< 4.0
3027 {only available when compiled with the |+float| feature}
3028
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003029
3030fmod({expr1}, {expr2}) *fmod()*
3031 Return the remainder of {expr1} / {expr2}, even if the
3032 division is not representable. Returns {expr1} - i * {expr2}
3033 for some integer i such that if {expr2} is non-zero, the
3034 result has the same sign as {expr1} and magnitude less than
3035 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003036 returned is zero. The value returned is a |Float|.
3037 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003038 Examples: >
3039 :echo fmod(12.33, 1.22)
3040< 0.13 >
3041 :echo fmod(-12.33, 1.22)
3042< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02003043 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003044
3045
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003046fnameescape({string}) *fnameescape()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003047 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003048 characters that have a special meaning, such as '%' and '|'
3049 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003050 For most systems the characters escaped are
3051 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3052 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003053 A leading '+' and '>' is also escaped (special after |:edit|
3054 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003055 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003056 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003057 :exe "edit " . fnameescape(fname)
3058< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003059 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003060
Bram Moolenaar071d4272004-06-13 20:20:40 +00003061fnamemodify({fname}, {mods}) *fnamemodify()*
3062 Modify file name {fname} according to {mods}. {mods} is a
3063 string of characters like it is used for file names on the
3064 command line. See |filename-modifiers|.
3065 Example: >
3066 :echo fnamemodify("main.c", ":p:h")
3067< results in: >
3068 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003069< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003070 |expand()| first then.
3071
3072foldclosed({lnum}) *foldclosed()*
3073 The result is a Number. If the line {lnum} is in a closed
3074 fold, the result is the number of the first line in that fold.
3075 If the line {lnum} is not in a closed fold, -1 is returned.
3076
3077foldclosedend({lnum}) *foldclosedend()*
3078 The result is a Number. If the line {lnum} is in a closed
3079 fold, the result is the number of the last line in that fold.
3080 If the line {lnum} is not in a closed fold, -1 is returned.
3081
3082foldlevel({lnum}) *foldlevel()*
3083 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003084 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003085 returned. If there is no fold at line {lnum}, zero is
3086 returned. It doesn't matter if the folds are open or closed.
3087 When used while updating folds (from 'foldexpr') -1 is
3088 returned for lines where folds are still to be updated and the
3089 foldlevel is unknown. As a special case the level of the
3090 previous line is usually available.
3091
3092 *foldtext()*
3093foldtext() Returns a String, to be displayed for a closed fold. This is
3094 the default function used for the 'foldtext' option and should
3095 only be called from evaluating 'foldtext'. It uses the
3096 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3097 The returned string looks like this: >
3098 +-- 45 lines: abcdef
Bram Moolenaar446cb832008-06-24 21:56:24 +00003099< The number of dashes depends on the foldlevel. The "45" is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003100 the number of lines in the fold. "abcdef" is the text in the
3101 first non-blank line of the fold. Leading white space, "//"
3102 or "/*" and the text from the 'foldmarker' and 'commentstring'
3103 options is removed.
3104 {not available when compiled without the |+folding| feature}
3105
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003106foldtextresult({lnum}) *foldtextresult()*
3107 Returns the text that is displayed for the closed fold at line
3108 {lnum}. Evaluates 'foldtext' in the appropriate context.
3109 When there is no closed fold at {lnum} an empty string is
3110 returned.
3111 {lnum} is used like with |getline()|. Thus "." is the current
3112 line, "'m" mark m, etc.
3113 Useful when exporting folded text, e.g., to HTML.
3114 {not available when compiled without the |+folding| feature}
3115
Bram Moolenaar071d4272004-06-13 20:20:40 +00003116 *foreground()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003117foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00003118 a client to a Vim server. |remote_send()|
3119 On Win32 systems this might not work, the OS does not always
3120 allow a window to bring itself to the foreground. Use
3121 |remote_foreground()| instead.
3122 {only in the Win32, Athena, Motif and GTK GUI versions and the
3123 Win32 console version}
3124
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003125
Bram Moolenaar13065c42005-01-08 16:08:21 +00003126function({name}) *function()* *E700*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003127 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003128 {name} can be a user defined function or an internal function.
3129
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003130
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003131garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003132 Cleanup unused |Lists| and |Dictionaries| that have circular
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003133 references. There is hardly ever a need to invoke this
3134 function, as it is automatically done when Vim runs out of
3135 memory or is waiting for the user to press a key after
3136 'updatetime'. Items without circular references are always
3137 freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003138 This is useful if you have deleted a very big |List| and/or
3139 |Dictionary| with circular references in a script that runs
3140 for a long time.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003141 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003142 collection will also be done when exiting Vim, if it wasn't
3143 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003144
Bram Moolenaar677ee682005-01-27 14:41:15 +00003145get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003146 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003147 available return {default}. Return zero when {default} is
3148 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003149get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003150 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003151 item is not available return {default}. Return zero when
3152 {default} is omitted.
3153
Bram Moolenaar45360022005-07-21 21:08:21 +00003154 *getbufline()*
3155getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003156 Return a |List| with the lines starting from {lnum} to {end}
3157 (inclusive) in the buffer {expr}. If {end} is omitted, a
3158 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003159
3160 For the use of {expr}, see |bufname()| above.
3161
Bram Moolenaar661b1822005-07-28 22:36:45 +00003162 For {lnum} and {end} "$" can be used for the last line of the
3163 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00003164
3165 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003166 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003167
3168 When {end} is greater than the number of lines in the buffer,
3169 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003170 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00003171 returned.
3172
Bram Moolenaar661b1822005-07-28 22:36:45 +00003173 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003174 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003175
3176 Example: >
3177 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003178
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003179getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003180 The result is the value of option or local buffer variable
3181 {varname} in buffer {expr}. Note that the name without "b:"
3182 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003183 When {varname} is empty returns a dictionary with all the
3184 buffer-local variables.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00003185 This also works for a global or buffer-local option, but it
3186 doesn't work for a global variable, window-local variable or
3187 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003188 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003189 When the buffer or variable doesn't exist {def} or an empty
3190 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003191 Examples: >
3192 :let bufmodified = getbufvar(1, "&mod")
3193 :echo "todo myvar = " . getbufvar("todo", "myvar")
3194<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003195getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00003196 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003197 If [expr] is omitted, wait until a character is available.
3198 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003199 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003200 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00003201 not consumed. Return zero if no character available.
3202
Bram Moolenaardfb18412013-12-11 18:53:29 +01003203 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaar91170f82006-05-05 21:15:17 +00003204 special key is returned. If it is an 8-bit character, the
3205 result is a number. Use nr2char() to convert it to a String.
3206 Otherwise a String is returned with the encoded character.
3207 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003208 (decimal: 128). This is the same value as the string
3209 "\<Key>", e.g., "\<Left>". The returned value is also a
3210 String when a modifier (shift, control, alt) was used that is
3211 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003212
Bram Moolenaardfb18412013-12-11 18:53:29 +01003213 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003214 one-byte character it is the character itself as a number.
3215 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003216
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003217 Use getcharmod() to obtain any additional modifiers.
3218
Bram Moolenaar219b8702006-11-01 14:32:36 +00003219 When the user clicks a mouse button, the mouse event will be
3220 returned. The position can then be found in |v:mouse_col|,
3221 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3222 mouse as it would normally happen: >
3223 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003224 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00003225 exe v:mouse_win . "wincmd w"
3226 exe v:mouse_lnum
3227 exe "normal " . v:mouse_col . "|"
3228 endif
3229<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003230 There is no prompt, you will somehow have to make clear to the
3231 user that a character has to be typed.
3232 There is no mapping for the character.
3233 Key codes are replaced, thus when the user presses the <Del>
3234 key you get the code for the <Del> key, not the raw character
3235 sequence. Examples: >
3236 getchar() == "\<Del>"
3237 getchar() == "\<S-Left>"
3238< This example redefines "f" to ignore case: >
3239 :nmap f :call FindChar()<CR>
3240 :function FindChar()
3241 : let c = nr2char(getchar())
3242 : while col('.') < col('$') - 1
3243 : normal l
3244 : if getline('.')[col('.') - 1] ==? c
3245 : break
3246 : endif
3247 : endwhile
3248 :endfunction
3249
3250getcharmod() *getcharmod()*
3251 The result is a Number which is the state of the modifiers for
3252 the last obtained character with getchar() or in another way.
3253 These values are added together:
3254 2 shift
3255 4 control
3256 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003257 16 meta (when it's different from ALT)
3258 32 mouse double click
3259 64 mouse triple click
3260 96 mouse quadruple click (== 32 + 64)
3261 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003262 Only the modifiers that have not been included in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003263 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003264 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003265
Bram Moolenaar071d4272004-06-13 20:20:40 +00003266getcmdline() *getcmdline()*
3267 Return the current command-line. Only works when the command
3268 line is being edited, thus requires use of |c_CTRL-\_e| or
3269 |c_CTRL-R_=|.
3270 Example: >
3271 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003272< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003273
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003274getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003275 Return the position of the cursor in the command line as a
3276 byte count. The first column is 1.
3277 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003278 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3279 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003280 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3281
3282getcmdtype() *getcmdtype()*
3283 Return the current command-line type. Possible return values
3284 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00003285 : normal Ex command
3286 > debug mode command |debug-mode|
3287 / forward search command
3288 ? backward search command
3289 @ |input()| command
3290 - |:insert| or |:append| command
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003291 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003292 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3293 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003294 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003295
3296 *getcwd()*
3297getcwd() The result is a String, which is the name of the current
3298 working directory.
3299
3300getfsize({fname}) *getfsize()*
3301 The result is a Number, which is the size in bytes of the
3302 given file {fname}.
3303 If {fname} is a directory, 0 is returned.
3304 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00003305 If the size of {fname} is too big to fit in a Number then -2
3306 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003307
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003308getfontname([{name}]) *getfontname()*
3309 Without an argument returns the name of the normal font being
3310 used. Like what is used for the Normal highlight group
3311 |hl-Normal|.
3312 With an argument a check is done whether {name} is a valid
3313 font name. If not then an empty string is returned.
3314 Otherwise the actual font name is returned, or {name} if the
3315 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00003316 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003317 gvimrc file. Use the |GUIEnter| autocommand to use this
3318 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003319 Note that the GTK 2 GUI accepts any font name, thus checking
3320 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003321
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003322getfperm({fname}) *getfperm()*
3323 The result is a String, which is the read, write, and execute
3324 permissions of the given file {fname}.
3325 If {fname} does not exist or its directory cannot be read, an
3326 empty string is returned.
3327 The result is of the form "rwxrwxrwx", where each group of
3328 "rwx" flags represent, in turn, the permissions of the owner
3329 of the file, the group the file belongs to, and other users.
3330 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02003331 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003332 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02003333 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003334< This will hopefully (from a security point of view) display
3335 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003336
Bram Moolenaar071d4272004-06-13 20:20:40 +00003337getftime({fname}) *getftime()*
3338 The result is a Number, which is the last modification time of
3339 the given file {fname}. The value is measured as seconds
3340 since 1st Jan 1970, and may be passed to strftime(). See also
3341 |localtime()| and |strftime()|.
3342 If the file {fname} can't be found -1 is returned.
3343
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003344getftype({fname}) *getftype()*
3345 The result is a String, which is a description of the kind of
3346 file of the given file {fname}.
3347 If {fname} does not exist an empty string is returned.
3348 Here is a table over different kinds of files and their
3349 results:
3350 Normal file "file"
3351 Directory "dir"
3352 Symbolic link "link"
3353 Block device "bdev"
3354 Character device "cdev"
3355 Socket "socket"
3356 FIFO "fifo"
3357 All other "other"
3358 Example: >
3359 getftype("/home")
3360< Note that a type such as "link" will only be returned on
3361 systems that support it. On some systems only "dir" and
3362 "file" are returned.
3363
Bram Moolenaar071d4272004-06-13 20:20:40 +00003364 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003365getline({lnum} [, {end}])
3366 Without {end} the result is a String, which is line {lnum}
3367 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003368 getline(1)
3369< When {lnum} is a String that doesn't start with a
3370 digit, line() is called to translate the String into a Number.
3371 To get the line under the cursor: >
3372 getline(".")
3373< When {lnum} is smaller than 1 or bigger than the number of
3374 lines in the buffer, an empty string is returned.
3375
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003376 When {end} is given the result is a |List| where each item is
3377 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003378 including line {end}.
3379 {end} is used in the same way as {lnum}.
3380 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003381 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003382 Example: >
3383 :let start = line('.')
3384 :let end = search("^$") - 1
3385 :let lines = getline(start, end)
3386
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003387< To get lines from another buffer see |getbufline()|
3388
Bram Moolenaar17c7c012006-01-26 22:25:15 +00003389getloclist({nr}) *getloclist()*
3390 Returns a list with all the entries in the location list for
3391 window {nr}. When {nr} is zero the current window is used.
3392 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00003393 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003394 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003395
Bram Moolenaar6ee10162007-07-26 20:58:42 +00003396getmatches() *getmatches()*
3397 Returns a |List| with all matches previously defined by
3398 |matchadd()| and the |:match| commands. |getmatches()| is
3399 useful in combination with |setmatches()|, as |setmatches()|
3400 can restore a list of matches saved by |getmatches()|.
3401 Example: >
3402 :echo getmatches()
3403< [{'group': 'MyGroup1', 'pattern': 'TODO',
3404 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3405 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3406 :let m = getmatches()
3407 :call clearmatches()
3408 :echo getmatches()
3409< [] >
3410 :call setmatches(m)
3411 :echo getmatches()
3412< [{'group': 'MyGroup1', 'pattern': 'TODO',
3413 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3414 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3415 :unlet m
3416<
3417
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003418getqflist() *getqflist()*
3419 Returns a list with all the current quickfix errors. Each
3420 list item is a dictionary with these entries:
3421 bufnr number of buffer that has the file name, use
3422 bufname() to get the name
3423 lnum line number in the buffer (first line is 1)
3424 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00003425 vcol non-zero: "col" is visual column
3426 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003427 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00003428 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003429 text description of the error
3430 type type of the error, 'E', '1', etc.
3431 valid non-zero: recognized error message
3432
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00003433 When there is no error list or it's empty an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00003434 returned. Quickfix list entries with non-existing buffer
3435 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00003436
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003437 Useful application: Find pattern matches in multiple files and
3438 do something with them: >
3439 :vimgrep /theword/jg *.c
3440 :for d in getqflist()
3441 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3442 :endfor
3443
3444
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003445getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003446 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003447 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003448 :let cliptext = getreg('*')
3449< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003450 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003451 getreg('=', 1) returns the expression itself, so that it can
3452 be restored with |setreg()|. For other registers the extra
3453 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003454 If {regname} is not specified, |v:register| is used.
3455
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003456
Bram Moolenaar071d4272004-06-13 20:20:40 +00003457getregtype([{regname}]) *getregtype()*
3458 The result is a String, which is type of register {regname}.
3459 The value will be one of:
3460 "v" for |characterwise| text
3461 "V" for |linewise| text
3462 "<CTRL-V>{width}" for |blockwise-visual| text
3463 0 for an empty or unknown register
3464 <CTRL-V> is one character with value 0x16.
3465 If {regname} is not specified, |v:register| is used.
3466
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003467gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02003468 Get the value of a tab-local variable {varname} in tab page
3469 {tabnr}. |t:var|
3470 Tabs are numbered starting with one.
3471 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003472 When the tab or variable doesn't exist {def} or an empty
3473 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02003474
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003475gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003476 Get the value of window-local variable {varname} in window
3477 {winnr} in tab page {tabnr}.
3478 When {varname} starts with "&" get the value of a window-local
3479 option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003480 When {varname} is empty a dictionary with all window-local
3481 variables is returned.
3482 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003483 Tabs are numbered starting with one. For the current tabpage
3484 use |getwinvar()|.
3485 When {winnr} is zero the current window is used.
3486 This also works for a global option, buffer-local option and
3487 window-local option, but it doesn't work for a global variable
3488 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003489 When the tab, window or variable doesn't exist {def} or an
3490 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003491 Examples: >
3492 :let list_is_on = gettabwinvar(1, 2, '&list')
3493 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003494<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003495 *getwinposx()*
3496getwinposx() The result is a Number, which is the X coordinate in pixels of
3497 the left hand side of the GUI Vim window. The result will be
3498 -1 if the information is not available.
3499
3500 *getwinposy()*
3501getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar446cb832008-06-24 21:56:24 +00003502 the top of the GUI Vim window. The result will be -1 if the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003503 information is not available.
3504
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003505getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003506 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003507 Examples: >
3508 :let list_is_on = getwinvar(2, '&list')
3509 :echo "myvar = " . getwinvar(1, 'myvar')
3510<
Bram Moolenaar84f72352012-03-11 15:57:40 +01003511glob({expr} [, {nosuf} [, {list}]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003512 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003513 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003514
3515 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003516 the 'suffixes' and 'wildignore' options apply: Names matching
3517 one of the patterns in 'wildignore' will be skipped and
3518 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01003519 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003520
3521 When {list} is present and it is non-zero the result is a List
3522 with all matching files. The advantage of using a List is,
3523 you also get filenames containing newlines correctly.
3524 Otherwise the result is a String and when there are several
3525 matches, they are separated by <NL> characters.
3526
3527 If the expansion fails, the result is an empty String or List.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02003528 A name for a non-existing file is not included. A symbolic
3529 link is only included if it points to an existing file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003530
3531 For most systems backticks can be used to get files names from
3532 any external command. Example: >
3533 :let tagfiles = glob("`find . -name tags -print`")
3534 :let &tags = substitute(tagfiles, "\n", ",", "g")
3535< The result of the program inside the backticks should be one
Bram Moolenaar446cb832008-06-24 21:56:24 +00003536 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003537
3538 See |expand()| for expanding special Vim variables. See
3539 |system()| for getting the raw output of an external command.
3540
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003541globpath({path}, {expr} [, {flag}]) *globpath()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003542 Perform glob() on all directories in {path} and concatenate
3543 the results. Example: >
3544 :echo globpath(&rtp, "syntax/c.vim")
3545< {path} is a comma-separated list of directory names. Each
3546 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003547 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003548 To add a comma inside a directory name escape it with a
3549 backslash. Note that on MS-Windows a directory may have a
3550 trailing backslash, remove it if you put a comma after it.
3551 If the expansion fails for one of the directories, there is no
3552 error message.
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003553 Unless the optional {flag} argument is given and is non-zero,
3554 the 'suffixes' and 'wildignore' options apply: Names matching
3555 one of the patterns in 'wildignore' will be skipped and
3556 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003557
Bram Moolenaar02743632005-07-25 20:42:36 +00003558 The "**" item can be used to search in a directory tree.
3559 For example, to find all "README.txt" files in the directories
3560 in 'runtimepath' and below: >
3561 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00003562< Upwards search and limiting the depth of "**" is not
3563 supported, thus using 'path' will not always work properly.
3564
Bram Moolenaar071d4272004-06-13 20:20:40 +00003565 *has()*
3566has({feature}) The result is a Number, which is 1 if the feature {feature} is
3567 supported, zero otherwise. The {feature} argument is a
3568 string. See |feature-list| below.
3569 Also see |exists()|.
3570
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003571
3572has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003573 The result is a Number, which is 1 if |Dictionary| {dict} has
3574 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003575
Bram Moolenaard267b9c2007-04-26 15:06:45 +00003576haslocaldir() *haslocaldir()*
3577 The result is a Number, which is 1 when the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00003578 window has set a local path via |:lcd|, and 0 otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003579
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003580hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003581 The result is a Number, which is 1 if there is a mapping that
3582 contains {what} in somewhere in the rhs (what it is mapped to)
3583 and this mapping exists in one of the modes indicated by
3584 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003585 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00003586 instead of mappings. Don't forget to specify Insert and/or
3587 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003588 Both the global mappings and the mappings local to the current
3589 buffer are checked for a match.
3590 If no matching mapping is found 0 is returned.
3591 The following characters are recognized in {mode}:
3592 n Normal mode
3593 v Visual mode
3594 o Operator-pending mode
3595 i Insert mode
3596 l Language-Argument ("r", "f", "t", etc.)
3597 c Command-line mode
3598 When {mode} is omitted, "nvo" is used.
3599
3600 This function is useful to check if a mapping already exists
Bram Moolenaar446cb832008-06-24 21:56:24 +00003601 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003602 :if !hasmapto('\ABCdoit')
3603 : map <Leader>d \ABCdoit
3604 :endif
3605< This installs the mapping to "\ABCdoit" only if there isn't
3606 already a mapping to "\ABCdoit".
3607
3608histadd({history}, {item}) *histadd()*
3609 Add the String {item} to the history {history} which can be
3610 one of: *hist-names*
3611 "cmd" or ":" command line history
3612 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00003613 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00003614 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02003615 "debug" or ">" debug command history
3616 The {history} string does not need to be the whole name, one
3617 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003618 If {item} does already exist in the history, it will be
3619 shifted to become the newest entry.
3620 The result is a Number: 1 if the operation was successful,
3621 otherwise 0 is returned.
3622
3623 Example: >
3624 :call histadd("input", strftime("%Y %b %d"))
3625 :let date=input("Enter date: ")
3626< This function is not available in the |sandbox|.
3627
3628histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003629 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003630 for the possible values of {history}.
3631
Bram Moolenaarc236c162008-07-13 17:41:49 +00003632 If the parameter {item} evaluates to a String, it is used as a
3633 regular expression. All entries matching that expression will
3634 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003635 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003636 If {item} evaluates to a Number, it will be interpreted as
3637 an index, see |:history-indexing|. The respective entry will
3638 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003639
3640 The result is a Number: 1 for a successful operation,
3641 otherwise 0 is returned.
3642
3643 Examples:
3644 Clear expression register history: >
3645 :call histdel("expr")
3646<
3647 Remove all entries starting with "*" from the search history: >
3648 :call histdel("/", '^\*')
3649<
3650 The following three are equivalent: >
3651 :call histdel("search", histnr("search"))
3652 :call histdel("search", -1)
3653 :call histdel("search", '^'.histget("search", -1).'$')
3654<
3655 To delete the last search pattern and use the last-but-one for
3656 the "n" command and 'hlsearch': >
3657 :call histdel("search", -1)
3658 :let @/ = histget("search", -1)
3659
3660histget({history} [, {index}]) *histget()*
3661 The result is a String, the entry with Number {index} from
3662 {history}. See |hist-names| for the possible values of
3663 {history}, and |:history-indexing| for {index}. If there is
3664 no such entry, an empty String is returned. When {index} is
3665 omitted, the most recent item from the history is used.
3666
3667 Examples:
3668 Redo the second last search from history. >
3669 :execute '/' . histget("search", -2)
3670
3671< Define an Ex command ":H {num}" that supports re-execution of
3672 the {num}th entry from the output of |:history|. >
3673 :command -nargs=1 H execute histget("cmd", 0+<args>)
3674<
3675histnr({history}) *histnr()*
3676 The result is the Number of the current entry in {history}.
3677 See |hist-names| for the possible values of {history}.
3678 If an error occurred, -1 is returned.
3679
3680 Example: >
3681 :let inp_index = histnr("expr")
3682<
3683hlexists({name}) *hlexists()*
3684 The result is a Number, which is non-zero if a highlight group
3685 called {name} exists. This is when the group has been
3686 defined in some way. Not necessarily when highlighting has
3687 been defined for it, it may also have been used for a syntax
3688 item.
3689 *highlight_exists()*
3690 Obsolete name: highlight_exists().
3691
3692 *hlID()*
3693hlID({name}) The result is a Number, which is the ID of the highlight group
3694 with name {name}. When the highlight group doesn't exist,
3695 zero is returned.
3696 This can be used to retrieve information about the highlight
Bram Moolenaar446cb832008-06-24 21:56:24 +00003697 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003698 "Comment" group: >
3699 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3700< *highlightID()*
3701 Obsolete name: highlightID().
3702
3703hostname() *hostname()*
3704 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003705 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00003706 256 characters long are truncated.
3707
3708iconv({expr}, {from}, {to}) *iconv()*
3709 The result is a String, which is the text {expr} converted
3710 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003711 When the conversion completely fails an empty string is
3712 returned. When some characters could not be converted they
3713 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003714 The encoding names are whatever the iconv() library function
3715 can accept, see ":!man 3 iconv".
3716 Most conversions require Vim to be compiled with the |+iconv|
3717 feature. Otherwise only UTF-8 to latin1 conversion and back
3718 can be done.
3719 This can be used to display messages with special characters,
3720 no matter what 'encoding' is set to. Write the message in
3721 UTF-8 and use: >
3722 echo iconv(utf8_str, "utf-8", &enc)
3723< Note that Vim uses UTF-8 for all Unicode encodings, conversion
3724 from/to UCS-2 is automatically changed to use UTF-8. You
3725 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003726 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003727
3728 *indent()*
3729indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3730 current buffer. The indent is counted in spaces, the value
3731 of 'tabstop' is relevant. {lnum} is used just like in
3732 |getline()|.
3733 When {lnum} is invalid -1 is returned.
3734
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003735
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003736index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003737 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003738 value equal to {expr}. There is no automatic conversion, so
3739 the String "4" is different from the Number 4. And the number
3740 4 is different from the Float 4.0. The value of 'ignorecase'
3741 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00003742 If {start} is given then start looking at the item with index
3743 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003744 When {ic} is given and it is non-zero, ignore case. Otherwise
3745 case must match.
3746 -1 is returned when {expr} is not found in {list}.
3747 Example: >
3748 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003749 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003750
3751
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003752input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003753 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003754 the command-line. The {prompt} argument is either a prompt
3755 string, or a blank string (for no prompt). A '\n' can be used
3756 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003757 The highlighting set with |:echohl| is used for the prompt.
3758 The input is entered just like a command-line, with the same
Bram Moolenaar446cb832008-06-24 21:56:24 +00003759 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003760 for lines typed for input().
3761 Example: >
3762 :if input("Coffee or beer? ") == "beer"
3763 : echo "Cheers!"
3764 :endif
3765<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003766 If the optional {text} argument is present and not empty, this
3767 is used for the default reply, as if the user typed this.
3768 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003769 :let color = input("Color? ", "white")
3770
3771< The optional {completion} argument specifies the type of
3772 completion supported for the input. Without it completion is
Bram Moolenaar446cb832008-06-24 21:56:24 +00003773 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003774 that can be supplied to a user-defined command using the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003775 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003776 more information. Example: >
3777 let fname = input("File: ", "", "file")
3778<
3779 NOTE: This function must not be used in a startup file, for
3780 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003781 Note: When input() is called from within a mapping it will
3782 consume remaining characters from that mapping, because a
3783 mapping is handled like the characters were typed.
3784 Use |inputsave()| before input() and |inputrestore()|
3785 after input() to avoid that. Another solution is to avoid
3786 that further characters follow in the mapping, e.g., by using
3787 |:execute| or |:normal|.
3788
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003789 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003790 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3791 :function GetFoo()
3792 : call inputsave()
3793 : let g:Foo = input("enter search pattern: ")
3794 : call inputrestore()
3795 :endfunction
3796
3797inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003798 Like |input()|, but when the GUI is running and text dialogs
3799 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003800 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02003801 :let n = inputdialog("value for shiftwidth", shiftwidth())
3802 :if n != ""
3803 : let &sw = n
3804 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00003805< When the dialog is cancelled {cancelreturn} is returned. When
3806 omitted an empty string is returned.
3807 Hitting <Enter> works like pressing the OK button. Hitting
3808 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003809 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003810
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003811inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003812 {textlist} must be a |List| of strings. This |List| is
3813 displayed, one string per line. The user will be prompted to
3814 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003815 The user can also select an item by clicking on it with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003816 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003817 above the first item a negative number is returned. When
3818 clicking on the prompt one more than the length of {textlist}
3819 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003820 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +00003821 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003822 the start of the string. And put a prompt in the first item.
3823 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003824 let color = inputlist(['Select color:', '1. red',
3825 \ '2. green', '3. blue'])
3826
Bram Moolenaar071d4272004-06-13 20:20:40 +00003827inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003828 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003829 Should be called the same number of times inputsave() is
3830 called. Calling it more often is harmless though.
3831 Returns 1 when there is nothing to restore, 0 otherwise.
3832
3833inputsave() *inputsave()*
3834 Preserve typeahead (also from mappings) and clear it, so that
3835 a following prompt gets input from the user. Should be
3836 followed by a matching inputrestore() after the prompt. Can
3837 be used several times, in which case there must be just as
3838 many inputrestore() calls.
3839 Returns 1 when out of memory, 0 otherwise.
3840
3841inputsecret({prompt} [, {text}]) *inputsecret()*
3842 This function acts much like the |input()| function with but
3843 two exceptions:
3844 a) the user's response will be displayed as a sequence of
3845 asterisks ("*") thereby keeping the entry secret, and
3846 b) the user's response will not be recorded on the input
3847 |history| stack.
3848 The result is a String, which is whatever the user actually
3849 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003850 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003851
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003852insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003853 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003854 If {idx} is specified insert {item} before the item with index
Bram Moolenaar446cb832008-06-24 21:56:24 +00003855 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003856 like omitting {idx}. A negative {idx} is also possible, see
3857 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003858 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003859 :let mylist = insert([2, 3, 5], 1)
3860 :call insert(mylist, 4, -1)
3861 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003862< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003863 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003864 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003865
Bram Moolenaard6e256c2011-12-14 15:32:50 +01003866invert({expr}) *invert()*
3867 Bitwise invert. The argument is converted to a number. A
3868 List, Dict or Float argument causes an error. Example: >
3869 :let bits = invert(bits)
3870
Bram Moolenaar071d4272004-06-13 20:20:40 +00003871isdirectory({directory}) *isdirectory()*
3872 The result is a Number, which is non-zero when a directory
3873 with the name {directory} exists. If {directory} doesn't
3874 exist, or isn't a directory, the result is FALSE. {directory}
3875 is any expression, which is used as a String.
3876
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003877islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003878 The result is a Number, which is non-zero when {expr} is the
3879 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003880 {expr} must be the name of a variable, |List| item or
3881 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003882 :let alist = [0, ['a', 'b'], 2, 3]
3883 :lockvar 1 alist
3884 :echo islocked('alist') " 1
3885 :echo islocked('alist[1]') " 0
3886
3887< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003888 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003889
Bram Moolenaar677ee682005-01-27 14:41:15 +00003890items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003891 Return a |List| with all the key-value pairs of {dict}. Each
3892 |List| item is a list with two items: the key of a {dict}
3893 entry and the value of this entry. The |List| is in arbitrary
3894 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003895
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003896
3897join({list} [, {sep}]) *join()*
3898 Join the items in {list} together into one String.
3899 When {sep} is specified it is put in between the items. If
3900 {sep} is omitted a single space is used.
3901 Note that {sep} is not added at the end. You might want to
3902 add it there too: >
3903 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003904< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003905 converted into a string like with |string()|.
3906 The opposite function is |split()|.
3907
Bram Moolenaard8b02732005-01-14 21:48:43 +00003908keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003909 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00003910 arbitrary order.
3911
Bram Moolenaar13065c42005-01-08 16:08:21 +00003912 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003913len({expr}) The result is a Number, which is the length of the argument.
3914 When {expr} is a String or a Number the length in bytes is
3915 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003916 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003917 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003918 When {expr} is a |Dictionary| the number of entries in the
3919 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003920 Otherwise an error is given.
3921
Bram Moolenaar071d4272004-06-13 20:20:40 +00003922 *libcall()* *E364* *E368*
3923libcall({libname}, {funcname}, {argument})
3924 Call function {funcname} in the run-time library {libname}
3925 with single argument {argument}.
3926 This is useful to call functions in a library that you
3927 especially made to be used with Vim. Since only one argument
3928 is possible, calling standard library functions is rather
3929 limited.
3930 The result is the String returned by the function. If the
3931 function returns NULL, this will appear as an empty string ""
3932 to Vim.
3933 If the function returns a number, use libcallnr()!
3934 If {argument} is a number, it is passed to the function as an
3935 int; if {argument} is a string, it is passed as a
3936 null-terminated string.
3937 This function will fail in |restricted-mode|.
3938
3939 libcall() allows you to write your own 'plug-in' extensions to
3940 Vim without having to recompile the program. It is NOT a
3941 means to call system functions! If you try to do so Vim will
3942 very probably crash.
3943
3944 For Win32, the functions you write must be placed in a DLL
3945 and use the normal C calling convention (NOT Pascal which is
3946 used in Windows System DLLs). The function must take exactly
3947 one parameter, either a character pointer or a long integer,
3948 and must return a character pointer or NULL. The character
3949 pointer returned must point to memory that will remain valid
3950 after the function has returned (e.g. in static data in the
3951 DLL). If it points to allocated memory, that memory will
3952 leak away. Using a static buffer in the function should work,
3953 it's then freed when the DLL is unloaded.
3954
3955 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00003956 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003957 because Vim thinks it's a pointer.
3958 For Win32 systems, {libname} should be the filename of the DLL
3959 without the ".DLL" suffix. A full path is only required if
3960 the DLL is not in the usual places.
3961 For Unix: When compiling your own plugins, remember that the
3962 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003963 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003964 feature is present}
3965 Examples: >
3966 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003967<
3968 *libcallnr()*
3969libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003970 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00003971 int instead of a string.
3972 {only in Win32 on some Unix versions, when the |+libcall|
3973 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003974 Examples: >
3975 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003976 :call libcallnr("libc.so", "printf", "Hello World!\n")
3977 :call libcallnr("libc.so", "sleep", 10)
3978<
3979 *line()*
3980line({expr}) The result is a Number, which is the line number of the file
3981 position given with {expr}. The accepted positions are:
3982 . the cursor position
3983 $ the last line in the current buffer
3984 'x position of mark x (if the mark is not set, 0 is
3985 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00003986 w0 first line visible in current window
3987 w$ last line visible in current window
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00003988 v In Visual mode: the start of the Visual area (the
3989 cursor is the end). When not in Visual mode
3990 returns the cursor position. Differs from |'<| in
3991 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003992 Note that a mark in another file can be used. The line number
3993 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003994 To get the column number use |col()|. To get both use
3995 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003996 Examples: >
3997 line(".") line number of the cursor
3998 line("'t") line number of mark t
3999 line("'" . marker) line number of mark marker
4000< *last-position-jump*
4001 This autocommand jumps to the last known position in a file
4002 just after opening it, if the '" mark is set: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004003 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004004
Bram Moolenaar071d4272004-06-13 20:20:40 +00004005line2byte({lnum}) *line2byte()*
4006 Return the byte count from the start of the buffer for line
4007 {lnum}. This includes the end-of-line character, depending on
4008 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004009 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004010 This can also be used to get the byte count for the line just
4011 below the last line: >
4012 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004013< This is the buffer size plus one. If 'fileencoding' is empty
4014 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004015 When {lnum} is invalid, or the |+byte_offset| feature has been
4016 disabled at compile time, -1 is returned.
4017 Also see |byte2line()|, |go| and |:goto|.
4018
4019lispindent({lnum}) *lispindent()*
4020 Get the amount of indent for line {lnum} according the lisp
4021 indenting rules, as with 'lisp'.
4022 The indent is counted in spaces, the value of 'tabstop' is
4023 relevant. {lnum} is used just like in |getline()|.
4024 When {lnum} is invalid or Vim was not compiled the
4025 |+lispindent| feature, -1 is returned.
4026
4027localtime() *localtime()*
4028 Return the current time, measured as seconds since 1st Jan
4029 1970. See also |strftime()| and |getftime()|.
4030
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004031
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004032log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004033 Return the natural logarithm (base e) of {expr} as a |Float|.
4034 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004035 (0, inf].
4036 Examples: >
4037 :echo log(10)
4038< 2.302585 >
4039 :echo log(exp(5))
4040< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02004041 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004042
4043
Bram Moolenaar446cb832008-06-24 21:56:24 +00004044log10({expr}) *log10()*
4045 Return the logarithm of Float {expr} to base 10 as a |Float|.
4046 {expr} must evaluate to a |Float| or a |Number|.
4047 Examples: >
4048 :echo log10(1000)
4049< 3.0 >
4050 :echo log10(0.01)
4051< -2.0
4052 {only available when compiled with the |+float| feature}
4053
Bram Moolenaard38b0552012-04-25 19:07:41 +02004054luaeval({expr}[, {expr}]) *luaeval()*
4055 Evaluate Lua expression {expr} and return its result converted
4056 to Vim data structures. Second {expr} may hold additional
4057 argument accessible as _A inside first {expr}.
4058 Strings are returned as they are.
4059 Boolean objects are converted to numbers.
4060 Numbers are converted to |Float| values if vim was compiled
4061 with |+float| and to numbers otherwise.
4062 Dictionaries and lists obtained by vim.eval() are returned
4063 as-is.
4064 Other objects are returned as zero without any errors.
4065 See |lua-luaeval| for more details.
4066 {only available when compiled with the |+lua| feature}
4067
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004068map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004069 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004070 Replace each item in {expr} with the result of evaluating
4071 {string}.
4072 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar627b1d32009-11-17 11:20:35 +00004073 For a |Dictionary| |v:key| has the key of the current item
4074 and for a |List| |v:key| has the index of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004075 Example: >
4076 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004077< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004078
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004079 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004080 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004081 |literal-string| to avoid having to double backslashes. You
4082 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004083
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004084 The operation is done in-place. If you want a |List| or
4085 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02004086 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004087
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004088< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004089 When an error is encountered while evaluating {string} no
4090 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004091
4092
Bram Moolenaarbd743252010-10-20 21:23:33 +02004093maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
4094 When {dict} is omitted or zero: Return the rhs of mapping
4095 {name} in mode {mode}. The returned String has special
4096 characters translated like in the output of the ":map" command
4097 listing.
4098
4099 When there is no mapping for {name}, an empty String is
4100 returned.
4101
4102 The {name} can have special key names, like in the ":map"
4103 command.
4104
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004105 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004106 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02004107 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004108 "o" Operator-pending
4109 "i" Insert
4110 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02004111 "s" Select
4112 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00004113 "l" langmap |language-mapping|
4114 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004115 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004116
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004117 When {abbr} is there and it is non-zero use abbreviations
4118 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004119
4120 When {dict} is there and it is non-zero return a dictionary
4121 containing all the information of the mapping with the
4122 following items:
4123 "lhs" The {lhs} of the mapping.
4124 "rhs" The {rhs} of the mapping as typed.
4125 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02004126 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004127 "expr" 1 for an expression mapping (|:map-<expr>|).
4128 "buffer" 1 for a buffer local mapping (|:map-local|).
4129 "mode" Modes for which the mapping is defined. In
4130 addition to the modes mentioned above, these
4131 characters will be used:
4132 " " Normal, Visual and Operator-pending
4133 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01004134 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02004135 "sid" The script local ID, used for <sid> mappings
4136 (|<SID>|).
Bram Moolenaardfb18412013-12-11 18:53:29 +01004137 "nowait" Do not wait for other, longer mappings.
4138 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02004139
Bram Moolenaar071d4272004-06-13 20:20:40 +00004140 The mappings local to the current buffer are checked first,
4141 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00004142 This function can be used to map a key even when it's already
4143 mapped, and have it do the original mapping too. Sketch: >
4144 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
4145
Bram Moolenaar071d4272004-06-13 20:20:40 +00004146
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004147mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004148 Check if there is a mapping that matches with {name} in mode
4149 {mode}. See |maparg()| for {mode} and special names in
4150 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004151 When {abbr} is there and it is non-zero use abbreviations
4152 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004153 A match happens with a mapping that starts with {name} and
4154 with a mapping which is equal to the start of {name}.
4155
Bram Moolenaar446cb832008-06-24 21:56:24 +00004156 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004157 mapcheck("a") yes yes yes
4158 mapcheck("abc") yes yes yes
4159 mapcheck("ax") yes no no
4160 mapcheck("b") no no no
4161
4162 The difference with maparg() is that mapcheck() finds a
4163 mapping that matches with {name}, while maparg() only finds a
4164 mapping for {name} exactly.
4165 When there is no mapping that starts with {name}, an empty
4166 String is returned. If there is one, the rhs of that mapping
4167 is returned. If there are several mappings that start with
4168 {name}, the rhs of one of them is returned.
4169 The mappings local to the current buffer are checked first,
4170 then the global mappings.
4171 This function can be used to check if a mapping can be added
4172 without being ambiguous. Example: >
4173 :if mapcheck("_vv") == ""
4174 : map _vv :set guifont=7x13<CR>
4175 :endif
4176< This avoids adding the "_vv" mapping when there already is a
4177 mapping for "_v" or for "_vvv".
4178
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004179match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004180 When {expr} is a |List| then this returns the index of the
4181 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004182 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004183 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004184 Number, which gives the index (byte offset) in {expr} where
4185 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004186 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004187 If there is no match -1 is returned.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02004188 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004189 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004190 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004191 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004192< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00004193 *strpbrk()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004194 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00004195 :let sepidx = match(line, '[.,;: \t]')
4196< *strcasestr()*
4197 Vim doesn't have a strcasestr() function. But you can add
4198 "\c" to the pattern to ignore case: >
4199 :let idx = match(haystack, '\cneedle')
4200<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004201 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004202 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004203 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004204 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004205 :echo match("testing", "ing", 2)
4206< result is again "4". >
4207 :echo match("testing", "ing", 4)
4208< result is again "4". >
4209 :echo match("testing", "t", 2)
4210< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004211 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00004212 {start} bytes later, thus "^" will match at {start}. Except
4213 when {count} is given, then it's like matches before the
4214 {start} byte are ignored (this is a bit complicated to keep it
4215 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004216 For a String, if {start} < 0, it will be set to 0. For a list
4217 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004218 If {start} is out of range ({start} > strlen({expr}) for a
4219 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004220
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004221 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004222 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004223 character further. Thus this example results in 1: >
4224 echo match("testing", "..", 0, 2)
4225< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004226 Note that when {count} is added the way {start} works changes,
4227 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004228
Bram Moolenaar071d4272004-06-13 20:20:40 +00004229 See |pattern| for the patterns that are accepted.
4230 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar446cb832008-06-24 21:56:24 +00004231 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00004232 done like 'magic' is set and 'cpoptions' is empty.
4233
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004234 *matchadd()* *E798* *E799* *E801*
4235matchadd({group}, {pattern}[, {priority}[, {id}]])
4236 Defines a pattern to be highlighted in the current window (a
4237 "match"). It will be highlighted with {group}. Returns an
4238 identification number (ID), which can be used to delete the
4239 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01004240 Matching is case sensitive and magic, unless case sensitivity
4241 or magicness are explicitly overridden in {pattern}. The
4242 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004243
4244 The optional {priority} argument assigns a priority to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004245 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004246 highlighting overrule that of a match with a lower priority.
4247 A priority is specified as an integer (negative numbers are no
4248 exception). If the {priority} argument is not specified, the
4249 default priority is 10. The priority of 'hlsearch' is zero,
4250 hence all matches with a priority greater than zero will
4251 overrule it. Syntax highlighting (see 'syntax') is a separate
4252 mechanism, and regardless of the chosen priority a match will
4253 always overrule syntax highlighting.
4254
4255 The optional {id} argument allows the request for a specific
4256 match ID. If a specified ID is already taken, an error
4257 message will appear and the match will not be added. An ID
4258 is specified as a positive integer (zero excluded). IDs 1, 2
4259 and 3 are reserved for |:match|, |:2match| and |:3match|,
4260 respectively. If the {id} argument is not specified,
4261 |matchadd()| automatically chooses a free ID.
4262
4263 The number of matches is not limited, as it is the case with
4264 the |:match| commands.
4265
4266 Example: >
4267 :highlight MyGroup ctermbg=green guibg=green
4268 :let m = matchadd("MyGroup", "TODO")
4269< Deletion of the pattern: >
4270 :call matchdelete(m)
4271
4272< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar446cb832008-06-24 21:56:24 +00004273 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004274 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004275
4276matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004277 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004278 |:2match| or |:3match| command.
4279 Return a |List| with two elements:
4280 The name of the highlight group used
4281 The pattern used.
4282 When {nr} is not 1, 2 or 3 returns an empty |List|.
4283 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004284 This is useful to save and restore a |:match|.
4285 Highlighting matches using the |:match| commands are limited
4286 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004287
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004288matchdelete({id}) *matchdelete()* *E802* *E803*
4289 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00004290 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004291 otherwise -1. See example for |matchadd()|. All matches can
4292 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004293
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004294matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004295 Same as |match()|, but return the index of first character
4296 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004297 :echo matchend("testing", "ing")
4298< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00004299 *strspn()* *strcspn()*
4300 Vim doesn't have a strspn() or strcspn() function, but you can
4301 do it with matchend(): >
4302 :let span = matchend(line, '[a-zA-Z]')
4303 :let span = matchend(line, '[^a-zA-Z]')
4304< Except that -1 is returned when there are no matches.
4305
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004306 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004307 :echo matchend("testing", "ing", 2)
4308< results in "7". >
4309 :echo matchend("testing", "ing", 5)
4310< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004311 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004312
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004313matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004314 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004315 list is the matched string, same as what matchstr() would
4316 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004317 in |:substitute|. When an optional submatch didn't match an
4318 empty string is used. Example: >
4319 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
4320< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004321 When there is no match an empty list is returned.
4322
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004323matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004324 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004325 :echo matchstr("testing", "ing")
4326< results in "ing".
4327 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004328 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004329 :echo matchstr("testing", "ing", 2)
4330< results in "ing". >
4331 :echo matchstr("testing", "ing", 5)
4332< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004333 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004334 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004335
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004336 *max()*
4337max({list}) Return the maximum value of all items in {list}.
4338 If {list} is not a list or one of the items in {list} cannot
4339 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004340 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004341
4342 *min()*
Bram Moolenaar79166c42007-05-10 18:29:51 +00004343min({list}) Return the minimum value of all items in {list}.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004344 If {list} is not a list or one of the items in {list} cannot
4345 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004346 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004347
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004348 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004349mkdir({name} [, {path} [, {prot}]])
4350 Create directory {name}.
4351 If {path} is "p" then intermediate directories are created as
4352 necessary. Otherwise it must be "".
4353 If {prot} is given it is used to set the protection bits of
4354 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar446cb832008-06-24 21:56:24 +00004355 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00004356 for others. This is only used for the last part of {name}.
4357 Thus if you create /tmp/foo/bar then /tmp/foo will be created
4358 with 0755.
4359 Example: >
4360 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
4361< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004362 Not available on all systems. To check use: >
4363 :if exists("*mkdir")
4364<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004365 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004366mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00004367 If [expr] is supplied and it evaluates to a non-zero Number or
4368 a non-empty String (|non-zero-arg|), then the full mode is
4369 returned, otherwise only the first letter is returned. Note
4370 that " " and "0" are also non-empty strings.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004371
Bram Moolenaar071d4272004-06-13 20:20:40 +00004372 n Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00004373 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00004374 v Visual by character
4375 V Visual by line
4376 CTRL-V Visual blockwise
4377 s Select by character
4378 S Select by line
4379 CTRL-S Select blockwise
4380 i Insert
Bram Moolenaar446cb832008-06-24 21:56:24 +00004381 R Replace |R|
4382 Rv Virtual Replace |gR|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004383 c Command-line
Bram Moolenaar446cb832008-06-24 21:56:24 +00004384 cv Vim Ex mode |gQ|
4385 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004386 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00004387 rm The -- more -- prompt
4388 r? A |:confirm| query of some sort
4389 ! Shell or external command is executing
4390 This is useful in the 'statusline' option or when used
4391 with |remote_expr()| In most other places it always returns
4392 "c" or "n".
4393 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004394
Bram Moolenaar7e506b62010-01-19 15:55:06 +01004395mzeval({expr}) *mzeval()*
4396 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02004397 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01004398 Numbers and strings are returned as they are.
4399 Pairs (including lists and improper lists) and vectors are
4400 returned as Vim |Lists|.
4401 Hash tables are represented as Vim |Dictionary| type with keys
4402 converted to strings.
4403 All other types are converted to string with display function.
4404 Examples: >
4405 :mz (define l (list 1 2 3))
4406 :mz (define h (make-hash)) (hash-set! h "list" l)
4407 :echo mzeval("l")
4408 :echo mzeval("h")
4409<
4410 {only available when compiled with the |+mzscheme| feature}
4411
Bram Moolenaar071d4272004-06-13 20:20:40 +00004412nextnonblank({lnum}) *nextnonblank()*
4413 Return the line number of the first line at or below {lnum}
4414 that is not blank. Example: >
4415 if getline(nextnonblank(1)) =~ "Java"
4416< When {lnum} is invalid or there is no non-blank line at or
4417 below it, zero is returned.
4418 See also |prevnonblank()|.
4419
Bram Moolenaard35d7842013-01-23 17:17:10 +01004420nr2char({expr}[, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004421 Return a string with a single character, which has the number
4422 value {expr}. Examples: >
4423 nr2char(64) returns "@"
4424 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01004425< When {utf8} is omitted or zero, the current 'encoding' is used.
4426 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004427 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01004428< With {utf8} set to 1, always return utf-8 characters.
4429 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00004430 nr2char(10), because NULs are represented with newline
4431 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004432 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004433
Bram Moolenaar18081e32008-02-20 19:11:07 +00004434 *getpid()*
4435getpid() Return a Number which is the process ID of the Vim process.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004436 On Unix and MS-Windows this is a unique number, until Vim
4437 exits. On MS-DOS it's always zero.
Bram Moolenaar18081e32008-02-20 19:11:07 +00004438
Bram Moolenaar0b238792006-03-02 22:49:12 +00004439 *getpos()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004440getpos({expr}) Get the position for {expr}. For possible values of {expr}
4441 see |line()|.
4442 The result is a |List| with four numbers:
4443 [bufnum, lnum, col, off]
4444 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4445 is the buffer number of the mark.
4446 "lnum" and "col" are the position in the buffer. The first
4447 column is 1.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004448 The "off" number is zero, unless 'virtualedit' is used. Then
4449 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004450 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar0b238792006-03-02 22:49:12 +00004451 character.
Bram Moolenaardfb18412013-12-11 18:53:29 +01004452 Note that for '< and '> Visual mode matters: when it is "V"
4453 (visual line mode) the column of '< is zero and the column of
4454 '> is a large number.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004455 This can be used to save and restore the cursor position: >
4456 let save_cursor = getpos(".")
4457 MoveTheCursorAround
Bram Moolenaardb552d602006-03-23 22:59:57 +00004458 call setpos('.', save_cursor)
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004459< Also see |setpos()|.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004460
Bram Moolenaard6e256c2011-12-14 15:32:50 +01004461or({expr}, {expr}) *or()*
4462 Bitwise OR on the two arguments. The arguments are converted
4463 to a number. A List, Dict or Float argument causes an error.
4464 Example: >
4465 :let bits = or(bits, 0x80)
4466
4467
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004468pathshorten({expr}) *pathshorten()*
4469 Shorten directory names in the path {expr} and return the
4470 result. The tail, the file name, is kept as-is. The other
4471 components in the path are reduced to single letters. Leading
4472 '~' and '.' characters are kept. Example: >
4473 :echo pathshorten('~/.vim/autoload/myfile.vim')
4474< ~/.v/a/myfile.vim ~
4475 It doesn't matter if the path exists or not.
4476
Bram Moolenaar446cb832008-06-24 21:56:24 +00004477pow({x}, {y}) *pow()*
4478 Return the power of {x} to the exponent {y} as a |Float|.
4479 {x} and {y} must evaluate to a |Float| or a |Number|.
4480 Examples: >
4481 :echo pow(3, 3)
4482< 27.0 >
4483 :echo pow(2, 16)
4484< 65536.0 >
4485 :echo pow(32, 0.20)
4486< 2.0
4487 {only available when compiled with the |+float| feature}
4488
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004489prevnonblank({lnum}) *prevnonblank()*
4490 Return the line number of the first line at or above {lnum}
4491 that is not blank. Example: >
4492 let ind = indent(prevnonblank(v:lnum - 1))
4493< When {lnum} is invalid or there is no non-blank line at or
4494 above it, zero is returned.
4495 Also see |nextnonblank()|.
4496
4497
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004498printf({fmt}, {expr1} ...) *printf()*
4499 Return a String with {fmt}, where "%" items are replaced by
4500 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004501 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004502< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004503 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004504
4505 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004506 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01004507 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00004508 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00004509 %.9s string truncated to 9 bytes
4510 %c single byte
4511 %d decimal number
4512 %5d decimal number padded with spaces to 5 characters
4513 %x hex number
4514 %04x hex number padded with zeros to at least 4 characters
4515 %X hex number using upper case letters
4516 %o octal number
4517 %f floating point number in the form 123.456
4518 %e floating point number in the form 1.234e3
4519 %E floating point number in the form 1.234E3
4520 %g floating point number, as %f or %e depending on value
4521 %G floating point number, as %f or %E depending on value
4522 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004523
4524 Conversion specifications start with '%' and end with the
4525 conversion type. All other characters are copied unchanged to
4526 the result.
4527
4528 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004529 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004530
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004531 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004532
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004533 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004534 Zero or more of the following flags:
4535
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004536 # The value should be converted to an "alternate
4537 form". For c, d, and s conversions, this option
4538 has no effect. For o conversions, the precision
4539 of the number is increased to force the first
4540 character of the output string to a zero (except
4541 if a zero value is printed with an explicit
4542 precision of zero).
4543 For x and X conversions, a non-zero result has
4544 the string "0x" (or "0X" for X conversions)
4545 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004546
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004547 0 (zero) Zero padding. For all conversions the converted
4548 value is padded on the left with zeros rather
4549 than blanks. If a precision is given with a
4550 numeric conversion (d, o, x, and X), the 0 flag
4551 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004552
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004553 - A negative field width flag; the converted value
4554 is to be left adjusted on the field boundary.
4555 The converted value is padded on the right with
4556 blanks, rather than on the left with blanks or
4557 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004558
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004559 ' ' (space) A blank should be left before a positive
4560 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004561
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004562 + A sign must always be placed before a number
Bram Moolenaar446cb832008-06-24 21:56:24 +00004563 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004564 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004565
4566 field-width
4567 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00004568 field width. If the converted value has fewer bytes
4569 than the field width, it will be padded with spaces on
4570 the left (or right, if the left-adjustment flag has
4571 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004572
4573 .precision
4574 An optional precision, in the form of a period '.'
4575 followed by an optional digit string. If the digit
4576 string is omitted, the precision is taken as zero.
4577 This gives the minimum number of digits to appear for
4578 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00004579 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004580 For floating point it is the number of digits after
4581 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004582
4583 type
4584 A character that specifies the type of conversion to
4585 be applied, see below.
4586
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004587 A field width or precision, or both, may be indicated by an
4588 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar446cb832008-06-24 21:56:24 +00004589 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004590 negative field width is treated as a left adjustment flag
4591 followed by a positive field width; a negative precision is
4592 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004593 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004594< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004595 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004596
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004597 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004598
Bram Moolenaar446cb832008-06-24 21:56:24 +00004599 *printf-d* *printf-o* *printf-x* *printf-X*
4600 doxX The Number argument is converted to signed decimal
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004601 (d), unsigned octal (o), or unsigned hexadecimal (x
4602 and X) notation. The letters "abcdef" are used for
4603 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004604 conversions.
4605 The precision, if any, gives the minimum number of
4606 digits that must appear; if the converted value
4607 requires fewer digits, it is padded on the left with
4608 zeros.
4609 In no case does a non-existent or small field width
4610 cause truncation of a numeric field; if the result of
4611 a conversion is wider than the field width, the field
4612 is expanded to contain the conversion result.
4613
Bram Moolenaar446cb832008-06-24 21:56:24 +00004614 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004615 c The Number argument is converted to a byte, and the
4616 resulting character is written.
4617
Bram Moolenaar446cb832008-06-24 21:56:24 +00004618 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004619 s The text of the String argument is used. If a
4620 precision is specified, no more bytes than the number
4621 specified are used.
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01004622 S The text of the String argument is used. If a
4623 precision is specified, no more display cells than the
4624 number specified are used. Without the |+multi_byte|
4625 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004626
Bram Moolenaar446cb832008-06-24 21:56:24 +00004627 *printf-f* *E807*
4628 f The Float argument is converted into a string of the
4629 form 123.456. The precision specifies the number of
4630 digits after the decimal point. When the precision is
4631 zero the decimal point is omitted. When the precision
4632 is not specified 6 is used. A really big number
4633 (out of range or dividing by zero) results in "inf".
4634 "0.0 / 0.0" results in "nan".
4635 Example: >
4636 echo printf("%.2f", 12.115)
4637< 12.12
4638 Note that roundoff depends on the system libraries.
4639 Use |round()| when in doubt.
4640
4641 *printf-e* *printf-E*
4642 e E The Float argument is converted into a string of the
4643 form 1.234e+03 or 1.234E+03 when using 'E'. The
4644 precision specifies the number of digits after the
4645 decimal point, like with 'f'.
4646
4647 *printf-g* *printf-G*
4648 g G The Float argument is converted like with 'f' if the
4649 value is between 0.001 (inclusive) and 10000000.0
4650 (exclusive). Otherwise 'e' is used for 'g' and 'E'
4651 for 'G'. When no precision is specified superfluous
4652 zeroes and '+' signs are removed, except for the zero
4653 immediately after the decimal point. Thus 10000000.0
4654 results in 1.0e7.
4655
4656 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004657 % A '%' is written. No argument is converted. The
4658 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004659
Bram Moolenaarc236c162008-07-13 17:41:49 +00004660 When a Number argument is expected a String argument is also
4661 accepted and automatically converted.
4662 When a Float or String argument is expected a Number argument
4663 is also accepted and automatically converted.
4664 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004665
Bram Moolenaar83bab712005-08-01 21:58:57 +00004666 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004667 The number of {exprN} arguments must exactly match the number
4668 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004669 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004670
4671
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004672pumvisible() *pumvisible()*
4673 Returns non-zero when the popup menu is visible, zero
4674 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004675 This can be used to avoid some things that would remove the
4676 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004677
Bram Moolenaare6ae6222013-05-21 21:01:10 +02004678 *E860*
Bram Moolenaar30b65812012-07-12 22:01:11 +02004679py3eval({expr}) *py3eval()*
4680 Evaluate Python expression {expr} and return its result
4681 converted to Vim data structures.
4682 Numbers and strings are returned as they are (strings are
4683 copied though, unicode strings are additionally converted to
4684 'encoding').
4685 Lists are represented as Vim |List| type.
4686 Dictionaries are represented as Vim |Dictionary| type with
4687 keys converted to strings.
4688 {only available when compiled with the |+python3| feature}
4689
4690 *E858* *E859*
4691pyeval({expr}) *pyeval()*
4692 Evaluate Python expression {expr} and return its result
4693 converted to Vim data structures.
4694 Numbers and strings are returned as they are (strings are
4695 copied though).
4696 Lists are represented as Vim |List| type.
Bram Moolenaard09acef2012-09-21 14:54:30 +02004697 Dictionaries are represented as Vim |Dictionary| type,
4698 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02004699 {only available when compiled with the |+python| feature}
4700
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004701 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00004702range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004703 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00004704 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
4705 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
4706 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4707 {max}] (increasing {expr} with {stride} each time, not
4708 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00004709 When the maximum is one before the start the result is an
4710 empty list. When the maximum is more than one before the
4711 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004712 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004713 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00004714 range(2, 4) " [2, 3, 4]
4715 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004716 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00004717 range(0) " []
4718 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00004719<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004720 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004721readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004722 Read file {fname} and return a |List|, each line of the file
4723 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004724 separated with CR will result in a single long line (unless a
4725 NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02004726 All NUL characters are replaced with a NL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004727 When {binary} is equal to "b" binary mode is used:
4728 - When the last line ends in a NL an extra empty list item is
4729 added.
4730 - No CR characters are removed.
4731 Otherwise:
4732 - CR characters that appear before a NL are removed.
4733 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02004734 - When 'encoding' is Unicode any UTF-8 byte order mark is
4735 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004736 When {max} is given this specifies the maximum number of lines
4737 to be read. Useful if you only want to check the first ten
4738 lines of a file: >
4739 :for line in readfile(fname, '', 10)
4740 : if line =~ 'Date' | echo line | endif
4741 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00004742< When {max} is negative -{max} lines from the end of the file
4743 are returned, or as many as there are.
4744 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004745 Note that without {max} the whole file is read into memory.
4746 Also note that there is no recognition of encoding. Read a
4747 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004748 When the file can't be opened an error message is given and
4749 the result is an empty list.
4750 Also see |writefile()|.
4751
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004752reltime([{start} [, {end}]]) *reltime()*
4753 Return an item that represents a time value. The format of
4754 the item depends on the system. It can be passed to
4755 |reltimestr()| to convert it to a string.
4756 Without an argument it returns the current time.
4757 With one argument is returns the time passed since the time
4758 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004759 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004760 and {end}.
4761 The {start} and {end} arguments must be values returned by
4762 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02004763 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004764
4765reltimestr({time}) *reltimestr()*
4766 Return a String that represents the time value of {time}.
4767 This is the number of seconds, a dot and the number of
4768 microseconds. Example: >
4769 let start = reltime()
4770 call MyFunction()
4771 echo reltimestr(reltime(start))
4772< Note that overhead for the commands will be added to the time.
4773 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004774 Leading spaces are used to make the string align nicely. You
4775 can use split() to remove it. >
4776 echo split(reltimestr(reltime(start)))[0]
4777< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004778 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004779
Bram Moolenaar071d4272004-06-13 20:20:40 +00004780 *remote_expr()* *E449*
4781remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00004782 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004783 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004784 The result must be a String or a |List|. A |List| is turned
4785 into a String by joining the items with a line break in
4786 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00004787 If {idvar} is present, it is taken as the name of a
4788 variable and a {serverid} for later use with
4789 remote_read() is stored there.
4790 See also |clientserver| |RemoteReply|.
4791 This function is not available in the |sandbox|.
4792 {only available when compiled with the |+clientserver| feature}
4793 Note: Any errors will cause a local error message to be issued
4794 and the result will be the empty string.
4795 Examples: >
4796 :echo remote_expr("gvim", "2+2")
4797 :echo remote_expr("gvim1", "b:current_syntax")
4798<
4799
4800remote_foreground({server}) *remote_foreground()*
4801 Move the Vim server with the name {server} to the foreground.
4802 This works like: >
4803 remote_expr({server}, "foreground()")
4804< Except that on Win32 systems the client does the work, to work
4805 around the problem that the OS doesn't always allow the server
4806 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00004807 Note: This does not restore the window if it was minimized,
4808 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004809 This function is not available in the |sandbox|.
4810 {only in the Win32, Athena, Motif and GTK GUI versions and the
4811 Win32 console version}
4812
4813
4814remote_peek({serverid} [, {retvar}]) *remote_peek()*
4815 Returns a positive number if there are available strings
4816 from {serverid}. Copies any reply string into the variable
Bram Moolenaar446cb832008-06-24 21:56:24 +00004817 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004818 name of a variable.
4819 Returns zero if none are available.
4820 Returns -1 if something is wrong.
4821 See also |clientserver|.
4822 This function is not available in the |sandbox|.
4823 {only available when compiled with the |+clientserver| feature}
4824 Examples: >
4825 :let repl = ""
4826 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
4827
4828remote_read({serverid}) *remote_read()*
4829 Return the oldest available reply from {serverid} and consume
4830 it. It blocks until a reply is available.
4831 See also |clientserver|.
4832 This function is not available in the |sandbox|.
4833 {only available when compiled with the |+clientserver| feature}
4834 Example: >
4835 :echo remote_read(id)
4836<
4837 *remote_send()* *E241*
4838remote_send({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00004839 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00004840 keys and the function returns immediately. At the Vim server
4841 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004842 If {idvar} is present, it is taken as the name of a variable
4843 and a {serverid} for later use with remote_read() is stored
4844 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004845 See also |clientserver| |RemoteReply|.
4846 This function is not available in the |sandbox|.
4847 {only available when compiled with the |+clientserver| feature}
4848 Note: Any errors will be reported in the server and may mess
4849 up the display.
4850 Examples: >
4851 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
4852 \ remote_read(serverid)
4853
4854 :autocmd NONE RemoteReply *
4855 \ echo remote_read(expand("<amatch>"))
4856 :echo remote_send("gvim", ":sleep 10 | echo ".
4857 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004858<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004859remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004860 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004861 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004862 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004863 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004864 item as {end} a list with one item is returned. When {end}
4865 points to an item before {idx} this is an error.
4866 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004867 Example: >
4868 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004869 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00004870remove({dict}, {key})
4871 Remove the entry from {dict} with key {key}. Example: >
4872 :echo "removed " . remove(dict, "one")
4873< If there is no {key} in {dict} this is an error.
4874
4875 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004876
Bram Moolenaar071d4272004-06-13 20:20:40 +00004877rename({from}, {to}) *rename()*
4878 Rename the file by the name {from} to the name {to}. This
4879 should also work to move files across file systems. The
4880 result is a Number, which is 0 if the file was renamed
4881 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00004882 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004883 This function is not available in the |sandbox|.
4884
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004885repeat({expr}, {count}) *repeat()*
4886 Repeat {expr} {count} times and return the concatenated
4887 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004888 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004889< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004890 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar446cb832008-06-24 21:56:24 +00004891 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004892 :let longlist = repeat(['a', 'b'], 3)
4893< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004894
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004895
Bram Moolenaar071d4272004-06-13 20:20:40 +00004896resolve({filename}) *resolve()* *E655*
4897 On MS-Windows, when {filename} is a shortcut (a .lnk file),
4898 returns the path the shortcut points to in a simplified form.
4899 On Unix, repeat resolving symbolic links in all path
4900 components of {filename} and return the simplified result.
4901 To cope with link cycles, resolving of symbolic links is
4902 stopped after 100 iterations.
4903 On other systems, return the simplified {filename}.
4904 The simplification step is done as by |simplify()|.
4905 resolve() keeps a leading path component specifying the
4906 current directory (provided the result is still a relative
4907 path name) and also keeps a trailing path separator.
4908
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004909 *reverse()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004910reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004911 {list}.
4912 If you want a list to remain unmodified make a copy first: >
4913 :let revlist = reverse(copy(mylist))
4914
Bram Moolenaar446cb832008-06-24 21:56:24 +00004915round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00004916 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00004917 as a |Float|. If {expr} lies halfway between two integral
4918 values, then use the larger one (away from zero).
4919 {expr} must evaluate to a |Float| or a |Number|.
4920 Examples: >
4921 echo round(0.456)
4922< 0.0 >
4923 echo round(4.5)
4924< 5.0 >
4925 echo round(-4.5)
4926< -5.0
4927 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01004928
Bram Moolenaar9a773482013-06-11 18:40:13 +02004929screenattr(row, col) *screenattr()*
4930 Like screenchar(), but return the attribute. This is a rather
4931 arbitrary number that can only be used to compare to the
4932 attribute at other positions.
4933
4934screenchar(row, col) *screenchar()*
4935 The result is a Number, which is the character at position
4936 [row, col] on the screen. This works for every possible
4937 screen position, also status lines, window separators and the
4938 command line. The top left position is row one, column one
4939 The character excludes composing characters. For double-byte
4940 encodings it may only be the first byte.
4941 This is mainly to be used for testing.
4942 Returns -1 when row or col is out of range.
4943
Bram Moolenaar34feacb2012-12-05 19:01:43 +01004944screencol() *screencol()*
4945 The result is a Number, which is the current screen column of
4946 the cursor. The leftmost column has number 1.
4947 This function is mainly used for testing.
4948
4949 Note: Always returns the current screen column, thus if used
4950 in a command (e.g. ":echo screencol()") it will return the
4951 column inside the command line, which is 1 when the command is
4952 executed. To get the cursor position in the file use one of
4953 the following mappings: >
4954 nnoremap <expr> GG ":echom ".screencol()."\n"
4955 nnoremap <silent> GG :echom screencol()<CR>
4956<
4957screenrow() *screenrow()*
4958 The result is a Number, which is the current screen row of the
4959 cursor. The top line has number one.
4960 This function is mainly used for testing.
4961
4962 Note: Same restrictions as with |screencol()|.
4963
Bram Moolenaar76929292008-01-06 19:07:36 +00004964search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004965 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004966 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004967
Bram Moolenaar2df58b42012-11-28 18:21:11 +01004968 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01004969 If there is no match a 0 is returned and the cursor doesn't
4970 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01004971
Bram Moolenaar071d4272004-06-13 20:20:40 +00004972 {flags} is a String, which can contain these character flags:
4973 'b' search backward instead of forward
Bram Moolenaar446cb832008-06-24 21:56:24 +00004974 'c' accept a match at the cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004975 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004976 'n' do Not move the cursor
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004977 'p' return number of matching sub-pattern (see below)
4978 's' set the ' mark at the previous location of the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004979 'w' wrap around the end of the file
4980 'W' don't wrap around the end of the file
4981 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
4982
Bram Moolenaar02743632005-07-25 20:42:36 +00004983 If the 's' flag is supplied, the ' mark is set, only if the
4984 cursor is moved. The 's' flag cannot be combined with the 'n'
4985 flag.
4986
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004987 'ignorecase', 'smartcase' and 'magic' are used.
4988
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004989 When the {stopline} argument is given then the search stops
4990 after searching this line. This is useful to restrict the
4991 search to a range of lines. Examples: >
4992 let match = search('(', 'b', line("w0"))
4993 let end = search('END', '', line("w$"))
4994< When {stopline} is used and it is not zero this also implies
4995 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00004996 A zero value is equal to not giving the argument.
4997
4998 When the {timeout} argument is given the search stops when
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02004999 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00005000 {timeout} is 500 the search stops after half a second.
5001 The value must not be negative. A zero value is like not
5002 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005003 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005004
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005005 *search()-sub-match*
5006 With the 'p' flag the returned value is one more than the
5007 first sub-match in \(\). One if none of them matched but the
5008 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005009 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005010
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005011 The cursor will be positioned at the match, unless the 'n'
5012 flag is used.
5013
Bram Moolenaar071d4272004-06-13 20:20:40 +00005014 Example (goes over all files in the argument list): >
5015 :let n = 1
5016 :while n <= argc() " loop over all files in arglist
5017 : exe "argument " . n
5018 : " start at the last char in the file and wrap for the
5019 : " first search to find match at start of file
5020 : normal G$
5021 : let flags = "w"
5022 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005023 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00005024 : let flags = "W"
5025 : endwhile
5026 : update " write the file if modified
5027 : let n = n + 1
5028 :endwhile
5029<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005030 Example for using some flags: >
5031 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
5032< This will search for the keywords "if", "else", and "endif"
5033 under or after the cursor. Because of the 'p' flag, it
5034 returns 1, 2, or 3 depending on which keyword is found, or 0
5035 if the search fails. With the cursor on the first word of the
5036 line:
5037 if (foo == 0) | let foo = foo + 1 | endif ~
5038 the function returns 1. Without the 'c' flag, the function
5039 finds the "endif" and returns 3. The same thing happens
5040 without the 'e' flag if the cursor is on the "f" of "if".
5041 The 'n' flag tells the function not to move the cursor.
5042
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005043
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005044searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
5045 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005046
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005047 With a non-zero {global} argument it works like |gD|, find
5048 first match in the file. Otherwise it works like |gd|, find
5049 first match in the function.
5050
5051 With a non-zero {thisblock} argument matches in a {} block
5052 that ends before the cursor position are ignored. Avoids
5053 finding variable declarations only valid in another scope.
5054
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005055 Moves the cursor to the found match.
5056 Returns zero for success, non-zero for failure.
5057 Example: >
5058 if searchdecl('myvar') == 0
5059 echo getline('.')
5060 endif
5061<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005062 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00005063searchpair({start}, {middle}, {end} [, {flags} [, {skip}
5064 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00005065 Search for the match of a nested start-end pair. This can be
5066 used to find the "endif" that matches an "if", while other
5067 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005068 The search starts at the cursor. The default is to search
5069 forward, include 'b' in {flags} to search backward.
5070 If a match is found, the cursor is positioned at it and the
5071 line number is returned. If no match is found 0 or -1 is
5072 returned and the cursor doesn't move. No error message is
5073 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005074
5075 {start}, {middle} and {end} are patterns, see |pattern|. They
5076 must not contain \( \) pairs. Use of \%( \) is allowed. When
5077 {middle} is not empty, it is found when searching from either
5078 direction, but only when not in a nested start-end pair. A
5079 typical use is: >
5080 searchpair('\<if\>', '\<else\>', '\<endif\>')
5081< By leaving {middle} empty the "else" is skipped.
5082
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005083 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
5084 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005085 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005086 outer pair. Implies the 'W' flag.
5087 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005088 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005089 Note: it's nearly always a good idea to use the 'W' flag, to
5090 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005091
5092 When a match for {start}, {middle} or {end} is found, the
5093 {skip} expression is evaluated with the cursor positioned on
5094 the start of the match. It should return non-zero if this
5095 match is to be skipped. E.g., because it is inside a comment
5096 or a string.
5097 When {skip} is omitted or empty, every match is accepted.
5098 When evaluating {skip} causes an error the search is aborted
5099 and -1 returned.
5100
Bram Moolenaar76929292008-01-06 19:07:36 +00005101 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005102
Bram Moolenaar071d4272004-06-13 20:20:40 +00005103 The value of 'ignorecase' is used. 'magic' is ignored, the
5104 patterns are used like it's on.
5105
5106 The search starts exactly at the cursor. A match with
5107 {start}, {middle} or {end} at the next character, in the
5108 direction of searching, is the first one found. Example: >
5109 if 1
5110 if 2
5111 endif 2
5112 endif 1
5113< When starting at the "if 2", with the cursor on the "i", and
5114 searching forwards, the "endif 2" is found. When starting on
5115 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar446cb832008-06-24 21:56:24 +00005116 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00005117 then this is considered to be a nested if/endif from "if 2" to
5118 "endif 2".
5119 When searching backwards and {end} is more than one character,
5120 it may be useful to put "\zs" at the end of the pattern, so
5121 that when the cursor is inside a match with the end it finds
5122 the matching start.
5123
5124 Example, to find the "endif" command in a Vim script: >
5125
5126 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
5127 \ 'getline(".") =~ "^\\s*\""')
5128
5129< The cursor must be at or after the "if" for which a match is
5130 to be found. Note that single-quote strings are used to avoid
5131 having to double the backslashes. The skip expression only
5132 catches comments at the start of a line, not after a command.
5133 Also, a word "en" or "if" halfway a line is considered a
5134 match.
5135 Another example, to search for the matching "{" of a "}": >
5136
5137 :echo searchpair('{', '', '}', 'bW')
5138
5139< This works when the cursor is at or before the "}" for which a
5140 match is to be found. To reject matches that syntax
5141 highlighting recognized as strings: >
5142
5143 :echo searchpair('{', '', '}', 'bW',
5144 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
5145<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005146 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00005147searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
5148 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005149 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005150 column position of the match. The first element of the |List|
5151 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005152 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005153 returns [0, 0]. >
5154
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005155 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
5156<
5157 See |match-parens| for a bigger and more useful example.
5158
Bram Moolenaar76929292008-01-06 19:07:36 +00005159searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005160 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005161 column position of the match. The first element of the |List|
5162 is the line number and the second element is the byte index of
5163 the column position of the match. If no match is found,
5164 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005165 Example: >
5166 :let [lnum, col] = searchpos('mypattern', 'n')
5167
5168< When the 'p' flag is given then there is an extra item with
5169 the sub-pattern match number |search()-sub-match|. Example: >
5170 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
5171< In this example "submatch" is 2 when a lowercase letter is
5172 found |/\l|, 3 when an uppercase letter is found |/\u|.
5173
Bram Moolenaar071d4272004-06-13 20:20:40 +00005174server2client( {clientid}, {string}) *server2client()*
5175 Send a reply string to {clientid}. The most recent {clientid}
5176 that sent a string can be retrieved with expand("<client>").
5177 {only available when compiled with the |+clientserver| feature}
5178 Note:
5179 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005180 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00005181 before calling any commands that waits for input.
5182 See also |clientserver|.
5183 Example: >
5184 :echo server2client(expand("<client>"), "HELLO")
5185<
5186serverlist() *serverlist()*
5187 Return a list of available server names, one per line.
5188 When there are no servers or the information is not available
5189 an empty string is returned. See also |clientserver|.
5190 {only available when compiled with the |+clientserver| feature}
5191 Example: >
5192 :echo serverlist()
5193<
5194setbufvar({expr}, {varname}, {val}) *setbufvar()*
5195 Set option or local variable {varname} in buffer {expr} to
5196 {val}.
5197 This also works for a global or local window option, but it
5198 doesn't work for a global or local window variable.
5199 For a local window option the global value is unchanged.
5200 For the use of {expr}, see |bufname()| above.
5201 Note that the variable name without "b:" must be used.
5202 Examples: >
5203 :call setbufvar(1, "&mod", 1)
5204 :call setbufvar("todo", "myvar", "foobar")
5205< This function is not available in the |sandbox|.
5206
5207setcmdpos({pos}) *setcmdpos()*
5208 Set the cursor position in the command line to byte position
Bram Moolenaar446cb832008-06-24 21:56:24 +00005209 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005210 Use |getcmdpos()| to obtain the current position.
5211 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00005212 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
5213 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
5214 set after the command line is set to the expression. For
5215 |c_CTRL-R_=| it is set after evaluating the expression but
5216 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005217 When the number is too big the cursor is put at the end of the
5218 line. A number smaller than one has undefined results.
5219 Returns 0 when successful, 1 when not editing the command
5220 line.
5221
Bram Moolenaar446cb832008-06-24 21:56:24 +00005222setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005223 Set line {lnum} of the current buffer to {text}. To insert
5224 lines use |append()|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005225 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005226 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005227 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005228 If this succeeds, 0 is returned. If this fails (most likely
5229 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005230 :call setline(5, strftime("%c"))
Bram Moolenaar446cb832008-06-24 21:56:24 +00005231< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005232 will be set to the items in the list. Example: >
5233 :call setline(5, ['aaa', 'bbb', 'ccc'])
5234< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02005235 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005236 : call setline(n, l)
5237 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00005238< Note: The '[ and '] marks are not set.
5239
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005240setloclist({nr}, {list} [, {action}]) *setloclist()*
5241 Create or replace or add to the location list for window {nr}.
5242 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00005243 list window, the displayed location list is modified. For an
5244 invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005245 Otherwise, same as |setqflist()|.
5246 Also see |location-list|.
5247
5248setmatches({list}) *setmatches()*
5249 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005250 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005251 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005252
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005253 *setpos()*
5254setpos({expr}, {list})
5255 Set the position for {expr}. Possible values:
5256 . the cursor
5257 'x mark x
5258
5259 {list} must be a |List| with four numbers:
5260 [bufnum, lnum, col, off]
5261
Bram Moolenaar446cb832008-06-24 21:56:24 +00005262 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005263 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005264 the current buffer. To set a mark in another buffer you can
5265 use the |bufnr()| function to turn a file name into a buffer
5266 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00005267 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005268
5269 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005270 column is 1. Use a zero "lnum" to delete a mark. If "col" is
5271 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005272
5273 The "off" number is only used when 'virtualedit' is set. Then
5274 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005275 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005276 character.
5277
Bram Moolenaardfb18412013-12-11 18:53:29 +01005278 Note that for '< and '> changing the line number may result in
5279 the marks to be effectively be swapped, so that '< is always
5280 before '>.
5281
Bram Moolenaar08250432008-02-13 11:42:46 +00005282 Returns 0 when the position could be set, -1 otherwise.
5283 An error message is given if {expr} is invalid.
5284
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005285 Also see |getpos()|
5286
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005287 This does not restore the preferred column for moving
5288 vertically. See |winrestview()| for that.
5289
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005290
Bram Moolenaar35c54e52005-05-20 21:25:31 +00005291setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005292 Create or replace or add to the quickfix list using the items
5293 in {list}. Each item in {list} is a dictionary.
5294 Non-dictionary items in {list} are ignored. Each dictionary
5295 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005296
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005297 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00005298 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005299 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00005300 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005301 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005302 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00005303 col column number
5304 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005305 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00005306 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005307 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00005308 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005309
Bram Moolenaar582fd852005-03-28 20:58:01 +00005310 The "col", "vcol", "nr", "type" and "text" entries are
5311 optional. Either "lnum" or "pattern" entry can be used to
5312 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005313 If the "filename" and "bufnr" entries are not present or
5314 neither the "lnum" or "pattern" entries are present, then the
5315 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005316 If both "pattern" and "lnum" are present then "pattern" will
5317 be used.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02005318 If you supply an empty {list}, the quickfix list will be
5319 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005320 Note that the list is not exactly the same as what
5321 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005322
Bram Moolenaar35c54e52005-05-20 21:25:31 +00005323 If {action} is set to 'a', then the items from {list} are
5324 added to the existing quickfix list. If there is no existing
5325 list, then a new list is created. If {action} is set to 'r',
5326 then the items from the current quickfix list are replaced
5327 with the items from {list}. If {action} is not present or is
5328 set to ' ', then a new list is created.
5329
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005330 Returns zero for success, -1 for failure.
5331
5332 This function can be used to create a quickfix list
5333 independent of the 'errorformat' setting. Use a command like
5334 ":cc 1" to jump to the first position.
5335
5336
Bram Moolenaar071d4272004-06-13 20:20:40 +00005337 *setreg()*
5338setreg({regname}, {value} [,{options}])
5339 Set the register {regname} to {value}.
5340 If {options} contains "a" or {regname} is upper case,
5341 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02005342 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005343 "c" or "v" |characterwise| mode
5344 "l" or "V" |linewise| mode
5345 "b" or "<CTRL-V>" |blockwise-visual| mode
5346 If a number immediately follows "b" or "<CTRL-V>" then this is
5347 used as the width of the selection - if it is not specified
5348 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005349 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005350
5351 If {options} contains no register settings, then the default
5352 is to use character mode unless {value} ends in a <NL>.
Bram Moolenaard09acef2012-09-21 14:54:30 +02005353 Setting the '=' register is not possible, but you can use >
5354 :let @= = var_expr
5355< Returns zero for success, non-zero for failure.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005356
5357 Examples: >
5358 :call setreg(v:register, @*)
5359 :call setreg('*', @%, 'ac')
5360 :call setreg('a', "1\n2\n3", 'b5')
5361
5362< This example shows using the functions to save and restore a
5363 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005364 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005365 :let var_amode = getregtype('a')
5366 ....
5367 :call setreg('a', var_a, var_amode)
5368
5369< You can also change the type of a register by appending
5370 nothing: >
5371 :call setreg('a', '', 'al')
5372
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005373settabvar({tabnr}, {varname}, {val}) *settabvar()*
5374 Set tab-local variable {varname} to {val} in tab page {tabnr}.
5375 |t:var|
5376 Note that the variable name without "t:" must be used.
5377 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005378 This function is not available in the |sandbox|.
5379
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005380settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
5381 Set option or local variable {varname} in window {winnr} to
5382 {val}.
5383 Tabs are numbered starting with one. For the current tabpage
5384 use |setwinvar()|.
5385 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005386 This also works for a global or local buffer option, but it
5387 doesn't work for a global or local buffer variable.
5388 For a local buffer option the global value is unchanged.
5389 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005390 Examples: >
5391 :call settabwinvar(1, 1, "&list", 0)
5392 :call settabwinvar(3, 2, "myvar", "foobar")
5393< This function is not available in the |sandbox|.
5394
5395setwinvar({nr}, {varname}, {val}) *setwinvar()*
5396 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005397 Examples: >
5398 :call setwinvar(1, "&list", 0)
5399 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005400
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01005401sha256({string}) *sha256()*
5402 Returns a String with 64 hex charactes, which is the SHA256
5403 checksum of {string}.
5404 {only available when compiled with the |+cryptv| feature}
5405
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005406shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005407 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005408 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005409 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005410 quotes within {string}.
5411 For other systems, it will enclose {string} in single quotes
5412 and replace all "'" with "'\''".
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005413 When the {special} argument is present and it's a non-zero
5414 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00005415 items such as "!", "%", "#" and "<cword>" will be preceded by
5416 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005417 command.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00005418 The "!" character will be escaped (again with a |non-zero-arg|
5419 {special}) when 'shell' contains "csh" in the tail. That is
5420 because for csh and tcsh "!" is used for history replacement
5421 even when inside single quotes.
5422 The <NL> character is also escaped. With a |non-zero-arg|
5423 {special} and 'shell' containing "csh" in the tail it's
5424 escaped a second time.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005425 Example of use with a |:!| command: >
5426 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
5427< This results in a directory listing for the file under the
5428 cursor. Example of use with |system()|: >
5429 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005430
5431
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02005432shiftwidth() *shiftwidth()*
5433 Returns the effective value of 'shiftwidth'. This is the
5434 'shiftwidth' value unless it is zero, in which case it is the
5435 'tabstop' value. To be backwards compatible in indent
5436 plugins, use this: >
5437 if exists('*shiftwidth')
5438 func s:sw()
5439 return shiftwidth()
5440 endfunc
5441 else
5442 func s:sw()
5443 return &sw
5444 endfunc
5445 endif
5446< And then use s:sw() instead of &sw.
5447
5448
Bram Moolenaar071d4272004-06-13 20:20:40 +00005449simplify({filename}) *simplify()*
5450 Simplify the file name as much as possible without changing
5451 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
5452 Unix) are not resolved. If the first path component in
5453 {filename} designates the current directory, this will be
5454 valid for the result as well. A trailing path separator is
5455 not removed either.
5456 Example: >
5457 simplify("./dir/.././/file/") == "./file/"
5458< Note: The combination "dir/.." is only removed if "dir" is
5459 a searchable directory or does not exist. On Unix, it is also
5460 removed when "dir" is a symbolic link within the same
5461 directory. In order to resolve all the involved symbolic
5462 links before simplifying the path name, use |resolve()|.
5463
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005464
Bram Moolenaar446cb832008-06-24 21:56:24 +00005465sin({expr}) *sin()*
5466 Return the sine of {expr}, measured in radians, as a |Float|.
5467 {expr} must evaluate to a |Float| or a |Number|.
5468 Examples: >
5469 :echo sin(100)
5470< -0.506366 >
5471 :echo sin(-4.01)
5472< 0.763301
5473 {only available when compiled with the |+float| feature}
5474
5475
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005476sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005477 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005478 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005479 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005480 Examples: >
5481 :echo sinh(0.5)
5482< 0.521095 >
5483 :echo sinh(-0.9)
5484< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02005485 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005486
5487
Bram Moolenaar5f894962011-06-19 02:55:37 +02005488sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005489 Sort the items in {list} in-place. Returns {list}. If you
5490 want a list to remain unmodified make a copy first: >
5491 :let sortedlist = sort(copy(mylist))
5492< Uses the string representation of each item to sort on.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005493 Numbers sort after Strings, |Lists| after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005494 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005495 When {func} is given and it is one then case is ignored.
Bram Moolenaar5f894962011-06-19 02:55:37 +02005496 {dict} is for functions with the "dict" attribute. It will be
5497 used to set the local variable "self". |Dictionary-function|
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005498 When {func} is a |Funcref| or a function name, this function
5499 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005500 items as argument and must return zero if they are equal, 1 or
5501 bigger if the first one sorts after the second one, -1 or
5502 smaller if the first one sorts before the second one.
5503 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005504 func MyCompare(i1, i2)
5505 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
5506 endfunc
5507 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005508< A shorter compare version for this specific simple case, which
5509 ignores overflow: >
5510 func MyCompare(i1, i2)
5511 return a:i1 - a:i2
5512 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005513<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00005514 *soundfold()*
5515soundfold({word})
5516 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00005517 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00005518 soundfolding. 'spell' must be set. When no sound folding is
5519 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00005520 This can be used for making spelling suggestions. Note that
5521 the method can be quite slow.
5522
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005523 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00005524spellbadword([{sentence}])
5525 Without argument: The result is the badly spelled word under
5526 or after the cursor. The cursor is moved to the start of the
5527 bad word. When no bad word is found in the cursor line the
5528 result is an empty string and the cursor doesn't move.
5529
5530 With argument: The result is the first word in {sentence} that
5531 is badly spelled. If there are no spelling mistakes the
5532 result is an empty string.
5533
5534 The return value is a list with two items:
5535 - The badly spelled word or an empty string.
5536 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005537 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00005538 "rare" rare word
5539 "local" word only valid in another region
5540 "caps" word should start with Capital
5541 Example: >
5542 echo spellbadword("the quik brown fox")
5543< ['quik', 'bad'] ~
5544
5545 The spelling information for the current window is used. The
5546 'spell' option must be set and the value of 'spelllang' is
5547 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005548
5549 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005550spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005551 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005552 When {max} is given up to this number of suggestions are
5553 returned. Otherwise up to 25 suggestions are returned.
5554
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005555 When the {capital} argument is given and it's non-zero only
5556 suggestions with a leading capital will be given. Use this
5557 after a match with 'spellcapcheck'.
5558
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005559 {word} can be a badly spelled word followed by other text.
5560 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00005561 suggestions also include the following text, thus you can
5562 replace a line.
5563
5564 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005565 returned. {word} itself is not included in the suggestions,
5566 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005567
5568 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00005569 'spell' option must be set and the values of 'spelllang' and
5570 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005571
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005572
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005573split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005574 Make a |List| out of {expr}. When {pattern} is omitted or
5575 empty each white-separated sequence of characters becomes an
5576 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005577 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01005578 removing the matched characters. 'ignorecase' is not used
5579 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005580 When the first or last item is empty it is omitted, unless the
5581 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00005582 Other empty items are kept when {pattern} matches at least one
5583 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005584 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005585 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005586< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005587 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00005588< If you want to keep the separator you can also use '\zs': >
5589 :echo split('abc:def:ghi', ':\zs')
5590< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005591 Splitting a table where the first element can be empty: >
5592 :let items = split(line, ':', 1)
5593< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005594
5595
Bram Moolenaar446cb832008-06-24 21:56:24 +00005596sqrt({expr}) *sqrt()*
5597 Return the non-negative square root of Float {expr} as a
5598 |Float|.
5599 {expr} must evaluate to a |Float| or a |Number|. When {expr}
5600 is negative the result is NaN (Not a Number).
5601 Examples: >
5602 :echo sqrt(100)
5603< 10.0 >
5604 :echo sqrt(-4.01)
5605< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00005606 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005607 {only available when compiled with the |+float| feature}
5608
5609
5610str2float( {expr}) *str2float()*
5611 Convert String {expr} to a Float. This mostly works the same
5612 as when using a floating point number in an expression, see
5613 |floating-point-format|. But it's a bit more permissive.
5614 E.g., "1e40" is accepted, while in an expression you need to
5615 write "1.0e40".
5616 Text after the number is silently ignored.
5617 The decimal point is always '.', no matter what the locale is
5618 set to. A comma ends the number: "12,345.67" is converted to
5619 12.0. You can strip out thousands separators with
5620 |substitute()|: >
5621 let f = str2float(substitute(text, ',', '', 'g'))
5622< {only available when compiled with the |+float| feature}
5623
5624
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005625str2nr( {expr} [, {base}]) *str2nr()*
5626 Convert string {expr} to a number.
5627 {base} is the conversion base, it can be 8, 10 or 16.
5628 When {base} is omitted base 10 is used. This also means that
5629 a leading zero doesn't cause octal conversion to be used, as
5630 with the default String to Number conversion.
5631 When {base} is 16 a leading "0x" or "0X" is ignored. With a
5632 different base the result will be zero.
5633 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005634
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005635
Bram Moolenaar72597a52010-07-18 15:31:08 +02005636strchars({expr}) *strchars()*
5637 The result is a Number, which is the number of characters
5638 String {expr} occupies. Composing characters are counted
5639 separately.
Bram Moolenaardc536092010-07-18 15:45:49 +02005640 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
5641
5642strdisplaywidth({expr}[, {col}]) *strdisplaywidth()*
5643 The result is a Number, which is the number of display cells
5644 String {expr} occupies on the screen.
5645 When {col} is omitted zero is used. Otherwise it is the
5646 screen column where to start. This matters for Tab
5647 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02005648 The option settings of the current window are used. This
5649 matters for anything that's displayed differently, such as
5650 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02005651 When {expr} contains characters with East Asian Width Class
5652 Ambiguous, this function's return value depends on 'ambiwidth'.
5653 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02005654
Bram Moolenaar071d4272004-06-13 20:20:40 +00005655strftime({format} [, {time}]) *strftime()*
5656 The result is a String, which is a formatted date and time, as
5657 specified by the {format} string. The given {time} is used,
5658 or the current time if no time is given. The accepted
5659 {format} depends on your system, thus this is not portable!
5660 See the manual page of the C function strftime() for the
5661 format. The maximum length of the result is 80 characters.
5662 See also |localtime()| and |getftime()|.
5663 The language can be changed with the |:language| command.
5664 Examples: >
5665 :echo strftime("%c") Sun Apr 27 11:49:23 1997
5666 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
5667 :echo strftime("%y%m%d %T") 970427 11:53:55
5668 :echo strftime("%H:%M") 11:55
5669 :echo strftime("%c", getftime("file.c"))
5670 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005671< Not available on all systems. To check use: >
5672 :if exists("*strftime")
5673
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005674stridx({haystack}, {needle} [, {start}]) *stridx()*
5675 The result is a Number, which gives the byte index in
5676 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00005677 If {start} is specified, the search starts at index {start}.
5678 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01005679 :let colon1 = stridx(line, ":")
5680 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00005681< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005682 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005683 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00005684 See also |strridx()|.
5685 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005686 :echo stridx("An Example", "Example") 3
5687 :echo stridx("Starting point", "Start") 0
5688 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005689< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005690 stridx() works similar to the C function strstr(). When used
5691 with a single character it works similar to strchr().
5692
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005693 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005694string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00005695 Float, String or a composition of them, then the result can be
5696 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005697 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00005698 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005699 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00005700 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00005701 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005702 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00005703 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00005704 Note that in String values the ' character is doubled.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005705 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005706
Bram Moolenaar071d4272004-06-13 20:20:40 +00005707 *strlen()*
5708strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00005709 {expr} in bytes.
5710 If you want to count the number of multi-byte characters (not
5711 counting composing characters) use something like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005712
5713 :let len = strlen(substitute(str, ".", "x", "g"))
Bram Moolenaare344bea2005-09-01 20:46:49 +00005714<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005715 If the argument is a Number it is first converted to a String.
5716 For other types an error is given.
Bram Moolenaardc536092010-07-18 15:45:49 +02005717 Also see |len()|, |strchars()|, |strdisplaywidth()| and
5718 |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005719
5720strpart({src}, {start}[, {len}]) *strpart()*
5721 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00005722 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005723 When non-existing bytes are included, this doesn't result in
5724 an error, the bytes are simply omitted.
5725 If {len} is missing, the copy continues from {start} till the
5726 end of the {src}. >
5727 strpart("abcdefg", 3, 2) == "de"
5728 strpart("abcdefg", -2, 4) == "ab"
5729 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00005730 strpart("abcdefg", 3) == "defg"
Bram Moolenaar071d4272004-06-13 20:20:40 +00005731< Note: To get the first character, {start} must be 0. For
5732 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00005733 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005734<
Bram Moolenaar677ee682005-01-27 14:41:15 +00005735strridx({haystack}, {needle} [, {start}]) *strridx()*
5736 The result is a Number, which gives the byte index in
5737 {haystack} of the last occurrence of the String {needle}.
5738 When {start} is specified, matches beyond this index are
5739 ignored. This can be used to find a match before a previous
5740 match: >
5741 :let lastcomma = strridx(line, ",")
5742 :let comma2 = strridx(line, ",", lastcomma - 1)
5743< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005744 For pattern searches use |match()|.
5745 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00005746 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005747 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005748 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005749< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005750 When used with a single character it works similar to the C
5751 function strrchr().
5752
Bram Moolenaar071d4272004-06-13 20:20:40 +00005753strtrans({expr}) *strtrans()*
5754 The result is a String, which is {expr} with all unprintable
5755 characters translated into printable characters |'isprint'|.
5756 Like they are shown in a window. Example: >
5757 echo strtrans(@a)
5758< This displays a newline in register a as "^@" instead of
5759 starting a new line.
5760
Bram Moolenaar72597a52010-07-18 15:31:08 +02005761strwidth({expr}) *strwidth()*
5762 The result is a Number, which is the number of display cells
5763 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02005764 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02005765 When {expr} contains characters with East Asian Width Class
5766 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02005767 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02005768
Bram Moolenaar071d4272004-06-13 20:20:40 +00005769submatch({nr}) *submatch()*
Bram Moolenaar251e1912011-06-19 05:09:16 +02005770 Only for an expression in a |:substitute| command or
5771 substitute() function.
5772 Returns the {nr}'th submatch of the matched text. When {nr}
5773 is 0 the whole matched text is returned.
5774 Also see |sub-replace-expression|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005775 Example: >
5776 :s/\d\+/\=submatch(0) + 1/
5777< This finds the first number in the line and adds one to it.
5778 A line break is included as a newline character.
5779
5780substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
5781 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02005782 the first match of {pat} is replaced with {sub}.
5783 When {flags} is "g", all matches of {pat} in {expr} are
5784 replaced. Otherwise {flags} should be "".
5785
5786 This works like the ":substitute" command (without any flags).
5787 But the matching with {pat} is always done like the 'magic'
5788 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01005789 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
5790 if you want to ignore or match case and ignore 'ignorecase'.
5791 'smartcase' is not used. See |string-match| for how {pat} is
5792 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02005793
5794 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005795 Note that some codes in {sub} have a special meaning
Bram Moolenaar446cb832008-06-24 21:56:24 +00005796 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00005797 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02005798
Bram Moolenaar071d4272004-06-13 20:20:40 +00005799 When {pat} does not match in {expr}, {expr} is returned
5800 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02005801
Bram Moolenaar071d4272004-06-13 20:20:40 +00005802 Example: >
5803 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
5804< This removes the last component of the 'path' option. >
5805 :echo substitute("testing", ".*", "\\U\\0", "")
5806< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02005807
5808 When {sub} starts with "\=", the remainder is interpreted as
5809 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02005810 :echo substitute(s, '%\(\x\x\)',
5811 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00005812
Bram Moolenaar47136d72004-10-12 20:02:24 +00005813synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005814 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00005815 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005816 The syntax ID can be used with |synIDattr()| and
5817 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00005818
Bram Moolenaar47136d72004-10-12 20:02:24 +00005819 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00005820 line. 'synmaxcol' applies, in a longer line zero is returned.
5821
Bram Moolenaar071d4272004-06-13 20:20:40 +00005822 When {trans} is non-zero, transparent items are reduced to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005823 item that they reveal. This is useful when wanting to know
Bram Moolenaar071d4272004-06-13 20:20:40 +00005824 the effective color. When {trans} is zero, the transparent
5825 item is returned. This is useful when wanting to know which
5826 syntax item is effective (e.g. inside parens).
5827 Warning: This function can be very slow. Best speed is
5828 obtained by going through the file in forward direction.
5829
5830 Example (echoes the name of the syntax item under the cursor): >
5831 :echo synIDattr(synID(line("."), col("."), 1), "name")
5832<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02005833
Bram Moolenaar071d4272004-06-13 20:20:40 +00005834synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
5835 The result is a String, which is the {what} attribute of
5836 syntax ID {synID}. This can be used to obtain information
5837 about a syntax item.
5838 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar446cb832008-06-24 21:56:24 +00005839 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00005840 used, the attributes for the currently active highlighting are
5841 used (GUI, cterm or term).
5842 Use synIDtrans() to follow linked highlight groups.
5843 {what} result
5844 "name" the name of the syntax item
5845 "fg" foreground color (GUI: color name used to set
5846 the color, cterm: color number as a string,
5847 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00005848 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01005849 "font" font name (only available in the GUI)
5850 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00005851 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005852 "fg#" like "fg", but for the GUI and the GUI is
5853 running the name in "#RRGGBB" form
5854 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00005855 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00005856 "bold" "1" if bold
5857 "italic" "1" if italic
5858 "reverse" "1" if reverse
5859 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01005860 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00005861 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005862 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00005863
5864 Example (echoes the color of the syntax item under the
5865 cursor): >
5866 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
5867<
5868synIDtrans({synID}) *synIDtrans()*
5869 The result is a Number, which is the translated syntax ID of
5870 {synID}. This is the syntax group ID of what is being used to
5871 highlight the character. Highlight links given with
5872 ":highlight link" are followed.
5873
Bram Moolenaar483c5d82010-10-20 18:45:33 +02005874synconcealed({lnum}, {col}) *synconcealed()*
5875 The result is a List. The first item in the list is 0 if the
5876 character at the position {lnum} and {col} is not part of a
5877 concealable region, 1 if it is. The second item in the list is
5878 a string. If the first item is 1, the second item contains the
5879 text which will be displayed in place of the concealed text,
5880 depending on the current setting of 'conceallevel'. The third
5881 and final item in the list is a unique number representing the
5882 specific syntax region matched. This allows detection of the
5883 beginning of a new concealable region if there are two
5884 consecutive regions with the same replacement character.
5885 For an example use see $VIMRUNTIME/syntax/2html.vim .
5886
5887
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00005888synstack({lnum}, {col}) *synstack()*
5889 Return a |List|, which is the stack of syntax items at the
5890 position {lnum} and {col} in the current window. Each item in
5891 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00005892 The first item in the List is the outer region, following are
5893 items contained in that one. The last one is what |synID()|
5894 returns, unless not the whole item is highlighted or it is a
5895 transparent item.
5896 This function is useful for debugging a syntax file.
5897 Example that shows the syntax stack under the cursor: >
5898 for id in synstack(line("."), col("."))
5899 echo synIDattr(id, "name")
5900 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02005901< When the position specified with {lnum} and {col} is invalid
5902 nothing is returned. The position just after the last
5903 character in a line and the first column in an empty line are
5904 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00005905
Bram Moolenaarc0197e22004-09-13 20:26:32 +00005906system({expr} [, {input}]) *system()* *E677*
5907 Get the output of the shell command {expr}.
5908 When {input} is given, this string is written to a file and
5909 passed as stdin to the command. The string is written as-is,
5910 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00005911 yourself. Pipes are not used.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005912 Note: Use |shellescape()| to escape special characters in a
5913 command argument. Newlines in {expr} may cause the command to
5914 fail. The characters in 'shellquote' and 'shellxquote' may
5915 also cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005916 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005917
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005918 The result is a String. Example: >
5919 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar071d4272004-06-13 20:20:40 +00005920
5921< To make the result more system-independent, the shell output
5922 is filtered to replace <CR> with <NL> for Macintosh, and
5923 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02005924 To avoid the string being truncated at a NUL, all NUL
5925 characters are replaced with SOH (0x01).
5926
Bram Moolenaar071d4272004-06-13 20:20:40 +00005927 The command executed is constructed using several options:
5928 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
5929 ({tmp} is an automatically generated file name).
5930 For Unix and OS/2 braces are put around {expr} to allow for
5931 concatenated commands.
5932
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005933 The command will be executed in "cooked" mode, so that a
5934 CTRL-C will interrupt the command (on Unix at least).
5935
Bram Moolenaar071d4272004-06-13 20:20:40 +00005936 The resulting error code can be found in |v:shell_error|.
5937 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00005938
5939 Note that any wrong value in the options mentioned above may
5940 make the function fail. It has also been reported to fail
5941 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005942 Unlike ":!cmd" there is no automatic check for changed files.
5943 Use |:checktime| to force a check.
5944
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005945
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005946tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005947 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005948 buffer associated with each window in the current tab page.
5949 {arg} specifies the number of tab page to be used. When
5950 omitted the current tab page is used.
5951 When {arg} is invalid the number zero is returned.
5952 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005953 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005954 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005955 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005956 endfor
5957< Note that a buffer may appear in more than one window.
5958
5959
5960tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00005961 The result is a Number, which is the number of the current
5962 tab page. The first tab page has number 1.
5963 When the optional argument is "$", the number of the last tab
5964 page is returned (the tab page count).
5965 The number can be used with the |:tab| command.
5966
5967
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005968tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02005969 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005970 {tabarg} specifies the number of tab page to be used.
5971 {arg} is used like with |winnr()|:
5972 - When omitted the current window number is returned. This is
5973 the window which will be used when going to this tab page.
5974 - When "$" the number of windows is returned.
5975 - When "#" the previous window nr is returned.
5976 Useful examples: >
5977 tabpagewinnr(1) " current window of tab page 1
5978 tabpagewinnr(4, '$') " number of windows in tab page 4
5979< When {tabarg} is invalid zero is returned.
5980
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00005981 *tagfiles()*
5982tagfiles() Returns a |List| with the file names used to search for tags
5983 for the current buffer. This is the 'tags' option expanded.
5984
5985
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005986taglist({expr}) *taglist()*
5987 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00005988 Each list item is a dictionary with at least the following
5989 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00005990 name Name of the tag.
5991 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005992 defined. It is either relative to the
5993 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005994 cmd Ex command used to locate the tag in
5995 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00005996 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005997 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005998 kind values. Only available when
5999 using a tags file generated by
6000 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00006001 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006002 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006003 More entries may be present, depending on the content of the
6004 tags file: access, implementation, inherits and signature.
6005 Refer to the ctags documentation for information about these
6006 fields. For C code the fields "struct", "class" and "enum"
6007 may appear, they give the name of the entity the tag is
6008 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006009
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00006010 The ex-command 'cmd' can be either an ex search pattern, a
6011 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006012
6013 If there are no matching tags, then an empty list is returned.
6014
6015 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01006016 used in {expr}. This also make the function work faster.
6017 Refer to |tag-regexp| for more information about the tag
6018 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006019
6020 Refer to |'tags'| for information about how the tags file is
6021 located by Vim. Refer to |tags-file-format| for the format of
6022 the tags file generated by the different ctags tools.
6023
Bram Moolenaar071d4272004-06-13 20:20:40 +00006024tempname() *tempname()* *temp-file-name*
6025 The result is a String, which is the name of a file that
Bram Moolenaar446cb832008-06-24 21:56:24 +00006026 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar071d4272004-06-13 20:20:40 +00006027 is different for at least 26 consecutive calls. Example: >
6028 :let tmpfile = tempname()
6029 :exe "redir > " . tmpfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006030< For Unix, the file will be in a private directory |tempfile|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006031 For MS-Windows forward slashes are used when the 'shellslash'
6032 option is set or when 'shellcmdflag' starts with '-'.
6033
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006034
6035tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006036 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006037 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006038 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006039 Examples: >
6040 :echo tan(10)
6041< 0.648361 >
6042 :echo tan(-4.01)
6043< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02006044 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006045
6046
6047tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006048 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006049 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006050 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006051 Examples: >
6052 :echo tanh(0.5)
6053< 0.462117 >
6054 :echo tanh(-1)
6055< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02006056 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006057
6058
Bram Moolenaar071d4272004-06-13 20:20:40 +00006059tolower({expr}) *tolower()*
6060 The result is a copy of the String given, with all uppercase
6061 characters turned into lowercase (just like applying |gu| to
6062 the string).
6063
6064toupper({expr}) *toupper()*
6065 The result is a copy of the String given, with all lowercase
6066 characters turned into uppercase (just like applying |gU| to
6067 the string).
6068
Bram Moolenaar8299df92004-07-10 09:47:34 +00006069tr({src}, {fromstr}, {tostr}) *tr()*
6070 The result is a copy of the {src} string with all characters
6071 which appear in {fromstr} replaced by the character in that
6072 position in the {tostr} string. Thus the first character in
6073 {fromstr} is translated into the first character in {tostr}
6074 and so on. Exactly like the unix "tr" command.
6075 This code also deals with multibyte characters properly.
6076
6077 Examples: >
6078 echo tr("hello there", "ht", "HT")
6079< returns "Hello THere" >
6080 echo tr("<blob>", "<>", "{}")
6081< returns "{blob}"
6082
Bram Moolenaar446cb832008-06-24 21:56:24 +00006083trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00006084 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00006085 equal to {expr} as a |Float| (truncate towards zero).
6086 {expr} must evaluate to a |Float| or a |Number|.
6087 Examples: >
6088 echo trunc(1.456)
6089< 1.0 >
6090 echo trunc(-5.456)
6091< -5.0 >
6092 echo trunc(4.0)
6093< 4.0
6094 {only available when compiled with the |+float| feature}
6095
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006096 *type()*
6097type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00006098 Number: 0
6099 String: 1
6100 Funcref: 2
6101 List: 3
6102 Dictionary: 4
Bram Moolenaar446cb832008-06-24 21:56:24 +00006103 Float: 5
Bram Moolenaar748bf032005-02-02 23:04:36 +00006104 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006105 :if type(myvar) == type(0)
6106 :if type(myvar) == type("")
6107 :if type(myvar) == type(function("tr"))
6108 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00006109 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00006110 :if type(myvar) == type(0.0)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006111
Bram Moolenaara17d4c12010-05-30 18:30:36 +02006112undofile({name}) *undofile()*
6113 Return the name of the undo file that would be used for a file
6114 with name {name} when writing. This uses the 'undodir'
6115 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02006116 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02006117 {name} is always expanded to the full path, since that is what
6118 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02006119 If {name} is empty undofile() returns an empty string, since a
6120 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02006121 Useful in combination with |:wundo| and |:rundo|.
6122 When compiled without the +persistent_undo option this always
6123 returns an empty string.
6124
Bram Moolenaara800b422010-06-27 01:15:55 +02006125undotree() *undotree()*
6126 Return the current state of the undo tree in a dictionary with
6127 the following items:
6128 "seq_last" The highest undo sequence number used.
6129 "seq_cur" The sequence number of the current position in
6130 the undo tree. This differs from "seq_last"
6131 when some changes were undone.
6132 "time_cur" Time last used for |:earlier| and related
6133 commands. Use |strftime()| to convert to
6134 something readable.
6135 "save_last" Number of the last file write. Zero when no
6136 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02006137 "save_cur" Number of the current position in the undo
6138 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02006139 "synced" Non-zero when the last undo block was synced.
6140 This happens when waiting from input from the
6141 user. See |undo-blocks|.
6142 "entries" A list of dictionaries with information about
6143 undo blocks.
6144
6145 The first item in the "entries" list is the oldest undo item.
6146 Each List item is a Dictionary with these items:
6147 "seq" Undo sequence number. Same as what appears in
6148 |:undolist|.
6149 "time" Timestamp when the change happened. Use
6150 |strftime()| to convert to something readable.
6151 "newhead" Only appears in the item that is the last one
6152 that was added. This marks the last change
6153 and where further changes will be added.
6154 "curhead" Only appears in the item that is the last one
6155 that was undone. This marks the current
6156 position in the undo tree, the block that will
6157 be used by a redo command. When nothing was
6158 undone after the last change this item will
6159 not appear anywhere.
6160 "save" Only appears on the last block before a file
6161 write. The number is the write count. The
6162 first write has number 1, the last one the
6163 "save_last" mentioned above.
6164 "alt" Alternate entry. This is again a List of undo
6165 blocks. Each item may again have an "alt"
6166 item.
6167
Bram Moolenaar677ee682005-01-27 14:41:15 +00006168values({dict}) *values()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006169 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006170 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006171
6172
Bram Moolenaar071d4272004-06-13 20:20:40 +00006173virtcol({expr}) *virtcol()*
6174 The result is a Number, which is the screen column of the file
6175 position given with {expr}. That is, the last screen position
6176 occupied by the character at that position, when the screen
6177 would be of unlimited width. When there is a <Tab> at the
6178 position, the returned Number will be the column at the end of
6179 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006180 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00006181 For the byte position use |col()|.
6182 For the use of {expr} see |col()|.
6183 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00006184 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006185 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02006186 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006187 When Virtual editing is active in the current mode, a position
6188 beyond the end of the line can be returned. |'virtualedit'|
6189 The accepted positions are:
6190 . the cursor position
6191 $ the end of the cursor line (the result is the
6192 number of displayed characters in the cursor line
6193 plus one)
6194 'x position of mark x (if the mark is not set, 0 is
6195 returned)
6196 Note that only marks in the current file can be used.
6197 Examples: >
6198 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
6199 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00006200 virtcol("'t") with text " there", with 't at 'h', returns 6
6201< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006202 A more advanced example that echoes the maximum length of
6203 all lines: >
6204 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
6205
Bram Moolenaar071d4272004-06-13 20:20:40 +00006206
6207visualmode([expr]) *visualmode()*
6208 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006209 used in the current buffer. Initially it returns an empty
6210 string, but once Visual mode has been used, it returns "v",
6211 "V", or "<CTRL-V>" (a single CTRL-V character) for
6212 character-wise, line-wise, or block-wise Visual mode
6213 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006214 Example: >
6215 :exe "normal " . visualmode()
6216< This enters the same Visual mode as before. It is also useful
6217 in scripts if you wish to act differently depending on the
6218 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006219 If Visual mode is active, use |mode()| to get the Visual mode
6220 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006221 *non-zero-arg*
6222 If [expr] is supplied and it evaluates to a non-zero Number or
6223 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaar446cb832008-06-24 21:56:24 +00006224 the old value is returned. Note that " " and "0" are also
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006225 non-empty strings, thus cause the mode to be cleared. A List,
6226 Dictionary or Float is not a Number or String, thus does not
6227 cause the mode to be cleared.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006228
Bram Moolenaar8738fc12013-02-20 17:59:11 +01006229wildmenumode() *wildmenumode()*
6230 Returns non-zero when the wildmenu is active and zero
6231 otherwise. See 'wildmenu' and 'wildmode'.
6232 This can be used in mappings to handle the 'wildcharm' option
6233 gracefully. (Makes only sense with |mapmode-c| mappings).
6234
6235 For example to make <c-j> work like <down> in wildmode, use: >
6236 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
6237<
6238 (Note, this needs the 'wildcharm' option set appropriately).
6239
6240
Bram Moolenaar071d4272004-06-13 20:20:40 +00006241 *winbufnr()*
6242winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006243 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00006244 the buffer in the current window is returned. When window
6245 {nr} doesn't exist, -1 is returned.
6246 Example: >
6247 :echo "The file in the current window is " . bufname(winbufnr(0))
6248<
6249 *wincol()*
6250wincol() The result is a Number, which is the virtual column of the
6251 cursor in the window. This is counting screen cells from the
6252 left side of the window. The leftmost column is one.
6253
6254winheight({nr}) *winheight()*
6255 The result is a Number, which is the height of window {nr}.
6256 When {nr} is zero, the height of the current window is
6257 returned. When window {nr} doesn't exist, -1 is returned.
6258 An existing window always has a height of zero or more.
6259 Examples: >
6260 :echo "The current window has " . winheight(0) . " lines."
6261<
6262 *winline()*
6263winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar446cb832008-06-24 21:56:24 +00006264 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00006265 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006266 If the cursor was moved the view on the file will be updated
6267 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006268
6269 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006270winnr([{arg}]) The result is a Number, which is the number of the current
6271 window. The top window has number 1.
6272 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006273 last window is returned (the window count). >
6274 let window_count = winnr('$')
6275< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006276 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006277 If there is no previous window or it is in another tab page 0
6278 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006279 The number can be used with |CTRL-W_w| and ":wincmd w"
6280 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006281 Also see |tabpagewinnr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006282
6283 *winrestcmd()*
6284winrestcmd() Returns a sequence of |:resize| commands that should restore
6285 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006286 are opened or closed and the current window and tab page is
6287 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006288 Example: >
6289 :let cmd = winrestcmd()
6290 :call MessWithWindowSizes()
6291 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006292<
6293 *winrestview()*
6294winrestview({dict})
6295 Uses the |Dictionary| returned by |winsaveview()| to restore
6296 the view of the current window.
6297 If you have changed the values the result is unpredictable.
6298 If the window size changed the result won't be the same.
6299
6300 *winsaveview()*
6301winsaveview() Returns a |Dictionary| that contains information to restore
6302 the view of the current window. Use |winrestview()| to
6303 restore the view.
6304 This is useful if you have a mapping that jumps around in the
6305 buffer and you want to go back to the original view.
6306 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00006307 option to temporarily switch off folding, so that folds are
6308 not opened when moving around.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006309 The return value includes:
6310 lnum cursor line number
6311 col cursor column
6312 coladd cursor column offset for 'virtualedit'
6313 curswant column for vertical movement
6314 topline first line in the window
6315 topfill filler lines, only in diff mode
6316 leftcol first column displayed
6317 skipcol columns skipped
6318 Note that no option values are saved.
6319
Bram Moolenaar071d4272004-06-13 20:20:40 +00006320
6321winwidth({nr}) *winwidth()*
6322 The result is a Number, which is the width of window {nr}.
6323 When {nr} is zero, the width of the current window is
6324 returned. When window {nr} doesn't exist, -1 is returned.
6325 An existing window always has a width of zero or more.
6326 Examples: >
6327 :echo "The current window has " . winwidth(0) . " columns."
6328 :if winwidth(0) <= 50
6329 : exe "normal 50\<C-W>|"
6330 :endif
6331<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006332 *writefile()*
6333writefile({list}, {fname} [, {binary}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006334 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006335 separated with a NL. Each list item must be a String or
6336 Number.
6337 When {binary} is equal to "b" binary mode is used: There will
6338 not be a NL after the last list item. An empty item at the
6339 end does cause the last line in the file to end in a NL.
6340 All NL characters are replaced with a NUL character.
6341 Inserting CR characters needs to be done before passing {list}
6342 to writefile().
6343 An existing file is overwritten, if possible.
6344 When the write fails -1 is returned, otherwise 0. There is an
6345 error message if the file can't be created or when writing
6346 fails.
6347 Also see |readfile()|.
6348 To copy a file byte for byte: >
6349 :let fl = readfile("foo", "b")
6350 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006351
6352
6353xor({expr}, {expr}) *xor()*
6354 Bitwise XOR on the two arguments. The arguments are converted
6355 to a number. A List, Dict or Float argument causes an error.
6356 Example: >
6357 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +01006358<
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006359
Bram Moolenaar071d4272004-06-13 20:20:40 +00006360
6361 *feature-list*
6362There are three types of features:
63631. Features that are only supported when they have been enabled when Vim
6364 was compiled |+feature-list|. Example: >
6365 :if has("cindent")
63662. Features that are only supported when certain conditions have been met.
6367 Example: >
6368 :if has("gui_running")
6369< *has-patch*
63703. Included patches. First check |v:version| for the version of Vim.
6371 Then the "patch123" feature means that patch 123 has been included for
6372 this version. Example (checking version 6.2.148 or later): >
6373 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006374< Note that it's possible for patch 147 to be omitted even though 148 is
6375 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006376
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02006377acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006378all_builtin_terms Compiled with all builtin terminals enabled.
6379amiga Amiga version of Vim.
6380arabic Compiled with Arabic support |Arabic|.
6381arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00006382autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006383balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00006384balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006385beos BeOS version of Vim.
6386browse Compiled with |:browse| support, and browse() will
6387 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +02006388browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006389builtin_terms Compiled with some builtin terminals.
6390byte_offset Compiled with support for 'o' in 'statusline'
6391cindent Compiled with 'cindent' support.
6392clientserver Compiled with remote invocation support |clientserver|.
6393clipboard Compiled with 'clipboard' support.
6394cmdline_compl Compiled with |cmdline-completion| support.
6395cmdline_hist Compiled with |cmdline-history| support.
6396cmdline_info Compiled with 'showcmd' and 'ruler' support.
6397comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006398compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006399cryptv Compiled with encryption support |encryption|.
6400cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006401debug Compiled with "DEBUG" defined.
6402dialog_con Compiled with console dialog support.
6403dialog_gui Compiled with GUI dialog support.
6404diff Compiled with |vimdiff| and 'diff' support.
6405digraphs Compiled with support for digraphs.
6406dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006407dos16 16 bits DOS version of Vim.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006408dos32 32 bits DOS (DJGPP) version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006409ebcdic Compiled on a machine with ebcdic character set.
6410emacs_tags Compiled with support for Emacs tags.
6411eval Compiled with expression evaluation support. Always
6412 true, of course!
6413ex_extra Compiled with extra Ex commands |+ex_extra|.
6414extra_search Compiled with support for |'incsearch'| and
6415 |'hlsearch'|
6416farsi Compiled with Farsi support |farsi|.
6417file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006418filterpipe When 'shelltemp' is off pipes are used for shell
6419 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00006420find_in_path Compiled with support for include file searches
6421 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006422float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006423fname_case Case in file names matters (for Amiga, MS-DOS, and
6424 Windows this is not present).
6425folding Compiled with |folding| support.
6426footer Compiled with GUI footer support. |gui-footer|
6427fork Compiled to use fork()/exec() instead of system().
6428gettext Compiled with message translation |multi-lang|
6429gui Compiled with GUI enabled.
6430gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006431gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006432gui_gtk Compiled with GTK+ GUI (any version).
6433gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
6434gui_mac Compiled with Macintosh GUI.
6435gui_motif Compiled with Motif GUI.
6436gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006437gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006438gui_win32 Compiled with MS Windows Win32 GUI.
6439gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006440hangul_input Compiled with Hangul input support. |hangul|
6441iconv Can use iconv() for conversion.
6442insert_expand Compiled with support for CTRL-X expansion commands in
6443 Insert mode.
6444jumplist Compiled with |jumplist| support.
6445keymap Compiled with 'keymap' support.
6446langmap Compiled with 'langmap' support.
6447libcall Compiled with |libcall()| support.
6448linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
6449 support.
6450lispindent Compiled with support for lisp indenting.
6451listcmds Compiled with commands for the buffer list |:files|
6452 and the argument list |arglist|.
6453localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02006454lua Compiled with Lua interface |Lua|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006455mac Macintosh version of Vim.
6456macunix Macintosh version of Vim, using Unix files (OS-X).
6457menu Compiled with support for |:menu|.
6458mksession Compiled with support for |:mksession|.
6459modify_fname Compiled with file name modifiers. |filename-modifiers|
6460mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006461mouse_dec Compiled with support for Dec terminal mouse.
6462mouse_gpm Compiled with support for gpm (Linux console mouse)
6463mouse_netterm Compiled with support for netterm mouse.
6464mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006465mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +02006466mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01006467mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006468mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006469mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00006470multi_byte Compiled with support for 'encoding'
6471multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006472multi_byte_ime Compiled with support for IME input method.
6473multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00006474mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02006475netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006476netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006477ole Compiled with OLE automation support for Win32.
6478os2 OS/2 version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006479path_extra Compiled with up/downwards search in 'path' and 'tags'
6480perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02006481persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006482postscript Compiled with PostScript file printing.
6483printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006484profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02006485python Compiled with Python 2.x interface. |has-python|
6486python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006487qnx QNX version of Vim.
6488quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00006489reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006490rightleft Compiled with 'rightleft' support.
6491ruby Compiled with Ruby interface |ruby|.
6492scrollbind Compiled with 'scrollbind' support.
6493showcmd Compiled with 'showcmd' support.
6494signs Compiled with |:sign| support.
6495smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006496sniff Compiled with SNiFF interface support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006497spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00006498startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006499statusline Compiled with support for 'statusline', 'rulerformat'
6500 and special formats of 'titlestring' and 'iconstring'.
6501sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006502syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006503syntax_items There are active syntax highlighting items for the
6504 current buffer.
6505system Compiled to use system() instead of fork()/exec().
6506tag_binary Compiled with binary searching in tags files
6507 |tag-binary-search|.
6508tag_old_static Compiled with support for old static tags
6509 |tag-old-static|.
6510tag_any_white Compiled with support for any white characters in tags
6511 files |tag-any-white|.
6512tcl Compiled with Tcl interface.
6513terminfo Compiled with terminfo instead of termcap.
6514termresponse Compiled with support for |t_RV| and |v:termresponse|.
6515textobjects Compiled with support for |text-objects|.
6516tgetent Compiled with tgetent support, able to use a termcap
6517 or terminfo file.
6518title Compiled with window title support |'title'|.
6519toolbar Compiled with support for |gui-toolbar|.
6520unix Unix version of Vim.
6521user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006522vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006523vim_starting True while initial source'ing takes place. |startup|
6524viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006525virtualedit Compiled with 'virtualedit' option.
6526visual Compiled with Visual mode.
6527visualextra Compiled with extra Visual mode commands.
6528 |blockwise-operators|.
6529vms VMS version of Vim.
6530vreplace Compiled with |gR| and |gr| commands.
6531wildignore Compiled with 'wildignore' option.
6532wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006533win16 Win16 version of Vim (MS-Windows 3.1).
Bram Moolenaard58e9292011-02-09 17:07:58 +01006534win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
6535 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006536win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006537win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006538win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006539winaltkeys Compiled with 'winaltkeys' option.
6540windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006541writebackup Compiled with 'writebackup' default on.
6542xfontset Compiled with X fontset support |xfontset|.
6543xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02006544xpm Compiled with pixmap support.
6545xpm_w32 Compiled with pixmap support for Win32. (Only for
6546 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006547xsmp Compiled with X session management support.
6548xsmp_interact Compiled with interactive X session management support.
6549xterm_clipboard Compiled with support for xterm clipboard.
6550xterm_save Compiled with support for saving and restoring the
6551 xterm screen.
6552x11 Compiled with X11 support.
6553
6554 *string-match*
6555Matching a pattern in a String
6556
6557A regexp pattern as explained at |pattern| is normally used to find a match in
6558the buffer lines. When a pattern is used to find a match in a String, almost
6559everything works in the same way. The difference is that a String is handled
6560like it is one line. When it contains a "\n" character, this is not seen as a
6561line break for the pattern. It can be matched with a "\n" in the pattern, or
6562with ".". Example: >
6563 :let a = "aaaa\nxxxx"
6564 :echo matchstr(a, "..\n..")
6565 aa
6566 xx
6567 :echo matchstr(a, "a.x")
6568 a
6569 x
6570
6571Don't forget that "^" will only match at the first character of the String and
6572"$" at the last character of the string. They don't match after or before a
6573"\n".
6574
6575==============================================================================
65765. Defining functions *user-functions*
6577
6578New functions can be defined. These can be called just like builtin
6579functions. The function executes a sequence of Ex commands. Normal mode
6580commands can be executed with the |:normal| command.
6581
6582The function name must start with an uppercase letter, to avoid confusion with
6583builtin functions. To prevent from using the same name in different scripts
6584avoid obvious, short names. A good habit is to start the function name with
6585the name of the script, e.g., "HTMLcolor()".
6586
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006587It's also possible to use curly braces, see |curly-braces-names|. And the
6588|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006589
6590 *local-function*
6591A function local to a script must start with "s:". A local script function
6592can only be called from within the script and from functions, user commands
6593and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006594function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00006595instead of "s:" when the mapping is expanded outside of the script.
6596
6597 *:fu* *:function* *E128* *E129* *E123*
6598:fu[nction] List all functions and their arguments.
6599
6600:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006601 {name} can also be a |Dictionary| entry that is a
6602 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006603 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006604
6605:fu[nction] /{pattern} List functions with a name matching {pattern}.
6606 Example that lists all functions ending with "File": >
6607 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00006608<
6609 *:function-verbose*
6610When 'verbose' is non-zero, listing a function will also display where it was
6611last defined. Example: >
6612
6613 :verbose function SetFileTypeSH
6614 function SetFileTypeSH(name)
6615 Last set from /usr/share/vim/vim-7.0/filetype.vim
6616<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00006617See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00006618
Bram Moolenaar15146672011-10-20 22:22:38 +02006619 *E124* *E125* *E853*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006620:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00006621 Define a new function by the name {name}. The name
6622 must be made of alphanumeric characters and '_', and
6623 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006624
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006625 {name} can also be a |Dictionary| entry that is a
6626 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006627 :function dict.init(arg)
Bram Moolenaar446cb832008-06-24 21:56:24 +00006628< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006629 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar446cb832008-06-24 21:56:24 +00006630 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006631 result is a |Funcref| to a numbered function. The
6632 function can only be used with a |Funcref| and will be
6633 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006634 *E127* *E122*
6635 When a function by this name already exists and [!] is
6636 not used an error message is given. When [!] is used,
6637 an existing function is silently replaced. Unless it
6638 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006639
6640 For the {arguments} see |function-argument|.
6641
Bram Moolenaar071d4272004-06-13 20:20:40 +00006642 *a:firstline* *a:lastline*
6643 When the [range] argument is added, the function is
6644 expected to take care of a range itself. The range is
6645 passed as "a:firstline" and "a:lastline". If [range]
6646 is excluded, ":{range}call" will call the function for
6647 each line in the range, with the cursor on the start
6648 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006649 The cursor is still moved to the first line of the
6650 range, as is the case with all Ex commands.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006651
Bram Moolenaar071d4272004-06-13 20:20:40 +00006652 When the [abort] argument is added, the function will
6653 abort as soon as an error is detected.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006654
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006655 When the [dict] argument is added, the function must
Bram Moolenaar446cb832008-06-24 21:56:24 +00006656 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006657 local variable "self" will then be set to the
6658 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006659
Bram Moolenaar446cb832008-06-24 21:56:24 +00006660 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00006661 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00006662 will not be changed by the function. This also
6663 implies that the effect of |:nohlsearch| is undone
6664 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00006665
Bram Moolenaar071d4272004-06-13 20:20:40 +00006666 *:endf* *:endfunction* *E126* *E193*
6667:endf[unction] The end of a function definition. Must be on a line
6668 by its own, without other commands.
6669
6670 *:delf* *:delfunction* *E130* *E131*
6671:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006672 {name} can also be a |Dictionary| entry that is a
6673 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006674 :delfunc dict.init
Bram Moolenaar446cb832008-06-24 21:56:24 +00006675< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006676 function is deleted if there are no more references to
6677 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006678 *:retu* *:return* *E133*
6679:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
6680 evaluated and returned as the result of the function.
6681 If "[expr]" is not given, the number 0 is returned.
6682 When a function ends without an explicit ":return",
6683 the number 0 is returned.
6684 Note that there is no check for unreachable lines,
6685 thus there is no warning if commands follow ":return".
6686
6687 If the ":return" is used after a |:try| but before the
6688 matching |:finally| (if present), the commands
6689 following the ":finally" up to the matching |:endtry|
6690 are executed first. This process applies to all
6691 nested ":try"s inside the function. The function
6692 returns at the outermost ":endtry".
6693
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006694 *function-argument* *a:var*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006695An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006696be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006697 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006698Up to 20 arguments can be given, separated by commas. After the named
6699arguments an argument "..." can be specified, which means that more arguments
6700may optionally be following. In the function the extra arguments can be used
6701as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006702can be 0). "a:000" is set to a |List| that contains these arguments. Note
6703that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006704 *E742*
6705The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006706However, if a |List| or |Dictionary| is used, you can change their contents.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006707Thus you can pass a |List| to a function and have the function add an item to
6708it. If you want to make sure the function cannot change a |List| or
6709|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006710
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006711When not using "...", the number of arguments in a function call must be equal
6712to the number of named arguments. When using "...", the number of arguments
6713may be larger.
6714
6715It is also possible to define a function without any arguments. You must
6716still supply the () then. The body of the function follows in the next lines,
6717until the matching |:endfunction|. It is allowed to define another function
6718inside a function body.
6719
6720 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006721Inside a function variables can be used. These are local variables, which
6722will disappear when the function returns. Global variables need to be
6723accessed with "g:".
6724
6725Example: >
6726 :function Table(title, ...)
6727 : echohl Title
6728 : echo a:title
6729 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00006730 : echo a:0 . " items:"
6731 : for s in a:000
6732 : echon ' ' . s
6733 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00006734 :endfunction
6735
6736This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00006737 call Table("Table", "line1", "line2")
6738 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006739
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006740To return more than one value, return a |List|: >
6741 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006742 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006743 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00006744 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006745 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00006746 :endfunction
6747
6748This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006749 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006750 :if success == "ok"
6751 : echo div
6752 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006753<
Bram Moolenaar39f05632006-03-19 22:15:26 +00006754 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006755:[range]cal[l] {name}([arguments])
6756 Call a function. The name of the function and its arguments
6757 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006758 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006759 Without a range and for functions that accept a range, the
6760 function is called once. When a range is given the cursor is
6761 positioned at the start of the first line before executing the
6762 function.
6763 When a range is given and the function doesn't handle it
6764 itself, the function is executed for each line in the range,
6765 with the cursor in the first column of that line. The cursor
6766 is left at the last line (possibly moved by the last function
Bram Moolenaar446cb832008-06-24 21:56:24 +00006767 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00006768 this works:
6769 *function-range-example* >
6770 :function Mynumber(arg)
6771 : echo line(".") . " " . a:arg
6772 :endfunction
6773 :1,5call Mynumber(getline("."))
6774<
6775 The "a:firstline" and "a:lastline" are defined anyway, they
6776 can be used to do something different at the start or end of
6777 the range.
6778
6779 Example of a function that handles the range itself: >
6780
6781 :function Cont() range
6782 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
6783 :endfunction
6784 :4,8call Cont()
6785<
6786 This function inserts the continuation character "\" in front
6787 of all the lines in the range, except the first one.
6788
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006789 When the function returns a composite value it can be further
6790 dereferenced, but the range will not be used then. Example: >
6791 :4,8call GetDict().method()
6792< Here GetDict() gets the range but method() does not.
6793
Bram Moolenaar071d4272004-06-13 20:20:40 +00006794 *E132*
6795The recursiveness of user functions is restricted with the |'maxfuncdepth'|
6796option.
6797
Bram Moolenaar7c626922005-02-07 22:01:03 +00006798
6799AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00006800 *autoload-functions*
6801When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00006802only when they are used. There are two methods: with an autocommand and with
6803the "autoload" directory in 'runtimepath'.
6804
6805
6806Using an autocommand ~
6807
Bram Moolenaar05159a02005-02-26 23:04:13 +00006808This is introduced in the user manual, section |41.14|.
6809
Bram Moolenaar7c626922005-02-07 22:01:03 +00006810The autocommand is useful if you have a plugin that is a long Vim script file.
6811You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006812That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00006813again, setting a variable to skip the |:finish| command.
6814
6815Use the FuncUndefined autocommand event with a pattern that matches the
6816function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006817
6818 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
6819
6820The file "~/vim/bufnetfuncs.vim" should then define functions that start with
6821"BufNet". Also see |FuncUndefined|.
6822
Bram Moolenaar7c626922005-02-07 22:01:03 +00006823
6824Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006825 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006826This is introduced in the user manual, section |41.15|.
6827
Bram Moolenaar7c626922005-02-07 22:01:03 +00006828Using a script in the "autoload" directory is simpler, but requires using
6829exactly the right file name. A function that can be autoloaded has a name
6830like this: >
6831
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006832 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00006833
6834When such a function is called, and it is not defined yet, Vim will search the
6835"autoload" directories in 'runtimepath' for a script file called
6836"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
6837then define the function like this: >
6838
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006839 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00006840 echo "Done!"
6841 endfunction
6842
Bram Moolenaar60a795a2005-09-16 21:55:43 +00006843The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00006844exactly, and the defined function must have the name exactly as it will be
6845called.
6846
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006847It is possible to use subdirectories. Every # in the function name works like
6848a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00006849
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006850 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00006851
6852Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
6853
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006854This also works when reading a variable that has not been set yet: >
6855
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006856 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006857
Bram Moolenaara5792f52005-11-23 21:25:05 +00006858However, when the autoload script was already loaded it won't be loaded again
6859for an unknown variable.
6860
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006861When assigning a value to such a variable nothing special happens. This can
6862be used to pass settings to the autoload script before it's loaded: >
6863
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006864 :let foo#bar#toggle = 1
6865 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006866
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006867Note that when you make a mistake and call a function that is supposed to be
6868defined in an autoload script, but the script doesn't actually define the
6869function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006870And you will get an error message every time.
6871
6872Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006873other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006874Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00006875
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006876Hint: If you distribute a bunch of scripts you can pack them together with the
6877|vimball| utility. Also read the user manual |distribute-script|.
6878
Bram Moolenaar071d4272004-06-13 20:20:40 +00006879==============================================================================
68806. Curly braces names *curly-braces-names*
6881
Bram Moolenaar84f72352012-03-11 15:57:40 +01006882In most places where you can use a variable, you can use a "curly braces name"
6883variable. This is a regular variable name with one or more expressions
6884wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006885 my_{adjective}_variable
6886
6887When Vim encounters this, it evaluates the expression inside the braces, puts
6888that in place of the expression, and re-interprets the whole as a variable
6889name. So in the above example, if the variable "adjective" was set to
6890"noisy", then the reference would be to "my_noisy_variable", whereas if
6891"adjective" was set to "quiet", then it would be to "my_quiet_variable".
6892
6893One application for this is to create a set of variables governed by an option
Bram Moolenaar446cb832008-06-24 21:56:24 +00006894value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006895 echo my_{&background}_message
6896
6897would output the contents of "my_dark_message" or "my_light_message" depending
6898on the current value of 'background'.
6899
6900You can use multiple brace pairs: >
6901 echo my_{adverb}_{adjective}_message
6902..or even nest them: >
6903 echo my_{ad{end_of_word}}_message
6904where "end_of_word" is either "verb" or "jective".
6905
6906However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006907variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006908 :let foo='a + b'
6909 :echo c{foo}d
6910.. since the result of expansion is "ca + bd", which is not a variable name.
6911
6912 *curly-braces-function-names*
6913You can call and define functions by an evaluated name in a similar way.
6914Example: >
6915 :let func_end='whizz'
6916 :call my_func_{func_end}(parameter)
6917
6918This would call the function "my_func_whizz(parameter)".
6919
Bram Moolenaar84f72352012-03-11 15:57:40 +01006920This does NOT work: >
6921 :let i = 3
6922 :let @{i} = '' " error
6923 :echo @{i} " error
6924
Bram Moolenaar071d4272004-06-13 20:20:40 +00006925==============================================================================
69267. Commands *expression-commands*
6927
6928:let {var-name} = {expr1} *:let* *E18*
6929 Set internal variable {var-name} to the result of the
6930 expression {expr1}. The variable will get the type
6931 from the {expr}. If {var-name} didn't exist yet, it
6932 is created.
6933
Bram Moolenaar13065c42005-01-08 16:08:21 +00006934:let {var-name}[{idx}] = {expr1} *E689*
6935 Set a list item to the result of the expression
6936 {expr1}. {var-name} must refer to a list and {idx}
6937 must be a valid index in that list. For nested list
6938 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006939 This cannot be used to add an item to a |List|.
6940 This cannot be used to set a byte in a String. You
6941 can do that like this: >
6942 :let var = var[0:2] . 'X' . var[4:]
6943<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006944 *E711* *E719*
6945:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006946 Set a sequence of items in a |List| to the result of
6947 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006948 correct number of items.
6949 {idx1} can be omitted, zero is used instead.
6950 {idx2} can be omitted, meaning the end of the list.
6951 When the selected range of items is partly past the
6952 end of the list, items will be added.
6953
Bram Moolenaar748bf032005-02-02 23:04:36 +00006954 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006955:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
6956:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
6957:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
6958 These fail if {var} was not set yet and when the type
6959 of {var} and {expr1} don't fit the operator.
6960
6961
Bram Moolenaar071d4272004-06-13 20:20:40 +00006962:let ${env-name} = {expr1} *:let-environment* *:let-$*
6963 Set environment variable {env-name} to the result of
6964 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006965:let ${env-name} .= {expr1}
6966 Append {expr1} to the environment variable {env-name}.
6967 If the environment variable didn't exist yet this
6968 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006969
6970:let @{reg-name} = {expr1} *:let-register* *:let-@*
6971 Write the result of the expression {expr1} in register
6972 {reg-name}. {reg-name} must be a single letter, and
6973 must be the name of a writable register (see
6974 |registers|). "@@" can be used for the unnamed
6975 register, "@/" for the search pattern.
6976 If the result of {expr1} ends in a <CR> or <NL>, the
6977 register will be linewise, otherwise it will be set to
6978 characterwise.
6979 This can be used to clear the last search pattern: >
6980 :let @/ = ""
6981< This is different from searching for an empty string,
6982 that would match everywhere.
6983
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006984:let @{reg-name} .= {expr1}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006985 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006986 register was empty it's like setting it to {expr1}.
6987
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006988:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006989 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006990 expression {expr1}. A String or Number value is
6991 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006992 For an option local to a window or buffer the effect
6993 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00006994 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006995 Example: >
6996 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00006997
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006998:let &{option-name} .= {expr1}
6999 For a string option: Append {expr1} to the value.
7000 Does not insert a comma like |:set+=|.
7001
7002:let &{option-name} += {expr1}
7003:let &{option-name} -= {expr1}
7004 For a number or boolean option: Add or subtract
7005 {expr1}.
7006
Bram Moolenaar071d4272004-06-13 20:20:40 +00007007:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007008:let &l:{option-name} .= {expr1}
7009:let &l:{option-name} += {expr1}
7010:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007011 Like above, but only set the local value of an option
7012 (if there is one). Works like |:setlocal|.
7013
7014:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007015:let &g:{option-name} .= {expr1}
7016:let &g:{option-name} += {expr1}
7017:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007018 Like above, but only set the global value of an option
7019 (if there is one). Works like |:setglobal|.
7020
Bram Moolenaar13065c42005-01-08 16:08:21 +00007021:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007022 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007023 the list is assigned to {name1}, the second item to
7024 {name2}, etc.
7025 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007026 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007027 Each name can be one of the items of the ":let"
7028 command as mentioned above.
7029 Example: >
7030 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007031< Detail: {expr1} is evaluated first, then the
7032 assignments are done in sequence. This matters if
7033 {name2} depends on {name1}. Example: >
7034 :let x = [0, 1]
7035 :let i = 0
7036 :let [i, x[i]] = [1, 2]
7037 :echo x
7038< The result is [0, 2].
7039
7040:let [{name1}, {name2}, ...] .= {expr1}
7041:let [{name1}, {name2}, ...] += {expr1}
7042:let [{name1}, {name2}, ...] -= {expr1}
7043 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007044 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007045
7046:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007047 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007048 items than there are names. A list of the remaining
7049 items is assigned to {lastname}. If there are no
7050 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007051 Example: >
7052 :let [a, b; rest] = ["aval", "bval", 3, 4]
7053<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007054:let [{name}, ..., ; {lastname}] .= {expr1}
7055:let [{name}, ..., ; {lastname}] += {expr1}
7056:let [{name}, ..., ; {lastname}] -= {expr1}
7057 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007058 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02007059
7060 *E121*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007061:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00007062 variable names may be given. Special names recognized
7063 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00007064 g: global variables
7065 b: local buffer variables
7066 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007067 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00007068 s: script-local variables
7069 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00007070 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007071
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007072:let List the values of all variables. The type of the
7073 variable is indicated before the value:
7074 <nothing> String
7075 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007076 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00007077
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007078
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007079:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007080 Remove the internal variable {name}. Several variable
7081 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007082 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007083 With [!] no error message is given for non-existing
7084 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007085 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00007086 :unlet list[3] " remove fourth item
7087 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007088< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00007089 :unlet dict['two']
7090 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00007091< This is especially useful to clean up used global
7092 variables and script-local variables (these are not
7093 deleted when the script ends). Function-local
7094 variables are automatically deleted when the function
7095 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007096
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007097:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
7098 Lock the internal variable {name}. Locking means that
7099 it can no longer be changed (until it is unlocked).
7100 A locked variable can be deleted: >
7101 :lockvar v
7102 :let v = 'asdf' " fails!
7103 :unlet v
7104< *E741*
7105 If you try to change a locked variable you get an
7106 error message: "E741: Value of {name} is locked"
7107
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007108 [depth] is relevant when locking a |List| or
7109 |Dictionary|. It specifies how deep the locking goes:
7110 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007111 cannot add or remove items, but can
7112 still change their values.
7113 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007114 the items. If an item is a |List| or
7115 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007116 items, but can still change the
7117 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007118 3 Like 2 but for the |List| /
7119 |Dictionary| in the |List| /
7120 |Dictionary|, one level deeper.
7121 The default [depth] is 2, thus when {name} is a |List|
7122 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007123 *E743*
7124 For unlimited depth use [!] and omit [depth].
7125 However, there is a maximum depth of 100 to catch
7126 loops.
7127
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007128 Note that when two variables refer to the same |List|
7129 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007130 locked when used through the other variable.
7131 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007132 :let l = [0, 1, 2, 3]
7133 :let cl = l
7134 :lockvar l
7135 :let cl[1] = 99 " won't work!
7136< You may want to make a copy of a list to avoid this.
7137 See |deepcopy()|.
7138
7139
7140:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
7141 Unlock the internal variable {name}. Does the
7142 opposite of |:lockvar|.
7143
7144
Bram Moolenaar071d4272004-06-13 20:20:40 +00007145:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
7146:en[dif] Execute the commands until the next matching ":else"
7147 or ":endif" if {expr1} evaluates to non-zero.
7148
7149 From Vim version 4.5 until 5.0, every Ex command in
7150 between the ":if" and ":endif" is ignored. These two
7151 commands were just to allow for future expansions in a
7152 backwards compatible way. Nesting was allowed. Note
7153 that any ":else" or ":elseif" was ignored, the "else"
7154 part was not executed either.
7155
7156 You can use this to remain compatible with older
7157 versions: >
7158 :if version >= 500
7159 : version-5-specific-commands
7160 :endif
7161< The commands still need to be parsed to find the
7162 "endif". Sometimes an older Vim has a problem with a
7163 new command. For example, ":silent" is recognized as
7164 a ":substitute" command. In that case ":execute" can
7165 avoid problems: >
7166 :if version >= 600
7167 : execute "silent 1,$delete"
7168 :endif
7169<
7170 NOTE: The ":append" and ":insert" commands don't work
7171 properly in between ":if" and ":endif".
7172
7173 *:else* *:el* *E581* *E583*
7174:el[se] Execute the commands until the next matching ":else"
7175 or ":endif" if they previously were not being
7176 executed.
7177
7178 *:elseif* *:elsei* *E582* *E584*
7179:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
7180 is no extra ":endif".
7181
7182:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007183 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007184:endw[hile] Repeat the commands between ":while" and ":endwhile",
7185 as long as {expr1} evaluates to non-zero.
7186 When an error is detected from a command inside the
7187 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00007188 Example: >
7189 :let lnum = 1
7190 :while lnum <= line("$")
7191 :call FixLine(lnum)
7192 :let lnum = lnum + 1
7193 :endwhile
7194<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007195 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00007196 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007197
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007198:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00007199:endfo[r] *:endfo* *:endfor*
7200 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007201 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007202 value of each item.
7203 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00007204 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00007205 Changing {list} inside the loop affects what items are
7206 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007207 :for item in copy(mylist)
7208< When not making a copy, Vim stores a reference to the
7209 next item in the list, before executing the commands
Bram Moolenaar446cb832008-06-24 21:56:24 +00007210 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007211 removed without effect. Removing any later item means
7212 it will not be found. Thus the following example
7213 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007214 for item in mylist
7215 call remove(mylist, 0)
7216 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007217< Note that reordering the list (e.g., with sort() or
7218 reverse()) may have unexpected effects.
7219 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00007220 identical to avoid errors for the type of {var}
7221 changing. Unlet the variable at the end of the loop
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007222 to allow multiple item types: >
7223 for item in ["foo", ["bar"]]
7224 echo item
7225 unlet item " E706 without this
7226 endfor
Bram Moolenaar12805862005-01-05 22:16:17 +00007227
Bram Moolenaar12805862005-01-05 22:16:17 +00007228:for [{var1}, {var2}, ...] in {listlist}
7229:endfo[r]
7230 Like ":for" above, but each item in {listlist} must be
7231 a list, of which each item is assigned to {var1},
7232 {var2}, etc. Example: >
7233 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
7234 :echo getline(lnum)[col]
7235 :endfor
7236<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007237 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00007238:con[tinue] When used inside a ":while" or ":for" loop, jumps back
7239 to the start of the loop.
7240 If it is used after a |:try| inside the loop but
7241 before the matching |:finally| (if present), the
7242 commands following the ":finally" up to the matching
7243 |:endtry| are executed first. This process applies to
7244 all nested ":try"s inside the loop. The outermost
7245 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007246
7247 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00007248:brea[k] When used inside a ":while" or ":for" loop, skips to
7249 the command after the matching ":endwhile" or
7250 ":endfor".
7251 If it is used after a |:try| inside the loop but
7252 before the matching |:finally| (if present), the
7253 commands following the ":finally" up to the matching
7254 |:endtry| are executed first. This process applies to
7255 all nested ":try"s inside the loop. The outermost
7256 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007257
7258:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
7259:endt[ry] Change the error handling for the commands between
7260 ":try" and ":endtry" including everything being
7261 executed across ":source" commands, function calls,
7262 or autocommand invocations.
7263
7264 When an error or interrupt is detected and there is
7265 a |:finally| command following, execution continues
7266 after the ":finally". Otherwise, or when the
7267 ":endtry" is reached thereafter, the next
7268 (dynamically) surrounding ":try" is checked for
7269 a corresponding ":finally" etc. Then the script
7270 processing is terminated. (Whether a function
7271 definition has an "abort" argument does not matter.)
7272 Example: >
7273 :try | edit too much | finally | echo "cleanup" | endtry
7274 :echo "impossible" " not reached, script terminated above
7275<
7276 Moreover, an error or interrupt (dynamically) inside
7277 ":try" and ":endtry" is converted to an exception. It
7278 can be caught as if it were thrown by a |:throw|
7279 command (see |:catch|). In this case, the script
7280 processing is not terminated.
7281
7282 The value "Vim:Interrupt" is used for an interrupt
7283 exception. An error in a Vim command is converted
7284 to a value of the form "Vim({command}):{errmsg}",
7285 other errors are converted to a value of the form
7286 "Vim:{errmsg}". {command} is the full command name,
7287 and {errmsg} is the message that is displayed if the
7288 error exception is not caught, always beginning with
7289 the error number.
7290 Examples: >
7291 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
7292 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
7293<
7294 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007295:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007296 |:finally|, or |:endtry| that belongs to the same
7297 |:try| as the ":catch" are executed when an exception
7298 matching {pattern} is being thrown and has not yet
7299 been caught by a previous ":catch". Otherwise, these
7300 commands are skipped.
7301 When {pattern} is omitted all errors are caught.
7302 Examples: >
7303 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
7304 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
7305 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
7306 :catch /^Vim(write):/ " catch all errors in :write
7307 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
7308 :catch /my-exception/ " catch user exception
7309 :catch /.*/ " catch everything
7310 :catch " same as /.*/
7311<
7312 Another character can be used instead of / around the
7313 {pattern}, so long as it does not have a special
7314 meaning (e.g., '|' or '"') and doesn't occur inside
7315 {pattern}.
7316 NOTE: It is not reliable to ":catch" the TEXT of
7317 an error message because it may vary in different
7318 locales.
7319
7320 *:fina* *:finally* *E606* *E607*
7321:fina[lly] The following commands until the matching |:endtry|
7322 are executed whenever the part between the matching
7323 |:try| and the ":finally" is left: either by falling
7324 through to the ":finally" or by a |:continue|,
7325 |:break|, |:finish|, or |:return|, or by an error or
7326 interrupt or exception (see |:throw|).
7327
7328 *:th* *:throw* *E608*
7329:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
7330 If the ":throw" is used after a |:try| but before the
7331 first corresponding |:catch|, commands are skipped
7332 until the first ":catch" matching {expr1} is reached.
7333 If there is no such ":catch" or if the ":throw" is
7334 used after a ":catch" but before the |:finally|, the
7335 commands following the ":finally" (if present) up to
7336 the matching |:endtry| are executed. If the ":throw"
7337 is after the ":finally", commands up to the ":endtry"
7338 are skipped. At the ":endtry", this process applies
7339 again for the next dynamically surrounding ":try"
7340 (which may be found in a calling function or sourcing
7341 script), until a matching ":catch" has been found.
7342 If the exception is not caught, the command processing
7343 is terminated.
7344 Example: >
7345 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01007346< Note that "catch" may need to be on a separate line
7347 for when an error causes the parsing to skip the whole
7348 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007349
7350 *:ec* *:echo*
7351:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
7352 first {expr1} starts on a new line.
7353 Also see |:comment|.
7354 Use "\n" to start a new line. Use "\r" to move the
7355 cursor to the first column.
7356 Uses the highlighting set by the |:echohl| command.
7357 Cannot be followed by a comment.
7358 Example: >
7359 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007360< *:echo-redraw*
7361 A later redraw may make the message disappear again.
7362 And since Vim mostly postpones redrawing until it's
7363 finished with a sequence of commands this happens
7364 quite often. To avoid that a command from before the
7365 ":echo" causes a redraw afterwards (redraws are often
7366 postponed until you type something), force a redraw
7367 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007368 :new | redraw | echo "there is a new window"
7369<
7370 *:echon*
7371:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
7372 |:comment|.
7373 Uses the highlighting set by the |:echohl| command.
7374 Cannot be followed by a comment.
7375 Example: >
7376 :echon "the value of 'shell' is " &shell
7377<
7378 Note the difference between using ":echo", which is a
7379 Vim command, and ":!echo", which is an external shell
7380 command: >
7381 :!echo % --> filename
7382< The arguments of ":!" are expanded, see |:_%|. >
7383 :!echo "%" --> filename or "filename"
7384< Like the previous example. Whether you see the double
7385 quotes or not depends on your 'shell'. >
7386 :echo % --> nothing
7387< The '%' is an illegal character in an expression. >
7388 :echo "%" --> %
7389< This just echoes the '%' character. >
7390 :echo expand("%") --> filename
7391< This calls the expand() function to expand the '%'.
7392
7393 *:echoh* *:echohl*
7394:echoh[l] {name} Use the highlight group {name} for the following
7395 |:echo|, |:echon| and |:echomsg| commands. Also used
7396 for the |input()| prompt. Example: >
7397 :echohl WarningMsg | echo "Don't panic!" | echohl None
7398< Don't forget to set the group back to "None",
7399 otherwise all following echo's will be highlighted.
7400
7401 *:echom* *:echomsg*
7402:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
7403 message in the |message-history|.
7404 Spaces are placed between the arguments as with the
7405 |:echo| command. But unprintable characters are
7406 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007407 The parsing works slightly different from |:echo|,
7408 more like |:execute|. All the expressions are first
7409 evaluated and concatenated before echoing anything.
7410 The expressions must evaluate to a Number or String, a
7411 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007412 Uses the highlighting set by the |:echohl| command.
7413 Example: >
7414 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007415< See |:echo-redraw| to avoid the message disappearing
7416 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007417 *:echoe* *:echoerr*
7418:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
7419 message in the |message-history|. When used in a
7420 script or function the line number will be added.
7421 Spaces are placed between the arguments as with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007422 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007423 the message is raised as an error exception instead
7424 (see |try-echoerr|).
7425 Example: >
7426 :echoerr "This script just failed!"
7427< If you just want a highlighted message use |:echohl|.
7428 And to get a beep: >
7429 :exe "normal \<Esc>"
7430<
7431 *:exe* *:execute*
7432:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007433 of {expr1} as an Ex command.
7434 Multiple arguments are concatenated, with a space in
7435 between. To avoid the extra space use the "."
7436 operator to concatenate strings into one argument.
7437 {expr1} is used as the processed command, command line
7438 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007439 Cannot be followed by a comment.
7440 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007441 :execute "buffer" nextbuf
7442 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007443<
7444 ":execute" can be used to append a command to commands
7445 that don't accept a '|'. Example: >
7446 :execute '!ls' | echo "theend"
7447
7448< ":execute" is also a nice way to avoid having to type
7449 control characters in a Vim script for a ":normal"
7450 command: >
7451 :execute "normal ixxx\<Esc>"
7452< This has an <Esc> character, see |expr-string|.
7453
Bram Moolenaar446cb832008-06-24 21:56:24 +00007454 Be careful to correctly escape special characters in
7455 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007456 for Vim commands, |shellescape()| for |:!| commands.
7457 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00007458 :execute "e " . fnameescape(filename)
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007459 :execute "!ls " . shellescape(expand('%:h'), 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00007460<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007461 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00007462 you cannot start or end a "while", "for" or "if"
7463 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007464 :execute 'while i > 5'
7465 :execute 'echo "test" | break'
7466<
7467 It is allowed to have a "while" or "if" command
7468 completely in the executed string: >
7469 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
7470<
7471
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007472 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007473 ":execute", ":echo" and ":echon" cannot be followed by
7474 a comment directly, because they see the '"' as the
7475 start of a string. But, you can use '|' followed by a
7476 comment. Example: >
7477 :echo "foo" | "this is a comment
7478
7479==============================================================================
74808. Exception handling *exception-handling*
7481
7482The Vim script language comprises an exception handling feature. This section
7483explains how it can be used in a Vim script.
7484
7485Exceptions may be raised by Vim on an error or on interrupt, see
7486|catch-errors| and |catch-interrupt|. You can also explicitly throw an
7487exception by using the ":throw" command, see |throw-catch|.
7488
7489
7490TRY CONDITIONALS *try-conditionals*
7491
7492Exceptions can be caught or can cause cleanup code to be executed. You can
7493use a try conditional to specify catch clauses (that catch exceptions) and/or
7494a finally clause (to be executed for cleanup).
7495 A try conditional begins with a |:try| command and ends at the matching
7496|:endtry| command. In between, you can use a |:catch| command to start
7497a catch clause, or a |:finally| command to start a finally clause. There may
7498be none or multiple catch clauses, but there is at most one finally clause,
7499which must not be followed by any catch clauses. The lines before the catch
7500clauses and the finally clause is called a try block. >
7501
7502 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00007503 : ...
7504 : ... TRY BLOCK
7505 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007506 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00007507 : ...
7508 : ... CATCH CLAUSE
7509 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007510 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00007511 : ...
7512 : ... CATCH CLAUSE
7513 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007514 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00007515 : ...
7516 : ... FINALLY CLAUSE
7517 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007518 :endtry
7519
7520The try conditional allows to watch code for exceptions and to take the
7521appropriate actions. Exceptions from the try block may be caught. Exceptions
7522from the try block and also the catch clauses may cause cleanup actions.
7523 When no exception is thrown during execution of the try block, the control
7524is transferred to the finally clause, if present. After its execution, the
7525script continues with the line following the ":endtry".
7526 When an exception occurs during execution of the try block, the remaining
7527lines in the try block are skipped. The exception is matched against the
7528patterns specified as arguments to the ":catch" commands. The catch clause
7529after the first matching ":catch" is taken, other catch clauses are not
7530executed. The catch clause ends when the next ":catch", ":finally", or
7531":endtry" command is reached - whatever is first. Then, the finally clause
7532(if present) is executed. When the ":endtry" is reached, the script execution
7533continues in the following line as usual.
7534 When an exception that does not match any of the patterns specified by the
7535":catch" commands is thrown in the try block, the exception is not caught by
7536that try conditional and none of the catch clauses is executed. Only the
7537finally clause, if present, is taken. The exception pends during execution of
7538the finally clause. It is resumed at the ":endtry", so that commands after
7539the ":endtry" are not executed and the exception might be caught elsewhere,
7540see |try-nesting|.
7541 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007542remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00007543not matched against the patterns in any of the ":catch" commands of the same
7544try conditional and none of its catch clauses is taken. If there is, however,
7545a finally clause, it is executed, and the exception pends during its
7546execution. The commands following the ":endtry" are not executed. The new
7547exception might, however, be caught elsewhere, see |try-nesting|.
7548 When during execution of the finally clause (if present) an exception is
Bram Moolenaar446cb832008-06-24 21:56:24 +00007549thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00007550clause has been taken because of an exception from the try block or one of the
7551catch clauses, the original (pending) exception is discarded. The commands
7552following the ":endtry" are not executed, and the exception from the finally
7553clause is propagated and can be caught elsewhere, see |try-nesting|.
7554
7555The finally clause is also executed, when a ":break" or ":continue" for
7556a ":while" loop enclosing the complete try conditional is executed from the
7557try block or a catch clause. Or when a ":return" or ":finish" is executed
7558from the try block or a catch clause of a try conditional in a function or
7559sourced script, respectively. The ":break", ":continue", ":return", or
7560":finish" pends during execution of the finally clause and is resumed when the
7561":endtry" is reached. It is, however, discarded when an exception is thrown
7562from the finally clause.
7563 When a ":break" or ":continue" for a ":while" loop enclosing the complete
7564try conditional or when a ":return" or ":finish" is encountered in the finally
7565clause, the rest of the finally clause is skipped, and the ":break",
7566":continue", ":return" or ":finish" is executed as usual. If the finally
7567clause has been taken because of an exception or an earlier ":break",
7568":continue", ":return", or ":finish" from the try block or a catch clause,
7569this pending exception or command is discarded.
7570
7571For examples see |throw-catch| and |try-finally|.
7572
7573
7574NESTING OF TRY CONDITIONALS *try-nesting*
7575
7576Try conditionals can be nested arbitrarily. That is, a complete try
7577conditional can be put into the try block, a catch clause, or the finally
7578clause of another try conditional. If the inner try conditional does not
7579catch an exception thrown in its try block or throws a new exception from one
7580of its catch clauses or its finally clause, the outer try conditional is
7581checked according to the rules above. If the inner try conditional is in the
7582try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar446cb832008-06-24 21:56:24 +00007583otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00007584nesting, whether the inner try conditional is directly contained in the outer
7585one, or whether the outer one sources a script or calls a function containing
7586the inner try conditional.
7587
7588When none of the active try conditionals catches an exception, just their
7589finally clauses are executed. Thereafter, the script processing terminates.
7590An error message is displayed in case of an uncaught exception explicitly
7591thrown by a ":throw" command. For uncaught error and interrupt exceptions
7592implicitly raised by Vim, the error message(s) or interrupt message are shown
7593as usual.
7594
7595For examples see |throw-catch|.
7596
7597
7598EXAMINING EXCEPTION HANDLING CODE *except-examine*
7599
7600Exception handling code can get tricky. If you are in doubt what happens, set
7601'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
7602script file. Then you see when an exception is thrown, discarded, caught, or
7603finished. When using a verbosity level of at least 14, things pending in
7604a finally clause are also shown. This information is also given in debug mode
7605(see |debug-scripts|).
7606
7607
7608THROWING AND CATCHING EXCEPTIONS *throw-catch*
7609
7610You can throw any number or string as an exception. Use the |:throw| command
7611and pass the value to be thrown as argument: >
7612 :throw 4711
7613 :throw "string"
7614< *throw-expression*
7615You can also specify an expression argument. The expression is then evaluated
7616first, and the result is thrown: >
7617 :throw 4705 + strlen("string")
7618 :throw strpart("strings", 0, 6)
7619
7620An exception might be thrown during evaluation of the argument of the ":throw"
7621command. Unless it is caught there, the expression evaluation is abandoned.
7622The ":throw" command then does not throw a new exception.
7623 Example: >
7624
7625 :function! Foo(arg)
7626 : try
7627 : throw a:arg
7628 : catch /foo/
7629 : endtry
7630 : return 1
7631 :endfunction
7632 :
7633 :function! Bar()
7634 : echo "in Bar"
7635 : return 4710
7636 :endfunction
7637 :
7638 :throw Foo("arrgh") + Bar()
7639
7640This throws "arrgh", and "in Bar" is not displayed since Bar() is not
7641executed. >
7642 :throw Foo("foo") + Bar()
7643however displays "in Bar" and throws 4711.
7644
7645Any other command that takes an expression as argument might also be
Bram Moolenaar446cb832008-06-24 21:56:24 +00007646abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00007647exception is then propagated to the caller of the command.
7648 Example: >
7649
7650 :if Foo("arrgh")
7651 : echo "then"
7652 :else
7653 : echo "else"
7654 :endif
7655
7656Here neither of "then" or "else" is displayed.
7657
7658 *catch-order*
7659Exceptions can be caught by a try conditional with one or more |:catch|
7660commands, see |try-conditionals|. The values to be caught by each ":catch"
7661command can be specified as a pattern argument. The subsequent catch clause
7662gets executed when a matching exception is caught.
7663 Example: >
7664
7665 :function! Foo(value)
7666 : try
7667 : throw a:value
7668 : catch /^\d\+$/
7669 : echo "Number thrown"
7670 : catch /.*/
7671 : echo "String thrown"
7672 : endtry
7673 :endfunction
7674 :
7675 :call Foo(0x1267)
7676 :call Foo('string')
7677
7678The first call to Foo() displays "Number thrown", the second "String thrown".
7679An exception is matched against the ":catch" commands in the order they are
7680specified. Only the first match counts. So you should place the more
7681specific ":catch" first. The following order does not make sense: >
7682
7683 : catch /.*/
7684 : echo "String thrown"
7685 : catch /^\d\+$/
7686 : echo "Number thrown"
7687
7688The first ":catch" here matches always, so that the second catch clause is
7689never taken.
7690
7691 *throw-variables*
7692If you catch an exception by a general pattern, you may access the exact value
7693in the variable |v:exception|: >
7694
7695 : catch /^\d\+$/
7696 : echo "Number thrown. Value is" v:exception
7697
7698You may also be interested where an exception was thrown. This is stored in
7699|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
7700exception most recently caught as long it is not finished.
7701 Example: >
7702
7703 :function! Caught()
7704 : if v:exception != ""
7705 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
7706 : else
7707 : echo 'Nothing caught'
7708 : endif
7709 :endfunction
7710 :
7711 :function! Foo()
7712 : try
7713 : try
7714 : try
7715 : throw 4711
7716 : finally
7717 : call Caught()
7718 : endtry
7719 : catch /.*/
7720 : call Caught()
7721 : throw "oops"
7722 : endtry
7723 : catch /.*/
7724 : call Caught()
7725 : finally
7726 : call Caught()
7727 : endtry
7728 :endfunction
7729 :
7730 :call Foo()
7731
7732This displays >
7733
7734 Nothing caught
7735 Caught "4711" in function Foo, line 4
7736 Caught "oops" in function Foo, line 10
7737 Nothing caught
7738
7739A practical example: The following command ":LineNumber" displays the line
7740number in the script or function where it has been used: >
7741
7742 :function! LineNumber()
7743 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
7744 :endfunction
7745 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
7746<
7747 *try-nested*
7748An exception that is not caught by a try conditional can be caught by
7749a surrounding try conditional: >
7750
7751 :try
7752 : try
7753 : throw "foo"
7754 : catch /foobar/
7755 : echo "foobar"
7756 : finally
7757 : echo "inner finally"
7758 : endtry
7759 :catch /foo/
7760 : echo "foo"
7761 :endtry
7762
7763The inner try conditional does not catch the exception, just its finally
7764clause is executed. The exception is then caught by the outer try
7765conditional. The example displays "inner finally" and then "foo".
7766
7767 *throw-from-catch*
7768You can catch an exception and throw a new one to be caught elsewhere from the
7769catch clause: >
7770
7771 :function! Foo()
7772 : throw "foo"
7773 :endfunction
7774 :
7775 :function! Bar()
7776 : try
7777 : call Foo()
7778 : catch /foo/
7779 : echo "Caught foo, throw bar"
7780 : throw "bar"
7781 : endtry
7782 :endfunction
7783 :
7784 :try
7785 : call Bar()
7786 :catch /.*/
7787 : echo "Caught" v:exception
7788 :endtry
7789
7790This displays "Caught foo, throw bar" and then "Caught bar".
7791
7792 *rethrow*
7793There is no real rethrow in the Vim script language, but you may throw
7794"v:exception" instead: >
7795
7796 :function! Bar()
7797 : try
7798 : call Foo()
7799 : catch /.*/
7800 : echo "Rethrow" v:exception
7801 : throw v:exception
7802 : endtry
7803 :endfunction
7804< *try-echoerr*
7805Note that this method cannot be used to "rethrow" Vim error or interrupt
7806exceptions, because it is not possible to fake Vim internal exceptions.
7807Trying so causes an error exception. You should throw your own exception
7808denoting the situation. If you want to cause a Vim error exception containing
7809the original error exception value, you can use the |:echoerr| command: >
7810
7811 :try
7812 : try
7813 : asdf
7814 : catch /.*/
7815 : echoerr v:exception
7816 : endtry
7817 :catch /.*/
7818 : echo v:exception
7819 :endtry
7820
7821This code displays
7822
Bram Moolenaar446cb832008-06-24 21:56:24 +00007823 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00007824
7825
7826CLEANUP CODE *try-finally*
7827
7828Scripts often change global settings and restore them at their end. If the
7829user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar446cb832008-06-24 21:56:24 +00007830an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007831a script when an error occurs or you explicitly throw an exception without
7832catching it. You can solve these problems by using a try conditional with
7833a finally clause for restoring the settings. Its execution is guaranteed on
7834normal control flow, on error, on an explicit ":throw", and on interrupt.
7835(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar446cb832008-06-24 21:56:24 +00007836to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00007837clause has been executed.)
7838Example: >
7839
7840 :try
7841 : let s:saved_ts = &ts
7842 : set ts=17
7843 :
7844 : " Do the hard work here.
7845 :
7846 :finally
7847 : let &ts = s:saved_ts
7848 : unlet s:saved_ts
7849 :endtry
7850
7851This method should be used locally whenever a function or part of a script
7852changes global settings which need to be restored on failure or normal exit of
7853that function or script part.
7854
7855 *break-finally*
7856Cleanup code works also when the try block or a catch clause is left by
7857a ":continue", ":break", ":return", or ":finish".
7858 Example: >
7859
7860 :let first = 1
7861 :while 1
7862 : try
7863 : if first
7864 : echo "first"
7865 : let first = 0
7866 : continue
7867 : else
7868 : throw "second"
7869 : endif
7870 : catch /.*/
7871 : echo v:exception
7872 : break
7873 : finally
7874 : echo "cleanup"
7875 : endtry
7876 : echo "still in while"
7877 :endwhile
7878 :echo "end"
7879
7880This displays "first", "cleanup", "second", "cleanup", and "end". >
7881
7882 :function! Foo()
7883 : try
7884 : return 4711
7885 : finally
7886 : echo "cleanup\n"
7887 : endtry
7888 : echo "Foo still active"
7889 :endfunction
7890 :
7891 :echo Foo() "returned by Foo"
7892
7893This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar446cb832008-06-24 21:56:24 +00007894extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007895return value.)
7896
7897 *except-from-finally*
7898Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
7899a finally clause is possible, but not recommended since it abandons the
7900cleanup actions for the try conditional. But, of course, interrupt and error
7901exceptions might get raised from a finally clause.
7902 Example where an error in the finally clause stops an interrupt from
7903working correctly: >
7904
7905 :try
7906 : try
7907 : echo "Press CTRL-C for interrupt"
7908 : while 1
7909 : endwhile
7910 : finally
7911 : unlet novar
7912 : endtry
7913 :catch /novar/
7914 :endtry
7915 :echo "Script still running"
7916 :sleep 1
7917
7918If you need to put commands that could fail into a finally clause, you should
7919think about catching or ignoring the errors in these commands, see
7920|catch-errors| and |ignore-errors|.
7921
7922
7923CATCHING ERRORS *catch-errors*
7924
7925If you want to catch specific errors, you just have to put the code to be
7926watched in a try block and add a catch clause for the error message. The
7927presence of the try conditional causes all errors to be converted to an
7928exception. No message is displayed and |v:errmsg| is not set then. To find
7929the right pattern for the ":catch" command, you have to know how the format of
7930the error exception is.
7931 Error exceptions have the following format: >
7932
7933 Vim({cmdname}):{errmsg}
7934or >
7935 Vim:{errmsg}
7936
7937{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar446cb832008-06-24 21:56:24 +00007938the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00007939when the error occurs outside try conditionals. It always begins with
7940a capital "E", followed by a two or three-digit error number, a colon, and
7941a space.
7942
7943Examples:
7944
7945The command >
7946 :unlet novar
7947normally produces the error message >
7948 E108: No such variable: "novar"
7949which is converted inside try conditionals to an exception >
7950 Vim(unlet):E108: No such variable: "novar"
7951
7952The command >
7953 :dwim
7954normally produces the error message >
7955 E492: Not an editor command: dwim
7956which is converted inside try conditionals to an exception >
7957 Vim:E492: Not an editor command: dwim
7958
7959You can catch all ":unlet" errors by a >
7960 :catch /^Vim(unlet):/
7961or all errors for misspelled command names by a >
7962 :catch /^Vim:E492:/
7963
7964Some error messages may be produced by different commands: >
7965 :function nofunc
7966and >
7967 :delfunction nofunc
7968both produce the error message >
7969 E128: Function name must start with a capital: nofunc
7970which is converted inside try conditionals to an exception >
7971 Vim(function):E128: Function name must start with a capital: nofunc
7972or >
7973 Vim(delfunction):E128: Function name must start with a capital: nofunc
7974respectively. You can catch the error by its number independently on the
7975command that caused it if you use the following pattern: >
7976 :catch /^Vim(\a\+):E128:/
7977
7978Some commands like >
7979 :let x = novar
7980produce multiple error messages, here: >
7981 E121: Undefined variable: novar
7982 E15: Invalid expression: novar
7983Only the first is used for the exception value, since it is the most specific
7984one (see |except-several-errors|). So you can catch it by >
7985 :catch /^Vim(\a\+):E121:/
7986
7987You can catch all errors related to the name "nofunc" by >
7988 :catch /\<nofunc\>/
7989
7990You can catch all Vim errors in the ":write" and ":read" commands by >
7991 :catch /^Vim(\(write\|read\)):E\d\+:/
7992
7993You can catch all Vim errors by the pattern >
7994 :catch /^Vim\((\a\+)\)\=:E\d\+:/
7995<
7996 *catch-text*
7997NOTE: You should never catch the error message text itself: >
7998 :catch /No such variable/
7999only works in the english locale, but not when the user has selected
8000a different language by the |:language| command. It is however helpful to
8001cite the message text in a comment: >
8002 :catch /^Vim(\a\+):E108:/ " No such variable
8003
8004
8005IGNORING ERRORS *ignore-errors*
8006
8007You can ignore errors in a specific Vim command by catching them locally: >
8008
8009 :try
8010 : write
8011 :catch
8012 :endtry
8013
8014But you are strongly recommended NOT to use this simple form, since it could
8015catch more than you want. With the ":write" command, some autocommands could
8016be executed and cause errors not related to writing, for instance: >
8017
8018 :au BufWritePre * unlet novar
8019
8020There could even be such errors you are not responsible for as a script
8021writer: a user of your script might have defined such autocommands. You would
8022then hide the error from the user.
8023 It is much better to use >
8024
8025 :try
8026 : write
8027 :catch /^Vim(write):/
8028 :endtry
8029
8030which only catches real write errors. So catch only what you'd like to ignore
8031intentionally.
8032
8033For a single command that does not cause execution of autocommands, you could
8034even suppress the conversion of errors to exceptions by the ":silent!"
8035command: >
8036 :silent! nunmap k
8037This works also when a try conditional is active.
8038
8039
8040CATCHING INTERRUPTS *catch-interrupt*
8041
8042When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar446cb832008-06-24 21:56:24 +00008043the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008044script is not terminated, then.
8045 Example: >
8046
8047 :function! TASK1()
8048 : sleep 10
8049 :endfunction
8050
8051 :function! TASK2()
8052 : sleep 20
8053 :endfunction
8054
8055 :while 1
8056 : let command = input("Type a command: ")
8057 : try
8058 : if command == ""
8059 : continue
8060 : elseif command == "END"
8061 : break
8062 : elseif command == "TASK1"
8063 : call TASK1()
8064 : elseif command == "TASK2"
8065 : call TASK2()
8066 : else
8067 : echo "\nIllegal command:" command
8068 : continue
8069 : endif
8070 : catch /^Vim:Interrupt$/
8071 : echo "\nCommand interrupted"
8072 : " Caught the interrupt. Continue with next prompt.
8073 : endtry
8074 :endwhile
8075
8076You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar446cb832008-06-24 21:56:24 +00008077a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008078
8079For testing what happens when CTRL-C would be pressed on a specific line in
8080your script, use the debug mode and execute the |>quit| or |>interrupt|
8081command on that line. See |debug-scripts|.
8082
8083
8084CATCHING ALL *catch-all*
8085
8086The commands >
8087
8088 :catch /.*/
8089 :catch //
8090 :catch
8091
8092catch everything, error exceptions, interrupt exceptions and exceptions
8093explicitly thrown by the |:throw| command. This is useful at the top level of
8094a script in order to catch unexpected things.
8095 Example: >
8096
8097 :try
8098 :
8099 : " do the hard work here
8100 :
8101 :catch /MyException/
8102 :
8103 : " handle known problem
8104 :
8105 :catch /^Vim:Interrupt$/
8106 : echo "Script interrupted"
8107 :catch /.*/
8108 : echo "Internal error (" . v:exception . ")"
8109 : echo " - occurred at " . v:throwpoint
8110 :endtry
8111 :" end of script
8112
8113Note: Catching all might catch more things than you want. Thus, you are
8114strongly encouraged to catch only for problems that you can really handle by
8115specifying a pattern argument to the ":catch".
8116 Example: Catching all could make it nearly impossible to interrupt a script
8117by pressing CTRL-C: >
8118
8119 :while 1
8120 : try
8121 : sleep 1
8122 : catch
8123 : endtry
8124 :endwhile
8125
8126
8127EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
8128
8129Exceptions may be used during execution of autocommands. Example: >
8130
8131 :autocmd User x try
8132 :autocmd User x throw "Oops!"
8133 :autocmd User x catch
8134 :autocmd User x echo v:exception
8135 :autocmd User x endtry
8136 :autocmd User x throw "Arrgh!"
8137 :autocmd User x echo "Should not be displayed"
8138 :
8139 :try
8140 : doautocmd User x
8141 :catch
8142 : echo v:exception
8143 :endtry
8144
8145This displays "Oops!" and "Arrgh!".
8146
8147 *except-autocmd-Pre*
8148For some commands, autocommands get executed before the main action of the
8149command takes place. If an exception is thrown and not caught in the sequence
8150of autocommands, the sequence and the command that caused its execution are
8151abandoned and the exception is propagated to the caller of the command.
8152 Example: >
8153
8154 :autocmd BufWritePre * throw "FAIL"
8155 :autocmd BufWritePre * echo "Should not be displayed"
8156 :
8157 :try
8158 : write
8159 :catch
8160 : echo "Caught:" v:exception "from" v:throwpoint
8161 :endtry
8162
8163Here, the ":write" command does not write the file currently being edited (as
8164you can see by checking 'modified'), since the exception from the BufWritePre
8165autocommand abandons the ":write". The exception is then caught and the
8166script displays: >
8167
8168 Caught: FAIL from BufWrite Auto commands for "*"
8169<
8170 *except-autocmd-Post*
8171For some commands, autocommands get executed after the main action of the
8172command has taken place. If this main action fails and the command is inside
8173an active try conditional, the autocommands are skipped and an error exception
8174is thrown that can be caught by the caller of the command.
8175 Example: >
8176
8177 :autocmd BufWritePost * echo "File successfully written!"
8178 :
8179 :try
8180 : write /i/m/p/o/s/s/i/b/l/e
8181 :catch
8182 : echo v:exception
8183 :endtry
8184
8185This just displays: >
8186
8187 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
8188
8189If you really need to execute the autocommands even when the main action
8190fails, trigger the event from the catch clause.
8191 Example: >
8192
8193 :autocmd BufWritePre * set noreadonly
8194 :autocmd BufWritePost * set readonly
8195 :
8196 :try
8197 : write /i/m/p/o/s/s/i/b/l/e
8198 :catch
8199 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
8200 :endtry
8201<
8202You can also use ":silent!": >
8203
8204 :let x = "ok"
8205 :let v:errmsg = ""
8206 :autocmd BufWritePost * if v:errmsg != ""
8207 :autocmd BufWritePost * let x = "after fail"
8208 :autocmd BufWritePost * endif
8209 :try
8210 : silent! write /i/m/p/o/s/s/i/b/l/e
8211 :catch
8212 :endtry
8213 :echo x
8214
8215This displays "after fail".
8216
8217If the main action of the command does not fail, exceptions from the
8218autocommands will be catchable by the caller of the command: >
8219
8220 :autocmd BufWritePost * throw ":-("
8221 :autocmd BufWritePost * echo "Should not be displayed"
8222 :
8223 :try
8224 : write
8225 :catch
8226 : echo v:exception
8227 :endtry
8228<
8229 *except-autocmd-Cmd*
8230For some commands, the normal action can be replaced by a sequence of
8231autocommands. Exceptions from that sequence will be catchable by the caller
8232of the command.
8233 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar446cb832008-06-24 21:56:24 +00008234had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00008235some way. >
8236
8237 :if !exists("cnt")
8238 : let cnt = 0
8239 :
8240 : autocmd BufWriteCmd * if &modified
8241 : autocmd BufWriteCmd * let cnt = cnt + 1
8242 : autocmd BufWriteCmd * if cnt % 3 == 2
8243 : autocmd BufWriteCmd * throw "BufWriteCmdError"
8244 : autocmd BufWriteCmd * endif
8245 : autocmd BufWriteCmd * write | set nomodified
8246 : autocmd BufWriteCmd * if cnt % 3 == 0
8247 : autocmd BufWriteCmd * throw "BufWriteCmdError"
8248 : autocmd BufWriteCmd * endif
8249 : autocmd BufWriteCmd * echo "File successfully written!"
8250 : autocmd BufWriteCmd * endif
8251 :endif
8252 :
8253 :try
8254 : write
8255 :catch /^BufWriteCmdError$/
8256 : if &modified
8257 : echo "Error on writing (file contents not changed)"
8258 : else
8259 : echo "Error after writing"
8260 : endif
8261 :catch /^Vim(write):/
8262 : echo "Error on writing"
8263 :endtry
8264
8265When this script is sourced several times after making changes, it displays
8266first >
8267 File successfully written!
8268then >
8269 Error on writing (file contents not changed)
8270then >
8271 Error after writing
8272etc.
8273
8274 *except-autocmd-ill*
8275You cannot spread a try conditional over autocommands for different events.
8276The following code is ill-formed: >
8277
8278 :autocmd BufWritePre * try
8279 :
8280 :autocmd BufWritePost * catch
8281 :autocmd BufWritePost * echo v:exception
8282 :autocmd BufWritePost * endtry
8283 :
8284 :write
8285
8286
8287EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
8288
8289Some programming languages allow to use hierarchies of exception classes or to
8290pass additional information with the object of an exception class. You can do
8291similar things in Vim.
8292 In order to throw an exception from a hierarchy, just throw the complete
8293class name with the components separated by a colon, for instance throw the
8294string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
8295 When you want to pass additional information with your exception class, add
8296it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
8297for an error when writing "myfile".
8298 With the appropriate patterns in the ":catch" command, you can catch for
8299base classes or derived classes of your hierarchy. Additional information in
8300parentheses can be cut out from |v:exception| with the ":substitute" command.
8301 Example: >
8302
8303 :function! CheckRange(a, func)
8304 : if a:a < 0
8305 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
8306 : endif
8307 :endfunction
8308 :
8309 :function! Add(a, b)
8310 : call CheckRange(a:a, "Add")
8311 : call CheckRange(a:b, "Add")
8312 : let c = a:a + a:b
8313 : if c < 0
8314 : throw "EXCEPT:MATHERR:OVERFLOW"
8315 : endif
8316 : return c
8317 :endfunction
8318 :
8319 :function! Div(a, b)
8320 : call CheckRange(a:a, "Div")
8321 : call CheckRange(a:b, "Div")
8322 : if (a:b == 0)
8323 : throw "EXCEPT:MATHERR:ZERODIV"
8324 : endif
8325 : return a:a / a:b
8326 :endfunction
8327 :
8328 :function! Write(file)
8329 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008330 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008331 : catch /^Vim(write):/
8332 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
8333 : endtry
8334 :endfunction
8335 :
8336 :try
8337 :
8338 : " something with arithmetics and I/O
8339 :
8340 :catch /^EXCEPT:MATHERR:RANGE/
8341 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
8342 : echo "Range error in" function
8343 :
8344 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
8345 : echo "Math error"
8346 :
8347 :catch /^EXCEPT:IO/
8348 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
8349 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
8350 : if file !~ '^/'
8351 : let file = dir . "/" . file
8352 : endif
8353 : echo 'I/O error for "' . file . '"'
8354 :
8355 :catch /^EXCEPT/
8356 : echo "Unspecified error"
8357 :
8358 :endtry
8359
8360The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
8361a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
8362exceptions with the "Vim" prefix; they are reserved for Vim.
8363 Vim error exceptions are parameterized with the name of the command that
8364failed, if known. See |catch-errors|.
8365
8366
8367PECULIARITIES
8368 *except-compat*
8369The exception handling concept requires that the command sequence causing the
8370exception is aborted immediately and control is transferred to finally clauses
8371and/or a catch clause.
8372
8373In the Vim script language there are cases where scripts and functions
8374continue after an error: in functions without the "abort" flag or in a command
8375after ":silent!", control flow goes to the following line, and outside
8376functions, control flow goes to the line following the outermost ":endwhile"
8377or ":endif". On the other hand, errors should be catchable as exceptions
8378(thus, requiring the immediate abortion).
8379
8380This problem has been solved by converting errors to exceptions and using
8381immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008382conditional is active. This is no restriction since an (error) exception can
8383be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00008384termination without catching the error, just use a try conditional without
8385catch clause. (You can cause cleanup code being executed before termination
8386by specifying a finally clause.)
8387
8388When no try conditional is active, the usual abortion and continuation
8389behavior is used instead of immediate abortion. This ensures compatibility of
8390scripts written for Vim 6.1 and earlier.
8391
8392However, when sourcing an existing script that does not use exception handling
8393commands (or when calling one of its functions) from inside an active try
8394conditional of a new script, you might change the control flow of the existing
8395script on error. You get the immediate abortion on error and can catch the
8396error in the new script. If however the sourced script suppresses error
8397messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar446cb832008-06-24 21:56:24 +00008398|v:errmsg| if appropriate), its execution path is not changed. The error is
8399not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00008400where this happens is for scripts that don't care about errors and produce
8401error messages. You probably won't want to use such code from your new
8402scripts.
8403
8404 *except-syntax-err*
8405Syntax errors in the exception handling commands are never caught by any of
8406the ":catch" commands of the try conditional they belong to. Its finally
8407clauses, however, is executed.
8408 Example: >
8409
8410 :try
8411 : try
8412 : throw 4711
8413 : catch /\(/
8414 : echo "in catch with syntax error"
8415 : catch
8416 : echo "inner catch-all"
8417 : finally
8418 : echo "inner finally"
8419 : endtry
8420 :catch
8421 : echo 'outer catch-all caught "' . v:exception . '"'
8422 : finally
8423 : echo "outer finally"
8424 :endtry
8425
8426This displays: >
8427 inner finally
8428 outer catch-all caught "Vim(catch):E54: Unmatched \("
8429 outer finally
8430The original exception is discarded and an error exception is raised, instead.
8431
8432 *except-single-line*
8433The ":try", ":catch", ":finally", and ":endtry" commands can be put on
8434a single line, but then syntax errors may make it difficult to recognize the
8435"catch" line, thus you better avoid this.
8436 Example: >
8437 :try | unlet! foo # | catch | endtry
8438raises an error exception for the trailing characters after the ":unlet!"
8439argument, but does not see the ":catch" and ":endtry" commands, so that the
8440error exception is discarded and the "E488: Trailing characters" message gets
8441displayed.
8442
8443 *except-several-errors*
8444When several errors appear in a single command, the first error message is
8445usually the most specific one and therefor converted to the error exception.
8446 Example: >
8447 echo novar
8448causes >
8449 E121: Undefined variable: novar
8450 E15: Invalid expression: novar
8451The value of the error exception inside try conditionals is: >
8452 Vim(echo):E121: Undefined variable: novar
8453< *except-syntax-error*
8454But when a syntax error is detected after a normal error in the same command,
8455the syntax error is used for the exception being thrown.
8456 Example: >
8457 unlet novar #
8458causes >
8459 E108: No such variable: "novar"
8460 E488: Trailing characters
8461The value of the error exception inside try conditionals is: >
8462 Vim(unlet):E488: Trailing characters
8463This is done because the syntax error might change the execution path in a way
8464not intended by the user. Example: >
8465 try
8466 try | unlet novar # | catch | echo v:exception | endtry
8467 catch /.*/
8468 echo "outer catch:" v:exception
8469 endtry
8470This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
8471a "E600: Missing :endtry" error message is given, see |except-single-line|.
8472
8473==============================================================================
84749. Examples *eval-examples*
8475
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008476Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008477>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008478 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008479 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008480 : let n = a:nr
8481 : let r = ""
8482 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008483 : let r = '01'[n % 2] . r
8484 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00008485 : endwhile
8486 : return r
8487 :endfunc
8488
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008489 :" The function String2Bin() converts each character in a string to a
8490 :" binary string, separated with dashes.
8491 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008492 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008493 : for ix in range(strlen(a:str))
8494 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
8495 : endfor
8496 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00008497 :endfunc
8498
8499Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008500 :echo Nr2Bin(32)
8501result: "100000" >
8502 :echo String2Bin("32")
8503result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008504
8505
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008506Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008507
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008508This example sorts lines with a specific compare function. >
8509
8510 :func SortBuffer()
8511 : let lines = getline(1, '$')
8512 : call sort(lines, function("Strcmp"))
8513 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008514 :endfunction
8515
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008516As a one-liner: >
8517 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00008518
Bram Moolenaar071d4272004-06-13 20:20:40 +00008519
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008520scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008521 *sscanf*
8522There is no sscanf() function in Vim. If you need to extract parts from a
8523line, you can use matchstr() and substitute() to do it. This example shows
8524how to get the file name, line number and column number out of a line like
8525"foobar.txt, 123, 45". >
8526 :" Set up the match bit
8527 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
8528 :"get the part matching the whole expression
8529 :let l = matchstr(line, mx)
8530 :"get each item out of the match
8531 :let file = substitute(l, mx, '\1', '')
8532 :let lnum = substitute(l, mx, '\2', '')
8533 :let col = substitute(l, mx, '\3', '')
8534
8535The input is in the variable "line", the results in the variables "file",
8536"lnum" and "col". (idea from Michael Geddes)
8537
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008538
8539getting the scriptnames in a Dictionary ~
8540 *scriptnames-dictionary*
8541The |:scriptnames| command can be used to get a list of all script files that
8542have been sourced. There is no equivalent function or variable for this
8543(because it's rarely needed). In case you need to manipulate the list this
8544code can be used: >
8545 " Get the output of ":scriptnames" in the scriptnames_output variable.
8546 let scriptnames_output = ''
8547 redir => scriptnames_output
8548 silent scriptnames
8549 redir END
8550
Bram Moolenaar446cb832008-06-24 21:56:24 +00008551 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008552 " "scripts" dictionary.
8553 let scripts = {}
8554 for line in split(scriptnames_output, "\n")
8555 " Only do non-blank lines.
8556 if line =~ '\S'
8557 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008558 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008559 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00008560 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008561 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00008562 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008563 endif
8564 endfor
8565 unlet scriptnames_output
8566
Bram Moolenaar071d4272004-06-13 20:20:40 +00008567==============================================================================
856810. No +eval feature *no-eval-feature*
8569
8570When the |+eval| feature was disabled at compile time, none of the expression
8571evaluation commands are available. To prevent this from causing Vim scripts
8572to generate all kinds of errors, the ":if" and ":endif" commands are still
8573recognized, though the argument of the ":if" and everything between the ":if"
8574and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
8575only if the commands are at the start of the line. The ":else" command is not
8576recognized.
8577
8578Example of how to avoid executing commands when the |+eval| feature is
8579missing: >
8580
8581 :if 1
8582 : echo "Expression evaluation is compiled in"
8583 :else
8584 : echo "You will _never_ see this message"
8585 :endif
8586
8587==============================================================================
858811. The sandbox *eval-sandbox* *sandbox* *E48*
8589
Bram Moolenaar368373e2010-07-19 20:46:22 +02008590The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
8591'foldtext' options may be evaluated in a sandbox. This means that you are
8592protected from these expressions having nasty side effects. This gives some
8593safety for when these options are set from a modeline. It is also used when
8594the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00008595The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008596
8597These items are not allowed in the sandbox:
8598 - changing the buffer text
8599 - defining or changing mapping, autocommands, functions, user commands
8600 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008601 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008602 - executing a shell command
8603 - reading or writing a file
8604 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00008605 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00008606This is not guaranteed 100% secure, but it should block most attacks.
8607
8608 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00008609:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00008610 option that may have been set from a modeline, e.g.
8611 'foldexpr'.
8612
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008613 *sandbox-option*
8614A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00008615have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008616restrictive, thus this only happens when the option was set from an insecure
8617location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00008618- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008619- while executing in the sandbox
8620- value coming from a modeline
8621
8622Note that when in the sandbox and saving an option value and restoring it, the
8623option will still be marked as it was set in the sandbox.
8624
8625==============================================================================
862612. Textlock *textlock*
8627
8628In a few situations it is not allowed to change the text in the buffer, jump
8629to another window and some other things that might confuse or break what Vim
8630is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar446cb832008-06-24 21:56:24 +00008631actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008632happen any moment the mouse cursor is resting at some position.
8633
8634This is not allowed when the textlock is active:
8635 - changing the buffer text
8636 - jumping to another buffer or window
8637 - editing another file
8638 - closing a window or quitting Vim
8639 - etc.
8640
Bram Moolenaar071d4272004-06-13 20:20:40 +00008641
8642 vim:tw=78:ts=8:ft=help:norl: