blob: 2e89098a665987f1d761fea0b515e26fddf861be [file] [log] [blame]
Bram Moolenaar683fa182015-11-30 21:38:24 +01001*eval.txt* For Vim version 7.4. Last change: 2015 Nov 30
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 Moolenaar7e38ea22014-04-05 22:55:53 +0200151 *list* *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
Bram Moolenaar327aa022014-03-25 18:24:23 +0100330 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000331
Bram Moolenaar13065c42005-01-08 16:08:21 +0000332
333For loop ~
334
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000335The |:for| loop executes commands for each item in a list. A variable is set
336to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000337 :for item in mylist
338 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000339 :endfor
340
341This works like: >
342 :let index = 0
343 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000344 : let item = mylist[index]
345 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000346 : let index = index + 1
347 :endwhile
348
349Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000350results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000351the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000352
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000353If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000354function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000355
Bram Moolenaar446cb832008-06-24 21:56:24 +0000356Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000357requires the argument to be a list of lists. >
358 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
359 : call Doit(lnum, col)
360 :endfor
361
362This works like a |:let| command is done for each list item. Again, the types
363must remain the same to avoid an error.
364
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000365It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000366 :for [i, j; rest] in listlist
367 : call Doit(i, j)
368 : if !empty(rest)
369 : echo "remainder: " . string(rest)
370 : endif
371 :endfor
372
373
374List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000375 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000376Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000377 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000378 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000379 :let l = len(list) " number of items in list
380 :let big = max(list) " maximum value in list
381 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000382 :let xs = count(list, 'x') " count nr of times 'x' appears in list
383 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000384 :let lines = getline(1, 10) " get ten text lines from buffer
385 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000386 :let list = split("a b c") " create list from items in a string
387 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000388 :let s = string(list) " String representation of list
389 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000390
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000391Don't forget that a combination of features can make things simple. For
392example, to add up all the numbers in a list: >
393 :exe 'let sum = ' . join(nrlist, '+')
394
Bram Moolenaar13065c42005-01-08 16:08:21 +0000395
Bram Moolenaard8b02732005-01-14 21:48:43 +00003961.4 Dictionaries ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200397 *dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000398A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399entry can be located with the key. The entries are stored without a specific
400ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000401
402
403Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000404 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000405A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000406braces. Each entry has a key and a value, separated by a colon. Each key can
407only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000408 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
409 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000410< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000411A key is always a String. You can use a Number, it will be converted to a
412String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar446cb832008-06-24 21:56:24 +0000413entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000414Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000415
Bram Moolenaar446cb832008-06-24 21:56:24 +0000416A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000417nested Dictionary: >
418 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
419
420An extra comma after the last entry is ignored.
421
422
423Accessing entries ~
424
425The normal way to access an entry is by putting the key in square brackets: >
426 :let val = mydict["one"]
427 :let mydict["four"] = 4
428
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000429You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000430
431For keys that consist entirely of letters, digits and underscore the following
432form can be used |expr-entry|: >
433 :let val = mydict.one
434 :let mydict.four = 4
435
436Since an entry can be any type, also a List and a Dictionary, the indexing and
437key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000438 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000439
440
441Dictionary to List conversion ~
442
Bram Moolenaar446cb832008-06-24 21:56:24 +0000443You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000444turn the Dictionary into a List and pass it to |:for|.
445
446Most often you want to loop over the keys, using the |keys()| function: >
447 :for key in keys(mydict)
448 : echo key . ': ' . mydict[key]
449 :endfor
450
451The List of keys is unsorted. You may want to sort them first: >
452 :for key in sort(keys(mydict))
453
454To loop over the values use the |values()| function: >
455 :for v in values(mydict)
456 : echo "value: " . v
457 :endfor
458
459If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000460a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000461 :for [key, value] in items(mydict)
462 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000463 :endfor
464
465
466Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000467 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000468Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
469Dictionary. Otherwise, assignment results in referring to the same
470Dictionary: >
471 :let onedict = {'a': 1, 'b': 2}
472 :let adict = onedict
473 :let adict['a'] = 11
474 :echo onedict['a']
475 11
476
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000477Two Dictionaries compare equal if all the key-value pairs compare equal. For
478more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000479
480
481Dictionary modification ~
482 *dict-modification*
483To change an already existing entry of a Dictionary, or to add a new entry,
484use |:let| this way: >
485 :let dict[4] = "four"
486 :let dict['one'] = item
487
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000488Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
489Three ways to remove the entry with key "aaa" from dict: >
490 :let i = remove(dict, 'aaa')
491 :unlet dict.aaa
492 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000493
494Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000495 :call extend(adict, bdict)
496This extends adict with all entries from bdict. Duplicate keys cause entries
497in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000498Note that the order of entries in a Dictionary is irrelevant, thus don't
499expect ":echo adict" to show the items from bdict after the older entries in
500adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000501
502Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000503 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000504This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000505
506
507Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100508 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000509When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000510special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000511 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000512 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000513 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000514 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
515 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000516
517This is like a method in object oriented programming. The entry in the
518Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
519the function was invoked from.
520
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000521It is also possible to add a function without the "dict" attribute as a
522Funcref to a Dictionary, but the "self" variable is not available then.
523
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000524 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000525To avoid the extra name for the function it can be defined and directly
526assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000527 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200528 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000529 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000530 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000531 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000532
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000533The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar446cb832008-06-24 21:56:24 +0000534that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000535|Funcref|. It will automatically be deleted when there is no |Funcref|
536remaining that refers to it.
537
538It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000539
Bram Moolenaar1affd722010-08-04 17:49:30 +0200540If you get an error for a numbered function, you can find out what it is with
541a trick. Assuming the function is 42, the command is: >
542 :function {42}
543
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000544
545Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000546 *E715*
547Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000548 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
549 :if empty(dict) " TRUE if dict is empty
550 :let l = len(dict) " number of items in dict
551 :let big = max(dict) " maximum value in dict
552 :let small = min(dict) " minimum value in dict
553 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
554 :let s = string(dict) " String representation of dict
555 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000556
557
5581.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000559 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000560If you need to know the type of a variable or expression, use the |type()|
561function.
562
563When the '!' flag is included in the 'viminfo' option, global variables that
564start with an uppercase letter, and don't contain a lowercase letter, are
565stored in the viminfo file |viminfo-file|.
566
567When the 'sessionoptions' option contains "global", global variables that
568start with an uppercase letter and contain at least one lowercase letter are
569stored in the session file |session-file|.
570
571variable name can be stored where ~
572my_var_6 not
573My_Var_6 session file
574MY_VAR_6 viminfo file
575
576
577It's possible to form a variable name with curly braces, see
578|curly-braces-names|.
579
580==============================================================================
5812. Expression syntax *expression-syntax*
582
583Expression syntax summary, from least to most significant:
584
585|expr1| expr2 ? expr1 : expr1 if-then-else
586
587|expr2| expr3 || expr3 .. logical OR
588
589|expr3| expr4 && expr4 .. logical AND
590
591|expr4| expr5 == expr5 equal
592 expr5 != expr5 not equal
593 expr5 > expr5 greater than
594 expr5 >= expr5 greater than or equal
595 expr5 < expr5 smaller than
596 expr5 <= expr5 smaller than or equal
597 expr5 =~ expr5 regexp matches
598 expr5 !~ expr5 regexp doesn't match
599
600 expr5 ==? expr5 equal, ignoring case
601 expr5 ==# expr5 equal, match case
602 etc. As above, append ? for ignoring case, # for
603 matching case
604
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000605 expr5 is expr5 same |List| instance
606 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000607
608|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000609 expr6 - expr6 .. number subtraction
610 expr6 . expr6 .. string concatenation
611
612|expr6| expr7 * expr7 .. number multiplication
613 expr7 / expr7 .. number division
614 expr7 % expr7 .. number modulo
615
616|expr7| ! expr7 logical NOT
617 - expr7 unary minus
618 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000619
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000620|expr8| expr8[expr1] byte of a String or item of a |List|
621 expr8[expr1 : expr1] substring of a String or sublist of a |List|
622 expr8.name entry in a |Dictionary|
623 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000624
625|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000626 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000627 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000628 [expr1, ...] |List|
629 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000630 &option option value
631 (expr1) nested expression
632 variable internal variable
633 va{ria}ble internal variable with curly braces
634 $VAR environment variable
635 @r contents of register 'r'
636 function(expr1, ...) function call
637 func{ti}on(expr1, ...) function call with curly braces
638
639
640".." indicates that the operations in this level can be concatenated.
641Example: >
642 &nu || &list && &shell == "csh"
643
644All expressions within one level are parsed from left to right.
645
646
647expr1 *expr1* *E109*
648-----
649
650expr2 ? expr1 : expr1
651
652The expression before the '?' is evaluated to a number. If it evaluates to
653non-zero, the result is the value of the expression between the '?' and ':',
654otherwise the result is the value of the expression after the ':'.
655Example: >
656 :echo lnum == 1 ? "top" : lnum
657
658Since the first expression is an "expr2", it cannot contain another ?:. The
659other two expressions can, thus allow for recursive use of ?:.
660Example: >
661 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
662
663To keep this readable, using |line-continuation| is suggested: >
664 :echo lnum == 1
665 :\ ? "top"
666 :\ : lnum == 1000
667 :\ ? "last"
668 :\ : lnum
669
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000670You should always put a space before the ':', otherwise it can be mistaken for
671use in a variable such as "a:1".
672
Bram Moolenaar071d4272004-06-13 20:20:40 +0000673
674expr2 and expr3 *expr2* *expr3*
675---------------
676
677 *expr-barbar* *expr-&&*
678The "||" and "&&" operators take one argument on each side. The arguments
679are (converted to) Numbers. The result is:
680
681 input output ~
682n1 n2 n1 || n2 n1 && n2 ~
683zero zero zero zero
684zero non-zero non-zero zero
685non-zero zero non-zero zero
686non-zero non-zero non-zero non-zero
687
688The operators can be concatenated, for example: >
689
690 &nu || &list && &shell == "csh"
691
692Note that "&&" takes precedence over "||", so this has the meaning of: >
693
694 &nu || (&list && &shell == "csh")
695
696Once the result is known, the expression "short-circuits", that is, further
697arguments are not evaluated. This is like what happens in C. For example: >
698
699 let a = 1
700 echo a || b
701
702This is valid even if there is no variable called "b" because "a" is non-zero,
703so the result must be non-zero. Similarly below: >
704
705 echo exists("b") && b == "yes"
706
707This is valid whether "b" has been defined or not. The second clause will
708only be evaluated if "b" has been defined.
709
710
711expr4 *expr4*
712-----
713
714expr5 {cmp} expr5
715
716Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
717if it evaluates to true.
718
Bram Moolenaar446cb832008-06-24 21:56:24 +0000719 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000720 *expr-<* *expr-<=* *expr-=~* *expr-!~*
721 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
722 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
723 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
724 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200725 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
726 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000727 use 'ignorecase' match case ignore case ~
728equal == ==# ==?
729not equal != !=# !=?
730greater than > ># >?
731greater than or equal >= >=# >=?
732smaller than < <# <?
733smaller than or equal <= <=# <=?
734regexp matches =~ =~# =~?
735regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200736same instance is is# is?
737different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000738
739Examples:
740"abc" ==# "Abc" evaluates to 0
741"abc" ==? "Abc" evaluates to 1
742"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
743
Bram Moolenaar13065c42005-01-08 16:08:21 +0000744 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000745A |List| can only be compared with a |List| and only "equal", "not equal" and
746"is" can be used. This compares the values of the list, recursively.
747Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000748
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000749 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000750A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
751equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000752recursively. Ignoring case means case is ignored when comparing item values.
753
Bram Moolenaar13065c42005-01-08 16:08:21 +0000754 *E693* *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000755A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
756equal" can be used. Case is never ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000757
Bram Moolenaar251e1912011-06-19 05:09:16 +0200758When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the
759expressions are referring to the same |List| or |Dictionary| instance. A copy
760of a |List| is different from the original |List|. When using "is" without
761a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot"
762equivalent to using "not equal". Except that a different type means the
763values are different: "4 == '4'" is true, "4 is '4'" is false and "0 is []" is
Bram Moolenaard09acef2012-09-21 14:54:30 +0200764false and not an error. "is#"/"isnot#" and "is?"/"isnot?" can be used to match
Bram Moolenaar251e1912011-06-19 05:09:16 +0200765and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000766
Bram Moolenaar071d4272004-06-13 20:20:40 +0000767When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +0000768and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
Bram Moolenaar071d4272004-06-13 20:20:40 +0000769because 'x' converted to a Number is zero.
770
771When comparing two Strings, this is done with strcmp() or stricmp(). This
772results in the mathematical difference (comparing byte values), not
773necessarily the alphabetical difference in the local language.
774
Bram Moolenaar446cb832008-06-24 21:56:24 +0000775When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000776'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000777
778When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000779'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
780
781'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000782
783The "=~" and "!~" operators match the lefthand argument with the righthand
784argument, which is used as a pattern. See |pattern| for what a pattern is.
785This matching is always done like 'magic' was set and 'cpoptions' is empty, no
786matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
787portable. To avoid backslashes in the regexp pattern to be doubled, use a
788single-quote string, see |literal-string|.
789Since a string is considered to be a single line, a multi-line pattern
790(containing \n, backslash-n) will not match. However, a literal NL character
791can be matched like an ordinary character. Examples:
792 "foo\nbar" =~ "\n" evaluates to 1
793 "foo\nbar" =~ "\\n" evaluates to 0
794
795
796expr5 and expr6 *expr5* *expr6*
797---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000798expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000799expr6 - expr6 .. Number subtraction *expr--*
800expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000802For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000803result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000804
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100805expr7 * expr7 .. Number multiplication *expr-star*
806expr7 / expr7 .. Number division *expr-/*
807expr7 % expr7 .. Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000808
809For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100810For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000811
812Note the difference between "+" and ".":
813 "123" + "456" = 579
814 "123" . "456" = "123456"
815
Bram Moolenaar446cb832008-06-24 21:56:24 +0000816Since '.' has the same precedence as '+' and '-', you need to read: >
817 1 . 90 + 90.0
818As: >
819 (1 . 90) + 90.0
820That works, since the String "190" is automatically converted to the Number
821190, which can be added to the Float 90.0. However: >
822 1 . 90 * 90.0
823Should be read as: >
824 1 . (90 * 90.0)
825Since '.' has lower precedence than '*'. This does NOT work, since this
826attempts to concatenate a Float and a String.
827
828When dividing a Number by zero the result depends on the value:
829 0 / 0 = -0x80000000 (like NaN for Float)
830 >0 / 0 = 0x7fffffff (like positive infinity)
831 <0 / 0 = -0x7fffffff (like negative infinity)
832 (before Vim 7.2 it was always 0x7fffffff)
833
Bram Moolenaar071d4272004-06-13 20:20:40 +0000834When the righthand side of '%' is zero, the result is 0.
835
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000836None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000837
Bram Moolenaar446cb832008-06-24 21:56:24 +0000838. and % do not work for Float. *E804*
839
Bram Moolenaar071d4272004-06-13 20:20:40 +0000840
841expr7 *expr7*
842-----
843! expr7 logical NOT *expr-!*
844- expr7 unary minus *expr-unary--*
845+ expr7 unary plus *expr-unary-+*
846
847For '!' non-zero becomes zero, zero becomes one.
848For '-' the sign of the number is changed.
849For '+' the number is unchanged.
850
851A String will be converted to a Number first.
852
Bram Moolenaar446cb832008-06-24 21:56:24 +0000853These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000854 !-1 == 0
855 !!8 == 1
856 --9 == 9
857
858
859expr8 *expr8*
860-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000861expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000862
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000863If expr8 is a Number or String this results in a String that contains the
864expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100865Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
866an alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000867
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000868Index zero gives the first character. This is like it works in C. Careful:
869text column numbers start with one! Example, to get the character under the
870cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000871 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000872
873If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000874String. A negative index always results in an empty string (reason: backwards
875compatibility). Use [-1:] to get the last byte.
876
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000877If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000878for possible index values. If the index is out of range this results in an
Bram Moolenaar446cb832008-06-24 21:56:24 +0000879error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000880 :let item = mylist[-1] " get last item
881
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000882Generally, if a |List| index is equal to or higher than the length of the
883|List|, or more negative than the length of the |List|, this results in an
884error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000885
Bram Moolenaard8b02732005-01-14 21:48:43 +0000886
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000887expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000888
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000889If expr8 is a Number or String this results in the substring with the bytes
890from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100891expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
892|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000893
894If expr1a is omitted zero is used. If expr1b is omitted the length of the
895string minus one is used.
896
897A negative number can be used to measure from the end of the string. -1 is
898the last character, -2 the last but one, etc.
899
900If an index goes out of range for the string characters are omitted. If
901expr1b is smaller than expr1a the result is an empty string.
902
903Examples: >
904 :let c = name[-1:] " last byte of a string
905 :let c = name[-2:-2] " last but one byte of a string
906 :let s = line(".")[4:] " from the fifth byte to the end
907 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100908<
909 *sublist* *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000910If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar446cb832008-06-24 21:56:24 +0000911the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000912just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000913 :let l = mylist[:3] " first four items
914 :let l = mylist[4:4] " List with one item
915 :let l = mylist[:] " shallow copy of a List
916
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000917Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
918error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000919
Bram Moolenaard8b02732005-01-14 21:48:43 +0000920
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000921expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000922
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000923If expr8 is a |Dictionary| and it is followed by a dot, then the following
924name will be used as a key in the |Dictionary|. This is just like:
925expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000926
927The name must consist of alphanumeric characters, just like a variable name,
928but it may start with a number. Curly braces cannot be used.
929
930There must not be white space before or after the dot.
931
932Examples: >
933 :let dict = {"one": 1, 2: "two"}
934 :echo dict.one
935 :echo dict .2
936
937Note that the dot is also used for String concatenation. To avoid confusion
938always put spaces around the dot for String concatenation.
939
940
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000941expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000942
943When expr8 is a |Funcref| type variable, invoke the function it refers to.
944
945
946
947 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000948number
949------
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100950number number constant *expr-number*
951 *hex-number* *octal-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000952
953Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
954
Bram Moolenaar446cb832008-06-24 21:56:24 +0000955 *floating-point-format*
956Floating point numbers can be written in two forms:
957
958 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +0100959 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +0000960
961{N} and {M} are numbers. Both {N} and {M} must be present and can only
962contain digits.
963[-+] means there is an optional plus or minus sign.
964{exp} is the exponent, power of 10.
965Only a decimal point is accepted, not a comma. No matter what the current
966locale is.
967{only when compiled with the |+float| feature}
968
969Examples:
970 123.456
971 +0.0001
972 55.0
973 -0.123
974 1.234e03
975 1.0E-6
976 -3.1416e+88
977
978These are INVALID:
979 3. empty {M}
980 1e40 missing .{M}
981
Bram Moolenaare37d50a2008-08-06 17:06:04 +0000982 *float-pi* *float-e*
983A few useful values to copy&paste: >
984 :let pi = 3.14159265359
985 :let e = 2.71828182846
986
Bram Moolenaar446cb832008-06-24 21:56:24 +0000987Rationale:
988Before floating point was introduced, the text "123.456" was interpreted as
989the two numbers "123" and "456", both converted to a string and concatenated,
990resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +0000991could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +0000992incompatibility was accepted in favor of being able to use the normal notation
993for floating point numbers.
994
995 *floating-point-precision*
996The precision and range of floating points numbers depends on what "double"
997means in the library Vim was compiled with. There is no way to change this at
998runtime.
999
1000The default for displaying a |Float| is to use 6 decimal places, like using
1001printf("%g", f). You can select something else when using the |printf()|
1002function. Example: >
1003 :echo printf('%.15e', atan(1))
1004< 7.853981633974483e-01
1005
1006
Bram Moolenaar071d4272004-06-13 20:20:40 +00001007
Bram Moolenaar979243b2015-06-26 19:35:49 +02001008string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001009------
1010"string" string constant *expr-quote*
1011
1012Note that double quotes are used.
1013
1014A string constant accepts these special characters:
1015\... three-digit octal number (e.g., "\316")
1016\.. two-digit octal number (must be followed by non-digit)
1017\. one-digit octal number (must be followed by non-digit)
1018\x.. byte specified with two hex numbers (e.g., "\x1f")
1019\x. byte specified with one hex number (must be followed by non-hex char)
1020\X.. same as \x..
1021\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001022\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001023 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001024\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001025\b backspace <BS>
1026\e escape <Esc>
1027\f formfeed <FF>
1028\n newline <NL>
1029\r return <CR>
1030\t tab <Tab>
1031\\ backslash
1032\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001033\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
1034 in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a
1035 utf-8 character, use \uxxxx as mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001036
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001037Note that "\xff" is stored as the byte 255, which may be invalid in some
1038encodings. Use "\u00ff" to store character 255 according to the current value
1039of 'encoding'.
1040
Bram Moolenaar071d4272004-06-13 20:20:40 +00001041Note that "\000" and "\x00" force the end of the string.
1042
1043
1044literal-string *literal-string* *E115*
1045---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001046'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001047
1048Note that single quotes are used.
1049
Bram Moolenaar446cb832008-06-24 21:56:24 +00001050This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001051meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001052
1053Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar446cb832008-06-24 21:56:24 +00001054to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001055 if a =~ "\\s*"
1056 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001057
1058
1059option *expr-option* *E112* *E113*
1060------
1061&option option value, local value if possible
1062&g:option global option value
1063&l:option local option value
1064
1065Examples: >
1066 echo "tabstop is " . &tabstop
1067 if &insertmode
1068
1069Any option name can be used here. See |options|. When using the local value
1070and there is no buffer-local or window-local value, the global value is used
1071anyway.
1072
1073
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001074register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001075--------
1076@r contents of register 'r'
1077
1078The result is the contents of the named register, as a single string.
1079Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar446cb832008-06-24 21:56:24 +00001080register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001081registers.
1082
1083When using the '=' register you get the expression itself, not what it
1084evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001085
1086
1087nesting *expr-nesting* *E110*
1088-------
1089(expr1) nested expression
1090
1091
1092environment variable *expr-env*
1093--------------------
1094$VAR environment variable
1095
1096The String value of any environment variable. When it is not defined, the
1097result is an empty string.
1098 *expr-env-expand*
1099Note that there is a difference between using $VAR directly and using
1100expand("$VAR"). Using it directly will only expand environment variables that
1101are known inside the current Vim session. Using expand() will first try using
1102the environment variables known inside the current Vim session. If that
1103fails, a shell will be used to expand the variable. This can be slow, but it
1104does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001105 :echo $shell
1106 :echo expand("$shell")
1107The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001108variable (if your shell supports it).
1109
1110
1111internal variable *expr-variable*
1112-----------------
1113variable internal variable
1114See below |internal-variables|.
1115
1116
Bram Moolenaar05159a02005-02-26 23:04:13 +00001117function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001118-------------
1119function(expr1, ...) function call
1120See below |functions|.
1121
1122
1123==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020011243. Internal variable *internal-variables* *E461*
1125
Bram Moolenaar071d4272004-06-13 20:20:40 +00001126An internal variable name can be made up of letters, digits and '_'. But it
1127cannot start with a digit. It's also possible to use curly braces, see
1128|curly-braces-names|.
1129
1130An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001131An internal variable is explicitly destroyed with the ":unlet" command
1132|:unlet|.
1133Using a name that is not an internal variable or refers to a variable that has
1134been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001135
1136There are several name spaces for variables. Which one is to be used is
1137specified by what is prepended:
1138
1139 (nothing) In a function: local to a function; otherwise: global
1140|buffer-variable| b: Local to the current buffer.
1141|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001142|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001143|global-variable| g: Global.
1144|local-variable| l: Local to a function.
1145|script-variable| s: Local to a |:source|'ed Vim script.
1146|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001147|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001148
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001149The scope name by itself can be used as a |Dictionary|. For example, to
1150delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001151 :for k in keys(s:)
1152 : unlet s:[k]
1153 :endfor
1154<
Bram Moolenaar531da592013-05-06 05:58:55 +02001155 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001156A variable name that is preceded with "b:" is local to the current buffer.
1157Thus you can have several "b:foo" variables, one for each buffer.
1158This kind of variable is deleted when the buffer is wiped out or deleted with
1159|:bdelete|.
1160
1161One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001162 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001163b:changedtick The total number of changes to the current buffer. It is
1164 incremented for each change. An undo command is also a change
1165 in this case. This can be used to perform an action only when
1166 the buffer has changed. Example: >
1167 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001168 : let my_changedtick = b:changedtick
1169 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001170 :endif
1171<
Bram Moolenaar531da592013-05-06 05:58:55 +02001172 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001173A variable name that is preceded with "w:" is local to the current window. It
1174is deleted when the window is closed.
1175
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001176 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001177A variable name that is preceded with "t:" is local to the current tab page,
1178It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001179without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001180
Bram Moolenaar531da592013-05-06 05:58:55 +02001181 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001182Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar446cb832008-06-24 21:56:24 +00001183access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001184place if you like.
1185
Bram Moolenaar531da592013-05-06 05:58:55 +02001186 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001187Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001188But you can also prepend "l:" if you like. However, without prepending "l:"
1189you may run into reserved variable names. For example "count". By itself it
1190refers to "v:count". Using "l:count" you can have a local variable with the
1191same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001192
1193 *script-variable* *s:var*
1194In a Vim script variables starting with "s:" can be used. They cannot be
1195accessed from outside of the scripts, thus are local to the script.
1196
1197They can be used in:
1198- commands executed while the script is sourced
1199- functions defined in the script
1200- autocommands defined in the script
1201- functions and autocommands defined in functions and autocommands which were
1202 defined in the script (recursively)
1203- user defined commands defined in the script
1204Thus not in:
1205- other scripts sourced from this one
1206- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001207- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001208- etc.
1209
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001210Script variables can be used to avoid conflicts with global variable names.
1211Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001212
1213 let s:counter = 0
1214 function MyCounter()
1215 let s:counter = s:counter + 1
1216 echo s:counter
1217 endfunction
1218 command Tick call MyCounter()
1219
1220You can now invoke "Tick" from any script, and the "s:counter" variable in
1221that script will not be changed, only the "s:counter" in the script where
1222"Tick" was defined is used.
1223
1224Another example that does the same: >
1225
1226 let s:counter = 0
1227 command Tick let s:counter = s:counter + 1 | echo s:counter
1228
1229When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001230script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001231defined.
1232
1233The script variables are also available when a function is defined inside a
1234function that is defined in a script. Example: >
1235
1236 let s:counter = 0
1237 function StartCounting(incr)
1238 if a:incr
1239 function MyCounter()
1240 let s:counter = s:counter + 1
1241 endfunction
1242 else
1243 function MyCounter()
1244 let s:counter = s:counter - 1
1245 endfunction
1246 endif
1247 endfunction
1248
1249This defines the MyCounter() function either for counting up or counting down
1250when calling StartCounting(). It doesn't matter from where StartCounting() is
1251called, the s:counter variable will be accessible in MyCounter().
1252
1253When the same script is sourced again it will use the same script variables.
1254They will remain valid as long as Vim is running. This can be used to
1255maintain a counter: >
1256
1257 if !exists("s:counter")
1258 let s:counter = 1
1259 echo "script executed for the first time"
1260 else
1261 let s:counter = s:counter + 1
1262 echo "script executed " . s:counter . " times now"
1263 endif
1264
1265Note that this means that filetype plugins don't get a different set of script
1266variables for each buffer. Use local buffer variables instead |b:var|.
1267
1268
Bram Moolenaar531da592013-05-06 05:58:55 +02001269Predefined Vim variables: *vim-variable* *v:var* *v:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001270
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001271 *v:beval_col* *beval_col-variable*
1272v:beval_col The number of the column, over which the mouse pointer is.
1273 This is the byte index in the |v:beval_lnum| line.
1274 Only valid while evaluating the 'balloonexpr' option.
1275
1276 *v:beval_bufnr* *beval_bufnr-variable*
1277v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1278 valid while evaluating the 'balloonexpr' option.
1279
1280 *v:beval_lnum* *beval_lnum-variable*
1281v:beval_lnum The number of the line, over which the mouse pointer is. Only
1282 valid while evaluating the 'balloonexpr' option.
1283
1284 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001285v:beval_text The text under or after the mouse pointer. Usually a word as
1286 it is useful for debugging a C program. 'iskeyword' applies,
1287 but a dot and "->" before the position is included. When on a
1288 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001289 word before it. When on a Visual area within one line the
1290 highlighted text is used.
1291 Only valid while evaluating the 'balloonexpr' option.
1292
1293 *v:beval_winnr* *beval_winnr-variable*
1294v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001295 valid while evaluating the 'balloonexpr' option. The first
1296 window has number zero (unlike most other places where a
1297 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001298
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001299 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001300v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001301 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001302 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001303
Bram Moolenaar071d4272004-06-13 20:20:40 +00001304 *v:charconvert_from* *charconvert_from-variable*
1305v:charconvert_from
1306 The name of the character encoding of a file to be converted.
1307 Only valid while evaluating the 'charconvert' option.
1308
1309 *v:charconvert_to* *charconvert_to-variable*
1310v:charconvert_to
1311 The name of the character encoding of a file after conversion.
1312 Only valid while evaluating the 'charconvert' option.
1313
1314 *v:cmdarg* *cmdarg-variable*
1315v:cmdarg This variable is used for two purposes:
1316 1. The extra arguments given to a file read/write command.
1317 Currently these are "++enc=" and "++ff=". This variable is
1318 set before an autocommand event for a file read/write
1319 command is triggered. There is a leading space to make it
1320 possible to append this variable directly after the
Bram Moolenaar446cb832008-06-24 21:56:24 +00001321 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001322 included here, because it will be executed anyway.
1323 2. When printing a PostScript file with ":hardcopy" this is
1324 the argument for the ":hardcopy" command. This can be used
1325 in 'printexpr'.
1326
1327 *v:cmdbang* *cmdbang-variable*
1328v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1329 was used the value is 1, otherwise it is 0. Note that this
1330 can only be used in autocommands. For user commands |<bang>|
1331 can be used.
1332
Bram Moolenaar42a45122015-07-10 17:56:23 +02001333 *v:completed_item* *completed_item-variable*
1334v:completed_item
1335 |Dictionary| containing the |complete-items| for the most
1336 recently completed word after |CompleteDone|. The
1337 |Dictionary| is empty if the completion failed.
1338
Bram Moolenaar071d4272004-06-13 20:20:40 +00001339 *v:count* *count-variable*
1340v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar446cb832008-06-24 21:56:24 +00001341 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001342 :map _x :<C-U>echo "the count is " . v:count<CR>
1343< Note: The <C-U> is required to remove the line range that you
1344 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001345 When there are two counts, as in "3d2w", they are multiplied,
1346 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001347 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001348 "count" also works, for backwards compatibility.
1349
1350 *v:count1* *count1-variable*
1351v:count1 Just like "v:count", but defaults to one when no count is
1352 used.
1353
1354 *v:ctype* *ctype-variable*
1355v:ctype The current locale setting for characters of the runtime
1356 environment. This allows Vim scripts to be aware of the
1357 current locale encoding. Technical: it's the value of
1358 LC_CTYPE. When not using a locale the value is "C".
1359 This variable can not be set directly, use the |:language|
1360 command.
1361 See |multi-lang|.
1362
1363 *v:dying* *dying-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001364v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001365 one. When multiple signals are caught the number increases.
1366 Can be used in an autocommand to check if Vim didn't
1367 terminate normally. {only works on Unix}
1368 Example: >
1369 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001370< Note: if another deadly signal is caught when v:dying is one,
1371 VimLeave autocommands will not be executed.
1372
Bram Moolenaar071d4272004-06-13 20:20:40 +00001373 *v:errmsg* *errmsg-variable*
1374v:errmsg Last given error message. It's allowed to set this variable.
1375 Example: >
1376 :let v:errmsg = ""
1377 :silent! next
1378 :if v:errmsg != ""
1379 : ... handle error
1380< "errmsg" also works, for backwards compatibility.
1381
Bram Moolenaar43345542015-11-29 17:35:35 +01001382 *v:errors* *errors-variable*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001383v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001384 This is a list of strings.
1385 The assert functions append an item when an assert fails.
1386 To remove old results make it empty: >
1387 :let v:errors = []
1388< If v:errors is set to anything but a list it is made an empty
1389 list by the assert function.
1390
Bram Moolenaar071d4272004-06-13 20:20:40 +00001391 *v:exception* *exception-variable*
1392v:exception The value of the exception most recently caught and not
1393 finished. See also |v:throwpoint| and |throw-variables|.
1394 Example: >
1395 :try
1396 : throw "oops"
1397 :catch /.*/
1398 : echo "caught" v:exception
1399 :endtry
1400< Output: "caught oops".
1401
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001402 *v:fcs_reason* *fcs_reason-variable*
1403v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1404 Can be used in an autocommand to decide what to do and/or what
1405 to set v:fcs_choice to. Possible values:
1406 deleted file no longer exists
1407 conflict file contents, mode or timestamp was
1408 changed and buffer is modified
1409 changed file contents has changed
1410 mode mode of file changed
1411 time only file timestamp changed
1412
1413 *v:fcs_choice* *fcs_choice-variable*
1414v:fcs_choice What should happen after a |FileChangedShell| event was
1415 triggered. Can be used in an autocommand to tell Vim what to
1416 do with the affected buffer:
1417 reload Reload the buffer (does not work if
1418 the file was deleted).
1419 ask Ask the user what to do, as if there
1420 was no autocommand. Except that when
1421 only the timestamp changed nothing
1422 will happen.
1423 <empty> Nothing, the autocommand should do
1424 everything that needs to be done.
1425 The default is empty. If another (invalid) value is used then
1426 Vim behaves like it is empty, there is no warning message.
1427
Bram Moolenaar071d4272004-06-13 20:20:40 +00001428 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001429v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001430 option used for ~
1431 'charconvert' file to be converted
1432 'diffexpr' original file
1433 'patchexpr' original file
1434 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001435 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001436
1437 *v:fname_out* *fname_out-variable*
1438v:fname_out The name of the output file. Only valid while
1439 evaluating:
1440 option used for ~
1441 'charconvert' resulting converted file (*)
1442 'diffexpr' output of diff
1443 'patchexpr' resulting patched file
1444 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar446cb832008-06-24 21:56:24 +00001445 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001446 for a read command (e.g., ":e file") it will be a temporary
1447 file and different from v:fname_in.
1448
1449 *v:fname_new* *fname_new-variable*
1450v:fname_new The name of the new version of the file. Only valid while
1451 evaluating 'diffexpr'.
1452
1453 *v:fname_diff* *fname_diff-variable*
1454v:fname_diff The name of the diff (patch) file. Only valid while
1455 evaluating 'patchexpr'.
1456
1457 *v:folddashes* *folddashes-variable*
1458v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1459 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001460 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001461
1462 *v:foldlevel* *foldlevel-variable*
1463v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001464 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001465
1466 *v:foldend* *foldend-variable*
1467v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001468 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001469
1470 *v:foldstart* *foldstart-variable*
1471v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001472 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001473
Bram Moolenaar817a8802013-11-09 01:44:43 +01001474 *v:hlsearch* *hlsearch-variable*
Bram Moolenaar76440e22014-11-27 19:14:49 +01001475v:hlsearch Variable that indicates whether search highlighting is on.
1476 Setting it makes sense only if 'hlsearch' is enabled which
1477 requires |+extra_search|. Setting this variable to zero acts
1478 the like |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001479 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001480< Note that the value is restored when returning from a
1481 function. |function-search-undo|.
1482
Bram Moolenaar843ee412004-06-30 16:16:41 +00001483 *v:insertmode* *insertmode-variable*
1484v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1485 events. Values:
1486 i Insert mode
1487 r Replace mode
1488 v Virtual Replace mode
1489
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001490 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001491v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001492 evaluating the expression used with |map()| and |filter()|.
1493 Read-only.
1494
Bram Moolenaar071d4272004-06-13 20:20:40 +00001495 *v:lang* *lang-variable*
1496v:lang The current locale setting for messages of the runtime
1497 environment. This allows Vim scripts to be aware of the
1498 current language. Technical: it's the value of LC_MESSAGES.
1499 The value is system dependent.
1500 This variable can not be set directly, use the |:language|
1501 command.
1502 It can be different from |v:ctype| when messages are desired
1503 in a different language than what is used for character
1504 encoding. See |multi-lang|.
1505
1506 *v:lc_time* *lc_time-variable*
1507v:lc_time The current locale setting for time messages of the runtime
1508 environment. This allows Vim scripts to be aware of the
1509 current language. Technical: it's the value of LC_TIME.
1510 This variable can not be set directly, use the |:language|
1511 command. See |multi-lang|.
1512
1513 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001514v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1515 'indentexpr' expressions, tab page number for 'guitablabel'
1516 and 'guitabtooltip'. Only valid while one of these
1517 expressions is being evaluated. Read-only when in the
1518 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519
Bram Moolenaar219b8702006-11-01 14:32:36 +00001520 *v:mouse_win* *mouse_win-variable*
1521v:mouse_win Window number for a mouse click obtained with |getchar()|.
1522 First window has number 1, like with |winnr()|. The value is
1523 zero when there was no mouse button click.
1524
1525 *v:mouse_lnum* *mouse_lnum-variable*
1526v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1527 This is the text line number, not the screen line number. The
1528 value is zero when there was no mouse button click.
1529
1530 *v:mouse_col* *mouse_col-variable*
1531v:mouse_col Column number for a mouse click obtained with |getchar()|.
1532 This is the screen column number, like with |virtcol()|. The
1533 value is zero when there was no mouse button click.
1534
Bram Moolenaard812df62008-11-09 12:46:09 +00001535 *v:oldfiles* *oldfiles-variable*
1536v:oldfiles List of file names that is loaded from the |viminfo| file on
1537 startup. These are the files that Vim remembers marks for.
1538 The length of the List is limited by the ' argument of the
1539 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001540 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001541 Also see |:oldfiles| and |c_#<|.
1542 The List can be modified, but this has no effect on what is
1543 stored in the |viminfo| file later. If you use values other
1544 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001545 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001546
Bram Moolenaar53744302015-07-17 17:38:22 +02001547 *v:option_new*
1548v:option_new New value of the option. Valid while executing an |OptionSet|
1549 autocommand.
1550 *v:option_old*
1551v:option_old Old value of the option. Valid while executing an |OptionSet|
1552 autocommand.
1553 *v:option_type*
1554v:option_type Scope of the set command. Valid while executing an
1555 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001556 *v:operator* *operator-variable*
1557v:operator The last operator given in Normal mode. This is a single
1558 character except for commands starting with <g> or <z>,
1559 in which case it is two characters. Best used alongside
1560 |v:prevcount| and |v:register|. Useful if you want to cancel
1561 Operator-pending mode and then use the operator, e.g.: >
1562 :omap O <Esc>:call MyMotion(v:operator)<CR>
1563< The value remains set until another operator is entered, thus
1564 don't expect it to be empty.
1565 v:operator is not set for |:delete|, |:yank| or other Ex
1566 commands.
1567 Read-only.
1568
Bram Moolenaar071d4272004-06-13 20:20:40 +00001569 *v:prevcount* *prevcount-variable*
1570v:prevcount The count given for the last but one Normal mode command.
1571 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001572 you want to cancel Visual or Operator-pending mode and then
1573 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001574 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1575< Read-only.
1576
Bram Moolenaar05159a02005-02-26 23:04:13 +00001577 *v:profiling* *profiling-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001578v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001579 See |profiling|.
1580
Bram Moolenaar071d4272004-06-13 20:20:40 +00001581 *v:progname* *progname-variable*
1582v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001583 invoked. Allows you to do special initialisations for |view|,
1584 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001585 Read-only.
1586
Bram Moolenaara1706c92014-04-01 19:55:49 +02001587 *v:progpath* *progpath-variable*
1588v:progpath Contains the command with which Vim was invoked, including the
1589 path. Useful if you want to message a Vim server using a
1590 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001591 To get the full path use: >
1592 echo exepath(v:progpath)
1593< NOTE: This does not work when the command is a relative path
1594 and the current directory has changed.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001595 Read-only.
1596
Bram Moolenaar071d4272004-06-13 20:20:40 +00001597 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001598v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001599 command (regardless of whether that command actually used a
1600 register). Or for the currently executing normal mode mapping
1601 (use this in custom commands that take a register).
1602 If none is supplied it is the default register '"', unless
1603 'clipboard' contains "unnamed" or "unnamedplus", then it is
1604 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001605 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001606
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001607 *v:scrollstart* *scrollstart-variable*
1608v:scrollstart String describing the script or function that caused the
1609 screen to scroll up. It's only set when it is empty, thus the
1610 first reason is remembered. It is set to "Unknown" for a
1611 typed command.
1612 This can be used to find out why your script causes the
1613 hit-enter prompt.
1614
Bram Moolenaar071d4272004-06-13 20:20:40 +00001615 *v:servername* *servername-variable*
1616v:servername The resulting registered |x11-clientserver| name if any.
1617 Read-only.
1618
Bram Moolenaar446cb832008-06-24 21:56:24 +00001619
1620v:searchforward *v:searchforward* *searchforward-variable*
1621 Search direction: 1 after a forward search, 0 after a
1622 backward search. It is reset to forward when directly setting
1623 the last search pattern, see |quote/|.
1624 Note that the value is restored when returning from a
1625 function. |function-search-undo|.
1626 Read-write.
1627
Bram Moolenaar071d4272004-06-13 20:20:40 +00001628 *v:shell_error* *shell_error-variable*
1629v:shell_error Result of the last shell command. When non-zero, the last
1630 shell command had an error. When zero, there was no problem.
1631 This only works when the shell returns the error code to Vim.
1632 The value -1 is often used when the command could not be
1633 executed. Read-only.
1634 Example: >
1635 :!mv foo bar
1636 :if v:shell_error
1637 : echo 'could not rename "foo" to "bar"!'
1638 :endif
1639< "shell_error" also works, for backwards compatibility.
1640
1641 *v:statusmsg* *statusmsg-variable*
1642v:statusmsg Last given status message. It's allowed to set this variable.
1643
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001644 *v:swapname* *swapname-variable*
1645v:swapname Only valid when executing |SwapExists| autocommands: Name of
1646 the swap file found. Read-only.
1647
1648 *v:swapchoice* *swapchoice-variable*
1649v:swapchoice |SwapExists| autocommands can set this to the selected choice
1650 for handling an existing swap file:
1651 'o' Open read-only
1652 'e' Edit anyway
1653 'r' Recover
1654 'd' Delete swapfile
1655 'q' Quit
1656 'a' Abort
Bram Moolenaar446cb832008-06-24 21:56:24 +00001657 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001658 results in the user being asked, as would happen when there is
1659 no SwapExists autocommand. The default is empty.
1660
Bram Moolenaarb3480382005-12-11 21:33:32 +00001661 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001662v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001663 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar446cb832008-06-24 21:56:24 +00001664 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001665 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001666 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001667
Bram Moolenaar071d4272004-06-13 20:20:40 +00001668 *v:termresponse* *termresponse-variable*
1669v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar446cb832008-06-24 21:56:24 +00001670 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001671 that starts with ESC [ or CSI and ends in a 'c', with only
1672 digits, ';' and '.' in between.
1673 When this option is set, the TermResponse autocommand event is
1674 fired, so that you can react to the response from the
1675 terminal.
1676 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1677 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1678 patch level (since this was introduced in patch 95, it's
1679 always 95 or bigger). Pc is always zero.
1680 {only when compiled with |+termresponse| feature}
1681
1682 *v:this_session* *this_session-variable*
1683v:this_session Full filename of the last loaded or saved session file. See
1684 |:mksession|. It is allowed to set this variable. When no
1685 session file has been saved, this variable is empty.
1686 "this_session" also works, for backwards compatibility.
1687
1688 *v:throwpoint* *throwpoint-variable*
1689v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001690 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001691 also |v:exception| and |throw-variables|.
1692 Example: >
1693 :try
1694 : throw "oops"
1695 :catch /.*/
1696 : echo "Exception from" v:throwpoint
1697 :endtry
1698< Output: "Exception from test.vim, line 2"
1699
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001700 *v:val* *val-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001701v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001702 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001703 |filter()|. Read-only.
1704
Bram Moolenaar071d4272004-06-13 20:20:40 +00001705 *v:version* *version-variable*
1706v:version Version number of Vim: Major version number times 100 plus
1707 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1708 is 501. Read-only. "version" also works, for backwards
1709 compatibility.
1710 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02001711 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001712< Note that patch numbers are specific to the version, thus both
1713 version 5.0 and 5.1 may have a patch 123, but these are
1714 completely different.
1715
1716 *v:warningmsg* *warningmsg-variable*
1717v:warningmsg Last given warning message. It's allowed to set this variable.
1718
Bram Moolenaar727c8762010-10-20 19:17:48 +02001719 *v:windowid* *windowid-variable*
1720v:windowid When any X11 based GUI is running or when running in a
1721 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001722 set to the window ID.
1723 When an MS-Windows GUI is running this will be set to the
1724 window handle.
1725 Otherwise the value is zero.
1726 Note: for windows inside Vim use |winnr()|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001727
Bram Moolenaar071d4272004-06-13 20:20:40 +00001728==============================================================================
17294. Builtin Functions *functions*
1730
1731See |function-list| for a list grouped by what the function is used for.
1732
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001733(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001734
1735USAGE RESULT DESCRIPTION ~
1736
Bram Moolenaar446cb832008-06-24 21:56:24 +00001737abs( {expr}) Float or Number absolute value of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001738acos( {expr}) Float arc cosine of {expr}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001739add( {list}, {item}) List append {item} to |List| {list}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001740and( {expr}, {expr}) Number bitwise AND
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001741append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001742append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001743argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001744argidx() Number current index in the argument list
Bram Moolenaar683fa182015-11-30 21:38:24 +01001745arglistid( [{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02001746 Number argument list id
Bram Moolenaar071d4272004-06-13 20:20:40 +00001747argv( {nr}) String {nr} entry of the argument list
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001748argv( ) List the argument list
Bram Moolenaar683fa182015-11-30 21:38:24 +01001749assert_equal( {exp}, {act} [, {msg}]) none assert that {exp} equals {act}
1750assert_false( {actual} [, {msg}]) none assert that {actual} is false
1751assert_true( {actual} [, {msg}]) none assert that {actual} is true
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001752asin( {expr}) Float arc sine of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001753atan( {expr}) Float arc tangent of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001754atan2( {expr}, {expr}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001755browse( {save}, {title}, {initdir}, {default})
1756 String put up a file requester
Bram Moolenaar446cb832008-06-24 21:56:24 +00001757browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001758bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001759buflisted( {expr}) Number TRUE if buffer {expr} is listed
1760bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001761bufname( {expr}) String Name of the buffer {expr}
Bram Moolenaar12969c02015-09-08 23:36:10 +02001762bufnr( {expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001763bufwinnr( {expr}) Number window number of buffer {expr}
1764byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001765byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01001766byteidxcomp( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001767call( {func}, {arglist} [, {dict}])
1768 any call {func} with arguments {arglist}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001769ceil( {expr}) Float round {expr} up
1770changenr() Number current change number
Bram Moolenaard35d7842013-01-23 17:17:10 +01001771char2nr( {expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001772cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001773clearmatches() none clear all matches
Bram Moolenaar071d4272004-06-13 20:20:40 +00001774col( {expr}) Number column nr of cursor or mark
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001775complete( {startcol}, {matches}) none set Insert mode completion
Bram Moolenaar572cb562005-08-05 21:35:02 +00001776complete_add( {expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00001777complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001778confirm( {msg} [, {choices} [, {default} [, {type}]]])
1779 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001780copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001781cos( {expr}) Float cosine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001782cosh( {expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02001783count( {list}, {expr} [, {ic} [, {start}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001784 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001785cscope_connection( [{num} , {dbpath} [, {prepend}]])
1786 Number checks existence of cscope connection
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01001787cursor( {lnum}, {col} [, {off}])
1788 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar0b238792006-03-02 22:49:12 +00001789cursor( {list}) Number move cursor to position in {list}
Bram Moolenaar92dff182014-02-11 19:15:50 +01001790deepcopy( {expr} [, {noref}]) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001791delete( {fname}) Number delete file {fname}
1792did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001793diff_filler( {lnum}) Number diff filler lines about {lnum}
1794diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001795empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001796escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001797eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001798eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001799executable( {expr}) Number 1 if executable {expr} exists
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001800exepath( {expr}) String full path of the command {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001801exists( {expr}) Number TRUE if {expr} exists
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001802extend( {expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001803 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001804exp( {expr}) Float exponential of {expr}
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001805expand( {expr} [, {nosuf} [, {list}]])
1806 any expand special keywords in {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001807feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001808filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001809filewritable( {file}) Number TRUE if {file} is a writable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001810filter( {expr}, {string}) List/Dict remove items from {expr} where
1811 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001812finddir( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001813 String find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001814findfile( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001815 String find file {name} in {path}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001816float2nr( {expr}) Number convert Float {expr} to a Number
1817floor( {expr}) Float round {expr} down
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001818fmod( {expr1}, {expr2}) Float remainder of {expr1} / {expr2}
Bram Moolenaaraebaf892008-05-28 14:49:58 +00001819fnameescape( {fname}) String escape special characters in {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001820fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001821foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1822foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001823foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001824foldtext( ) String line displayed for closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001825foldtextresult( {lnum}) String text for closed fold at {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001826foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001827function( {name}) Funcref reference to function {name}
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001828garbagecollect( [{atexit}]) none free memory, breaking cyclic references
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001829get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001830get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001831getbufline( {expr}, {lnum} [, {end}])
1832 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001833getbufvar( {expr}, {varname} [, {def}])
1834 any variable {varname} in buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001835getchar( [expr]) Number get one character from the user
1836getcharmod( ) Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02001837getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00001838getcmdline() String return the current command-line
1839getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02001840getcmdtype() String return current command-line type
1841getcmdwintype() String return current command-line window type
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02001842getcurpos() List position of the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00001843getcwd() String the current working directory
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02001844getfontname( [{name}]) String name of font being used
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001845getfperm( {fname}) String file permissions of file {fname}
1846getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001847getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001848getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001849getline( {lnum}) String line {lnum} of current buffer
1850getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001851getloclist( {nr}) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001852getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00001853getpid() Number process ID of Vim
Bram Moolenaar0b238792006-03-02 22:49:12 +00001854getpos( {expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001855getqflist() List list of quickfix items
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02001856getreg( [{regname} [, 1 [, {list}]]])
1857 String or List contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001858getregtype( [{regname}]) String type of register
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001859gettabvar( {nr}, {varname} [, {def}])
1860 any variable {varname} in tab {nr} or {def}
1861gettabwinvar( {tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001862 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001863getwinposx() Number X coord in pixels of GUI Vim window
1864getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001865getwinvar( {nr}, {varname} [, {def}])
1866 any variable {varname} in window {nr}
Bram Moolenaard8b77f72015-03-05 21:21:19 +01001867glob( {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001868 any expand file wildcards in {expr}
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01001869glob2regpat( {expr}) String convert a glob pat into a search pat
Bram Moolenaard8b77f72015-03-05 21:21:19 +01001870globpath( {path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00001871 String do glob({expr}) for all dirs in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001872has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001873has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaard267b9c2007-04-26 15:06:45 +00001874haslocaldir() Number TRUE if current window executed |:lcd|
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001875hasmapto( {what} [, {mode} [, {abbr}]])
1876 Number TRUE if mapping to {what} exists
Bram Moolenaar071d4272004-06-13 20:20:40 +00001877histadd( {history},{item}) String add an item to a history
1878histdel( {history} [, {item}]) String remove an item from a history
1879histget( {history} [, {index}]) String get the item {index} from a history
1880histnr( {history}) Number highest index of a history
1881hlexists( {name}) Number TRUE if highlight group {name} exists
1882hlID( {name}) Number syntax ID of highlight group {name}
1883hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001884iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1885indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001886index( {list}, {expr} [, {start} [, {ic}]])
1887 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001888input( {prompt} [, {text} [, {completion}]])
1889 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001890inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001891inputlist( {textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001892inputrestore() Number restore typeahead
1893inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001894inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001895insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001896invert( {expr}) Number bitwise invert
Bram Moolenaar071d4272004-06-13 20:20:40 +00001897isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001898islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001899items( {dict}) List key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001900join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001901keys( {dict}) List keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001902len( {expr}) Number the length of {expr}
1903libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001904libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1905line( {expr}) Number line nr of cursor, last line or mark
1906line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001907lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001908localtime() Number current time
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001909log( {expr}) Float natural logarithm (base e) of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001910log10( {expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaard38b0552012-04-25 19:07:41 +02001911luaeval( {expr}[, {expr}]) any evaluate |Lua| expression
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001912map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaarbd743252010-10-20 21:23:33 +02001913maparg( {name}[, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001914 String or Dict
1915 rhs of mapping {name} in mode {mode}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001916mapcheck( {name}[, {mode} [, {abbr}]])
1917 String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001918match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001919 Number position where {pat} matches in {expr}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001920matchadd( {group}, {pattern}[, {priority}[, {id}]])
1921 Number highlight {pattern} with {group}
Bram Moolenaarb3414592014-06-17 17:48:32 +02001922matchaddpos( {group}, {list}[, {priority}[, {id}]])
1923 Number highlight positions with {group}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001924matcharg( {nr}) List arguments of |:match|
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001925matchdelete( {id}) Number delete match identified by {id}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001926matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001927 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001928matchlist( {expr}, {pat}[, {start}[, {count}]])
1929 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001930matchstr( {expr}, {pat}[, {start}[, {count}]])
1931 String {count}'th match of {pat} in {expr}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001932max( {list}) Number maximum value of items in {list}
1933min( {list}) Number minimum value of items in {list}
1934mkdir( {name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001935 Number create directory {name}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001936mode( [expr]) String current editing mode
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001937mzeval( {expr}) any evaluate |MzScheme| expression
Bram Moolenaar071d4272004-06-13 20:20:40 +00001938nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaard35d7842013-01-23 17:17:10 +01001939nr2char( {expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001940or( {expr}, {expr}) Number bitwise OR
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001941pathshorten( {expr}) String shorten directory names in a path
Bram Moolenaar446cb832008-06-24 21:56:24 +00001942pow( {x}, {y}) Float {x} to the power of {y}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001943prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001944printf( {fmt}, {expr1}...) String format text
1945pumvisible() Number whether popup menu is visible
Bram Moolenaar30b65812012-07-12 22:01:11 +02001946pyeval( {expr}) any evaluate |Python| expression
1947py3eval( {expr}) any evaluate |python3| expression
Bram Moolenaard8b02732005-01-14 21:48:43 +00001948range( {expr} [, {max} [, {stride}]])
1949 List items from {expr} to {max}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001950readfile( {fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001951 List get list of lines from file {fname}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001952reltime( [{start} [, {end}]]) List get time value
1953reltimestr( {time}) String turn time value into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00001954remote_expr( {server}, {string} [, {idvar}])
1955 String send expression
1956remote_foreground( {server}) Number bring Vim server to the foreground
1957remote_peek( {serverid} [, {retvar}])
1958 Number check for reply string
1959remote_read( {serverid}) String read reply string
1960remote_send( {server}, {string} [, {idvar}])
1961 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001962remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001963remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001964rename( {from}, {to}) Number rename (move) file from {from} to {to}
1965repeat( {expr}, {count}) String repeat {expr} {count} times
1966resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001967reverse( {list}) List reverse {list} in-place
Bram Moolenaar446cb832008-06-24 21:56:24 +00001968round( {expr}) Float round off {expr}
Bram Moolenaar9a773482013-06-11 18:40:13 +02001969screenattr( {row}, {col}) Number attribute at screen position
1970screenchar( {row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01001971screencol() Number current cursor column
1972screenrow() Number current cursor row
Bram Moolenaar76929292008-01-06 19:07:36 +00001973search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1974 Number search for {pattern}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001975searchdecl( {name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00001976 Number search for variable declaration
Bram Moolenaar76929292008-01-06 19:07:36 +00001977searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001978 Number search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00001979searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001980 List search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00001981searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001982 List search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001983server2client( {clientid}, {string})
1984 Number send reply string
1985serverlist() String get a list of available servers
1986setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
Bram Moolenaardbd24b52015-08-11 14:26:19 +02001987setcharsearch( {dict}) Dict set character search from {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001988setcmdpos( {pos}) Number set cursor position in command-line
1989setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001990setloclist( {nr}, {list}[, {action}])
1991 Number modify location list using {list}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001992setmatches( {list}) Number restore a list of matches
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001993setpos( {expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001994setqflist( {list}[, {action}]) Number modify quickfix list using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001995setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001996settabvar( {nr}, {varname}, {val}) set {varname} in tab page {nr} to {val}
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001997settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1998 {winnr} in tab page {tabnr} to {val}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001999setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01002000sha256( {string}) String SHA256 checksum of {string}
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002001shellescape( {string} [, {special}])
2002 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002003 command argument
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02002004shiftwidth() Number effective value of 'shiftwidth'
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002005simplify( {filename}) String simplify filename as much as possible
Bram Moolenaar446cb832008-06-24 21:56:24 +00002006sin( {expr}) Float sine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002007sinh( {expr}) Float hyperbolic sine of {expr}
Bram Moolenaar5f894962011-06-19 02:55:37 +02002008sort( {list} [, {func} [, {dict}]])
2009 List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00002010soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002011spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002012spellsuggest( {word} [, {max} [, {capital}]])
2013 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00002014split( {expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002015 List make |List| from {pat} separated {expr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01002016sqrt( {expr}) Float square root of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002017str2float( {expr}) Float convert String to Float
2018str2nr( {expr} [, {base}]) Number convert String to Number
Bram Moolenaar641e48c2015-06-25 16:09:26 +02002019strchars( {expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaardc536092010-07-18 15:45:49 +02002020strdisplaywidth( {expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002021strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002022stridx( {haystack}, {needle}[, {start}])
2023 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002024string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00002025strlen( {expr}) Number length of the String {expr}
2026strpart( {src}, {start}[, {len}])
2027 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00002028strridx( {haystack}, {needle} [, {start}])
2029 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002030strtrans( {expr}) String translate string to make it printable
Bram Moolenaar72597a52010-07-18 15:31:08 +02002031strwidth( {expr}) Number display cell length of the String {expr}
Bram Moolenaar41571762014-04-02 19:00:58 +02002032submatch( {nr}[, {list}]) String or List
2033 specific match in ":s" or substitute()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002034substitute( {expr}, {pat}, {sub}, {flags})
2035 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00002036synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002037synIDattr( {synID}, {what} [, {mode}])
2038 String attribute {what} of syntax ID {synID}
2039synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaar483c5d82010-10-20 18:45:33 +02002040synconcealed( {lnum}, {col}) List info about concealing
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002041synstack( {lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002042system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02002043systemlist( {expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00002044tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
2045tabpagenr( [{arg}]) Number number of current or last tab page
2046tabpagewinnr( {tabarg}[, {arg}])
2047 Number number of current window in tab page
2048taglist( {expr}) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002049tagfiles() List tags files used
Bram Moolenaar071d4272004-06-13 20:20:40 +00002050tempname() String name for a temporary file
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002051tan( {expr}) Float tangent of {expr}
2052tanh( {expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002053tolower( {expr}) String the String {expr} switched to lowercase
2054toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00002055tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
2056 to chars in {tostr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01002057trunc( {expr}) Float truncate Float {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002058type( {name}) Number type of variable {name}
Bram Moolenaara17d4c12010-05-30 18:30:36 +02002059undofile( {name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002060undotree() List undo file tree
Bram Moolenaar327aa022014-03-25 18:24:23 +01002061uniq( {list} [, {func} [, {dict}]])
2062 List remove adjacent duplicates from a list
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002063values( {dict}) List values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002064virtcol( {expr}) Number screen column of cursor or mark
2065visualmode( [expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002066wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar071d4272004-06-13 20:20:40 +00002067winbufnr( {nr}) Number buffer number of window {nr}
2068wincol() Number window column of the cursor
2069winheight( {nr}) Number height of window {nr}
2070winline() Number window line of the cursor
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00002071winnr( [{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002072winrestcmd() String returns command to restore window sizes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002073winrestview( {dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002074winsaveview() Dict save view of current window
Bram Moolenaar071d4272004-06-13 20:20:40 +00002075winwidth( {nr}) Number width of window {nr}
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01002076writefile( {list}, {fname} [, {flags}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002077 Number write list of lines to file {fname}
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002078xor( {expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002079
Bram Moolenaar446cb832008-06-24 21:56:24 +00002080abs({expr}) *abs()*
2081 Return the absolute value of {expr}. When {expr} evaluates to
2082 a |Float| abs() returns a |Float|. When {expr} can be
2083 converted to a |Number| abs() returns a |Number|. Otherwise
2084 abs() gives an error message and returns -1.
2085 Examples: >
2086 echo abs(1.456)
2087< 1.456 >
2088 echo abs(-5.456)
2089< 5.456 >
2090 echo abs(-4)
2091< 4
2092 {only available when compiled with the |+float| feature}
2093
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002094
2095acos({expr}) *acos()*
2096 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002097 |Float| in the range of [0, pi].
2098 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002099 [-1, 1].
2100 Examples: >
2101 :echo acos(0)
2102< 1.570796 >
2103 :echo acos(-0.5)
2104< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002105 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002106
2107
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002108add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002109 Append the item {expr} to |List| {list}. Returns the
2110 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002111 :let alist = add([1, 2, 3], item)
2112 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002113< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002114 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002115 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002116
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002117
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002118and({expr}, {expr}) *and()*
2119 Bitwise AND on the two arguments. The arguments are converted
2120 to a number. A List, Dict or Float argument causes an error.
2121 Example: >
2122 :let flag = and(bits, 0x80)
2123
2124
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002125append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002126 When {expr} is a |List|: Append each item of the |List| as a
2127 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002128 Otherwise append {expr} as one text line below line {lnum} in
2129 the current buffer.
2130 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002131 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar446cb832008-06-24 21:56:24 +00002132 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002133 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002134 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002135<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002136 *argc()*
2137argc() The result is the number of files in the argument list of the
2138 current window. See |arglist|.
2139
2140 *argidx()*
2141argidx() The result is the current index in the argument list. 0 is
2142 the first file. argc() - 1 is the last one. See |arglist|.
2143
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002144 *arglistid()*
2145arglistid([{winnr}, [ {tabnr} ]])
2146 Return the argument list ID. This is a number which
2147 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002148 global argument list. See |arglist|.
2149 Return -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002150
2151 Without arguments use the current window.
2152 With {winnr} only use this window in the current tab page.
2153 With {winnr} and {tabnr} use the window in the specified tab
2154 page.
2155
Bram Moolenaar071d4272004-06-13 20:20:40 +00002156 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002157argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002158 current window. See |arglist|. "argv(0)" is the first one.
2159 Example: >
2160 :let i = 0
2161 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002162 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002163 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2164 : let i = i + 1
2165 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002166< Without the {nr} argument a |List| with the whole |arglist| is
2167 returned.
2168
Bram Moolenaar683fa182015-11-30 21:38:24 +01002169 *assert_equal()*
2170assert_equal({expected}, {actual}, [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002171 When {expected} and {actual} are not equal an error message is
2172 added to |v:errors|.
2173 There is no automatic conversion, the String "4" is different
2174 from the Number 4. And the number 4 is different from the
2175 Float 4.0. The value of 'ignorecase' is not used here, case
2176 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002177 When {msg} is omitted an error in the form "Expected
2178 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002179 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002180 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002181< Will result in a string to be added to |v:errors|:
2182 test.vim line 12: Expected 'foo' but got 'bar' ~
2183
Bram Moolenaar683fa182015-11-30 21:38:24 +01002184assert_false({actual}, [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002185 When {actual} is not false an error message is added to
Bram Moolenaar683fa182015-11-30 21:38:24 +01002186 |v:errors|, like with |assert_equal()|..
Bram Moolenaar43345542015-11-29 17:35:35 +01002187 A value is false when it is zero. When "{actual}" is not a
2188 number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002189 When {msg} is omitted an error in the form "Expected False but
2190 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002191
Bram Moolenaar683fa182015-11-30 21:38:24 +01002192assert_true({actual}, [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002193 When {actual} is not true an error message is added to
Bram Moolenaar683fa182015-11-30 21:38:24 +01002194 |v:errors|, like with |assert_equal()|..
Bram Moolenaar43345542015-11-29 17:35:35 +01002195 A value is true when it is a non-zeron number. When {actual}
2196 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002197 When {msg} is omitted an error in the form "Expected True but
2198 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002199
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002200asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002201 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002202 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002203 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002204 [-1, 1].
2205 Examples: >
2206 :echo asin(0.8)
2207< 0.927295 >
2208 :echo asin(-0.5)
2209< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002210 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002211
2212
Bram Moolenaar446cb832008-06-24 21:56:24 +00002213atan({expr}) *atan()*
2214 Return the principal value of the arc tangent of {expr}, in
2215 the range [-pi/2, +pi/2] radians, as a |Float|.
2216 {expr} must evaluate to a |Float| or a |Number|.
2217 Examples: >
2218 :echo atan(100)
2219< 1.560797 >
2220 :echo atan(-4.01)
2221< -1.326405
2222 {only available when compiled with the |+float| feature}
2223
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002224
2225atan2({expr1}, {expr2}) *atan2()*
2226 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002227 radians, as a |Float| in the range [-pi, pi].
2228 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002229 Examples: >
2230 :echo atan2(-1, 1)
2231< -0.785398 >
2232 :echo atan2(1, -1)
2233< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002234 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002235
2236
Bram Moolenaar071d4272004-06-13 20:20:40 +00002237 *browse()*
2238browse({save}, {title}, {initdir}, {default})
2239 Put up a file requester. This only works when "has("browse")"
2240 returns non-zero (only in some GUI versions).
2241 The input fields are:
2242 {save} when non-zero, select file to write
2243 {title} title for the requester
2244 {initdir} directory to start browsing in
2245 {default} default file name
2246 When the "Cancel" button is hit, something went wrong, or
2247 browsing is not possible, an empty string is returned.
2248
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002249 *browsedir()*
2250browsedir({title}, {initdir})
2251 Put up a directory requester. This only works when
2252 "has("browse")" returns non-zero (only in some GUI versions).
2253 On systems where a directory browser is not supported a file
2254 browser is used. In that case: select a file in the directory
2255 to be used.
2256 The input fields are:
2257 {title} title for the requester
2258 {initdir} directory to start browsing in
2259 When the "Cancel" button is hit, something went wrong, or
2260 browsing is not possible, an empty string is returned.
2261
Bram Moolenaar071d4272004-06-13 20:20:40 +00002262bufexists({expr}) *bufexists()*
2263 The result is a Number, which is non-zero if a buffer called
2264 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002265 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002266 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002267 exactly. The name can be:
2268 - Relative to the current directory.
2269 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002270 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002271 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002272 Unlisted buffers will be found.
2273 Note that help files are listed by their short name in the
2274 output of |:buffers|, but bufexists() requires using their
2275 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002276 bufexists() may report a buffer exists, but to use the name
2277 with a |:buffer| command you may need to use |expand()|. Esp
2278 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002279 Use "bufexists(0)" to test for the existence of an alternate
2280 file name.
2281 *buffer_exists()*
2282 Obsolete name: buffer_exists().
2283
2284buflisted({expr}) *buflisted()*
2285 The result is a Number, which is non-zero if a buffer called
2286 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002287 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002288
2289bufloaded({expr}) *bufloaded()*
2290 The result is a Number, which is non-zero if a buffer called
2291 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002292 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002293
2294bufname({expr}) *bufname()*
2295 The result is the name of a buffer, as it is displayed by the
2296 ":ls" command.
2297 If {expr} is a Number, that buffer number's name is given.
2298 Number zero is the alternate buffer for the current window.
2299 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002300 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002301 set and 'cpoptions' is empty. When there is more than one
2302 match an empty string is returned.
2303 "" or "%" can be used for the current buffer, "#" for the
2304 alternate buffer.
2305 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002306 or middle of the buffer name is accepted. If you only want a
2307 full match then put "^" at the start and "$" at the end of the
2308 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002309 Listed buffers are found first. If there is a single match
2310 with a listed buffer, that one is returned. Next unlisted
2311 buffers are searched for.
2312 If the {expr} is a String, but you want to use it as a buffer
2313 number, force it to be a Number by adding zero to it: >
2314 :echo bufname("3" + 0)
2315< If the buffer doesn't exist, or doesn't have a name, an empty
2316 string is returned. >
2317 bufname("#") alternate buffer name
2318 bufname(3) name of buffer 3
2319 bufname("%") name of current buffer
2320 bufname("file2") name of buffer where "file2" matches.
2321< *buffer_name()*
2322 Obsolete name: buffer_name().
2323
2324 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002325bufnr({expr} [, {create}])
2326 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002327 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002328 above.
2329 If the buffer doesn't exist, -1 is returned. Or, if the
2330 {create} argument is present and not zero, a new, unlisted,
2331 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002332 bufnr("$") is the last buffer: >
2333 :let last_buffer = bufnr("$")
2334< The result is a Number, which is the highest buffer number
2335 of existing buffers. Note that not all buffers with a smaller
2336 number necessarily exist, because ":bwipeout" may have removed
2337 them. Use bufexists() to test for the existence of a buffer.
2338 *buffer_number()*
2339 Obsolete name: buffer_number().
2340 *last_buffer_nr()*
2341 Obsolete name for bufnr("$"): last_buffer_nr().
2342
2343bufwinnr({expr}) *bufwinnr()*
2344 The result is a Number, which is the number of the first
2345 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar446cb832008-06-24 21:56:24 +00002346 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002347 there is no such window, -1 is returned. Example: >
2348
2349 echo "A window containing buffer 1 is " . (bufwinnr(1))
2350
2351< The number can be used with |CTRL-W_w| and ":wincmd w"
2352 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002353 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002354
2355
2356byte2line({byte}) *byte2line()*
2357 Return the line number that contains the character at byte
2358 count {byte} in the current buffer. This includes the
2359 end-of-line character, depending on the 'fileformat' option
2360 for the current buffer. The first character has byte count
2361 one.
2362 Also see |line2byte()|, |go| and |:goto|.
2363 {not available when compiled without the |+byte_offset|
2364 feature}
2365
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002366byteidx({expr}, {nr}) *byteidx()*
2367 Return byte index of the {nr}'th character in the string
2368 {expr}. Use zero for the first character, it returns zero.
2369 This function is only useful when there are multibyte
2370 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002371 Composing characters are not counted separately, their byte
2372 length is added to the preceding base character. See
2373 |byteidxcomp()| below for counting composing characters
2374 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002375 Example : >
2376 echo matchstr(str, ".", byteidx(str, 3))
2377< will display the fourth character. Another way to do the
2378 same: >
2379 let s = strpart(str, byteidx(str, 3))
2380 echo strpart(s, 0, byteidx(s, 1))
2381< If there are less than {nr} characters -1 is returned.
2382 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002383 in bytes is returned.
2384
2385byteidxcomp({expr}, {nr}) *byteidxcomp()*
2386 Like byteidx(), except that a composing character is counted
2387 as a separate character. Example: >
2388 let s = 'e' . nr2char(0x301)
2389 echo byteidx(s, 1)
2390 echo byteidxcomp(s, 1)
2391 echo byteidxcomp(s, 2)
2392< The first and third echo result in 3 ('e' plus composing
2393 character is 3 bytes), the second echo results in 1 ('e' is
2394 one byte).
2395 Only works different from byteidx() when 'encoding' is set to
2396 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002397
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002398call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002399 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002400 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002401 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002402 a:firstline and a:lastline are set to the cursor line.
2403 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002404 {dict} is for functions with the "dict" attribute. It will be
2405 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002406
Bram Moolenaar446cb832008-06-24 21:56:24 +00002407ceil({expr}) *ceil()*
2408 Return the smallest integral value greater than or equal to
2409 {expr} as a |Float| (round up).
2410 {expr} must evaluate to a |Float| or a |Number|.
2411 Examples: >
2412 echo ceil(1.456)
2413< 2.0 >
2414 echo ceil(-5.456)
2415< -5.0 >
2416 echo ceil(4.0)
2417< 4.0
2418 {only available when compiled with the |+float| feature}
2419
Bram Moolenaarca003e12006-03-17 23:19:38 +00002420changenr() *changenr()*
2421 Return the number of the most recent change. This is the same
2422 number as what is displayed with |:undolist| and can be used
2423 with the |:undo| command.
2424 When a change was made it is the number of that change. After
2425 redo it is the number of the redone change. After undo it is
2426 one less than the number of the undone change.
2427
Bram Moolenaard35d7842013-01-23 17:17:10 +01002428char2nr({expr}[, {utf8}]) *char2nr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002429 Return number value of the first char in {expr}. Examples: >
2430 char2nr(" ") returns 32
2431 char2nr("ABC") returns 65
Bram Moolenaard35d7842013-01-23 17:17:10 +01002432< When {utf8} is omitted or zero, the current 'encoding' is used.
2433 Example for "utf-8": >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002434 char2nr("á") returns 225
2435 char2nr("á"[0]) returns 195
Bram Moolenaard35d7842013-01-23 17:17:10 +01002436< With {utf8} set to 1, always treat as utf-8 characters.
2437 A combining character is a separate character.
Bram Moolenaar97293012011-07-18 19:40:27 +02002438 |nr2char()| does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002439
2440cindent({lnum}) *cindent()*
2441 Get the amount of indent for line {lnum} according the C
2442 indenting rules, as with 'cindent'.
2443 The indent is counted in spaces, the value of 'tabstop' is
2444 relevant. {lnum} is used just like in |getline()|.
2445 When {lnum} is invalid or Vim was not compiled the |+cindent|
2446 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00002447 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002448
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002449clearmatches() *clearmatches()*
2450 Clears all matches previously defined by |matchadd()| and the
2451 |:match| commands.
2452
Bram Moolenaar071d4272004-06-13 20:20:40 +00002453 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002454col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00002455 position given with {expr}. The accepted positions are:
2456 . the cursor position
2457 $ the end of the cursor line (the result is the
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02002458 number of bytes in the cursor line plus one)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002459 'x position of mark x (if the mark is not set, 0 is
2460 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01002461 v In Visual mode: the start of the Visual area (the
2462 cursor is the end). When not in Visual mode
2463 returns the cursor position. Differs from |'<| in
2464 that it's updated right away.
Bram Moolenaar477933c2007-07-17 14:32:23 +00002465 Additionally {expr} can be [lnum, col]: a |List| with the line
2466 and column number. Most useful when the column is "$", to get
Bram Moolenaar446cb832008-06-24 21:56:24 +00002467 the last column of a specific line. When "lnum" or "col" is
Bram Moolenaar477933c2007-07-17 14:32:23 +00002468 out of range then col() returns zero.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002469 To get the line number use |line()|. To get both use
Bram Moolenaar0b238792006-03-02 22:49:12 +00002470 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002471 For the screen column position use |virtcol()|.
2472 Note that only marks in the current file can be used.
2473 Examples: >
2474 col(".") column of cursor
2475 col("$") length of cursor line plus one
2476 col("'t") column of mark t
2477 col("'" . markname) column of mark markname
Bram Moolenaar446cb832008-06-24 21:56:24 +00002478< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002479 For an uppercase mark the column may actually be in another
2480 buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002481 For the cursor position, when 'virtualedit' is active, the
2482 column is one higher if the cursor is after the end of the
2483 line. This can be used to obtain the column in Insert mode: >
2484 :imap <F2> <C-O>:let save_ve = &ve<CR>
2485 \<C-O>:set ve=all<CR>
2486 \<C-O>:echo col(".") . "\n" <Bar>
2487 \let &ve = save_ve<CR>
2488<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002489
Bram Moolenaara94bc432006-03-10 21:42:59 +00002490complete({startcol}, {matches}) *complete()* *E785*
2491 Set the matches for Insert mode completion.
2492 Can only be used in Insert mode. You need to use a mapping
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002493 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2494 with an expression mapping.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002495 {startcol} is the byte offset in the line where the completed
2496 text start. The text up to the cursor is the original text
2497 that will be replaced by the matches. Use col('.') for an
2498 empty string. "col('.') - 1" will replace one character by a
2499 match.
2500 {matches} must be a |List|. Each |List| item is one match.
2501 See |complete-items| for the kind of items that are possible.
2502 Note that the after calling this function you need to avoid
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002503 inserting anything that would cause completion to stop.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002504 The match can be selected with CTRL-N and CTRL-P as usual with
2505 Insert mode completion. The popup menu will appear if
2506 specified, see |ins-completion-menu|.
2507 Example: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002508 inoremap <F5> <C-R>=ListMonths()<CR>
Bram Moolenaara94bc432006-03-10 21:42:59 +00002509
2510 func! ListMonths()
2511 call complete(col('.'), ['January', 'February', 'March',
2512 \ 'April', 'May', 'June', 'July', 'August', 'September',
2513 \ 'October', 'November', 'December'])
2514 return ''
2515 endfunc
2516< This isn't very useful, but it shows how it works. Note that
2517 an empty string is returned to avoid a zero being inserted.
2518
Bram Moolenaar572cb562005-08-05 21:35:02 +00002519complete_add({expr}) *complete_add()*
2520 Add {expr} to the list of matches. Only to be used by the
2521 function specified with the 'completefunc' option.
2522 Returns 0 for failure (empty string or out of memory),
2523 1 when the match was added, 2 when the match was already in
2524 the list.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002525 See |complete-functions| for an explanation of {expr}. It is
Bram Moolenaar39f05632006-03-19 22:15:26 +00002526 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002527
2528complete_check() *complete_check()*
2529 Check for a key typed while looking for completion matches.
2530 This is to be used when looking for matches takes some time.
2531 Returns non-zero when searching for matches is to be aborted,
2532 zero otherwise.
2533 Only to be used by the function specified with the
2534 'completefunc' option.
2535
Bram Moolenaar071d4272004-06-13 20:20:40 +00002536 *confirm()*
2537confirm({msg} [, {choices} [, {default} [, {type}]]])
2538 Confirm() offers the user a dialog, from which a choice can be
2539 made. It returns the number of the choice. For the first
2540 choice this is 1.
2541 Note: confirm() is only supported when compiled with dialog
2542 support, see |+dialog_con| and |+dialog_gui|.
Bram Moolenaara800b422010-06-27 01:15:55 +02002543
Bram Moolenaar071d4272004-06-13 20:20:40 +00002544 {msg} is displayed in a |dialog| with {choices} as the
2545 alternatives. When {choices} is missing or empty, "&OK" is
2546 used (and translated).
2547 {msg} is a String, use '\n' to include a newline. Only on
2548 some systems the string is wrapped when it doesn't fit.
Bram Moolenaara800b422010-06-27 01:15:55 +02002549
Bram Moolenaar071d4272004-06-13 20:20:40 +00002550 {choices} is a String, with the individual choices separated
2551 by '\n', e.g. >
2552 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2553< The letter after the '&' is the shortcut key for that choice.
2554 Thus you can type 'c' to select "Cancel". The shortcut does
2555 not need to be the first letter: >
2556 confirm("file has been modified", "&Save\nSave &All")
2557< For the console, the first letter of each choice is used as
2558 the default shortcut key.
Bram Moolenaara800b422010-06-27 01:15:55 +02002559
Bram Moolenaar071d4272004-06-13 20:20:40 +00002560 The optional {default} argument is the number of the choice
2561 that is made if the user hits <CR>. Use 1 to make the first
2562 choice the default one. Use 0 to not set a default. If
2563 {default} is omitted, 1 is used.
Bram Moolenaara800b422010-06-27 01:15:55 +02002564
2565 The optional {type} argument gives the type of dialog. This
2566 is only used for the icon of the GTK, Mac, Motif and Win32
2567 GUI. It can be one of these values: "Error", "Question",
2568 "Info", "Warning" or "Generic". Only the first character is
2569 relevant. When {type} is omitted, "Generic" is used.
2570
Bram Moolenaar071d4272004-06-13 20:20:40 +00002571 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2572 or another valid interrupt key, confirm() returns 0.
2573
2574 An example: >
2575 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2576 :if choice == 0
2577 : echo "make up your mind!"
2578 :elseif choice == 3
2579 : echo "tasteful"
2580 :else
2581 : echo "I prefer bananas myself."
2582 :endif
2583< In a GUI dialog, buttons are used. The layout of the buttons
2584 depends on the 'v' flag in 'guioptions'. If it is included,
Bram Moolenaar446cb832008-06-24 21:56:24 +00002585 the buttons are always put vertically. Otherwise, confirm()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002586 tries to put the buttons in one horizontal line. If they
2587 don't fit, a vertical layout is used anyway. For some systems
2588 the horizontal layout is always used.
2589
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002590 *copy()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002591copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002592 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002593 When {expr} is a |List| a shallow copy is created. This means
2594 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002595 copy, and vice versa. But the items are identical, thus
2596 changing an item changes the contents of both |Lists|. Also
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002597 see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002598
Bram Moolenaar446cb832008-06-24 21:56:24 +00002599cos({expr}) *cos()*
2600 Return the cosine of {expr}, measured in radians, as a |Float|.
2601 {expr} must evaluate to a |Float| or a |Number|.
2602 Examples: >
2603 :echo cos(100)
2604< 0.862319 >
2605 :echo cos(-4.01)
2606< -0.646043
2607 {only available when compiled with the |+float| feature}
2608
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002609
2610cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002611 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002612 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002613 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002614 Examples: >
2615 :echo cosh(0.5)
2616< 1.127626 >
2617 :echo cosh(-0.5)
2618< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02002619 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002620
Bram Moolenaar446cb832008-06-24 21:56:24 +00002621
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002622count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002623 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002624 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002625 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002626 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002627 When {ic} is given and it's non-zero then case is ignored.
2628
2629
Bram Moolenaar071d4272004-06-13 20:20:40 +00002630 *cscope_connection()*
2631cscope_connection([{num} , {dbpath} [, {prepend}]])
2632 Checks for the existence of a |cscope| connection. If no
2633 parameters are specified, then the function returns:
2634 0, if cscope was not available (not compiled in), or
2635 if there are no cscope connections;
2636 1, if there is at least one cscope connection.
2637
2638 If parameters are specified, then the value of {num}
2639 determines how existence of a cscope connection is checked:
2640
2641 {num} Description of existence check
2642 ----- ------------------------------
2643 0 Same as no parameters (e.g., "cscope_connection()").
2644 1 Ignore {prepend}, and use partial string matches for
2645 {dbpath}.
2646 2 Ignore {prepend}, and use exact string matches for
2647 {dbpath}.
2648 3 Use {prepend}, use partial string matches for both
2649 {dbpath} and {prepend}.
2650 4 Use {prepend}, use exact string matches for both
2651 {dbpath} and {prepend}.
2652
2653 Note: All string comparisons are case sensitive!
2654
2655 Examples. Suppose we had the following (from ":cs show"): >
2656
2657 # pid database name prepend path
2658 0 27664 cscope.out /usr/local
2659<
2660 Invocation Return Val ~
2661 ---------- ---------- >
2662 cscope_connection() 1
2663 cscope_connection(1, "out") 1
2664 cscope_connection(2, "out") 0
2665 cscope_connection(3, "out") 0
2666 cscope_connection(3, "out", "local") 1
2667 cscope_connection(4, "out") 0
2668 cscope_connection(4, "out", "local") 0
2669 cscope_connection(4, "cscope.out", "/usr/local") 1
2670<
Bram Moolenaar0b238792006-03-02 22:49:12 +00002671cursor({lnum}, {col} [, {off}]) *cursor()*
2672cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002673 Positions the cursor at the column (byte count) {col} in the
2674 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02002675
Bram Moolenaar0b238792006-03-02 22:49:12 +00002676 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02002677 with two, three or four item:
2678 [{lnum}, {col}, {off}]
2679 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02002680 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002681 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02002682
Bram Moolenaar071d4272004-06-13 20:20:40 +00002683 Does not change the jumplist.
2684 If {lnum} is greater than the number of lines in the buffer,
2685 the cursor will be positioned at the last line in the buffer.
2686 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002687 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002688 the cursor will be positioned at the last character in the
2689 line.
2690 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002691 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02002692 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002693
Bram Moolenaar0b238792006-03-02 22:49:12 +00002694 When 'virtualedit' is used {off} specifies the offset in
2695 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00002696 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00002697 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002698
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002699
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002700deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002701 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002702 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002703 When {expr} is a |List| a full copy is created. This means
2704 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002705 copy, and vice versa. When an item is a |List|, a copy for it
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002706 is made, recursively. Thus changing an item in the copy does
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002707 not change the contents of the original |List|.
2708 When {noref} is omitted or zero a contained |List| or
2709 |Dictionary| is only copied once. All references point to
2710 this single copy. With {noref} set to 1 every occurrence of a
2711 |List| or |Dictionary| results in a new copy. This also means
2712 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002713 *E724*
2714 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002715 that refers back to a higher level making a deep copy with
2716 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002717 Also see |copy()|.
2718
2719delete({fname}) *delete()*
2720 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002721 which is 0 if the file was deleted successfully, and non-zero
2722 when the deletion failed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002723 Use |remove()| to delete an item from a |List|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +01002724 To delete a line from the buffer use |:delete|. Use |:exe|
2725 when the line number is in a variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002726
2727 *did_filetype()*
2728did_filetype() Returns non-zero when autocommands are being executed and the
2729 FileType event has been triggered at least once. Can be used
2730 to avoid triggering the FileType event again in the scripts
2731 that detect the file type. |FileType|
2732 When editing another file, the counter is reset, thus this
2733 really checks if the FileType event has been triggered for the
2734 current buffer. This allows an autocommand that starts
2735 editing another buffer to set 'filetype' and load a syntax
2736 file.
2737
Bram Moolenaar47136d72004-10-12 20:02:24 +00002738diff_filler({lnum}) *diff_filler()*
2739 Returns the number of filler lines above line {lnum}.
2740 These are the lines that were inserted at this point in
2741 another diff'ed window. These filler lines are shown in the
2742 display but don't exist in the buffer.
2743 {lnum} is used like with |getline()|. Thus "." is the current
2744 line, "'m" mark m, etc.
2745 Returns 0 if the current window is not in diff mode.
2746
2747diff_hlID({lnum}, {col}) *diff_hlID()*
2748 Returns the highlight ID for diff mode at line {lnum} column
2749 {col} (byte index). When the current line does not have a
2750 diff change zero is returned.
2751 {lnum} is used like with |getline()|. Thus "." is the current
2752 line, "'m" mark m, etc.
2753 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2754 line.
2755 The highlight ID can be used with |synIDattr()| to obtain
2756 syntax information about the highlighting.
2757
Bram Moolenaar13065c42005-01-08 16:08:21 +00002758empty({expr}) *empty()*
2759 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002760 A |List| or |Dictionary| is empty when it does not have any
Bram Moolenaar446cb832008-06-24 21:56:24 +00002761 items. A Number is empty when its value is zero.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002762 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002763 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002764
Bram Moolenaar071d4272004-06-13 20:20:40 +00002765escape({string}, {chars}) *escape()*
2766 Escape the characters in {chars} that occur in {string} with a
2767 backslash. Example: >
2768 :echo escape('c:\program files\vim', ' \')
2769< results in: >
2770 c:\\program\ files\\vim
Bram Moolenaar446cb832008-06-24 21:56:24 +00002771< Also see |shellescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002772
Bram Moolenaar446cb832008-06-24 21:56:24 +00002773 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002774eval({string}) Evaluate {string} and return the result. Especially useful to
2775 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002776 This works for Numbers, Floats, Strings and composites of
2777 them. Also works for |Funcref|s that refer to existing
2778 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002779
Bram Moolenaar071d4272004-06-13 20:20:40 +00002780eventhandler() *eventhandler()*
2781 Returns 1 when inside an event handler. That is that Vim got
2782 interrupted while waiting for the user to type a character,
2783 e.g., when dropping a file on Vim. This means interactive
2784 commands cannot be used. Otherwise zero is returned.
2785
2786executable({expr}) *executable()*
2787 This function checks if an executable with the name {expr}
2788 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002789 arguments.
2790 executable() uses the value of $PATH and/or the normal
2791 searchpath for programs. *PATHEXT*
2792 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2793 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar446cb832008-06-24 21:56:24 +00002794 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2795 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002796 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar446cb832008-06-24 21:56:24 +00002797 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002798 Unix shell, then the name is also tried without adding an
2799 extension.
2800 On MS-DOS and MS-Windows it only checks if the file exists and
2801 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002802 On MS-Windows an executable in the same directory as Vim is
2803 always found. Since this directory is added to $PATH it
2804 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002805 The result is a Number:
2806 1 exists
2807 0 does not exist
2808 -1 not implemented on this system
2809
Bram Moolenaarc7f02552014-04-01 21:00:59 +02002810exepath({expr}) *exepath()*
2811 If {expr} is an executable and is either an absolute path, a
2812 relative path or found in $PATH, return the full path.
2813 Note that the current directory is used when {expr} starts
2814 with "./", which may be a problem for Vim: >
2815 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02002816< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02002817 an empty string is returned.
2818
Bram Moolenaar071d4272004-06-13 20:20:40 +00002819 *exists()*
2820exists({expr}) The result is a Number, which is non-zero if {expr} is
2821 defined, zero otherwise. The {expr} argument is a string,
2822 which contains one of these:
2823 &option-name Vim option (only checks if it exists,
2824 not if it really works)
2825 +option-name Vim option that works.
2826 $ENVNAME environment variable (could also be
2827 done by comparing with an empty
2828 string)
2829 *funcname built-in function (see |functions|)
2830 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02002831 |user-functions|). Also works for a
2832 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002833 varname internal variable (see
Bram Moolenaar446cb832008-06-24 21:56:24 +00002834 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002835 for |curly-braces-names|, |Dictionary|
2836 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00002837 that evaluating an index may cause an
2838 error message for an invalid
2839 expression. E.g.: >
2840 :let l = [1, 2, 3]
2841 :echo exists("l[5]")
2842< 0 >
2843 :echo exists("l[xx]")
2844< E121: Undefined variable: xx
2845 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00002846 :cmdname Ex command: built-in command, user
2847 command or command modifier |:command|.
2848 Returns:
2849 1 for match with start of a command
2850 2 full match with a command
2851 3 matches several user commands
2852 To check for a supported command
2853 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00002854 :2match The |:2match| command.
2855 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002856 #event autocommand defined for this event
2857 #event#pattern autocommand defined for this event and
2858 pattern (the pattern is taken
2859 literally and compared to the
2860 autocommand patterns character by
2861 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002862 #group autocommand group exists
2863 #group#event autocommand defined for this group and
2864 event.
2865 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002866 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002867 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002868 ##event autocommand for this event is
2869 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002870 For checking for a supported feature use |has()|.
2871
2872 Examples: >
2873 exists("&shortname")
2874 exists("$HOSTNAME")
2875 exists("*strftime")
2876 exists("*s:MyFunc")
2877 exists("bufcount")
2878 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002879 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002880 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002881 exists("#filetypeindent")
2882 exists("#filetypeindent#FileType")
2883 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002884 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002885< There must be no space between the symbol (&/$/*/#) and the
2886 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002887 There must be no extra characters after the name, although in
2888 a few cases this is ignored. That may become more strict in
2889 the future, thus don't count on it!
2890 Working example: >
2891 exists(":make")
2892< NOT working example: >
2893 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00002894
2895< Note that the argument must be a string, not the name of the
2896 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002897 exists(bufcount)
2898< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00002899 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002900
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002901exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002902 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002903 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002904 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002905 Examples: >
2906 :echo exp(2)
2907< 7.389056 >
2908 :echo exp(-1)
2909< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02002910 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002911
2912
Bram Moolenaar84f72352012-03-11 15:57:40 +01002913expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002914 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01002915 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002916
Bram Moolenaar84f72352012-03-11 15:57:40 +01002917 If {list} is given and it is non-zero, a List will be returned.
2918 Otherwise the result is a String and when there are several
2919 matches, they are separated by <NL> characters. [Note: in
2920 version 5.0 a space was used, which caused problems when a
2921 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00002922
Bram Moolenaar446cb832008-06-24 21:56:24 +00002923 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02002924 for a non-existing file is not included, unless {expr} does
2925 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002926
2927 When {expr} starts with '%', '#' or '<', the expansion is done
2928 like for the |cmdline-special| variables with their associated
2929 modifiers. Here is a short overview:
2930
2931 % current file name
2932 # alternate file name
2933 #n alternate file name n
2934 <cfile> file name under the cursor
2935 <afile> autocmd file name
2936 <abuf> autocmd buffer number (as a String!)
2937 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01002938 <sfile> sourced script file or function name
Bram Moolenaar81af9252010-12-10 20:35:50 +01002939 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00002940 <cword> word under the cursor
2941 <cWORD> WORD under the cursor
2942 <client> the {clientid} of the last received
2943 message |server2client()|
2944 Modifiers:
2945 :p expand to full path
2946 :h head (last path component removed)
2947 :t tail (last path component only)
2948 :r root (one extension removed)
2949 :e extension only
2950
2951 Example: >
2952 :let &tags = expand("%:p:h") . "/tags"
2953< Note that when expanding a string that starts with '%', '#' or
2954 '<', any following text is ignored. This does NOT work: >
2955 :let doesntwork = expand("%:h.bak")
2956< Use this: >
2957 :let doeswork = expand("%:h") . ".bak"
2958< Also note that expanding "<cfile>" and others only returns the
2959 referenced file name without further expansion. If "<cfile>"
2960 is "~/.cshrc", you need to do another expand() to have the
2961 "~/" expanded into the path of the home directory: >
2962 :echo expand(expand("<cfile>"))
2963<
2964 There cannot be white space between the variables and the
2965 following modifier. The |fnamemodify()| function can be used
2966 to modify normal file names.
2967
2968 When using '%' or '#', and the current or alternate file name
2969 is not defined, an empty string is used. Using "%:p" in a
2970 buffer with no name, results in the current directory, with a
2971 '/' added.
2972
2973 When {expr} does not start with '%', '#' or '<', it is
2974 expanded like a file name is expanded on the command line.
2975 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002976 {nosuf} argument is given and it is non-zero.
2977 Names for non-existing files are included. The "**" item can
2978 be used to search in a directory tree. For example, to find
2979 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00002980 :echo expand("**/README")
2981<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002982 Expand() can also be used to expand variables and environment
2983 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02002984 slow, because a shell may be used to do the expansion. See
2985 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002986 The expanded variable is still handled like a list of file
Bram Moolenaar446cb832008-06-24 21:56:24 +00002987 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002988 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2989 "$FOOBAR".
2990
2991 See |glob()| for finding existing files. See |system()| for
2992 getting the raw output of an external command.
2993
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002994extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002995 {expr1} and {expr2} must be both |Lists| or both
2996 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002997
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002998 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002999 If {expr3} is given insert the items of {expr2} before item
3000 {expr3} in {expr1}. When {expr3} is zero insert before the
3001 first item. When {expr3} is equal to len({expr1}) then
3002 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003003 Examples: >
3004 :echo sort(extend(mylist, [7, 5]))
3005 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00003006< When {expr1} is the same List as {expr2} then the number of
3007 items copied is equal to the original length of the List.
3008 E.g., when {expr3} is 1 you get N new copies of the first item
3009 (where N is the original length of the List).
3010 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003011 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003012 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003013<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003014 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003015 Add all entries from {expr2} to {expr1}.
3016 If a key exists in both {expr1} and {expr2} then {expr3} is
3017 used to decide what to do:
3018 {expr3} = "keep": keep the value of {expr1}
3019 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003020 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003021 When {expr3} is omitted then "force" is assumed.
3022
3023 {expr1} is changed when {expr2} is not empty. If necessary
3024 make a copy of {expr1} first.
3025 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02003026 When {expr1} is locked and {expr2} is not empty the operation
3027 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003028 Returns {expr1}.
3029
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003030
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003031feedkeys({string} [, {mode}]) *feedkeys()*
3032 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003033 come from a mapping or were typed by the user.
3034 By default the string is added to the end of the typeahead
3035 buffer, thus if a mapping is still being executed the
3036 characters come after them. Use the 'i' flag to insert before
3037 other characters, they will be executed next, before any
3038 characters from a mapping.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003039 The function does not wait for processing of keys contained in
3040 {string}.
3041 To include special keys into {string}, use double-quotes
3042 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00003043 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003044 feedkeys('\<CR>') pushes 5 characters.
3045 If {mode} is absent, keys are remapped.
3046 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003047 'm' Remap keys. This is default.
3048 'n' Do not remap keys.
3049 't' Handle keys as if typed; otherwise they are handled as
3050 if coming from a mapping. This matters for undo,
3051 opening folds, etc.
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003052 'i' Insert the string instead of appending (see above).
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003053 Return value is always 0.
3054
Bram Moolenaar071d4272004-06-13 20:20:40 +00003055filereadable({file}) *filereadable()*
3056 The result is a Number, which is TRUE when a file with the
3057 name {file} exists, and can be read. If {file} doesn't exist,
3058 or is a directory, the result is FALSE. {file} is any
3059 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003060 If you don't care about the file being readable you can use
3061 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003062 *file_readable()*
3063 Obsolete name: file_readable().
3064
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003065
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003066filewritable({file}) *filewritable()*
3067 The result is a Number, which is 1 when a file with the
3068 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00003069 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003070 directory, and we can write to it, the result is 2.
3071
3072
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003073filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003074 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003075 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003076 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003077 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003078 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003079 Examples: >
3080 :call filter(mylist, 'v:val !~ "OLD"')
3081< Removes the items where "OLD" appears. >
3082 :call filter(mydict, 'v:key >= 8')
3083< Removes the items with a key below 8. >
3084 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003085< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003086
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003087 Note that {string} is the result of expression and is then
3088 used as an expression again. Often it is good to use a
3089 |literal-string| to avoid having to double backslashes.
3090
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003091 The operation is done in-place. If you want a |List| or
3092 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00003093 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003094
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003095< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00003096 When an error is encountered while evaluating {string} no
3097 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003098
3099
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003100finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00003101 Find directory {name} in {path}. Supports both downwards and
3102 upwards recursive directory searches. See |file-searching|
3103 for the syntax of {path}.
3104 Returns the path of the first found match. When the found
3105 directory is below the current directory a relative path is
3106 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003107 If {path} is omitted or empty then 'path' is used.
3108 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003109 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00003110 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003111 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003112 {only available when compiled with the |+file_in_path|
3113 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003114
3115findfile({name}[, {path}[, {count}]]) *findfile()*
3116 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003117 Uses 'suffixesadd'.
3118 Example: >
3119 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003120< Searches from the directory of the current file upwards until
3121 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003122
Bram Moolenaar446cb832008-06-24 21:56:24 +00003123float2nr({expr}) *float2nr()*
3124 Convert {expr} to a Number by omitting the part after the
3125 decimal point.
3126 {expr} must evaluate to a |Float| or a Number.
3127 When the value of {expr} is out of range for a |Number| the
3128 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
3129 in -0x80000000.
3130 Examples: >
3131 echo float2nr(3.95)
3132< 3 >
3133 echo float2nr(-23.45)
3134< -23 >
3135 echo float2nr(1.0e100)
3136< 2147483647 >
3137 echo float2nr(-1.0e150)
3138< -2147483647 >
3139 echo float2nr(1.0e-100)
3140< 0
3141 {only available when compiled with the |+float| feature}
3142
3143
3144floor({expr}) *floor()*
3145 Return the largest integral value less than or equal to
3146 {expr} as a |Float| (round down).
3147 {expr} must evaluate to a |Float| or a |Number|.
3148 Examples: >
3149 echo floor(1.856)
3150< 1.0 >
3151 echo floor(-5.456)
3152< -6.0 >
3153 echo floor(4.0)
3154< 4.0
3155 {only available when compiled with the |+float| feature}
3156
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003157
3158fmod({expr1}, {expr2}) *fmod()*
3159 Return the remainder of {expr1} / {expr2}, even if the
3160 division is not representable. Returns {expr1} - i * {expr2}
3161 for some integer i such that if {expr2} is non-zero, the
3162 result has the same sign as {expr1} and magnitude less than
3163 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003164 returned is zero. The value returned is a |Float|.
3165 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003166 Examples: >
3167 :echo fmod(12.33, 1.22)
3168< 0.13 >
3169 :echo fmod(-12.33, 1.22)
3170< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02003171 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003172
3173
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003174fnameescape({string}) *fnameescape()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003175 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003176 characters that have a special meaning, such as '%' and '|'
3177 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003178 For most systems the characters escaped are
3179 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3180 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003181 A leading '+' and '>' is also escaped (special after |:edit|
3182 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003183 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003184 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003185 :exe "edit " . fnameescape(fname)
3186< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003187 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003188
Bram Moolenaar071d4272004-06-13 20:20:40 +00003189fnamemodify({fname}, {mods}) *fnamemodify()*
3190 Modify file name {fname} according to {mods}. {mods} is a
3191 string of characters like it is used for file names on the
3192 command line. See |filename-modifiers|.
3193 Example: >
3194 :echo fnamemodify("main.c", ":p:h")
3195< results in: >
3196 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003197< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003198 |expand()| first then.
3199
3200foldclosed({lnum}) *foldclosed()*
3201 The result is a Number. If the line {lnum} is in a closed
3202 fold, the result is the number of the first line in that fold.
3203 If the line {lnum} is not in a closed fold, -1 is returned.
3204
3205foldclosedend({lnum}) *foldclosedend()*
3206 The result is a Number. If the line {lnum} is in a closed
3207 fold, the result is the number of the last line in that fold.
3208 If the line {lnum} is not in a closed fold, -1 is returned.
3209
3210foldlevel({lnum}) *foldlevel()*
3211 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003212 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003213 returned. If there is no fold at line {lnum}, zero is
3214 returned. It doesn't matter if the folds are open or closed.
3215 When used while updating folds (from 'foldexpr') -1 is
3216 returned for lines where folds are still to be updated and the
3217 foldlevel is unknown. As a special case the level of the
3218 previous line is usually available.
3219
3220 *foldtext()*
3221foldtext() Returns a String, to be displayed for a closed fold. This is
3222 the default function used for the 'foldtext' option and should
3223 only be called from evaluating 'foldtext'. It uses the
3224 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3225 The returned string looks like this: >
3226 +-- 45 lines: abcdef
Bram Moolenaar446cb832008-06-24 21:56:24 +00003227< The number of dashes depends on the foldlevel. The "45" is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003228 the number of lines in the fold. "abcdef" is the text in the
3229 first non-blank line of the fold. Leading white space, "//"
3230 or "/*" and the text from the 'foldmarker' and 'commentstring'
3231 options is removed.
3232 {not available when compiled without the |+folding| feature}
3233
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003234foldtextresult({lnum}) *foldtextresult()*
3235 Returns the text that is displayed for the closed fold at line
3236 {lnum}. Evaluates 'foldtext' in the appropriate context.
3237 When there is no closed fold at {lnum} an empty string is
3238 returned.
3239 {lnum} is used like with |getline()|. Thus "." is the current
3240 line, "'m" mark m, etc.
3241 Useful when exporting folded text, e.g., to HTML.
3242 {not available when compiled without the |+folding| feature}
3243
Bram Moolenaar071d4272004-06-13 20:20:40 +00003244 *foreground()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003245foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00003246 a client to a Vim server. |remote_send()|
3247 On Win32 systems this might not work, the OS does not always
3248 allow a window to bring itself to the foreground. Use
3249 |remote_foreground()| instead.
3250 {only in the Win32, Athena, Motif and GTK GUI versions and the
3251 Win32 console version}
3252
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003253
Bram Moolenaar13065c42005-01-08 16:08:21 +00003254function({name}) *function()* *E700*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003255 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003256 {name} can be a user defined function or an internal function.
3257
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003258
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003259garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003260 Cleanup unused |Lists| and |Dictionaries| that have circular
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003261 references. There is hardly ever a need to invoke this
3262 function, as it is automatically done when Vim runs out of
3263 memory or is waiting for the user to press a key after
3264 'updatetime'. Items without circular references are always
3265 freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003266 This is useful if you have deleted a very big |List| and/or
3267 |Dictionary| with circular references in a script that runs
3268 for a long time.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003269 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003270 collection will also be done when exiting Vim, if it wasn't
3271 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003272
Bram Moolenaar677ee682005-01-27 14:41:15 +00003273get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003274 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003275 available return {default}. Return zero when {default} is
3276 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003277get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003278 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003279 item is not available return {default}. Return zero when
3280 {default} is omitted.
3281
Bram Moolenaar45360022005-07-21 21:08:21 +00003282 *getbufline()*
3283getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003284 Return a |List| with the lines starting from {lnum} to {end}
3285 (inclusive) in the buffer {expr}. If {end} is omitted, a
3286 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003287
3288 For the use of {expr}, see |bufname()| above.
3289
Bram Moolenaar661b1822005-07-28 22:36:45 +00003290 For {lnum} and {end} "$" can be used for the last line of the
3291 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00003292
3293 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003294 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003295
3296 When {end} is greater than the number of lines in the buffer,
3297 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003298 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00003299 returned.
3300
Bram Moolenaar661b1822005-07-28 22:36:45 +00003301 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003302 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003303
3304 Example: >
3305 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003306
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003307getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003308 The result is the value of option or local buffer variable
3309 {varname} in buffer {expr}. Note that the name without "b:"
3310 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003311 When {varname} is empty returns a dictionary with all the
3312 buffer-local variables.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00003313 This also works for a global or buffer-local option, but it
3314 doesn't work for a global variable, window-local variable or
3315 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003316 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003317 When the buffer or variable doesn't exist {def} or an empty
3318 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003319 Examples: >
3320 :let bufmodified = getbufvar(1, "&mod")
3321 :echo "todo myvar = " . getbufvar("todo", "myvar")
3322<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003323getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00003324 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003325 If [expr] is omitted, wait until a character is available.
3326 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003327 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003328 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00003329 not consumed. Return zero if no character available.
3330
Bram Moolenaardfb18412013-12-11 18:53:29 +01003331 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaar91170f82006-05-05 21:15:17 +00003332 special key is returned. If it is an 8-bit character, the
3333 result is a number. Use nr2char() to convert it to a String.
3334 Otherwise a String is returned with the encoded character.
3335 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003336 (decimal: 128). This is the same value as the string
3337 "\<Key>", e.g., "\<Left>". The returned value is also a
3338 String when a modifier (shift, control, alt) was used that is
3339 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003340
Bram Moolenaar822ff862014-06-12 21:46:14 +02003341 When [expr] is 0 and Esc is typed, there will be a short delay
3342 while Vim waits to see if this is the start of an escape
3343 sequence.
3344
Bram Moolenaardfb18412013-12-11 18:53:29 +01003345 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003346 one-byte character it is the character itself as a number.
3347 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003348
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003349 Use getcharmod() to obtain any additional modifiers.
3350
Bram Moolenaar219b8702006-11-01 14:32:36 +00003351 When the user clicks a mouse button, the mouse event will be
3352 returned. The position can then be found in |v:mouse_col|,
3353 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3354 mouse as it would normally happen: >
3355 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003356 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00003357 exe v:mouse_win . "wincmd w"
3358 exe v:mouse_lnum
3359 exe "normal " . v:mouse_col . "|"
3360 endif
3361<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003362 There is no prompt, you will somehow have to make clear to the
3363 user that a character has to be typed.
3364 There is no mapping for the character.
3365 Key codes are replaced, thus when the user presses the <Del>
3366 key you get the code for the <Del> key, not the raw character
3367 sequence. Examples: >
3368 getchar() == "\<Del>"
3369 getchar() == "\<S-Left>"
3370< This example redefines "f" to ignore case: >
3371 :nmap f :call FindChar()<CR>
3372 :function FindChar()
3373 : let c = nr2char(getchar())
3374 : while col('.') < col('$') - 1
3375 : normal l
3376 : if getline('.')[col('.') - 1] ==? c
3377 : break
3378 : endif
3379 : endwhile
3380 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01003381<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003382 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01003383 |<CursorHold>|. Often you will want to ignore this and get
3384 another character: >
3385 :function GetKey()
3386 : let c = getchar()
3387 : while c == "\<CursorHold>"
3388 : let c = getchar()
3389 : endwhile
3390 : return c
3391 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00003392
3393getcharmod() *getcharmod()*
3394 The result is a Number which is the state of the modifiers for
3395 the last obtained character with getchar() or in another way.
3396 These values are added together:
3397 2 shift
3398 4 control
3399 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003400 16 meta (when it's different from ALT)
3401 32 mouse double click
3402 64 mouse triple click
3403 96 mouse quadruple click (== 32 + 64)
3404 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003405 Only the modifiers that have not been included in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003406 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003407 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003408
Bram Moolenaardbd24b52015-08-11 14:26:19 +02003409getcharsearch() *getcharsearch()*
3410 Return the current character search information as a {dict}
3411 with the following entries:
3412
3413 char character previously used for a character
3414 search (|t|, |f|, |T|, or |F|); empty string
3415 if no character search has been performed
3416 forward direction of character search; 1 for forward,
3417 0 for backward
3418 until type of character search; 1 for a |t| or |T|
3419 character search, 0 for an |f| or |F|
3420 character search
3421
3422 This can be useful to always have |;| and |,| search
3423 forward/backward regardless of the direction of the previous
3424 character search: >
3425 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3426 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3427< Also see |setcharsearch()|.
3428
Bram Moolenaar071d4272004-06-13 20:20:40 +00003429getcmdline() *getcmdline()*
3430 Return the current command-line. Only works when the command
3431 line is being edited, thus requires use of |c_CTRL-\_e| or
3432 |c_CTRL-R_=|.
3433 Example: >
3434 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003435< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003436
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003437getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003438 Return the position of the cursor in the command line as a
3439 byte count. The first column is 1.
3440 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003441 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3442 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003443 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3444
3445getcmdtype() *getcmdtype()*
3446 Return the current command-line type. Possible return values
3447 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00003448 : normal Ex command
3449 > debug mode command |debug-mode|
3450 / forward search command
3451 ? backward search command
3452 @ |input()| command
3453 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02003454 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003455 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003456 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3457 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003458 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003459
Bram Moolenaarfb539272014-08-22 19:21:47 +02003460getcmdwintype() *getcmdwintype()*
3461 Return the current |command-line-window| type. Possible return
3462 values are the same as |getcmdtype()|. Returns an empty string
3463 when not in the command-line window.
3464
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003465 *getcurpos()*
3466getcurpos() Get the position of the cursor. This is like getpos('.'), but
3467 includes an extra item in the list:
3468 [bufnum, lnum, col, off, curswant]
3469 The "curswant" number is the preferred column when moving the
3470 cursor vertically.
3471 This can be used to save and restore the cursor position: >
3472 let save_cursor = getcurpos()
3473 MoveTheCursorAround
3474 call setpos('.', save_cursor)
Bram Moolenaarfb539272014-08-22 19:21:47 +02003475<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003476 *getcwd()*
3477getcwd() The result is a String, which is the name of the current
3478 working directory.
3479
3480getfsize({fname}) *getfsize()*
3481 The result is a Number, which is the size in bytes of the
3482 given file {fname}.
3483 If {fname} is a directory, 0 is returned.
3484 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00003485 If the size of {fname} is too big to fit in a Number then -2
3486 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003487
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003488getfontname([{name}]) *getfontname()*
3489 Without an argument returns the name of the normal font being
3490 used. Like what is used for the Normal highlight group
3491 |hl-Normal|.
3492 With an argument a check is done whether {name} is a valid
3493 font name. If not then an empty string is returned.
3494 Otherwise the actual font name is returned, or {name} if the
3495 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00003496 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003497 gvimrc file. Use the |GUIEnter| autocommand to use this
3498 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003499 Note that the GTK 2 GUI accepts any font name, thus checking
3500 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003501
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003502getfperm({fname}) *getfperm()*
3503 The result is a String, which is the read, write, and execute
3504 permissions of the given file {fname}.
3505 If {fname} does not exist or its directory cannot be read, an
3506 empty string is returned.
3507 The result is of the form "rwxrwxrwx", where each group of
3508 "rwx" flags represent, in turn, the permissions of the owner
3509 of the file, the group the file belongs to, and other users.
3510 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02003511 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003512 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02003513 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003514< This will hopefully (from a security point of view) display
3515 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003516
Bram Moolenaar071d4272004-06-13 20:20:40 +00003517getftime({fname}) *getftime()*
3518 The result is a Number, which is the last modification time of
3519 the given file {fname}. The value is measured as seconds
3520 since 1st Jan 1970, and may be passed to strftime(). See also
3521 |localtime()| and |strftime()|.
3522 If the file {fname} can't be found -1 is returned.
3523
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003524getftype({fname}) *getftype()*
3525 The result is a String, which is a description of the kind of
3526 file of the given file {fname}.
3527 If {fname} does not exist an empty string is returned.
3528 Here is a table over different kinds of files and their
3529 results:
3530 Normal file "file"
3531 Directory "dir"
3532 Symbolic link "link"
3533 Block device "bdev"
3534 Character device "cdev"
3535 Socket "socket"
3536 FIFO "fifo"
3537 All other "other"
3538 Example: >
3539 getftype("/home")
3540< Note that a type such as "link" will only be returned on
3541 systems that support it. On some systems only "dir" and
3542 "file" are returned.
3543
Bram Moolenaar071d4272004-06-13 20:20:40 +00003544 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003545getline({lnum} [, {end}])
3546 Without {end} the result is a String, which is line {lnum}
3547 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003548 getline(1)
3549< When {lnum} is a String that doesn't start with a
3550 digit, line() is called to translate the String into a Number.
3551 To get the line under the cursor: >
3552 getline(".")
3553< When {lnum} is smaller than 1 or bigger than the number of
3554 lines in the buffer, an empty string is returned.
3555
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003556 When {end} is given the result is a |List| where each item is
3557 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003558 including line {end}.
3559 {end} is used in the same way as {lnum}.
3560 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003561 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003562 Example: >
3563 :let start = line('.')
3564 :let end = search("^$") - 1
3565 :let lines = getline(start, end)
3566
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003567< To get lines from another buffer see |getbufline()|
3568
Bram Moolenaar17c7c012006-01-26 22:25:15 +00003569getloclist({nr}) *getloclist()*
3570 Returns a list with all the entries in the location list for
3571 window {nr}. When {nr} is zero the current window is used.
3572 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00003573 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003574 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003575
Bram Moolenaar6ee10162007-07-26 20:58:42 +00003576getmatches() *getmatches()*
3577 Returns a |List| with all matches previously defined by
3578 |matchadd()| and the |:match| commands. |getmatches()| is
3579 useful in combination with |setmatches()|, as |setmatches()|
3580 can restore a list of matches saved by |getmatches()|.
3581 Example: >
3582 :echo getmatches()
3583< [{'group': 'MyGroup1', 'pattern': 'TODO',
3584 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3585 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3586 :let m = getmatches()
3587 :call clearmatches()
3588 :echo getmatches()
3589< [] >
3590 :call setmatches(m)
3591 :echo getmatches()
3592< [{'group': 'MyGroup1', 'pattern': 'TODO',
3593 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3594 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3595 :unlet m
3596<
Bram Moolenaar822ff862014-06-12 21:46:14 +02003597 *getpid()*
3598getpid() Return a Number which is the process ID of the Vim process.
3599 On Unix and MS-Windows this is a unique number, until Vim
3600 exits. On MS-DOS it's always zero.
3601
3602 *getpos()*
3603getpos({expr}) Get the position for {expr}. For possible values of {expr}
3604 see |line()|. For getting the cursor position see
3605 |getcurpos()|.
3606 The result is a |List| with four numbers:
3607 [bufnum, lnum, col, off]
3608 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3609 is the buffer number of the mark.
3610 "lnum" and "col" are the position in the buffer. The first
3611 column is 1.
3612 The "off" number is zero, unless 'virtualedit' is used. Then
3613 it is the offset in screen columns from the start of the
3614 character. E.g., a position within a <Tab> or after the last
3615 character.
3616 Note that for '< and '> Visual mode matters: when it is "V"
3617 (visual line mode) the column of '< is zero and the column of
3618 '> is a large number.
3619 This can be used to save and restore the position of a mark: >
3620 let save_a_mark = getpos("'a")
3621 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01003622 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02003623< Also see |getcurpos()| and |setpos()|.
3624
Bram Moolenaar6ee10162007-07-26 20:58:42 +00003625
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003626getqflist() *getqflist()*
3627 Returns a list with all the current quickfix errors. Each
3628 list item is a dictionary with these entries:
3629 bufnr number of buffer that has the file name, use
3630 bufname() to get the name
3631 lnum line number in the buffer (first line is 1)
3632 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00003633 vcol non-zero: "col" is visual column
3634 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003635 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00003636 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003637 text description of the error
3638 type type of the error, 'E', '1', etc.
3639 valid non-zero: recognized error message
3640
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00003641 When there is no error list or it's empty an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00003642 returned. Quickfix list entries with non-existing buffer
3643 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00003644
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003645 Useful application: Find pattern matches in multiple files and
3646 do something with them: >
3647 :vimgrep /theword/jg *.c
3648 :for d in getqflist()
3649 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3650 :endfor
3651
3652
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02003653getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003654 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003655 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003656 :let cliptext = getreg('*')
3657< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003658 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003659 getreg('=', 1) returns the expression itself, so that it can
3660 be restored with |setreg()|. For other registers the extra
3661 argument is ignored, thus you can always give it.
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02003662 If {list} is present and non-zero result type is changed to
3663 |List|. Each list item is one text line. Use it if you care
3664 about zero bytes possibly present inside register: without
3665 third argument both NLs and zero bytes are represented as NLs
3666 (see |NL-used-for-Nul|).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003667 If {regname} is not specified, |v:register| is used.
3668
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003669
Bram Moolenaar071d4272004-06-13 20:20:40 +00003670getregtype([{regname}]) *getregtype()*
3671 The result is a String, which is type of register {regname}.
3672 The value will be one of:
3673 "v" for |characterwise| text
3674 "V" for |linewise| text
3675 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01003676 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00003677 <CTRL-V> is one character with value 0x16.
3678 If {regname} is not specified, |v:register| is used.
3679
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003680gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02003681 Get the value of a tab-local variable {varname} in tab page
3682 {tabnr}. |t:var|
3683 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02003684 When {varname} is empty a dictionary with all tab-local
3685 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02003686 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003687 When the tab or variable doesn't exist {def} or an empty
3688 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02003689
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003690gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003691 Get the value of window-local variable {varname} in window
3692 {winnr} in tab page {tabnr}.
3693 When {varname} starts with "&" get the value of a window-local
3694 option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003695 When {varname} is empty a dictionary with all window-local
3696 variables is returned.
3697 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003698 Tabs are numbered starting with one. For the current tabpage
3699 use |getwinvar()|.
3700 When {winnr} is zero the current window is used.
3701 This also works for a global option, buffer-local option and
3702 window-local option, but it doesn't work for a global variable
3703 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003704 When the tab, window or variable doesn't exist {def} or an
3705 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003706 Examples: >
3707 :let list_is_on = gettabwinvar(1, 2, '&list')
3708 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003709<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003710 *getwinposx()*
3711getwinposx() The result is a Number, which is the X coordinate in pixels of
3712 the left hand side of the GUI Vim window. The result will be
3713 -1 if the information is not available.
3714
3715 *getwinposy()*
3716getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar446cb832008-06-24 21:56:24 +00003717 the top of the GUI Vim window. The result will be -1 if the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003718 information is not available.
3719
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003720getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003721 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003722 Examples: >
3723 :let list_is_on = getwinvar(2, '&list')
3724 :echo "myvar = " . getwinvar(1, 'myvar')
3725<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01003726glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003727 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003728 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003729
3730 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003731 the 'suffixes' and 'wildignore' options apply: Names matching
3732 one of the patterns in 'wildignore' will be skipped and
3733 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01003734 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003735
3736 When {list} is present and it is non-zero the result is a List
3737 with all matching files. The advantage of using a List is,
3738 you also get filenames containing newlines correctly.
3739 Otherwise the result is a String and when there are several
3740 matches, they are separated by <NL> characters.
3741
3742 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01003743
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02003744 A name for a non-existing file is not included. A symbolic
3745 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01003746 However, when the {alllinks} argument is present and it is
3747 non-zero then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003748
3749 For most systems backticks can be used to get files names from
3750 any external command. Example: >
3751 :let tagfiles = glob("`find . -name tags -print`")
3752 :let &tags = substitute(tagfiles, "\n", ",", "g")
3753< The result of the program inside the backticks should be one
Bram Moolenaar446cb832008-06-24 21:56:24 +00003754 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003755
3756 See |expand()| for expanding special Vim variables. See
3757 |system()| for getting the raw output of an external command.
3758
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01003759glob2regpat({expr}) *glob2regpat()*
3760 Convert a file pattern, as used by glob(), into a search
3761 pattern. The result can be used to match with a string that
3762 is a file name. E.g. >
3763 if filename =~ glob2regpat('Make*.mak')
3764< This is equivalent to: >
3765 if filename =~ '^Make.*\.mak$'
3766<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01003767 *globpath()*
3768globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00003769 Perform glob() on all directories in {path} and concatenate
3770 the results. Example: >
3771 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02003772<
3773 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00003774 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003775 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003776 To add a comma inside a directory name escape it with a
3777 backslash. Note that on MS-Windows a directory may have a
3778 trailing backslash, remove it if you put a comma after it.
3779 If the expansion fails for one of the directories, there is no
3780 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02003781
3782 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003783 the 'suffixes' and 'wildignore' options apply: Names matching
3784 one of the patterns in 'wildignore' will be skipped and
3785 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003786
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02003787 When {list} is present and it is non-zero the result is a List
3788 with all matching files. The advantage of using a List is, you
3789 also get filenames containing newlines correctly. Otherwise
3790 the result is a String and when there are several matches,
3791 they are separated by <NL> characters. Example: >
3792 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
3793<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01003794 {allinks} is used as with |glob()|.
3795
Bram Moolenaar02743632005-07-25 20:42:36 +00003796 The "**" item can be used to search in a directory tree.
3797 For example, to find all "README.txt" files in the directories
3798 in 'runtimepath' and below: >
3799 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00003800< Upwards search and limiting the depth of "**" is not
3801 supported, thus using 'path' will not always work properly.
3802
Bram Moolenaar071d4272004-06-13 20:20:40 +00003803 *has()*
3804has({feature}) The result is a Number, which is 1 if the feature {feature} is
3805 supported, zero otherwise. The {feature} argument is a
3806 string. See |feature-list| below.
3807 Also see |exists()|.
3808
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003809
3810has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003811 The result is a Number, which is 1 if |Dictionary| {dict} has
3812 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003813
Bram Moolenaard267b9c2007-04-26 15:06:45 +00003814haslocaldir() *haslocaldir()*
3815 The result is a Number, which is 1 when the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00003816 window has set a local path via |:lcd|, and 0 otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003817
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003818hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003819 The result is a Number, which is 1 if there is a mapping that
3820 contains {what} in somewhere in the rhs (what it is mapped to)
3821 and this mapping exists in one of the modes indicated by
3822 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003823 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00003824 instead of mappings. Don't forget to specify Insert and/or
3825 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003826 Both the global mappings and the mappings local to the current
3827 buffer are checked for a match.
3828 If no matching mapping is found 0 is returned.
3829 The following characters are recognized in {mode}:
3830 n Normal mode
3831 v Visual mode
3832 o Operator-pending mode
3833 i Insert mode
3834 l Language-Argument ("r", "f", "t", etc.)
3835 c Command-line mode
3836 When {mode} is omitted, "nvo" is used.
3837
3838 This function is useful to check if a mapping already exists
Bram Moolenaar446cb832008-06-24 21:56:24 +00003839 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003840 :if !hasmapto('\ABCdoit')
3841 : map <Leader>d \ABCdoit
3842 :endif
3843< This installs the mapping to "\ABCdoit" only if there isn't
3844 already a mapping to "\ABCdoit".
3845
3846histadd({history}, {item}) *histadd()*
3847 Add the String {item} to the history {history} which can be
3848 one of: *hist-names*
3849 "cmd" or ":" command line history
3850 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00003851 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00003852 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02003853 "debug" or ">" debug command history
3854 The {history} string does not need to be the whole name, one
3855 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003856 If {item} does already exist in the history, it will be
3857 shifted to become the newest entry.
3858 The result is a Number: 1 if the operation was successful,
3859 otherwise 0 is returned.
3860
3861 Example: >
3862 :call histadd("input", strftime("%Y %b %d"))
3863 :let date=input("Enter date: ")
3864< This function is not available in the |sandbox|.
3865
3866histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003867 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003868 for the possible values of {history}.
3869
Bram Moolenaarc236c162008-07-13 17:41:49 +00003870 If the parameter {item} evaluates to a String, it is used as a
3871 regular expression. All entries matching that expression will
3872 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003873 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003874 If {item} evaluates to a Number, it will be interpreted as
3875 an index, see |:history-indexing|. The respective entry will
3876 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003877
3878 The result is a Number: 1 for a successful operation,
3879 otherwise 0 is returned.
3880
3881 Examples:
3882 Clear expression register history: >
3883 :call histdel("expr")
3884<
3885 Remove all entries starting with "*" from the search history: >
3886 :call histdel("/", '^\*')
3887<
3888 The following three are equivalent: >
3889 :call histdel("search", histnr("search"))
3890 :call histdel("search", -1)
3891 :call histdel("search", '^'.histget("search", -1).'$')
3892<
3893 To delete the last search pattern and use the last-but-one for
3894 the "n" command and 'hlsearch': >
3895 :call histdel("search", -1)
3896 :let @/ = histget("search", -1)
3897
3898histget({history} [, {index}]) *histget()*
3899 The result is a String, the entry with Number {index} from
3900 {history}. See |hist-names| for the possible values of
3901 {history}, and |:history-indexing| for {index}. If there is
3902 no such entry, an empty String is returned. When {index} is
3903 omitted, the most recent item from the history is used.
3904
3905 Examples:
3906 Redo the second last search from history. >
3907 :execute '/' . histget("search", -2)
3908
3909< Define an Ex command ":H {num}" that supports re-execution of
3910 the {num}th entry from the output of |:history|. >
3911 :command -nargs=1 H execute histget("cmd", 0+<args>)
3912<
3913histnr({history}) *histnr()*
3914 The result is the Number of the current entry in {history}.
3915 See |hist-names| for the possible values of {history}.
3916 If an error occurred, -1 is returned.
3917
3918 Example: >
3919 :let inp_index = histnr("expr")
3920<
3921hlexists({name}) *hlexists()*
3922 The result is a Number, which is non-zero if a highlight group
3923 called {name} exists. This is when the group has been
3924 defined in some way. Not necessarily when highlighting has
3925 been defined for it, it may also have been used for a syntax
3926 item.
3927 *highlight_exists()*
3928 Obsolete name: highlight_exists().
3929
3930 *hlID()*
3931hlID({name}) The result is a Number, which is the ID of the highlight group
3932 with name {name}. When the highlight group doesn't exist,
3933 zero is returned.
3934 This can be used to retrieve information about the highlight
Bram Moolenaar446cb832008-06-24 21:56:24 +00003935 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003936 "Comment" group: >
3937 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3938< *highlightID()*
3939 Obsolete name: highlightID().
3940
3941hostname() *hostname()*
3942 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003943 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00003944 256 characters long are truncated.
3945
3946iconv({expr}, {from}, {to}) *iconv()*
3947 The result is a String, which is the text {expr} converted
3948 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003949 When the conversion completely fails an empty string is
3950 returned. When some characters could not be converted they
3951 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003952 The encoding names are whatever the iconv() library function
3953 can accept, see ":!man 3 iconv".
3954 Most conversions require Vim to be compiled with the |+iconv|
3955 feature. Otherwise only UTF-8 to latin1 conversion and back
3956 can be done.
3957 This can be used to display messages with special characters,
3958 no matter what 'encoding' is set to. Write the message in
3959 UTF-8 and use: >
3960 echo iconv(utf8_str, "utf-8", &enc)
3961< Note that Vim uses UTF-8 for all Unicode encodings, conversion
3962 from/to UCS-2 is automatically changed to use UTF-8. You
3963 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003964 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003965
3966 *indent()*
3967indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3968 current buffer. The indent is counted in spaces, the value
3969 of 'tabstop' is relevant. {lnum} is used just like in
3970 |getline()|.
3971 When {lnum} is invalid -1 is returned.
3972
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003973
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003974index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003975 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003976 value equal to {expr}. There is no automatic conversion, so
3977 the String "4" is different from the Number 4. And the number
3978 4 is different from the Float 4.0. The value of 'ignorecase'
3979 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00003980 If {start} is given then start looking at the item with index
3981 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003982 When {ic} is given and it is non-zero, ignore case. Otherwise
3983 case must match.
3984 -1 is returned when {expr} is not found in {list}.
3985 Example: >
3986 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003987 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003988
3989
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003990input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003991 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003992 the command-line. The {prompt} argument is either a prompt
3993 string, or a blank string (for no prompt). A '\n' can be used
3994 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003995 The highlighting set with |:echohl| is used for the prompt.
3996 The input is entered just like a command-line, with the same
Bram Moolenaar446cb832008-06-24 21:56:24 +00003997 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003998 for lines typed for input().
3999 Example: >
4000 :if input("Coffee or beer? ") == "beer"
4001 : echo "Cheers!"
4002 :endif
4003<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004004 If the optional {text} argument is present and not empty, this
4005 is used for the default reply, as if the user typed this.
4006 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004007 :let color = input("Color? ", "white")
4008
4009< The optional {completion} argument specifies the type of
4010 completion supported for the input. Without it completion is
Bram Moolenaar446cb832008-06-24 21:56:24 +00004011 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004012 that can be supplied to a user-defined command using the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004013 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004014 more information. Example: >
4015 let fname = input("File: ", "", "file")
4016<
4017 NOTE: This function must not be used in a startup file, for
4018 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004019 Note: When input() is called from within a mapping it will
4020 consume remaining characters from that mapping, because a
4021 mapping is handled like the characters were typed.
4022 Use |inputsave()| before input() and |inputrestore()|
4023 after input() to avoid that. Another solution is to avoid
4024 that further characters follow in the mapping, e.g., by using
4025 |:execute| or |:normal|.
4026
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004027 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004028 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
4029 :function GetFoo()
4030 : call inputsave()
4031 : let g:Foo = input("enter search pattern: ")
4032 : call inputrestore()
4033 :endfunction
4034
4035inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004036 Like |input()|, but when the GUI is running and text dialogs
4037 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004038 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02004039 :let n = inputdialog("value for shiftwidth", shiftwidth())
4040 :if n != ""
4041 : let &sw = n
4042 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00004043< When the dialog is cancelled {cancelreturn} is returned. When
4044 omitted an empty string is returned.
4045 Hitting <Enter> works like pressing the OK button. Hitting
4046 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004047 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004048
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004049inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004050 {textlist} must be a |List| of strings. This |List| is
4051 displayed, one string per line. The user will be prompted to
4052 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004053 The user can also select an item by clicking on it with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004054 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004055 above the first item a negative number is returned. When
4056 clicking on the prompt one more than the length of {textlist}
4057 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004058 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +00004059 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004060 the start of the string. And put a prompt in the first item.
4061 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004062 let color = inputlist(['Select color:', '1. red',
4063 \ '2. green', '3. blue'])
4064
Bram Moolenaar071d4272004-06-13 20:20:40 +00004065inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004066 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004067 Should be called the same number of times inputsave() is
4068 called. Calling it more often is harmless though.
4069 Returns 1 when there is nothing to restore, 0 otherwise.
4070
4071inputsave() *inputsave()*
4072 Preserve typeahead (also from mappings) and clear it, so that
4073 a following prompt gets input from the user. Should be
4074 followed by a matching inputrestore() after the prompt. Can
4075 be used several times, in which case there must be just as
4076 many inputrestore() calls.
4077 Returns 1 when out of memory, 0 otherwise.
4078
4079inputsecret({prompt} [, {text}]) *inputsecret()*
4080 This function acts much like the |input()| function with but
4081 two exceptions:
4082 a) the user's response will be displayed as a sequence of
4083 asterisks ("*") thereby keeping the entry secret, and
4084 b) the user's response will not be recorded on the input
4085 |history| stack.
4086 The result is a String, which is whatever the user actually
4087 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004088 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004089
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004090insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004091 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004092 If {idx} is specified insert {item} before the item with index
Bram Moolenaar446cb832008-06-24 21:56:24 +00004093 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004094 like omitting {idx}. A negative {idx} is also possible, see
4095 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004096 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004097 :let mylist = insert([2, 3, 5], 1)
4098 :call insert(mylist, 4, -1)
4099 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004100< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004101 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004102 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004103
Bram Moolenaard6e256c2011-12-14 15:32:50 +01004104invert({expr}) *invert()*
4105 Bitwise invert. The argument is converted to a number. A
4106 List, Dict or Float argument causes an error. Example: >
4107 :let bits = invert(bits)
4108
Bram Moolenaar071d4272004-06-13 20:20:40 +00004109isdirectory({directory}) *isdirectory()*
4110 The result is a Number, which is non-zero when a directory
4111 with the name {directory} exists. If {directory} doesn't
4112 exist, or isn't a directory, the result is FALSE. {directory}
4113 is any expression, which is used as a String.
4114
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004115islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004116 The result is a Number, which is non-zero when {expr} is the
4117 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004118 {expr} must be the name of a variable, |List| item or
4119 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004120 :let alist = [0, ['a', 'b'], 2, 3]
4121 :lockvar 1 alist
4122 :echo islocked('alist') " 1
4123 :echo islocked('alist[1]') " 0
4124
4125< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004126 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004127
Bram Moolenaar677ee682005-01-27 14:41:15 +00004128items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004129 Return a |List| with all the key-value pairs of {dict}. Each
4130 |List| item is a list with two items: the key of a {dict}
4131 entry and the value of this entry. The |List| is in arbitrary
4132 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004133
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004134
4135join({list} [, {sep}]) *join()*
4136 Join the items in {list} together into one String.
4137 When {sep} is specified it is put in between the items. If
4138 {sep} is omitted a single space is used.
4139 Note that {sep} is not added at the end. You might want to
4140 add it there too: >
4141 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004142< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004143 converted into a string like with |string()|.
4144 The opposite function is |split()|.
4145
Bram Moolenaard8b02732005-01-14 21:48:43 +00004146keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004147 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00004148 arbitrary order.
4149
Bram Moolenaar13065c42005-01-08 16:08:21 +00004150 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004151len({expr}) The result is a Number, which is the length of the argument.
4152 When {expr} is a String or a Number the length in bytes is
4153 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004154 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004155 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004156 When {expr} is a |Dictionary| the number of entries in the
4157 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004158 Otherwise an error is given.
4159
Bram Moolenaar071d4272004-06-13 20:20:40 +00004160 *libcall()* *E364* *E368*
4161libcall({libname}, {funcname}, {argument})
4162 Call function {funcname} in the run-time library {libname}
4163 with single argument {argument}.
4164 This is useful to call functions in a library that you
4165 especially made to be used with Vim. Since only one argument
4166 is possible, calling standard library functions is rather
4167 limited.
4168 The result is the String returned by the function. If the
4169 function returns NULL, this will appear as an empty string ""
4170 to Vim.
4171 If the function returns a number, use libcallnr()!
4172 If {argument} is a number, it is passed to the function as an
4173 int; if {argument} is a string, it is passed as a
4174 null-terminated string.
4175 This function will fail in |restricted-mode|.
4176
4177 libcall() allows you to write your own 'plug-in' extensions to
4178 Vim without having to recompile the program. It is NOT a
4179 means to call system functions! If you try to do so Vim will
4180 very probably crash.
4181
4182 For Win32, the functions you write must be placed in a DLL
4183 and use the normal C calling convention (NOT Pascal which is
4184 used in Windows System DLLs). The function must take exactly
4185 one parameter, either a character pointer or a long integer,
4186 and must return a character pointer or NULL. The character
4187 pointer returned must point to memory that will remain valid
4188 after the function has returned (e.g. in static data in the
4189 DLL). If it points to allocated memory, that memory will
4190 leak away. Using a static buffer in the function should work,
4191 it's then freed when the DLL is unloaded.
4192
4193 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00004194 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00004195 because Vim thinks it's a pointer.
4196 For Win32 systems, {libname} should be the filename of the DLL
4197 without the ".DLL" suffix. A full path is only required if
4198 the DLL is not in the usual places.
4199 For Unix: When compiling your own plugins, remember that the
4200 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004201 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004202 feature is present}
4203 Examples: >
4204 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004205<
4206 *libcallnr()*
4207libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004208 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004209 int instead of a string.
4210 {only in Win32 on some Unix versions, when the |+libcall|
4211 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00004212 Examples: >
4213 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004214 :call libcallnr("libc.so", "printf", "Hello World!\n")
4215 :call libcallnr("libc.so", "sleep", 10)
4216<
4217 *line()*
4218line({expr}) The result is a Number, which is the line number of the file
4219 position given with {expr}. The accepted positions are:
4220 . the cursor position
4221 $ the last line in the current buffer
4222 'x position of mark x (if the mark is not set, 0 is
4223 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00004224 w0 first line visible in current window
4225 w$ last line visible in current window
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00004226 v In Visual mode: the start of the Visual area (the
4227 cursor is the end). When not in Visual mode
4228 returns the cursor position. Differs from |'<| in
4229 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004230 Note that a mark in another file can be used. The line number
4231 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004232 To get the column number use |col()|. To get both use
4233 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004234 Examples: >
4235 line(".") line number of the cursor
4236 line("'t") line number of mark t
4237 line("'" . marker) line number of mark marker
4238< *last-position-jump*
4239 This autocommand jumps to the last known position in a file
4240 just after opening it, if the '" mark is set: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004241 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004242
Bram Moolenaar071d4272004-06-13 20:20:40 +00004243line2byte({lnum}) *line2byte()*
4244 Return the byte count from the start of the buffer for line
4245 {lnum}. This includes the end-of-line character, depending on
4246 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004247 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004248 This can also be used to get the byte count for the line just
4249 below the last line: >
4250 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004251< This is the buffer size plus one. If 'fileencoding' is empty
4252 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004253 When {lnum} is invalid, or the |+byte_offset| feature has been
4254 disabled at compile time, -1 is returned.
4255 Also see |byte2line()|, |go| and |:goto|.
4256
4257lispindent({lnum}) *lispindent()*
4258 Get the amount of indent for line {lnum} according the lisp
4259 indenting rules, as with 'lisp'.
4260 The indent is counted in spaces, the value of 'tabstop' is
4261 relevant. {lnum} is used just like in |getline()|.
4262 When {lnum} is invalid or Vim was not compiled the
4263 |+lispindent| feature, -1 is returned.
4264
4265localtime() *localtime()*
4266 Return the current time, measured as seconds since 1st Jan
4267 1970. See also |strftime()| and |getftime()|.
4268
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004269
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004270log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004271 Return the natural logarithm (base e) of {expr} as a |Float|.
4272 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004273 (0, inf].
4274 Examples: >
4275 :echo log(10)
4276< 2.302585 >
4277 :echo log(exp(5))
4278< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02004279 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004280
4281
Bram Moolenaar446cb832008-06-24 21:56:24 +00004282log10({expr}) *log10()*
4283 Return the logarithm of Float {expr} to base 10 as a |Float|.
4284 {expr} must evaluate to a |Float| or a |Number|.
4285 Examples: >
4286 :echo log10(1000)
4287< 3.0 >
4288 :echo log10(0.01)
4289< -2.0
4290 {only available when compiled with the |+float| feature}
4291
Bram Moolenaard38b0552012-04-25 19:07:41 +02004292luaeval({expr}[, {expr}]) *luaeval()*
4293 Evaluate Lua expression {expr} and return its result converted
4294 to Vim data structures. Second {expr} may hold additional
4295 argument accessible as _A inside first {expr}.
4296 Strings are returned as they are.
4297 Boolean objects are converted to numbers.
4298 Numbers are converted to |Float| values if vim was compiled
4299 with |+float| and to numbers otherwise.
4300 Dictionaries and lists obtained by vim.eval() are returned
4301 as-is.
4302 Other objects are returned as zero without any errors.
4303 See |lua-luaeval| for more details.
4304 {only available when compiled with the |+lua| feature}
4305
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004306map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004307 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004308 Replace each item in {expr} with the result of evaluating
4309 {string}.
4310 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar627b1d32009-11-17 11:20:35 +00004311 For a |Dictionary| |v:key| has the key of the current item
4312 and for a |List| |v:key| has the index of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004313 Example: >
4314 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004315< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004316
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004317 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004318 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004319 |literal-string| to avoid having to double backslashes. You
4320 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004321
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004322 The operation is done in-place. If you want a |List| or
4323 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02004324 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004325
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004326< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004327 When an error is encountered while evaluating {string} no
4328 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004329
4330
Bram Moolenaarbd743252010-10-20 21:23:33 +02004331maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
4332 When {dict} is omitted or zero: Return the rhs of mapping
4333 {name} in mode {mode}. The returned String has special
4334 characters translated like in the output of the ":map" command
4335 listing.
4336
4337 When there is no mapping for {name}, an empty String is
4338 returned.
4339
4340 The {name} can have special key names, like in the ":map"
4341 command.
4342
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004343 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004344 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02004345 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004346 "o" Operator-pending
4347 "i" Insert
4348 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02004349 "s" Select
4350 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00004351 "l" langmap |language-mapping|
4352 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004353 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004354
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004355 When {abbr} is there and it is non-zero use abbreviations
4356 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004357
4358 When {dict} is there and it is non-zero return a dictionary
4359 containing all the information of the mapping with the
4360 following items:
4361 "lhs" The {lhs} of the mapping.
4362 "rhs" The {rhs} of the mapping as typed.
4363 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02004364 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004365 "expr" 1 for an expression mapping (|:map-<expr>|).
4366 "buffer" 1 for a buffer local mapping (|:map-local|).
4367 "mode" Modes for which the mapping is defined. In
4368 addition to the modes mentioned above, these
4369 characters will be used:
4370 " " Normal, Visual and Operator-pending
4371 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01004372 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02004373 "sid" The script local ID, used for <sid> mappings
4374 (|<SID>|).
Bram Moolenaardfb18412013-12-11 18:53:29 +01004375 "nowait" Do not wait for other, longer mappings.
4376 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02004377
Bram Moolenaar071d4272004-06-13 20:20:40 +00004378 The mappings local to the current buffer are checked first,
4379 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00004380 This function can be used to map a key even when it's already
4381 mapped, and have it do the original mapping too. Sketch: >
4382 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
4383
Bram Moolenaar071d4272004-06-13 20:20:40 +00004384
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004385mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004386 Check if there is a mapping that matches with {name} in mode
4387 {mode}. See |maparg()| for {mode} and special names in
4388 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004389 When {abbr} is there and it is non-zero use abbreviations
4390 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004391 A match happens with a mapping that starts with {name} and
4392 with a mapping which is equal to the start of {name}.
4393
Bram Moolenaar446cb832008-06-24 21:56:24 +00004394 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004395 mapcheck("a") yes yes yes
4396 mapcheck("abc") yes yes yes
4397 mapcheck("ax") yes no no
4398 mapcheck("b") no no no
4399
4400 The difference with maparg() is that mapcheck() finds a
4401 mapping that matches with {name}, while maparg() only finds a
4402 mapping for {name} exactly.
4403 When there is no mapping that starts with {name}, an empty
4404 String is returned. If there is one, the rhs of that mapping
4405 is returned. If there are several mappings that start with
4406 {name}, the rhs of one of them is returned.
4407 The mappings local to the current buffer are checked first,
4408 then the global mappings.
4409 This function can be used to check if a mapping can be added
4410 without being ambiguous. Example: >
4411 :if mapcheck("_vv") == ""
4412 : map _vv :set guifont=7x13<CR>
4413 :endif
4414< This avoids adding the "_vv" mapping when there already is a
4415 mapping for "_v" or for "_vvv".
4416
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004417match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004418 When {expr} is a |List| then this returns the index of the
4419 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004420 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004421 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004422 Number, which gives the index (byte offset) in {expr} where
4423 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004424 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004425 If there is no match -1 is returned.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02004426 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004427 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004428 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004429 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004430< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00004431 *strpbrk()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004432 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00004433 :let sepidx = match(line, '[.,;: \t]')
4434< *strcasestr()*
4435 Vim doesn't have a strcasestr() function. But you can add
4436 "\c" to the pattern to ignore case: >
4437 :let idx = match(haystack, '\cneedle')
4438<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004439 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004440 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004441 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004442 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004443 :echo match("testing", "ing", 2)
4444< result is again "4". >
4445 :echo match("testing", "ing", 4)
4446< result is again "4". >
4447 :echo match("testing", "t", 2)
4448< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004449 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00004450 {start} bytes later, thus "^" will match at {start}. Except
4451 when {count} is given, then it's like matches before the
4452 {start} byte are ignored (this is a bit complicated to keep it
4453 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004454 For a String, if {start} < 0, it will be set to 0. For a list
4455 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004456 If {start} is out of range ({start} > strlen({expr}) for a
4457 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004458
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004459 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004460 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004461 character further. Thus this example results in 1: >
4462 echo match("testing", "..", 0, 2)
4463< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004464 Note that when {count} is added the way {start} works changes,
4465 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004466
Bram Moolenaar071d4272004-06-13 20:20:40 +00004467 See |pattern| for the patterns that are accepted.
4468 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar446cb832008-06-24 21:56:24 +00004469 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00004470 done like 'magic' is set and 'cpoptions' is empty.
4471
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004472 *matchadd()* *E798* *E799* *E801*
Bram Moolenaarf9132812015-07-21 19:19:13 +02004473matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004474 Defines a pattern to be highlighted in the current window (a
4475 "match"). It will be highlighted with {group}. Returns an
4476 identification number (ID), which can be used to delete the
4477 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01004478 Matching is case sensitive and magic, unless case sensitivity
4479 or magicness are explicitly overridden in {pattern}. The
4480 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02004481 The "Conceal" value is special, it causes the match to be
4482 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004483
4484 The optional {priority} argument assigns a priority to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004485 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004486 highlighting overrule that of a match with a lower priority.
4487 A priority is specified as an integer (negative numbers are no
4488 exception). If the {priority} argument is not specified, the
4489 default priority is 10. The priority of 'hlsearch' is zero,
4490 hence all matches with a priority greater than zero will
4491 overrule it. Syntax highlighting (see 'syntax') is a separate
4492 mechanism, and regardless of the chosen priority a match will
4493 always overrule syntax highlighting.
4494
4495 The optional {id} argument allows the request for a specific
4496 match ID. If a specified ID is already taken, an error
4497 message will appear and the match will not be added. An ID
4498 is specified as a positive integer (zero excluded). IDs 1, 2
4499 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02004500 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004501 |matchadd()| automatically chooses a free ID.
4502
Bram Moolenaar6561d522015-07-21 15:48:27 +02004503 The optional {dict} argmument allows for further custom
4504 values. Currently this is used to specify a match specifc
4505 conceal character that will be shown for |hl-Conceal|
4506 highlighted matches. The dict can have the following members:
4507
4508 conceal Special character to show instead of the
4509 match (only for |hl-Conceal| highlighed
4510 matches, see |:syn-cchar|)
4511
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004512 The number of matches is not limited, as it is the case with
4513 the |:match| commands.
4514
4515 Example: >
4516 :highlight MyGroup ctermbg=green guibg=green
4517 :let m = matchadd("MyGroup", "TODO")
4518< Deletion of the pattern: >
4519 :call matchdelete(m)
4520
4521< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar446cb832008-06-24 21:56:24 +00004522 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004523 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004524
Bram Moolenaar6561d522015-07-21 15:48:27 +02004525matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()*
Bram Moolenaarb3414592014-06-17 17:48:32 +02004526 Same as |matchadd()|, but requires a list of positions {pos}
4527 instead of a pattern. This command is faster than |matchadd()|
4528 because it does not require to handle regular expressions and
4529 sets buffer line boundaries to redraw screen. It is supposed
4530 to be used when fast match additions and deletions are
4531 required, for example to highlight matching parentheses.
4532
4533 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02004534 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02004535 line has number 1.
4536 - A list with one number, e.g., [23]. The whole line with this
4537 number will be highlighted.
4538 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02004539 the line number, the second one is the column number (first
4540 column is 1, the value must correspond to the byte index as
4541 |col()| would return). The character at this position will
4542 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02004543 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02004544 the third number gives the length of the highlight in bytes.
Bram Moolenaarb3414592014-06-17 17:48:32 +02004545
4546 The maximum number of positions is 8.
4547
4548 Example: >
4549 :highlight MyGroup ctermbg=green guibg=green
4550 :let m = matchaddpos("MyGroup", [[23, 24], 34])
4551< Deletion of the pattern: >
4552 :call matchdelete(m)
4553
4554< Matches added by |matchaddpos()| are returned by
4555 |getmatches()| with an entry "pos1", "pos2", etc., with the
4556 value a list like the {pos} item.
4557 These matches cannot be set via |setmatches()|, however they
4558 can still be deleted by |clearmatches()|.
4559
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004560matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004561 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004562 |:2match| or |:3match| command.
4563 Return a |List| with two elements:
4564 The name of the highlight group used
4565 The pattern used.
4566 When {nr} is not 1, 2 or 3 returns an empty |List|.
4567 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004568 This is useful to save and restore a |:match|.
4569 Highlighting matches using the |:match| commands are limited
4570 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004571
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004572matchdelete({id}) *matchdelete()* *E802* *E803*
4573 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00004574 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004575 otherwise -1. See example for |matchadd()|. All matches can
4576 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004577
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004578matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004579 Same as |match()|, but return the index of first character
4580 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004581 :echo matchend("testing", "ing")
4582< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00004583 *strspn()* *strcspn()*
4584 Vim doesn't have a strspn() or strcspn() function, but you can
4585 do it with matchend(): >
4586 :let span = matchend(line, '[a-zA-Z]')
4587 :let span = matchend(line, '[^a-zA-Z]')
4588< Except that -1 is returned when there are no matches.
4589
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004590 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004591 :echo matchend("testing", "ing", 2)
4592< results in "7". >
4593 :echo matchend("testing", "ing", 5)
4594< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004595 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004596
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004597matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004598 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004599 list is the matched string, same as what matchstr() would
4600 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004601 in |:substitute|. When an optional submatch didn't match an
4602 empty string is used. Example: >
4603 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
4604< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004605 When there is no match an empty list is returned.
4606
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004607matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004608 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004609 :echo matchstr("testing", "ing")
4610< results in "ing".
4611 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004612 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004613 :echo matchstr("testing", "ing", 2)
4614< results in "ing". >
4615 :echo matchstr("testing", "ing", 5)
4616< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004617 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004618 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004619
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004620 *max()*
4621max({list}) Return the maximum value of all items in {list}.
4622 If {list} is not a list or one of the items in {list} cannot
4623 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004624 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004625
4626 *min()*
Bram Moolenaar79166c42007-05-10 18:29:51 +00004627min({list}) Return the minimum value of all items in {list}.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004628 If {list} is not a list or one of the items in {list} cannot
4629 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004630 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004631
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004632 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004633mkdir({name} [, {path} [, {prot}]])
4634 Create directory {name}.
4635 If {path} is "p" then intermediate directories are created as
4636 necessary. Otherwise it must be "".
4637 If {prot} is given it is used to set the protection bits of
4638 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar446cb832008-06-24 21:56:24 +00004639 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00004640 for others. This is only used for the last part of {name}.
4641 Thus if you create /tmp/foo/bar then /tmp/foo will be created
4642 with 0755.
4643 Example: >
4644 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
4645< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004646 Not available on all systems. To check use: >
4647 :if exists("*mkdir")
4648<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004649 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004650mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00004651 If [expr] is supplied and it evaluates to a non-zero Number or
4652 a non-empty String (|non-zero-arg|), then the full mode is
4653 returned, otherwise only the first letter is returned. Note
4654 that " " and "0" are also non-empty strings.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004655
Bram Moolenaar071d4272004-06-13 20:20:40 +00004656 n Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00004657 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00004658 v Visual by character
4659 V Visual by line
4660 CTRL-V Visual blockwise
4661 s Select by character
4662 S Select by line
4663 CTRL-S Select blockwise
4664 i Insert
Bram Moolenaar446cb832008-06-24 21:56:24 +00004665 R Replace |R|
4666 Rv Virtual Replace |gR|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004667 c Command-line
Bram Moolenaar446cb832008-06-24 21:56:24 +00004668 cv Vim Ex mode |gQ|
4669 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004670 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00004671 rm The -- more -- prompt
4672 r? A |:confirm| query of some sort
4673 ! Shell or external command is executing
4674 This is useful in the 'statusline' option or when used
4675 with |remote_expr()| In most other places it always returns
4676 "c" or "n".
4677 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004678
Bram Moolenaar7e506b62010-01-19 15:55:06 +01004679mzeval({expr}) *mzeval()*
4680 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02004681 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01004682 Numbers and strings are returned as they are.
4683 Pairs (including lists and improper lists) and vectors are
4684 returned as Vim |Lists|.
4685 Hash tables are represented as Vim |Dictionary| type with keys
4686 converted to strings.
4687 All other types are converted to string with display function.
4688 Examples: >
4689 :mz (define l (list 1 2 3))
4690 :mz (define h (make-hash)) (hash-set! h "list" l)
4691 :echo mzeval("l")
4692 :echo mzeval("h")
4693<
4694 {only available when compiled with the |+mzscheme| feature}
4695
Bram Moolenaar071d4272004-06-13 20:20:40 +00004696nextnonblank({lnum}) *nextnonblank()*
4697 Return the line number of the first line at or below {lnum}
4698 that is not blank. Example: >
4699 if getline(nextnonblank(1)) =~ "Java"
4700< When {lnum} is invalid or there is no non-blank line at or
4701 below it, zero is returned.
4702 See also |prevnonblank()|.
4703
Bram Moolenaard35d7842013-01-23 17:17:10 +01004704nr2char({expr}[, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004705 Return a string with a single character, which has the number
4706 value {expr}. Examples: >
4707 nr2char(64) returns "@"
4708 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01004709< When {utf8} is omitted or zero, the current 'encoding' is used.
4710 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004711 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01004712< With {utf8} set to 1, always return utf-8 characters.
4713 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00004714 nr2char(10), because NULs are represented with newline
4715 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004716 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004717
Bram Moolenaard6e256c2011-12-14 15:32:50 +01004718or({expr}, {expr}) *or()*
4719 Bitwise OR on the two arguments. The arguments are converted
4720 to a number. A List, Dict or Float argument causes an error.
4721 Example: >
4722 :let bits = or(bits, 0x80)
4723
4724
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004725pathshorten({expr}) *pathshorten()*
4726 Shorten directory names in the path {expr} and return the
4727 result. The tail, the file name, is kept as-is. The other
4728 components in the path are reduced to single letters. Leading
4729 '~' and '.' characters are kept. Example: >
4730 :echo pathshorten('~/.vim/autoload/myfile.vim')
4731< ~/.v/a/myfile.vim ~
4732 It doesn't matter if the path exists or not.
4733
Bram Moolenaar446cb832008-06-24 21:56:24 +00004734pow({x}, {y}) *pow()*
4735 Return the power of {x} to the exponent {y} as a |Float|.
4736 {x} and {y} must evaluate to a |Float| or a |Number|.
4737 Examples: >
4738 :echo pow(3, 3)
4739< 27.0 >
4740 :echo pow(2, 16)
4741< 65536.0 >
4742 :echo pow(32, 0.20)
4743< 2.0
4744 {only available when compiled with the |+float| feature}
4745
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004746prevnonblank({lnum}) *prevnonblank()*
4747 Return the line number of the first line at or above {lnum}
4748 that is not blank. Example: >
4749 let ind = indent(prevnonblank(v:lnum - 1))
4750< When {lnum} is invalid or there is no non-blank line at or
4751 above it, zero is returned.
4752 Also see |nextnonblank()|.
4753
4754
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004755printf({fmt}, {expr1} ...) *printf()*
4756 Return a String with {fmt}, where "%" items are replaced by
4757 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004758 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004759< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004760 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004761
4762 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004763 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01004764 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00004765 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00004766 %.9s string truncated to 9 bytes
4767 %c single byte
4768 %d decimal number
4769 %5d decimal number padded with spaces to 5 characters
4770 %x hex number
4771 %04x hex number padded with zeros to at least 4 characters
4772 %X hex number using upper case letters
4773 %o octal number
4774 %f floating point number in the form 123.456
4775 %e floating point number in the form 1.234e3
4776 %E floating point number in the form 1.234E3
4777 %g floating point number, as %f or %e depending on value
4778 %G floating point number, as %f or %E depending on value
4779 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004780
4781 Conversion specifications start with '%' and end with the
4782 conversion type. All other characters are copied unchanged to
4783 the result.
4784
4785 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004786 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004787
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004788 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004789
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004790 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004791 Zero or more of the following flags:
4792
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004793 # The value should be converted to an "alternate
4794 form". For c, d, and s conversions, this option
4795 has no effect. For o conversions, the precision
4796 of the number is increased to force the first
4797 character of the output string to a zero (except
4798 if a zero value is printed with an explicit
4799 precision of zero).
4800 For x and X conversions, a non-zero result has
4801 the string "0x" (or "0X" for X conversions)
4802 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004803
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004804 0 (zero) Zero padding. For all conversions the converted
4805 value is padded on the left with zeros rather
4806 than blanks. If a precision is given with a
4807 numeric conversion (d, o, x, and X), the 0 flag
4808 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004809
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004810 - A negative field width flag; the converted value
4811 is to be left adjusted on the field boundary.
4812 The converted value is padded on the right with
4813 blanks, rather than on the left with blanks or
4814 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004815
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004816 ' ' (space) A blank should be left before a positive
4817 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004818
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004819 + A sign must always be placed before a number
Bram Moolenaar446cb832008-06-24 21:56:24 +00004820 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004821 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004822
4823 field-width
4824 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00004825 field width. If the converted value has fewer bytes
4826 than the field width, it will be padded with spaces on
4827 the left (or right, if the left-adjustment flag has
4828 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004829
4830 .precision
4831 An optional precision, in the form of a period '.'
4832 followed by an optional digit string. If the digit
4833 string is omitted, the precision is taken as zero.
4834 This gives the minimum number of digits to appear for
4835 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00004836 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004837 For floating point it is the number of digits after
4838 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004839
4840 type
4841 A character that specifies the type of conversion to
4842 be applied, see below.
4843
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004844 A field width or precision, or both, may be indicated by an
4845 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar446cb832008-06-24 21:56:24 +00004846 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004847 negative field width is treated as a left adjustment flag
4848 followed by a positive field width; a negative precision is
4849 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004850 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004851< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004852 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004853
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004854 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004855
Bram Moolenaar446cb832008-06-24 21:56:24 +00004856 *printf-d* *printf-o* *printf-x* *printf-X*
4857 doxX The Number argument is converted to signed decimal
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004858 (d), unsigned octal (o), or unsigned hexadecimal (x
4859 and X) notation. The letters "abcdef" are used for
4860 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004861 conversions.
4862 The precision, if any, gives the minimum number of
4863 digits that must appear; if the converted value
4864 requires fewer digits, it is padded on the left with
4865 zeros.
4866 In no case does a non-existent or small field width
4867 cause truncation of a numeric field; if the result of
4868 a conversion is wider than the field width, the field
4869 is expanded to contain the conversion result.
4870
Bram Moolenaar446cb832008-06-24 21:56:24 +00004871 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004872 c The Number argument is converted to a byte, and the
4873 resulting character is written.
4874
Bram Moolenaar446cb832008-06-24 21:56:24 +00004875 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004876 s The text of the String argument is used. If a
4877 precision is specified, no more bytes than the number
4878 specified are used.
Bram Moolenaar0122c402015-02-03 19:13:34 +01004879 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01004880 S The text of the String argument is used. If a
4881 precision is specified, no more display cells than the
4882 number specified are used. Without the |+multi_byte|
4883 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004884
Bram Moolenaar446cb832008-06-24 21:56:24 +00004885 *printf-f* *E807*
4886 f The Float argument is converted into a string of the
4887 form 123.456. The precision specifies the number of
4888 digits after the decimal point. When the precision is
4889 zero the decimal point is omitted. When the precision
4890 is not specified 6 is used. A really big number
4891 (out of range or dividing by zero) results in "inf".
4892 "0.0 / 0.0" results in "nan".
4893 Example: >
4894 echo printf("%.2f", 12.115)
4895< 12.12
4896 Note that roundoff depends on the system libraries.
4897 Use |round()| when in doubt.
4898
4899 *printf-e* *printf-E*
4900 e E The Float argument is converted into a string of the
4901 form 1.234e+03 or 1.234E+03 when using 'E'. The
4902 precision specifies the number of digits after the
4903 decimal point, like with 'f'.
4904
4905 *printf-g* *printf-G*
4906 g G The Float argument is converted like with 'f' if the
4907 value is between 0.001 (inclusive) and 10000000.0
4908 (exclusive). Otherwise 'e' is used for 'g' and 'E'
4909 for 'G'. When no precision is specified superfluous
4910 zeroes and '+' signs are removed, except for the zero
4911 immediately after the decimal point. Thus 10000000.0
4912 results in 1.0e7.
4913
4914 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004915 % A '%' is written. No argument is converted. The
4916 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004917
Bram Moolenaarc236c162008-07-13 17:41:49 +00004918 When a Number argument is expected a String argument is also
4919 accepted and automatically converted.
4920 When a Float or String argument is expected a Number argument
4921 is also accepted and automatically converted.
4922 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004923
Bram Moolenaar83bab712005-08-01 21:58:57 +00004924 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004925 The number of {exprN} arguments must exactly match the number
4926 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004927 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004928
4929
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004930pumvisible() *pumvisible()*
4931 Returns non-zero when the popup menu is visible, zero
4932 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004933 This can be used to avoid some things that would remove the
4934 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004935
Bram Moolenaare6ae6222013-05-21 21:01:10 +02004936 *E860*
Bram Moolenaar30b65812012-07-12 22:01:11 +02004937py3eval({expr}) *py3eval()*
4938 Evaluate Python expression {expr} and return its result
4939 converted to Vim data structures.
4940 Numbers and strings are returned as they are (strings are
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004941 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02004942 'encoding').
4943 Lists are represented as Vim |List| type.
4944 Dictionaries are represented as Vim |Dictionary| type with
4945 keys converted to strings.
4946 {only available when compiled with the |+python3| feature}
4947
4948 *E858* *E859*
4949pyeval({expr}) *pyeval()*
4950 Evaluate Python expression {expr} and return its result
4951 converted to Vim data structures.
4952 Numbers and strings are returned as they are (strings are
4953 copied though).
4954 Lists are represented as Vim |List| type.
Bram Moolenaard09acef2012-09-21 14:54:30 +02004955 Dictionaries are represented as Vim |Dictionary| type,
4956 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02004957 {only available when compiled with the |+python| feature}
4958
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004959 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00004960range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004961 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00004962 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
4963 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
4964 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4965 {max}] (increasing {expr} with {stride} each time, not
4966 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00004967 When the maximum is one before the start the result is an
4968 empty list. When the maximum is more than one before the
4969 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004970 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004971 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00004972 range(2, 4) " [2, 3, 4]
4973 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004974 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00004975 range(0) " []
4976 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00004977<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004978 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004979readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004980 Read file {fname} and return a |List|, each line of the file
4981 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004982 separated with CR will result in a single long line (unless a
4983 NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02004984 All NUL characters are replaced with a NL character.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02004985 When {binary} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004986 - When the last line ends in a NL an extra empty list item is
4987 added.
4988 - No CR characters are removed.
4989 Otherwise:
4990 - CR characters that appear before a NL are removed.
4991 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02004992 - When 'encoding' is Unicode any UTF-8 byte order mark is
4993 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004994 When {max} is given this specifies the maximum number of lines
4995 to be read. Useful if you only want to check the first ten
4996 lines of a file: >
4997 :for line in readfile(fname, '', 10)
4998 : if line =~ 'Date' | echo line | endif
4999 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00005000< When {max} is negative -{max} lines from the end of the file
5001 are returned, or as many as there are.
5002 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005003 Note that without {max} the whole file is read into memory.
5004 Also note that there is no recognition of encoding. Read a
5005 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005006 When the file can't be opened an error message is given and
5007 the result is an empty list.
5008 Also see |writefile()|.
5009
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005010reltime([{start} [, {end}]]) *reltime()*
5011 Return an item that represents a time value. The format of
5012 the item depends on the system. It can be passed to
5013 |reltimestr()| to convert it to a string.
5014 Without an argument it returns the current time.
5015 With one argument is returns the time passed since the time
5016 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005017 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005018 and {end}.
5019 The {start} and {end} arguments must be values returned by
5020 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02005021 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005022
5023reltimestr({time}) *reltimestr()*
5024 Return a String that represents the time value of {time}.
5025 This is the number of seconds, a dot and the number of
5026 microseconds. Example: >
5027 let start = reltime()
5028 call MyFunction()
5029 echo reltimestr(reltime(start))
5030< Note that overhead for the commands will be added to the time.
5031 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005032 Leading spaces are used to make the string align nicely. You
5033 can use split() to remove it. >
5034 echo split(reltimestr(reltime(start)))[0]
5035< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005036 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005037
Bram Moolenaar071d4272004-06-13 20:20:40 +00005038 *remote_expr()* *E449*
5039remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005040 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005041 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005042 The result must be a String or a |List|. A |List| is turned
5043 into a String by joining the items with a line break in
5044 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00005045 If {idvar} is present, it is taken as the name of a
5046 variable and a {serverid} for later use with
5047 remote_read() is stored there.
5048 See also |clientserver| |RemoteReply|.
5049 This function is not available in the |sandbox|.
5050 {only available when compiled with the |+clientserver| feature}
5051 Note: Any errors will cause a local error message to be issued
5052 and the result will be the empty string.
5053 Examples: >
5054 :echo remote_expr("gvim", "2+2")
5055 :echo remote_expr("gvim1", "b:current_syntax")
5056<
5057
5058remote_foreground({server}) *remote_foreground()*
5059 Move the Vim server with the name {server} to the foreground.
5060 This works like: >
5061 remote_expr({server}, "foreground()")
5062< Except that on Win32 systems the client does the work, to work
5063 around the problem that the OS doesn't always allow the server
5064 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00005065 Note: This does not restore the window if it was minimized,
5066 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005067 This function is not available in the |sandbox|.
5068 {only in the Win32, Athena, Motif and GTK GUI versions and the
5069 Win32 console version}
5070
5071
5072remote_peek({serverid} [, {retvar}]) *remote_peek()*
5073 Returns a positive number if there are available strings
5074 from {serverid}. Copies any reply string into the variable
Bram Moolenaar446cb832008-06-24 21:56:24 +00005075 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005076 name of a variable.
5077 Returns zero if none are available.
5078 Returns -1 if something is wrong.
5079 See also |clientserver|.
5080 This function is not available in the |sandbox|.
5081 {only available when compiled with the |+clientserver| feature}
5082 Examples: >
5083 :let repl = ""
5084 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
5085
5086remote_read({serverid}) *remote_read()*
5087 Return the oldest available reply from {serverid} and consume
5088 it. It blocks until a reply is available.
5089 See also |clientserver|.
5090 This function is not available in the |sandbox|.
5091 {only available when compiled with the |+clientserver| feature}
5092 Example: >
5093 :echo remote_read(id)
5094<
5095 *remote_send()* *E241*
5096remote_send({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005097 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00005098 keys and the function returns immediately. At the Vim server
5099 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005100 If {idvar} is present, it is taken as the name of a variable
5101 and a {serverid} for later use with remote_read() is stored
5102 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005103 See also |clientserver| |RemoteReply|.
5104 This function is not available in the |sandbox|.
5105 {only available when compiled with the |+clientserver| feature}
5106 Note: Any errors will be reported in the server and may mess
5107 up the display.
5108 Examples: >
5109 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
5110 \ remote_read(serverid)
5111
5112 :autocmd NONE RemoteReply *
5113 \ echo remote_read(expand("<amatch>"))
5114 :echo remote_send("gvim", ":sleep 10 | echo ".
5115 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005116<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005117remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005118 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005119 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005120 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005121 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005122 item as {end} a list with one item is returned. When {end}
5123 points to an item before {idx} this is an error.
5124 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005125 Example: >
5126 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005127 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00005128remove({dict}, {key})
5129 Remove the entry from {dict} with key {key}. Example: >
5130 :echo "removed " . remove(dict, "one")
5131< If there is no {key} in {dict} this is an error.
5132
5133 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005134
Bram Moolenaar071d4272004-06-13 20:20:40 +00005135rename({from}, {to}) *rename()*
5136 Rename the file by the name {from} to the name {to}. This
5137 should also work to move files across file systems. The
5138 result is a Number, which is 0 if the file was renamed
5139 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00005140 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005141 This function is not available in the |sandbox|.
5142
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005143repeat({expr}, {count}) *repeat()*
5144 Repeat {expr} {count} times and return the concatenated
5145 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005146 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005147< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005148 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar446cb832008-06-24 21:56:24 +00005149 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005150 :let longlist = repeat(['a', 'b'], 3)
5151< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005152
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005153
Bram Moolenaar071d4272004-06-13 20:20:40 +00005154resolve({filename}) *resolve()* *E655*
5155 On MS-Windows, when {filename} is a shortcut (a .lnk file),
5156 returns the path the shortcut points to in a simplified form.
5157 On Unix, repeat resolving symbolic links in all path
5158 components of {filename} and return the simplified result.
5159 To cope with link cycles, resolving of symbolic links is
5160 stopped after 100 iterations.
5161 On other systems, return the simplified {filename}.
5162 The simplification step is done as by |simplify()|.
5163 resolve() keeps a leading path component specifying the
5164 current directory (provided the result is still a relative
5165 path name) and also keeps a trailing path separator.
5166
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005167 *reverse()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005168reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005169 {list}.
5170 If you want a list to remain unmodified make a copy first: >
5171 :let revlist = reverse(copy(mylist))
5172
Bram Moolenaar446cb832008-06-24 21:56:24 +00005173round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00005174 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00005175 as a |Float|. If {expr} lies halfway between two integral
5176 values, then use the larger one (away from zero).
5177 {expr} must evaluate to a |Float| or a |Number|.
5178 Examples: >
5179 echo round(0.456)
5180< 0.0 >
5181 echo round(4.5)
5182< 5.0 >
5183 echo round(-4.5)
5184< -5.0
5185 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005186
Bram Moolenaar9a773482013-06-11 18:40:13 +02005187screenattr(row, col) *screenattr()*
5188 Like screenchar(), but return the attribute. This is a rather
5189 arbitrary number that can only be used to compare to the
5190 attribute at other positions.
5191
5192screenchar(row, col) *screenchar()*
5193 The result is a Number, which is the character at position
5194 [row, col] on the screen. This works for every possible
5195 screen position, also status lines, window separators and the
5196 command line. The top left position is row one, column one
5197 The character excludes composing characters. For double-byte
5198 encodings it may only be the first byte.
5199 This is mainly to be used for testing.
5200 Returns -1 when row or col is out of range.
5201
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005202screencol() *screencol()*
5203 The result is a Number, which is the current screen column of
5204 the cursor. The leftmost column has number 1.
5205 This function is mainly used for testing.
5206
5207 Note: Always returns the current screen column, thus if used
5208 in a command (e.g. ":echo screencol()") it will return the
5209 column inside the command line, which is 1 when the command is
5210 executed. To get the cursor position in the file use one of
5211 the following mappings: >
5212 nnoremap <expr> GG ":echom ".screencol()."\n"
5213 nnoremap <silent> GG :echom screencol()<CR>
5214<
5215screenrow() *screenrow()*
5216 The result is a Number, which is the current screen row of the
5217 cursor. The top line has number one.
5218 This function is mainly used for testing.
5219
5220 Note: Same restrictions as with |screencol()|.
5221
Bram Moolenaar76929292008-01-06 19:07:36 +00005222search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005223 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00005224 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005225
Bram Moolenaar2df58b42012-11-28 18:21:11 +01005226 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005227 If there is no match a 0 is returned and the cursor doesn't
5228 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005229
Bram Moolenaar071d4272004-06-13 20:20:40 +00005230 {flags} is a String, which can contain these character flags:
5231 'b' search backward instead of forward
Bram Moolenaar446cb832008-06-24 21:56:24 +00005232 'c' accept a match at the cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005233 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005234 'n' do Not move the cursor
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005235 'p' return number of matching sub-pattern (see below)
5236 's' set the ' mark at the previous location of the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00005237 'w' wrap around the end of the file
5238 'W' don't wrap around the end of the file
5239 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
5240
Bram Moolenaar02743632005-07-25 20:42:36 +00005241 If the 's' flag is supplied, the ' mark is set, only if the
5242 cursor is moved. The 's' flag cannot be combined with the 'n'
5243 flag.
5244
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005245 'ignorecase', 'smartcase' and 'magic' are used.
5246
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005247 When the {stopline} argument is given then the search stops
5248 after searching this line. This is useful to restrict the
5249 search to a range of lines. Examples: >
5250 let match = search('(', 'b', line("w0"))
5251 let end = search('END', '', line("w$"))
5252< When {stopline} is used and it is not zero this also implies
5253 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00005254 A zero value is equal to not giving the argument.
5255
5256 When the {timeout} argument is given the search stops when
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02005257 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00005258 {timeout} is 500 the search stops after half a second.
5259 The value must not be negative. A zero value is like not
5260 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005261 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005262
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005263 *search()-sub-match*
5264 With the 'p' flag the returned value is one more than the
5265 first sub-match in \(\). One if none of them matched but the
5266 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005267 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005268
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005269 The cursor will be positioned at the match, unless the 'n'
5270 flag is used.
5271
Bram Moolenaar071d4272004-06-13 20:20:40 +00005272 Example (goes over all files in the argument list): >
5273 :let n = 1
5274 :while n <= argc() " loop over all files in arglist
5275 : exe "argument " . n
5276 : " start at the last char in the file and wrap for the
5277 : " first search to find match at start of file
5278 : normal G$
5279 : let flags = "w"
5280 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005281 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00005282 : let flags = "W"
5283 : endwhile
5284 : update " write the file if modified
5285 : let n = n + 1
5286 :endwhile
5287<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005288 Example for using some flags: >
5289 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
5290< This will search for the keywords "if", "else", and "endif"
5291 under or after the cursor. Because of the 'p' flag, it
5292 returns 1, 2, or 3 depending on which keyword is found, or 0
5293 if the search fails. With the cursor on the first word of the
5294 line:
5295 if (foo == 0) | let foo = foo + 1 | endif ~
5296 the function returns 1. Without the 'c' flag, the function
5297 finds the "endif" and returns 3. The same thing happens
5298 without the 'e' flag if the cursor is on the "f" of "if".
5299 The 'n' flag tells the function not to move the cursor.
5300
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005301
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005302searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
5303 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005304
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005305 With a non-zero {global} argument it works like |gD|, find
5306 first match in the file. Otherwise it works like |gd|, find
5307 first match in the function.
5308
5309 With a non-zero {thisblock} argument matches in a {} block
5310 that ends before the cursor position are ignored. Avoids
5311 finding variable declarations only valid in another scope.
5312
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005313 Moves the cursor to the found match.
5314 Returns zero for success, non-zero for failure.
5315 Example: >
5316 if searchdecl('myvar') == 0
5317 echo getline('.')
5318 endif
5319<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005320 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00005321searchpair({start}, {middle}, {end} [, {flags} [, {skip}
5322 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00005323 Search for the match of a nested start-end pair. This can be
5324 used to find the "endif" that matches an "if", while other
5325 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005326 The search starts at the cursor. The default is to search
5327 forward, include 'b' in {flags} to search backward.
5328 If a match is found, the cursor is positioned at it and the
5329 line number is returned. If no match is found 0 or -1 is
5330 returned and the cursor doesn't move. No error message is
5331 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005332
5333 {start}, {middle} and {end} are patterns, see |pattern|. They
5334 must not contain \( \) pairs. Use of \%( \) is allowed. When
5335 {middle} is not empty, it is found when searching from either
5336 direction, but only when not in a nested start-end pair. A
5337 typical use is: >
5338 searchpair('\<if\>', '\<else\>', '\<endif\>')
5339< By leaving {middle} empty the "else" is skipped.
5340
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005341 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
5342 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005343 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005344 outer pair. Implies the 'W' flag.
5345 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005346 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005347 Note: it's nearly always a good idea to use the 'W' flag, to
5348 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005349
5350 When a match for {start}, {middle} or {end} is found, the
5351 {skip} expression is evaluated with the cursor positioned on
5352 the start of the match. It should return non-zero if this
5353 match is to be skipped. E.g., because it is inside a comment
5354 or a string.
5355 When {skip} is omitted or empty, every match is accepted.
5356 When evaluating {skip} causes an error the search is aborted
5357 and -1 returned.
5358
Bram Moolenaar76929292008-01-06 19:07:36 +00005359 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005360
Bram Moolenaar071d4272004-06-13 20:20:40 +00005361 The value of 'ignorecase' is used. 'magic' is ignored, the
5362 patterns are used like it's on.
5363
5364 The search starts exactly at the cursor. A match with
5365 {start}, {middle} or {end} at the next character, in the
5366 direction of searching, is the first one found. Example: >
5367 if 1
5368 if 2
5369 endif 2
5370 endif 1
5371< When starting at the "if 2", with the cursor on the "i", and
5372 searching forwards, the "endif 2" is found. When starting on
5373 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar446cb832008-06-24 21:56:24 +00005374 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00005375 then this is considered to be a nested if/endif from "if 2" to
5376 "endif 2".
5377 When searching backwards and {end} is more than one character,
5378 it may be useful to put "\zs" at the end of the pattern, so
5379 that when the cursor is inside a match with the end it finds
5380 the matching start.
5381
5382 Example, to find the "endif" command in a Vim script: >
5383
5384 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
5385 \ 'getline(".") =~ "^\\s*\""')
5386
5387< The cursor must be at or after the "if" for which a match is
5388 to be found. Note that single-quote strings are used to avoid
5389 having to double the backslashes. The skip expression only
5390 catches comments at the start of a line, not after a command.
5391 Also, a word "en" or "if" halfway a line is considered a
5392 match.
5393 Another example, to search for the matching "{" of a "}": >
5394
5395 :echo searchpair('{', '', '}', 'bW')
5396
5397< This works when the cursor is at or before the "}" for which a
5398 match is to be found. To reject matches that syntax
5399 highlighting recognized as strings: >
5400
5401 :echo searchpair('{', '', '}', 'bW',
5402 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
5403<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005404 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00005405searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
5406 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005407 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005408 column position of the match. The first element of the |List|
5409 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005410 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005411 returns [0, 0]. >
5412
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005413 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
5414<
5415 See |match-parens| for a bigger and more useful example.
5416
Bram Moolenaar76929292008-01-06 19:07:36 +00005417searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005418 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005419 column position of the match. The first element of the |List|
5420 is the line number and the second element is the byte index of
5421 the column position of the match. If no match is found,
5422 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005423 Example: >
5424 :let [lnum, col] = searchpos('mypattern', 'n')
5425
5426< When the 'p' flag is given then there is an extra item with
5427 the sub-pattern match number |search()-sub-match|. Example: >
5428 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
5429< In this example "submatch" is 2 when a lowercase letter is
5430 found |/\l|, 3 when an uppercase letter is found |/\u|.
5431
Bram Moolenaar071d4272004-06-13 20:20:40 +00005432server2client( {clientid}, {string}) *server2client()*
5433 Send a reply string to {clientid}. The most recent {clientid}
5434 that sent a string can be retrieved with expand("<client>").
5435 {only available when compiled with the |+clientserver| feature}
5436 Note:
5437 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005438 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00005439 before calling any commands that waits for input.
5440 See also |clientserver|.
5441 Example: >
5442 :echo server2client(expand("<client>"), "HELLO")
5443<
5444serverlist() *serverlist()*
5445 Return a list of available server names, one per line.
5446 When there are no servers or the information is not available
5447 an empty string is returned. See also |clientserver|.
5448 {only available when compiled with the |+clientserver| feature}
5449 Example: >
5450 :echo serverlist()
5451<
5452setbufvar({expr}, {varname}, {val}) *setbufvar()*
5453 Set option or local variable {varname} in buffer {expr} to
5454 {val}.
5455 This also works for a global or local window option, but it
5456 doesn't work for a global or local window variable.
5457 For a local window option the global value is unchanged.
5458 For the use of {expr}, see |bufname()| above.
5459 Note that the variable name without "b:" must be used.
5460 Examples: >
5461 :call setbufvar(1, "&mod", 1)
5462 :call setbufvar("todo", "myvar", "foobar")
5463< This function is not available in the |sandbox|.
5464
Bram Moolenaar12969c02015-09-08 23:36:10 +02005465setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02005466 Set the current character search information to {dict},
5467 which contains one or more of the following entries:
5468
5469 char character which will be used for a subsequent
5470 |,| or |;| command; an empty string clears the
5471 character search
5472 forward direction of character search; 1 for forward,
5473 0 for backward
5474 until type of character search; 1 for a |t| or |T|
5475 character search, 0 for an |f| or |F|
5476 character search
5477
5478 This can be useful to save/restore a user's character search
5479 from a script: >
5480 :let prevsearch = getcharsearch()
5481 :" Perform a command which clobbers user's search
5482 :call setcharsearch(prevsearch)
5483< Also see |getcharsearch()|.
5484
Bram Moolenaar071d4272004-06-13 20:20:40 +00005485setcmdpos({pos}) *setcmdpos()*
5486 Set the cursor position in the command line to byte position
Bram Moolenaar446cb832008-06-24 21:56:24 +00005487 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005488 Use |getcmdpos()| to obtain the current position.
5489 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00005490 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
5491 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
5492 set after the command line is set to the expression. For
5493 |c_CTRL-R_=| it is set after evaluating the expression but
5494 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005495 When the number is too big the cursor is put at the end of the
5496 line. A number smaller than one has undefined results.
5497 Returns 0 when successful, 1 when not editing the command
5498 line.
5499
Bram Moolenaar446cb832008-06-24 21:56:24 +00005500setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005501 Set line {lnum} of the current buffer to {text}. To insert
5502 lines use |append()|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005503 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005504 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005505 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005506 If this succeeds, 0 is returned. If this fails (most likely
5507 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005508 :call setline(5, strftime("%c"))
Bram Moolenaar446cb832008-06-24 21:56:24 +00005509< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005510 will be set to the items in the list. Example: >
5511 :call setline(5, ['aaa', 'bbb', 'ccc'])
5512< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02005513 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005514 : call setline(n, l)
5515 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00005516< Note: The '[ and '] marks are not set.
5517
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005518setloclist({nr}, {list} [, {action}]) *setloclist()*
5519 Create or replace or add to the location list for window {nr}.
5520 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00005521 list window, the displayed location list is modified. For an
5522 invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005523 Otherwise, same as |setqflist()|.
5524 Also see |location-list|.
5525
5526setmatches({list}) *setmatches()*
5527 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005528 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005529 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005530
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005531 *setpos()*
5532setpos({expr}, {list})
5533 Set the position for {expr}. Possible values:
5534 . the cursor
5535 'x mark x
5536
Bram Moolenaar493c1782014-05-28 14:34:46 +02005537 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005538 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02005539 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005540
Bram Moolenaar446cb832008-06-24 21:56:24 +00005541 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005542 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005543 the current buffer. To set a mark in another buffer you can
5544 use the |bufnr()| function to turn a file name into a buffer
5545 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00005546 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005547
5548 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005549 column is 1. Use a zero "lnum" to delete a mark. If "col" is
5550 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005551
5552 The "off" number is only used when 'virtualedit' is set. Then
5553 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005554 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005555 character.
5556
Bram Moolenaar493c1782014-05-28 14:34:46 +02005557 The "curswant" number is only used when setting the cursor
5558 position. It sets the preferred column for when moving the
5559 cursor vertically. When the "curswant" number is missing the
5560 preferred column is not set. When it is present and setting a
5561 mark position it is not used.
5562
Bram Moolenaardfb18412013-12-11 18:53:29 +01005563 Note that for '< and '> changing the line number may result in
5564 the marks to be effectively be swapped, so that '< is always
5565 before '>.
5566
Bram Moolenaar08250432008-02-13 11:42:46 +00005567 Returns 0 when the position could be set, -1 otherwise.
5568 An error message is given if {expr} is invalid.
5569
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005570 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005571
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005572 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02005573 vertically; if you set the cursor position with this, |j| and
5574 |k| motions will jump to previous columns! Use |cursor()| to
5575 also set the preferred column. Also see the "curswant" key in
5576 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005577
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005578
Bram Moolenaar35c54e52005-05-20 21:25:31 +00005579setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005580 Create or replace or add to the quickfix list using the items
5581 in {list}. Each item in {list} is a dictionary.
5582 Non-dictionary items in {list} are ignored. Each dictionary
5583 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005584
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005585 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00005586 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005587 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00005588 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005589 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005590 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00005591 col column number
5592 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005593 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00005594 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005595 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00005596 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005597
Bram Moolenaar582fd852005-03-28 20:58:01 +00005598 The "col", "vcol", "nr", "type" and "text" entries are
5599 optional. Either "lnum" or "pattern" entry can be used to
5600 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005601 If the "filename" and "bufnr" entries are not present or
5602 neither the "lnum" or "pattern" entries are present, then the
5603 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005604 If both "pattern" and "lnum" are present then "pattern" will
5605 be used.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02005606 If you supply an empty {list}, the quickfix list will be
5607 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005608 Note that the list is not exactly the same as what
5609 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005610
Bram Moolenaar35c54e52005-05-20 21:25:31 +00005611 If {action} is set to 'a', then the items from {list} are
5612 added to the existing quickfix list. If there is no existing
5613 list, then a new list is created. If {action} is set to 'r',
5614 then the items from the current quickfix list are replaced
5615 with the items from {list}. If {action} is not present or is
5616 set to ' ', then a new list is created.
5617
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005618 Returns zero for success, -1 for failure.
5619
5620 This function can be used to create a quickfix list
5621 independent of the 'errorformat' setting. Use a command like
5622 ":cc 1" to jump to the first position.
5623
5624
Bram Moolenaar071d4272004-06-13 20:20:40 +00005625 *setreg()*
5626setreg({regname}, {value} [,{options}])
5627 Set the register {regname} to {value}.
Bram Moolenaar5a50c222014-04-02 22:17:10 +02005628 {value} may be any value returned by |getreg()|, including
5629 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005630 If {options} contains "a" or {regname} is upper case,
5631 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02005632 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005633 "c" or "v" |characterwise| mode
5634 "l" or "V" |linewise| mode
5635 "b" or "<CTRL-V>" |blockwise-visual| mode
5636 If a number immediately follows "b" or "<CTRL-V>" then this is
5637 used as the width of the selection - if it is not specified
5638 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005639 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005640
5641 If {options} contains no register settings, then the default
Bram Moolenaar5a50c222014-04-02 22:17:10 +02005642 is to use character mode unless {value} ends in a <NL> for
5643 string {value} and linewise mode for list {value}. Blockwise
5644 mode is never selected automatically.
5645 Returns zero for success, non-zero for failure.
5646
5647 *E883*
Bram Moolenaar34401cc2014-08-29 15:12:19 +02005648 Note: you may not use |List| containing more than one item to
Bram Moolenaar5a50c222014-04-02 22:17:10 +02005649 set search and expression registers. Lists containing no
5650 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005651
5652 Examples: >
5653 :call setreg(v:register, @*)
5654 :call setreg('*', @%, 'ac')
5655 :call setreg('a', "1\n2\n3", 'b5')
5656
5657< This example shows using the functions to save and restore a
Bram Moolenaar5a50c222014-04-02 22:17:10 +02005658 register (note: you may not reliably restore register value
5659 without using the third argument to |getreg()| as without it
5660 newlines are represented as newlines AND Nul bytes are
5661 represented as newlines as well, see |NL-used-for-Nul|). >
5662 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005663 :let var_amode = getregtype('a')
5664 ....
5665 :call setreg('a', var_a, var_amode)
5666
5667< You can also change the type of a register by appending
5668 nothing: >
5669 :call setreg('a', '', 'al')
5670
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005671settabvar({tabnr}, {varname}, {val}) *settabvar()*
5672 Set tab-local variable {varname} to {val} in tab page {tabnr}.
5673 |t:var|
5674 Note that the variable name without "t:" must be used.
5675 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005676 This function is not available in the |sandbox|.
5677
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005678settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
5679 Set option or local variable {varname} in window {winnr} to
5680 {val}.
5681 Tabs are numbered starting with one. For the current tabpage
5682 use |setwinvar()|.
5683 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005684 This also works for a global or local buffer option, but it
5685 doesn't work for a global or local buffer variable.
5686 For a local buffer option the global value is unchanged.
5687 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005688 Examples: >
5689 :call settabwinvar(1, 1, "&list", 0)
5690 :call settabwinvar(3, 2, "myvar", "foobar")
5691< This function is not available in the |sandbox|.
5692
5693setwinvar({nr}, {varname}, {val}) *setwinvar()*
5694 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005695 Examples: >
5696 :call setwinvar(1, "&list", 0)
5697 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005698
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01005699sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01005700 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01005701 checksum of {string}.
5702 {only available when compiled with the |+cryptv| feature}
5703
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005704shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005705 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005706 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005707 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005708 quotes within {string}.
5709 For other systems, it will enclose {string} in single quotes
5710 and replace all "'" with "'\''".
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005711 When the {special} argument is present and it's a non-zero
5712 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00005713 items such as "!", "%", "#" and "<cword>" will be preceded by
5714 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005715 command.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00005716 The "!" character will be escaped (again with a |non-zero-arg|
5717 {special}) when 'shell' contains "csh" in the tail. That is
5718 because for csh and tcsh "!" is used for history replacement
5719 even when inside single quotes.
5720 The <NL> character is also escaped. With a |non-zero-arg|
5721 {special} and 'shell' containing "csh" in the tail it's
5722 escaped a second time.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005723 Example of use with a |:!| command: >
5724 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
5725< This results in a directory listing for the file under the
5726 cursor. Example of use with |system()|: >
5727 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01005728< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005729
5730
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02005731shiftwidth() *shiftwidth()*
5732 Returns the effective value of 'shiftwidth'. This is the
5733 'shiftwidth' value unless it is zero, in which case it is the
5734 'tabstop' value. To be backwards compatible in indent
5735 plugins, use this: >
5736 if exists('*shiftwidth')
5737 func s:sw()
5738 return shiftwidth()
5739 endfunc
5740 else
5741 func s:sw()
5742 return &sw
5743 endfunc
5744 endif
5745< And then use s:sw() instead of &sw.
5746
5747
Bram Moolenaar071d4272004-06-13 20:20:40 +00005748simplify({filename}) *simplify()*
5749 Simplify the file name as much as possible without changing
5750 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
5751 Unix) are not resolved. If the first path component in
5752 {filename} designates the current directory, this will be
5753 valid for the result as well. A trailing path separator is
5754 not removed either.
5755 Example: >
5756 simplify("./dir/.././/file/") == "./file/"
5757< Note: The combination "dir/.." is only removed if "dir" is
5758 a searchable directory or does not exist. On Unix, it is also
5759 removed when "dir" is a symbolic link within the same
5760 directory. In order to resolve all the involved symbolic
5761 links before simplifying the path name, use |resolve()|.
5762
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005763
Bram Moolenaar446cb832008-06-24 21:56:24 +00005764sin({expr}) *sin()*
5765 Return the sine of {expr}, measured in radians, as a |Float|.
5766 {expr} must evaluate to a |Float| or a |Number|.
5767 Examples: >
5768 :echo sin(100)
5769< -0.506366 >
5770 :echo sin(-4.01)
5771< 0.763301
5772 {only available when compiled with the |+float| feature}
5773
5774
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005775sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005776 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005777 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005778 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005779 Examples: >
5780 :echo sinh(0.5)
5781< 0.521095 >
5782 :echo sinh(-0.9)
5783< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02005784 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005785
5786
Bram Moolenaar5f894962011-06-19 02:55:37 +02005787sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01005788 Sort the items in {list} in-place. Returns {list}.
5789
5790 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005791 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02005792
Bram Moolenaar946e27a2014-06-25 18:50:27 +02005793< When {func} is omitted, is empty or zero, then sort() uses the
5794 string representation of each item to sort on. Numbers sort
5795 after Strings, |Lists| after Numbers. For sorting text in the
5796 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01005797
Bram Moolenaar34401cc2014-08-29 15:12:19 +02005798 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02005799 ignored.
5800
5801 When {func} is given and it is 'n' then all items will be
5802 sorted numerical (Implementation detail: This uses the
5803 strtod() function to parse numbers, Strings, Lists, Dicts and
5804 Funcrefs will be considered as being 0).
5805
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01005806 When {func} is given and it is 'N' then all items will be
5807 sorted numerical. This is like 'n' but a string containing
5808 digits will be used as the number they represent.
5809
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005810 When {func} is a |Funcref| or a function name, this function
5811 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005812 items as argument and must return zero if they are equal, 1 or
5813 bigger if the first one sorts after the second one, -1 or
5814 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01005815
5816 {dict} is for functions with the "dict" attribute. It will be
5817 used to set the local variable "self". |Dictionary-function|
5818
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02005819 The sort is stable, items which compare equal (as number or as
5820 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02005821 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02005822 same order as they were originally.
5823
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01005824 The sort is stable, items which compare equal (as number or as
5825 string) will keep their relative position. E.g., when sorting
5826 on numbers, text strings will sort next to each other, in the
5827 same order as they were originally.
5828
Bram Moolenaar327aa022014-03-25 18:24:23 +01005829 Also see |uniq()|.
5830
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005831 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005832 func MyCompare(i1, i2)
5833 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
5834 endfunc
5835 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005836< A shorter compare version for this specific simple case, which
5837 ignores overflow: >
5838 func MyCompare(i1, i2)
5839 return a:i1 - a:i2
5840 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005841<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00005842 *soundfold()*
5843soundfold({word})
5844 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00005845 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00005846 soundfolding. 'spell' must be set. When no sound folding is
5847 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00005848 This can be used for making spelling suggestions. Note that
5849 the method can be quite slow.
5850
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005851 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00005852spellbadword([{sentence}])
5853 Without argument: The result is the badly spelled word under
5854 or after the cursor. The cursor is moved to the start of the
5855 bad word. When no bad word is found in the cursor line the
5856 result is an empty string and the cursor doesn't move.
5857
5858 With argument: The result is the first word in {sentence} that
5859 is badly spelled. If there are no spelling mistakes the
5860 result is an empty string.
5861
5862 The return value is a list with two items:
5863 - The badly spelled word or an empty string.
5864 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005865 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00005866 "rare" rare word
5867 "local" word only valid in another region
5868 "caps" word should start with Capital
5869 Example: >
5870 echo spellbadword("the quik brown fox")
5871< ['quik', 'bad'] ~
5872
5873 The spelling information for the current window is used. The
5874 'spell' option must be set and the value of 'spelllang' is
5875 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005876
5877 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005878spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005879 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005880 When {max} is given up to this number of suggestions are
5881 returned. Otherwise up to 25 suggestions are returned.
5882
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005883 When the {capital} argument is given and it's non-zero only
5884 suggestions with a leading capital will be given. Use this
5885 after a match with 'spellcapcheck'.
5886
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005887 {word} can be a badly spelled word followed by other text.
5888 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00005889 suggestions also include the following text, thus you can
5890 replace a line.
5891
5892 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005893 returned. {word} itself is not included in the suggestions,
5894 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005895
5896 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00005897 'spell' option must be set and the values of 'spelllang' and
5898 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005899
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005900
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005901split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005902 Make a |List| out of {expr}. When {pattern} is omitted or
5903 empty each white-separated sequence of characters becomes an
5904 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005905 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01005906 removing the matched characters. 'ignorecase' is not used
5907 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005908 When the first or last item is empty it is omitted, unless the
5909 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00005910 Other empty items are kept when {pattern} matches at least one
5911 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005912 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005913 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005914< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005915 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02005916< If you want to keep the separator you can also use '\zs' at
5917 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00005918 :echo split('abc:def:ghi', ':\zs')
5919< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005920 Splitting a table where the first element can be empty: >
5921 :let items = split(line, ':', 1)
5922< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005923
5924
Bram Moolenaar446cb832008-06-24 21:56:24 +00005925sqrt({expr}) *sqrt()*
5926 Return the non-negative square root of Float {expr} as a
5927 |Float|.
5928 {expr} must evaluate to a |Float| or a |Number|. When {expr}
5929 is negative the result is NaN (Not a Number).
5930 Examples: >
5931 :echo sqrt(100)
5932< 10.0 >
5933 :echo sqrt(-4.01)
5934< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00005935 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005936 {only available when compiled with the |+float| feature}
5937
5938
5939str2float( {expr}) *str2float()*
5940 Convert String {expr} to a Float. This mostly works the same
5941 as when using a floating point number in an expression, see
5942 |floating-point-format|. But it's a bit more permissive.
5943 E.g., "1e40" is accepted, while in an expression you need to
5944 write "1.0e40".
5945 Text after the number is silently ignored.
5946 The decimal point is always '.', no matter what the locale is
5947 set to. A comma ends the number: "12,345.67" is converted to
5948 12.0. You can strip out thousands separators with
5949 |substitute()|: >
5950 let f = str2float(substitute(text, ',', '', 'g'))
5951< {only available when compiled with the |+float| feature}
5952
5953
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005954str2nr( {expr} [, {base}]) *str2nr()*
5955 Convert string {expr} to a number.
5956 {base} is the conversion base, it can be 8, 10 or 16.
5957 When {base} is omitted base 10 is used. This also means that
5958 a leading zero doesn't cause octal conversion to be used, as
5959 with the default String to Number conversion.
5960 When {base} is 16 a leading "0x" or "0X" is ignored. With a
5961 different base the result will be zero.
5962 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005963
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005964
Bram Moolenaar979243b2015-06-26 19:35:49 +02005965strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02005966 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02005967 in String {expr}.
5968 When {skipcc} is omitted or zero, composing characters are
5969 counted separately.
5970 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02005971 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
5972
Bram Moolenaar86ae7202015-07-10 19:31:35 +02005973
5974 {skipcc} is only available after 7.4.755. For backward
5975 compatibility, you can define a wrapper function: >
5976 if has("patch-7.4.755")
5977 function s:strchars(str, skipcc)
5978 return strchars(a:str, a:skipcc)
5979 endfunction
5980 else
5981 function s:strchars(str, skipcc)
5982 if a:skipcc
5983 return strlen(substitute(a:str, ".", "x", "g"))
5984 else
5985 return strchars(a:str)
5986 endif
5987 endfunction
5988 endif
5989<
5990
Bram Moolenaardc536092010-07-18 15:45:49 +02005991strdisplaywidth({expr}[, {col}]) *strdisplaywidth()*
5992 The result is a Number, which is the number of display cells
Bram Moolenaar979243b2015-06-26 19:35:49 +02005993 String {expr} occupies on the screen when it starts at {col}.
Bram Moolenaardc536092010-07-18 15:45:49 +02005994 When {col} is omitted zero is used. Otherwise it is the
5995 screen column where to start. This matters for Tab
5996 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02005997 The option settings of the current window are used. This
5998 matters for anything that's displayed differently, such as
5999 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006000 When {expr} contains characters with East Asian Width Class
6001 Ambiguous, this function's return value depends on 'ambiwidth'.
6002 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006003
Bram Moolenaar071d4272004-06-13 20:20:40 +00006004strftime({format} [, {time}]) *strftime()*
6005 The result is a String, which is a formatted date and time, as
6006 specified by the {format} string. The given {time} is used,
6007 or the current time if no time is given. The accepted
6008 {format} depends on your system, thus this is not portable!
6009 See the manual page of the C function strftime() for the
6010 format. The maximum length of the result is 80 characters.
6011 See also |localtime()| and |getftime()|.
6012 The language can be changed with the |:language| command.
6013 Examples: >
6014 :echo strftime("%c") Sun Apr 27 11:49:23 1997
6015 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
6016 :echo strftime("%y%m%d %T") 970427 11:53:55
6017 :echo strftime("%H:%M") 11:55
6018 :echo strftime("%c", getftime("file.c"))
6019 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006020< Not available on all systems. To check use: >
6021 :if exists("*strftime")
6022
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006023stridx({haystack}, {needle} [, {start}]) *stridx()*
6024 The result is a Number, which gives the byte index in
6025 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006026 If {start} is specified, the search starts at index {start}.
6027 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01006028 :let colon1 = stridx(line, ":")
6029 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00006030< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006031 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006032 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006033 See also |strridx()|.
6034 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006035 :echo stridx("An Example", "Example") 3
6036 :echo stridx("Starting point", "Start") 0
6037 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006038< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006039 stridx() works similar to the C function strstr(). When used
6040 with a single character it works similar to strchr().
6041
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006042 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006043string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00006044 Float, String or a composition of them, then the result can be
6045 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006046 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00006047 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006048 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00006049 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00006050 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006051 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00006052 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00006053 Note that in String values the ' character is doubled.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006054 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006055
Bram Moolenaar071d4272004-06-13 20:20:40 +00006056 *strlen()*
6057strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00006058 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006059 If the argument is a Number it is first converted to a String.
6060 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02006061 If you want to count the number of multi-byte characters use
6062 |strchars()|.
6063 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006064
6065strpart({src}, {start}[, {len}]) *strpart()*
6066 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00006067 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006068 When non-existing bytes are included, this doesn't result in
6069 an error, the bytes are simply omitted.
6070 If {len} is missing, the copy continues from {start} till the
6071 end of the {src}. >
6072 strpart("abcdefg", 3, 2) == "de"
6073 strpart("abcdefg", -2, 4) == "ab"
6074 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00006075 strpart("abcdefg", 3) == "defg"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006076< Note: To get the first character, {start} must be 0. For
6077 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00006078 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006079<
Bram Moolenaar677ee682005-01-27 14:41:15 +00006080strridx({haystack}, {needle} [, {start}]) *strridx()*
6081 The result is a Number, which gives the byte index in
6082 {haystack} of the last occurrence of the String {needle}.
6083 When {start} is specified, matches beyond this index are
6084 ignored. This can be used to find a match before a previous
6085 match: >
6086 :let lastcomma = strridx(line, ",")
6087 :let comma2 = strridx(line, ",", lastcomma - 1)
6088< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006089 For pattern searches use |match()|.
6090 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00006091 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006092 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006093 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006094< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006095 When used with a single character it works similar to the C
6096 function strrchr().
6097
Bram Moolenaar071d4272004-06-13 20:20:40 +00006098strtrans({expr}) *strtrans()*
6099 The result is a String, which is {expr} with all unprintable
6100 characters translated into printable characters |'isprint'|.
6101 Like they are shown in a window. Example: >
6102 echo strtrans(@a)
6103< This displays a newline in register a as "^@" instead of
6104 starting a new line.
6105
Bram Moolenaar72597a52010-07-18 15:31:08 +02006106strwidth({expr}) *strwidth()*
6107 The result is a Number, which is the number of display cells
6108 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02006109 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006110 When {expr} contains characters with East Asian Width Class
6111 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006112 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006113
Bram Moolenaar41571762014-04-02 19:00:58 +02006114submatch({nr}[, {list}]) *submatch()*
Bram Moolenaar251e1912011-06-19 05:09:16 +02006115 Only for an expression in a |:substitute| command or
6116 substitute() function.
6117 Returns the {nr}'th submatch of the matched text. When {nr}
6118 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02006119 Note that a NL in the string can stand for a line break of a
6120 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006121 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02006122
6123 If {list} is present and non-zero then submatch() returns
6124 a list of strings, similar to |getline()| with two arguments.
6125 NL characters in the text represent NUL characters in the
6126 text.
6127 Only returns more than one item for |:substitute|, inside
6128 |substitute()| this list will always contain one or zero
6129 items, since there are no real line breaks.
6130
Bram Moolenaar071d4272004-06-13 20:20:40 +00006131 Example: >
6132 :s/\d\+/\=submatch(0) + 1/
6133< This finds the first number in the line and adds one to it.
6134 A line break is included as a newline character.
6135
6136substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
6137 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02006138 the first match of {pat} is replaced with {sub}.
6139 When {flags} is "g", all matches of {pat} in {expr} are
6140 replaced. Otherwise {flags} should be "".
6141
6142 This works like the ":substitute" command (without any flags).
6143 But the matching with {pat} is always done like the 'magic'
6144 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006145 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
6146 if you want to ignore or match case and ignore 'ignorecase'.
6147 'smartcase' is not used. See |string-match| for how {pat} is
6148 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006149
6150 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006151 Note that some codes in {sub} have a special meaning
Bram Moolenaar446cb832008-06-24 21:56:24 +00006152 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006153 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006154
Bram Moolenaar071d4272004-06-13 20:20:40 +00006155 When {pat} does not match in {expr}, {expr} is returned
6156 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006157
Bram Moolenaar071d4272004-06-13 20:20:40 +00006158 Example: >
6159 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
6160< This removes the last component of the 'path' option. >
6161 :echo substitute("testing", ".*", "\\U\\0", "")
6162< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02006163
6164 When {sub} starts with "\=", the remainder is interpreted as
6165 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006166 :echo substitute(s, '%\(\x\x\)',
6167 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00006168
Bram Moolenaar47136d72004-10-12 20:02:24 +00006169synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006170 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00006171 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006172 The syntax ID can be used with |synIDattr()| and
6173 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006174
Bram Moolenaar47136d72004-10-12 20:02:24 +00006175 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006176 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02006177 Note that when the position is after the last character,
6178 that's where the cursor can be in Insert mode, synID() returns
6179 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006180
Bram Moolenaar071d4272004-06-13 20:20:40 +00006181 When {trans} is non-zero, transparent items are reduced to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006182 item that they reveal. This is useful when wanting to know
Bram Moolenaar071d4272004-06-13 20:20:40 +00006183 the effective color. When {trans} is zero, the transparent
6184 item is returned. This is useful when wanting to know which
6185 syntax item is effective (e.g. inside parens).
6186 Warning: This function can be very slow. Best speed is
6187 obtained by going through the file in forward direction.
6188
6189 Example (echoes the name of the syntax item under the cursor): >
6190 :echo synIDattr(synID(line("."), col("."), 1), "name")
6191<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02006192
Bram Moolenaar071d4272004-06-13 20:20:40 +00006193synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
6194 The result is a String, which is the {what} attribute of
6195 syntax ID {synID}. This can be used to obtain information
6196 about a syntax item.
6197 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006198 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00006199 used, the attributes for the currently active highlighting are
6200 used (GUI, cterm or term).
6201 Use synIDtrans() to follow linked highlight groups.
6202 {what} result
6203 "name" the name of the syntax item
6204 "fg" foreground color (GUI: color name used to set
6205 the color, cterm: color number as a string,
6206 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006207 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01006208 "font" font name (only available in the GUI)
6209 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006210 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006211 "fg#" like "fg", but for the GUI and the GUI is
6212 running the name in "#RRGGBB" form
6213 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006214 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006215 "bold" "1" if bold
6216 "italic" "1" if italic
6217 "reverse" "1" if reverse
6218 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01006219 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00006220 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006221 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00006222
6223 Example (echoes the color of the syntax item under the
6224 cursor): >
6225 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
6226<
6227synIDtrans({synID}) *synIDtrans()*
6228 The result is a Number, which is the translated syntax ID of
6229 {synID}. This is the syntax group ID of what is being used to
6230 highlight the character. Highlight links given with
6231 ":highlight link" are followed.
6232
Bram Moolenaar483c5d82010-10-20 18:45:33 +02006233synconcealed({lnum}, {col}) *synconcealed()*
6234 The result is a List. The first item in the list is 0 if the
6235 character at the position {lnum} and {col} is not part of a
6236 concealable region, 1 if it is. The second item in the list is
6237 a string. If the first item is 1, the second item contains the
6238 text which will be displayed in place of the concealed text,
6239 depending on the current setting of 'conceallevel'. The third
6240 and final item in the list is a unique number representing the
6241 specific syntax region matched. This allows detection of the
6242 beginning of a new concealable region if there are two
6243 consecutive regions with the same replacement character.
6244 For an example use see $VIMRUNTIME/syntax/2html.vim .
6245
6246
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006247synstack({lnum}, {col}) *synstack()*
6248 Return a |List|, which is the stack of syntax items at the
6249 position {lnum} and {col} in the current window. Each item in
6250 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006251 The first item in the List is the outer region, following are
6252 items contained in that one. The last one is what |synID()|
6253 returns, unless not the whole item is highlighted or it is a
6254 transparent item.
6255 This function is useful for debugging a syntax file.
6256 Example that shows the syntax stack under the cursor: >
6257 for id in synstack(line("."), col("."))
6258 echo synIDattr(id, "name")
6259 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02006260< When the position specified with {lnum} and {col} is invalid
6261 nothing is returned. The position just after the last
6262 character in a line and the first column in an empty line are
6263 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006264
Bram Moolenaarc0197e22004-09-13 20:26:32 +00006265system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02006266 Get the output of the shell command {expr} as a string. See
6267 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02006268
6269 When {input} is given and is a string this string is written
6270 to a file and passed as stdin to the command. The string is
6271 written as-is, you need to take care of using the correct line
6272 separators yourself.
6273 If {input} is given and is a |List| it is written to the file
6274 in a way |writefile()| does with {binary} set to "b" (i.e.
6275 with a newline between each list item with newlines inside
6276 list items converted to NULs).
6277 Pipes are not used.
6278
Bram Moolenaar52a72462014-08-29 15:53:52 +02006279 When prepended by |:silent| the shell will not be set to
6280 cooked mode. This is meant to be used for commands that do
6281 not need the user to type. It avoids stray characters showing
6282 up on the screen which require |CTRL-L| to remove. >
6283 :silent let f = system('ls *.vim')
6284<
Bram Moolenaar26df0922014-02-23 23:39:13 +01006285 Note: Use |shellescape()| or |::S| with |expand()| or
6286 |fnamemodify()| to escape special characters in a command
6287 argument. Newlines in {expr} may cause the command to fail.
6288 The characters in 'shellquote' and 'shellxquote' may also
6289 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006290 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006291
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006292 The result is a String. Example: >
6293 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01006294 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00006295
6296< To make the result more system-independent, the shell output
6297 is filtered to replace <CR> with <NL> for Macintosh, and
6298 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02006299 To avoid the string being truncated at a NUL, all NUL
6300 characters are replaced with SOH (0x01).
6301
Bram Moolenaar071d4272004-06-13 20:20:40 +00006302 The command executed is constructed using several options:
6303 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
6304 ({tmp} is an automatically generated file name).
6305 For Unix and OS/2 braces are put around {expr} to allow for
6306 concatenated commands.
6307
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006308 The command will be executed in "cooked" mode, so that a
6309 CTRL-C will interrupt the command (on Unix at least).
6310
Bram Moolenaar071d4272004-06-13 20:20:40 +00006311 The resulting error code can be found in |v:shell_error|.
6312 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00006313
6314 Note that any wrong value in the options mentioned above may
6315 make the function fail. It has also been reported to fail
6316 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006317 Unlike ":!cmd" there is no automatic check for changed files.
6318 Use |:checktime| to force a check.
6319
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006320
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02006321systemlist({expr} [, {input}]) *systemlist()*
6322 Same as |system()|, but returns a |List| with lines (parts of
6323 output separated by NL) with NULs transformed into NLs. Output
6324 is the same as |readfile()| will output with {binary} argument
6325 set to "b".
6326
6327 Returns an empty string on error, so be careful not to run
6328 into |E706|.
6329
6330
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006331tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006332 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006333 buffer associated with each window in the current tab page.
6334 {arg} specifies the number of tab page to be used. When
6335 omitted the current tab page is used.
6336 When {arg} is invalid the number zero is returned.
6337 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006338 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006339 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006340 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006341 endfor
6342< Note that a buffer may appear in more than one window.
6343
6344
6345tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00006346 The result is a Number, which is the number of the current
6347 tab page. The first tab page has number 1.
6348 When the optional argument is "$", the number of the last tab
6349 page is returned (the tab page count).
6350 The number can be used with the |:tab| command.
6351
6352
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01006353tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02006354 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006355 {tabarg} specifies the number of tab page to be used.
6356 {arg} is used like with |winnr()|:
6357 - When omitted the current window number is returned. This is
6358 the window which will be used when going to this tab page.
6359 - When "$" the number of windows is returned.
6360 - When "#" the previous window nr is returned.
6361 Useful examples: >
6362 tabpagewinnr(1) " current window of tab page 1
6363 tabpagewinnr(4, '$') " number of windows in tab page 4
6364< When {tabarg} is invalid zero is returned.
6365
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00006366 *tagfiles()*
6367tagfiles() Returns a |List| with the file names used to search for tags
6368 for the current buffer. This is the 'tags' option expanded.
6369
6370
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006371taglist({expr}) *taglist()*
6372 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00006373 Each list item is a dictionary with at least the following
6374 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00006375 name Name of the tag.
6376 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006377 defined. It is either relative to the
6378 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006379 cmd Ex command used to locate the tag in
6380 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00006381 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006382 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006383 kind values. Only available when
6384 using a tags file generated by
6385 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00006386 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006387 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006388 More entries may be present, depending on the content of the
6389 tags file: access, implementation, inherits and signature.
6390 Refer to the ctags documentation for information about these
6391 fields. For C code the fields "struct", "class" and "enum"
6392 may appear, they give the name of the entity the tag is
6393 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006394
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00006395 The ex-command 'cmd' can be either an ex search pattern, a
6396 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006397
6398 If there are no matching tags, then an empty list is returned.
6399
6400 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01006401 used in {expr}. This also make the function work faster.
6402 Refer to |tag-regexp| for more information about the tag
6403 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006404
6405 Refer to |'tags'| for information about how the tags file is
6406 located by Vim. Refer to |tags-file-format| for the format of
6407 the tags file generated by the different ctags tools.
6408
Bram Moolenaar071d4272004-06-13 20:20:40 +00006409tempname() *tempname()* *temp-file-name*
6410 The result is a String, which is the name of a file that
Bram Moolenaar446cb832008-06-24 21:56:24 +00006411 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar071d4272004-06-13 20:20:40 +00006412 is different for at least 26 consecutive calls. Example: >
6413 :let tmpfile = tempname()
6414 :exe "redir > " . tmpfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006415< For Unix, the file will be in a private directory |tempfile|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006416 For MS-Windows forward slashes are used when the 'shellslash'
6417 option is set or when 'shellcmdflag' starts with '-'.
6418
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006419
6420tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006421 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006422 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006423 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006424 Examples: >
6425 :echo tan(10)
6426< 0.648361 >
6427 :echo tan(-4.01)
6428< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02006429 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006430
6431
6432tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006433 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006434 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006435 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006436 Examples: >
6437 :echo tanh(0.5)
6438< 0.462117 >
6439 :echo tanh(-1)
6440< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02006441 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006442
6443
Bram Moolenaar071d4272004-06-13 20:20:40 +00006444tolower({expr}) *tolower()*
6445 The result is a copy of the String given, with all uppercase
6446 characters turned into lowercase (just like applying |gu| to
6447 the string).
6448
6449toupper({expr}) *toupper()*
6450 The result is a copy of the String given, with all lowercase
6451 characters turned into uppercase (just like applying |gU| to
6452 the string).
6453
Bram Moolenaar8299df92004-07-10 09:47:34 +00006454tr({src}, {fromstr}, {tostr}) *tr()*
6455 The result is a copy of the {src} string with all characters
6456 which appear in {fromstr} replaced by the character in that
6457 position in the {tostr} string. Thus the first character in
6458 {fromstr} is translated into the first character in {tostr}
6459 and so on. Exactly like the unix "tr" command.
6460 This code also deals with multibyte characters properly.
6461
6462 Examples: >
6463 echo tr("hello there", "ht", "HT")
6464< returns "Hello THere" >
6465 echo tr("<blob>", "<>", "{}")
6466< returns "{blob}"
6467
Bram Moolenaar446cb832008-06-24 21:56:24 +00006468trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00006469 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00006470 equal to {expr} as a |Float| (truncate towards zero).
6471 {expr} must evaluate to a |Float| or a |Number|.
6472 Examples: >
6473 echo trunc(1.456)
6474< 1.0 >
6475 echo trunc(-5.456)
6476< -5.0 >
6477 echo trunc(4.0)
6478< 4.0
6479 {only available when compiled with the |+float| feature}
6480
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006481 *type()*
6482type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00006483 Number: 0
6484 String: 1
6485 Funcref: 2
6486 List: 3
6487 Dictionary: 4
Bram Moolenaar446cb832008-06-24 21:56:24 +00006488 Float: 5
Bram Moolenaar748bf032005-02-02 23:04:36 +00006489 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006490 :if type(myvar) == type(0)
6491 :if type(myvar) == type("")
6492 :if type(myvar) == type(function("tr"))
6493 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00006494 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00006495 :if type(myvar) == type(0.0)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006496
Bram Moolenaara17d4c12010-05-30 18:30:36 +02006497undofile({name}) *undofile()*
6498 Return the name of the undo file that would be used for a file
6499 with name {name} when writing. This uses the 'undodir'
6500 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02006501 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02006502 {name} is always expanded to the full path, since that is what
6503 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02006504 If {name} is empty undofile() returns an empty string, since a
6505 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02006506 Useful in combination with |:wundo| and |:rundo|.
6507 When compiled without the +persistent_undo option this always
6508 returns an empty string.
6509
Bram Moolenaara800b422010-06-27 01:15:55 +02006510undotree() *undotree()*
6511 Return the current state of the undo tree in a dictionary with
6512 the following items:
6513 "seq_last" The highest undo sequence number used.
6514 "seq_cur" The sequence number of the current position in
6515 the undo tree. This differs from "seq_last"
6516 when some changes were undone.
6517 "time_cur" Time last used for |:earlier| and related
6518 commands. Use |strftime()| to convert to
6519 something readable.
6520 "save_last" Number of the last file write. Zero when no
6521 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02006522 "save_cur" Number of the current position in the undo
6523 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02006524 "synced" Non-zero when the last undo block was synced.
6525 This happens when waiting from input from the
6526 user. See |undo-blocks|.
6527 "entries" A list of dictionaries with information about
6528 undo blocks.
6529
6530 The first item in the "entries" list is the oldest undo item.
6531 Each List item is a Dictionary with these items:
6532 "seq" Undo sequence number. Same as what appears in
6533 |:undolist|.
6534 "time" Timestamp when the change happened. Use
6535 |strftime()| to convert to something readable.
6536 "newhead" Only appears in the item that is the last one
6537 that was added. This marks the last change
6538 and where further changes will be added.
6539 "curhead" Only appears in the item that is the last one
6540 that was undone. This marks the current
6541 position in the undo tree, the block that will
6542 be used by a redo command. When nothing was
6543 undone after the last change this item will
6544 not appear anywhere.
6545 "save" Only appears on the last block before a file
6546 write. The number is the write count. The
6547 first write has number 1, the last one the
6548 "save_last" mentioned above.
6549 "alt" Alternate entry. This is again a List of undo
6550 blocks. Each item may again have an "alt"
6551 item.
6552
Bram Moolenaar327aa022014-03-25 18:24:23 +01006553uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
6554 Remove second and succeeding copies of repeated adjacent
6555 {list} items in-place. Returns {list}. If you want a list
6556 to remain unmodified make a copy first: >
6557 :let newlist = uniq(copy(mylist))
6558< The default compare function uses the string representation of
6559 each item. For the use of {func} and {dict} see |sort()|.
6560
Bram Moolenaar677ee682005-01-27 14:41:15 +00006561values({dict}) *values()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006562 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006563 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006564
6565
Bram Moolenaar071d4272004-06-13 20:20:40 +00006566virtcol({expr}) *virtcol()*
6567 The result is a Number, which is the screen column of the file
6568 position given with {expr}. That is, the last screen position
6569 occupied by the character at that position, when the screen
6570 would be of unlimited width. When there is a <Tab> at the
6571 position, the returned Number will be the column at the end of
6572 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006573 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00006574 For the byte position use |col()|.
6575 For the use of {expr} see |col()|.
6576 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00006577 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006578 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02006579 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006580 When Virtual editing is active in the current mode, a position
6581 beyond the end of the line can be returned. |'virtualedit'|
6582 The accepted positions are:
6583 . the cursor position
6584 $ the end of the cursor line (the result is the
6585 number of displayed characters in the cursor line
6586 plus one)
6587 'x position of mark x (if the mark is not set, 0 is
6588 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01006589 v In Visual mode: the start of the Visual area (the
6590 cursor is the end). When not in Visual mode
6591 returns the cursor position. Differs from |'<| in
6592 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006593 Note that only marks in the current file can be used.
6594 Examples: >
6595 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
6596 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00006597 virtcol("'t") with text " there", with 't at 'h', returns 6
6598< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006599 A more advanced example that echoes the maximum length of
6600 all lines: >
6601 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
6602
Bram Moolenaar071d4272004-06-13 20:20:40 +00006603
6604visualmode([expr]) *visualmode()*
6605 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006606 used in the current buffer. Initially it returns an empty
6607 string, but once Visual mode has been used, it returns "v",
6608 "V", or "<CTRL-V>" (a single CTRL-V character) for
6609 character-wise, line-wise, or block-wise Visual mode
6610 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006611 Example: >
6612 :exe "normal " . visualmode()
6613< This enters the same Visual mode as before. It is also useful
6614 in scripts if you wish to act differently depending on the
6615 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006616 If Visual mode is active, use |mode()| to get the Visual mode
6617 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006618 *non-zero-arg*
6619 If [expr] is supplied and it evaluates to a non-zero Number or
6620 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaar446cb832008-06-24 21:56:24 +00006621 the old value is returned. Note that " " and "0" are also
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006622 non-empty strings, thus cause the mode to be cleared. A List,
6623 Dictionary or Float is not a Number or String, thus does not
6624 cause the mode to be cleared.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006625
Bram Moolenaar8738fc12013-02-20 17:59:11 +01006626wildmenumode() *wildmenumode()*
6627 Returns non-zero when the wildmenu is active and zero
6628 otherwise. See 'wildmenu' and 'wildmode'.
6629 This can be used in mappings to handle the 'wildcharm' option
6630 gracefully. (Makes only sense with |mapmode-c| mappings).
6631
6632 For example to make <c-j> work like <down> in wildmode, use: >
6633 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
6634<
6635 (Note, this needs the 'wildcharm' option set appropriately).
6636
6637
Bram Moolenaar071d4272004-06-13 20:20:40 +00006638 *winbufnr()*
6639winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006640 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00006641 the buffer in the current window is returned. When window
6642 {nr} doesn't exist, -1 is returned.
6643 Example: >
6644 :echo "The file in the current window is " . bufname(winbufnr(0))
6645<
6646 *wincol()*
6647wincol() The result is a Number, which is the virtual column of the
6648 cursor in the window. This is counting screen cells from the
6649 left side of the window. The leftmost column is one.
6650
6651winheight({nr}) *winheight()*
6652 The result is a Number, which is the height of window {nr}.
6653 When {nr} is zero, the height of the current window is
6654 returned. When window {nr} doesn't exist, -1 is returned.
6655 An existing window always has a height of zero or more.
6656 Examples: >
6657 :echo "The current window has " . winheight(0) . " lines."
6658<
6659 *winline()*
6660winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar446cb832008-06-24 21:56:24 +00006661 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00006662 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006663 If the cursor was moved the view on the file will be updated
6664 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006665
6666 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006667winnr([{arg}]) The result is a Number, which is the number of the current
6668 window. The top window has number 1.
6669 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006670 last window is returned (the window count). >
6671 let window_count = winnr('$')
6672< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006673 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006674 If there is no previous window or it is in another tab page 0
6675 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006676 The number can be used with |CTRL-W_w| and ":wincmd w"
6677 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006678 Also see |tabpagewinnr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006679
6680 *winrestcmd()*
6681winrestcmd() Returns a sequence of |:resize| commands that should restore
6682 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006683 are opened or closed and the current window and tab page is
6684 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006685 Example: >
6686 :let cmd = winrestcmd()
6687 :call MessWithWindowSizes()
6688 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006689<
6690 *winrestview()*
6691winrestview({dict})
6692 Uses the |Dictionary| returned by |winsaveview()| to restore
6693 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +02006694 Note: The {dict} does not have to contain all values, that are
6695 returned by |winsaveview()|. If values are missing, those
6696 settings won't be restored. So you can use: >
6697 :call winrestview({'curswant': 4})
6698<
6699 This will only set the curswant value (the column the cursor
6700 wants to move on vertical movements) of the cursor to column 5
6701 (yes, that is 5), while all other settings will remain the
6702 same. This is useful, if you set the cursor position manually.
6703
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006704 If you have changed the values the result is unpredictable.
6705 If the window size changed the result won't be the same.
6706
6707 *winsaveview()*
6708winsaveview() Returns a |Dictionary| that contains information to restore
6709 the view of the current window. Use |winrestview()| to
6710 restore the view.
6711 This is useful if you have a mapping that jumps around in the
6712 buffer and you want to go back to the original view.
6713 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00006714 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +02006715 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006716 The return value includes:
6717 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +02006718 col cursor column (Note: the first column
6719 zero, as opposed to what getpos()
6720 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006721 coladd cursor column offset for 'virtualedit'
6722 curswant column for vertical movement
6723 topline first line in the window
6724 topfill filler lines, only in diff mode
6725 leftcol first column displayed
6726 skipcol columns skipped
6727 Note that no option values are saved.
6728
Bram Moolenaar071d4272004-06-13 20:20:40 +00006729
6730winwidth({nr}) *winwidth()*
6731 The result is a Number, which is the width of window {nr}.
6732 When {nr} is zero, the width of the current window is
6733 returned. When window {nr} doesn't exist, -1 is returned.
6734 An existing window always has a width of zero or more.
6735 Examples: >
6736 :echo "The current window has " . winwidth(0) . " columns."
6737 :if winwidth(0) <= 50
6738 : exe "normal 50\<C-W>|"
6739 :endif
6740<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006741 *writefile()*
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01006742writefile({list}, {fname} [, {flags}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006743 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006744 separated with a NL. Each list item must be a String or
6745 Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01006746 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006747 not be a NL after the last list item. An empty item at the
6748 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01006749
6750 When {flags} contains "a" then append mode is used, lines are
6751 append to the file: >
6752 :call writefile(["foo"], "event.log", "a")
6753 :call writefile(["bar"], "event.log", "a")
6754>
6755< All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006756 Inserting CR characters needs to be done before passing {list}
6757 to writefile().
6758 An existing file is overwritten, if possible.
6759 When the write fails -1 is returned, otherwise 0. There is an
6760 error message if the file can't be created or when writing
6761 fails.
6762 Also see |readfile()|.
6763 To copy a file byte for byte: >
6764 :let fl = readfile("foo", "b")
6765 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006766
6767
6768xor({expr}, {expr}) *xor()*
6769 Bitwise XOR on the two arguments. The arguments are converted
6770 to a number. A List, Dict or Float argument causes an error.
6771 Example: >
6772 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +01006773<
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006774
Bram Moolenaar071d4272004-06-13 20:20:40 +00006775
6776 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006777There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +000067781. Features that are only supported when they have been enabled when Vim
6779 was compiled |+feature-list|. Example: >
6780 :if has("cindent")
67812. Features that are only supported when certain conditions have been met.
6782 Example: >
6783 :if has("gui_running")
6784< *has-patch*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020067853. Included patches. The "patch123" feature means that patch 123 has been
6786 included. Note that this form does not check the version of Vim, you need
6787 to inspect |v:version| for that.
6788 Example (checking version 6.2.148 or later): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006789 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02006790< Note that it's possible for patch 147 to be omitted even though 148 is
6791 included.
6792
67934. Beyond a certain version or at a certain version and including a specific
Bram Moolenaarbcb98982014-05-01 14:08:19 +02006794 patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or
6795 later, or it is version 7.4 and patch 237 was included.
6796 Note that this only works for patch 7.4.237 and later, before that you
6797 need to use the example above that checks v:version. Example: >
6798 :if has("patch-7.4.248")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02006799< Note that it's possible for patch 147 to be omitted even though 148 is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006800 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006801
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02006802acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006803all_builtin_terms Compiled with all builtin terminals enabled.
6804amiga Amiga version of Vim.
6805arabic Compiled with Arabic support |Arabic|.
6806arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00006807autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006808balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00006809balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006810beos BeOS version of Vim.
6811browse Compiled with |:browse| support, and browse() will
6812 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +02006813browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006814builtin_terms Compiled with some builtin terminals.
6815byte_offset Compiled with support for 'o' in 'statusline'
6816cindent Compiled with 'cindent' support.
6817clientserver Compiled with remote invocation support |clientserver|.
6818clipboard Compiled with 'clipboard' support.
6819cmdline_compl Compiled with |cmdline-completion| support.
6820cmdline_hist Compiled with |cmdline-history| support.
6821cmdline_info Compiled with 'showcmd' and 'ruler' support.
6822comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006823compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006824cryptv Compiled with encryption support |encryption|.
6825cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006826debug Compiled with "DEBUG" defined.
6827dialog_con Compiled with console dialog support.
6828dialog_gui Compiled with GUI dialog support.
6829diff Compiled with |vimdiff| and 'diff' support.
6830digraphs Compiled with support for digraphs.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006831directx Compiled with support for Direct-X and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006832dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006833dos16 16 bits DOS version of Vim.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006834dos32 32 bits DOS (DJGPP) version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006835ebcdic Compiled on a machine with ebcdic character set.
6836emacs_tags Compiled with support for Emacs tags.
6837eval Compiled with expression evaluation support. Always
6838 true, of course!
6839ex_extra Compiled with extra Ex commands |+ex_extra|.
6840extra_search Compiled with support for |'incsearch'| and
6841 |'hlsearch'|
6842farsi Compiled with Farsi support |farsi|.
6843file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006844filterpipe When 'shelltemp' is off pipes are used for shell
6845 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00006846find_in_path Compiled with support for include file searches
6847 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006848float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006849fname_case Case in file names matters (for Amiga, MS-DOS, and
6850 Windows this is not present).
6851folding Compiled with |folding| support.
6852footer Compiled with GUI footer support. |gui-footer|
6853fork Compiled to use fork()/exec() instead of system().
6854gettext Compiled with message translation |multi-lang|
6855gui Compiled with GUI enabled.
6856gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006857gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006858gui_gtk Compiled with GTK+ GUI (any version).
6859gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
6860gui_mac Compiled with Macintosh GUI.
6861gui_motif Compiled with Motif GUI.
6862gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006863gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006864gui_win32 Compiled with MS Windows Win32 GUI.
6865gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006866hangul_input Compiled with Hangul input support. |hangul|
6867iconv Can use iconv() for conversion.
6868insert_expand Compiled with support for CTRL-X expansion commands in
6869 Insert mode.
6870jumplist Compiled with |jumplist| support.
6871keymap Compiled with 'keymap' support.
6872langmap Compiled with 'langmap' support.
6873libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +02006874linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
6875 'breakindent' support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006876lispindent Compiled with support for lisp indenting.
6877listcmds Compiled with commands for the buffer list |:files|
6878 and the argument list |arglist|.
6879localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02006880lua Compiled with Lua interface |Lua|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006881mac Macintosh version of Vim.
6882macunix Macintosh version of Vim, using Unix files (OS-X).
6883menu Compiled with support for |:menu|.
6884mksession Compiled with support for |:mksession|.
6885modify_fname Compiled with file name modifiers. |filename-modifiers|
6886mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006887mouse_dec Compiled with support for Dec terminal mouse.
6888mouse_gpm Compiled with support for gpm (Linux console mouse)
6889mouse_netterm Compiled with support for netterm mouse.
6890mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006891mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +02006892mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01006893mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006894mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006895mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00006896multi_byte Compiled with support for 'encoding'
6897multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006898multi_byte_ime Compiled with support for IME input method.
6899multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00006900mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02006901netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006902netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006903ole Compiled with OLE automation support for Win32.
6904os2 OS/2 version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006905path_extra Compiled with up/downwards search in 'path' and 'tags'
6906perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02006907persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006908postscript Compiled with PostScript file printing.
6909printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006910profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02006911python Compiled with Python 2.x interface. |has-python|
6912python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006913qnx QNX version of Vim.
6914quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00006915reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006916rightleft Compiled with 'rightleft' support.
6917ruby Compiled with Ruby interface |ruby|.
6918scrollbind Compiled with 'scrollbind' support.
6919showcmd Compiled with 'showcmd' support.
6920signs Compiled with |:sign| support.
6921smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006922sniff Compiled with SNiFF interface support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006923spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00006924startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006925statusline Compiled with support for 'statusline', 'rulerformat'
6926 and special formats of 'titlestring' and 'iconstring'.
6927sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006928syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006929syntax_items There are active syntax highlighting items for the
6930 current buffer.
6931system Compiled to use system() instead of fork()/exec().
6932tag_binary Compiled with binary searching in tags files
6933 |tag-binary-search|.
6934tag_old_static Compiled with support for old static tags
6935 |tag-old-static|.
6936tag_any_white Compiled with support for any white characters in tags
6937 files |tag-any-white|.
6938tcl Compiled with Tcl interface.
6939terminfo Compiled with terminfo instead of termcap.
6940termresponse Compiled with support for |t_RV| and |v:termresponse|.
6941textobjects Compiled with support for |text-objects|.
6942tgetent Compiled with tgetent support, able to use a termcap
6943 or terminfo file.
6944title Compiled with window title support |'title'|.
6945toolbar Compiled with support for |gui-toolbar|.
6946unix Unix version of Vim.
6947user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006948vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006949vim_starting True while initial source'ing takes place. |startup|
6950viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006951virtualedit Compiled with 'virtualedit' option.
6952visual Compiled with Visual mode.
6953visualextra Compiled with extra Visual mode commands.
6954 |blockwise-operators|.
6955vms VMS version of Vim.
6956vreplace Compiled with |gR| and |gr| commands.
6957wildignore Compiled with 'wildignore' option.
6958wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006959win16 Win16 version of Vim (MS-Windows 3.1).
Bram Moolenaard58e9292011-02-09 17:07:58 +01006960win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
6961 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006962win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006963win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006964win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006965winaltkeys Compiled with 'winaltkeys' option.
6966windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006967writebackup Compiled with 'writebackup' default on.
6968xfontset Compiled with X fontset support |xfontset|.
6969xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02006970xpm Compiled with pixmap support.
6971xpm_w32 Compiled with pixmap support for Win32. (Only for
6972 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006973xsmp Compiled with X session management support.
6974xsmp_interact Compiled with interactive X session management support.
6975xterm_clipboard Compiled with support for xterm clipboard.
6976xterm_save Compiled with support for saving and restoring the
6977 xterm screen.
6978x11 Compiled with X11 support.
6979
6980 *string-match*
6981Matching a pattern in a String
6982
6983A regexp pattern as explained at |pattern| is normally used to find a match in
6984the buffer lines. When a pattern is used to find a match in a String, almost
6985everything works in the same way. The difference is that a String is handled
6986like it is one line. When it contains a "\n" character, this is not seen as a
6987line break for the pattern. It can be matched with a "\n" in the pattern, or
6988with ".". Example: >
6989 :let a = "aaaa\nxxxx"
6990 :echo matchstr(a, "..\n..")
6991 aa
6992 xx
6993 :echo matchstr(a, "a.x")
6994 a
6995 x
6996
6997Don't forget that "^" will only match at the first character of the String and
6998"$" at the last character of the string. They don't match after or before a
6999"\n".
7000
7001==============================================================================
70025. Defining functions *user-functions*
7003
7004New functions can be defined. These can be called just like builtin
7005functions. The function executes a sequence of Ex commands. Normal mode
7006commands can be executed with the |:normal| command.
7007
7008The function name must start with an uppercase letter, to avoid confusion with
7009builtin functions. To prevent from using the same name in different scripts
7010avoid obvious, short names. A good habit is to start the function name with
7011the name of the script, e.g., "HTMLcolor()".
7012
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007013It's also possible to use curly braces, see |curly-braces-names|. And the
7014|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007015
7016 *local-function*
7017A function local to a script must start with "s:". A local script function
7018can only be called from within the script and from functions, user commands
7019and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007020function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00007021instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007022There are only script-local functions, no buffer-local or window-local
7023functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007024
7025 *:fu* *:function* *E128* *E129* *E123*
7026:fu[nction] List all functions and their arguments.
7027
7028:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007029 {name} can also be a |Dictionary| entry that is a
7030 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007031 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007032
7033:fu[nction] /{pattern} List functions with a name matching {pattern}.
7034 Example that lists all functions ending with "File": >
7035 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00007036<
7037 *:function-verbose*
7038When 'verbose' is non-zero, listing a function will also display where it was
7039last defined. Example: >
7040
7041 :verbose function SetFileTypeSH
7042 function SetFileTypeSH(name)
7043 Last set from /usr/share/vim/vim-7.0/filetype.vim
7044<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007045See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00007046
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007047 *E124* *E125* *E853* *E884*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007048:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007049 Define a new function by the name {name}. The name
7050 must be made of alphanumeric characters and '_', and
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007051 must start with a capital or "s:" (see above). Note
7052 that using "b:" or "g:" is not allowed. (since patch
7053 7.4.260 E884 is given if the function name has a colon
7054 in the name, e.g. for "foo:bar()". Before that patch
7055 no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007056
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007057 {name} can also be a |Dictionary| entry that is a
7058 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007059 :function dict.init(arg)
Bram Moolenaar446cb832008-06-24 21:56:24 +00007060< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007061 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar446cb832008-06-24 21:56:24 +00007062 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007063 result is a |Funcref| to a numbered function. The
7064 function can only be used with a |Funcref| and will be
7065 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007066 *E127* *E122*
7067 When a function by this name already exists and [!] is
7068 not used an error message is given. When [!] is used,
7069 an existing function is silently replaced. Unless it
7070 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007071
7072 For the {arguments} see |function-argument|.
7073
Bram Moolenaar8d043172014-01-23 14:24:41 +01007074 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007075 When the [range] argument is added, the function is
7076 expected to take care of a range itself. The range is
7077 passed as "a:firstline" and "a:lastline". If [range]
7078 is excluded, ":{range}call" will call the function for
7079 each line in the range, with the cursor on the start
7080 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007081 The cursor is still moved to the first line of the
7082 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +01007083 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007084 When the [abort] argument is added, the function will
7085 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +01007086 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007087 When the [dict] argument is added, the function must
Bram Moolenaar446cb832008-06-24 21:56:24 +00007088 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007089 local variable "self" will then be set to the
7090 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007091
Bram Moolenaar446cb832008-06-24 21:56:24 +00007092 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00007093 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00007094 will not be changed by the function. This also
7095 implies that the effect of |:nohlsearch| is undone
7096 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00007097
Bram Moolenaar071d4272004-06-13 20:20:40 +00007098 *:endf* *:endfunction* *E126* *E193*
7099:endf[unction] The end of a function definition. Must be on a line
7100 by its own, without other commands.
7101
7102 *:delf* *:delfunction* *E130* *E131*
7103:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007104 {name} can also be a |Dictionary| entry that is a
7105 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007106 :delfunc dict.init
Bram Moolenaar446cb832008-06-24 21:56:24 +00007107< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007108 function is deleted if there are no more references to
7109 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007110 *:retu* *:return* *E133*
7111:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
7112 evaluated and returned as the result of the function.
7113 If "[expr]" is not given, the number 0 is returned.
7114 When a function ends without an explicit ":return",
7115 the number 0 is returned.
7116 Note that there is no check for unreachable lines,
7117 thus there is no warning if commands follow ":return".
7118
7119 If the ":return" is used after a |:try| but before the
7120 matching |:finally| (if present), the commands
7121 following the ":finally" up to the matching |:endtry|
7122 are executed first. This process applies to all
7123 nested ":try"s inside the function. The function
7124 returns at the outermost ":endtry".
7125
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007126 *function-argument* *a:var*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007127An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007128be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007129 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007130Up to 20 arguments can be given, separated by commas. After the named
7131arguments an argument "..." can be specified, which means that more arguments
7132may optionally be following. In the function the extra arguments can be used
7133as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007134can be 0). "a:000" is set to a |List| that contains these arguments. Note
7135that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007136 *E742*
7137The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007138However, if a |List| or |Dictionary| is used, you can change their contents.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007139Thus you can pass a |List| to a function and have the function add an item to
7140it. If you want to make sure the function cannot change a |List| or
7141|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007142
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007143When not using "...", the number of arguments in a function call must be equal
7144to the number of named arguments. When using "...", the number of arguments
7145may be larger.
7146
7147It is also possible to define a function without any arguments. You must
7148still supply the () then. The body of the function follows in the next lines,
7149until the matching |:endfunction|. It is allowed to define another function
7150inside a function body.
7151
7152 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007153Inside a function variables can be used. These are local variables, which
7154will disappear when the function returns. Global variables need to be
7155accessed with "g:".
7156
7157Example: >
7158 :function Table(title, ...)
7159 : echohl Title
7160 : echo a:title
7161 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00007162 : echo a:0 . " items:"
7163 : for s in a:000
7164 : echon ' ' . s
7165 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00007166 :endfunction
7167
7168This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00007169 call Table("Table", "line1", "line2")
7170 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007171
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007172To return more than one value, return a |List|: >
7173 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007174 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007175 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007176 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007177 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007178 :endfunction
7179
7180This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007181 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007182 :if success == "ok"
7183 : echo div
7184 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007185<
Bram Moolenaar39f05632006-03-19 22:15:26 +00007186 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007187:[range]cal[l] {name}([arguments])
7188 Call a function. The name of the function and its arguments
7189 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007190 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007191 Without a range and for functions that accept a range, the
7192 function is called once. When a range is given the cursor is
7193 positioned at the start of the first line before executing the
7194 function.
7195 When a range is given and the function doesn't handle it
7196 itself, the function is executed for each line in the range,
7197 with the cursor in the first column of that line. The cursor
7198 is left at the last line (possibly moved by the last function
Bram Moolenaar446cb832008-06-24 21:56:24 +00007199 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00007200 this works:
7201 *function-range-example* >
7202 :function Mynumber(arg)
7203 : echo line(".") . " " . a:arg
7204 :endfunction
7205 :1,5call Mynumber(getline("."))
7206<
7207 The "a:firstline" and "a:lastline" are defined anyway, they
7208 can be used to do something different at the start or end of
7209 the range.
7210
7211 Example of a function that handles the range itself: >
7212
7213 :function Cont() range
7214 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
7215 :endfunction
7216 :4,8call Cont()
7217<
7218 This function inserts the continuation character "\" in front
7219 of all the lines in the range, except the first one.
7220
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007221 When the function returns a composite value it can be further
7222 dereferenced, but the range will not be used then. Example: >
7223 :4,8call GetDict().method()
7224< Here GetDict() gets the range but method() does not.
7225
Bram Moolenaar071d4272004-06-13 20:20:40 +00007226 *E132*
7227The recursiveness of user functions is restricted with the |'maxfuncdepth'|
7228option.
7229
Bram Moolenaar7c626922005-02-07 22:01:03 +00007230
7231AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00007232 *autoload-functions*
7233When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00007234only when they are used. There are two methods: with an autocommand and with
7235the "autoload" directory in 'runtimepath'.
7236
7237
7238Using an autocommand ~
7239
Bram Moolenaar05159a02005-02-26 23:04:13 +00007240This is introduced in the user manual, section |41.14|.
7241
Bram Moolenaar7c626922005-02-07 22:01:03 +00007242The autocommand is useful if you have a plugin that is a long Vim script file.
7243You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007244That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00007245again, setting a variable to skip the |:finish| command.
7246
7247Use the FuncUndefined autocommand event with a pattern that matches the
7248function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007249
7250 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
7251
7252The file "~/vim/bufnetfuncs.vim" should then define functions that start with
7253"BufNet". Also see |FuncUndefined|.
7254
Bram Moolenaar7c626922005-02-07 22:01:03 +00007255
7256Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007257 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00007258This is introduced in the user manual, section |41.15|.
7259
Bram Moolenaar7c626922005-02-07 22:01:03 +00007260Using a script in the "autoload" directory is simpler, but requires using
7261exactly the right file name. A function that can be autoloaded has a name
7262like this: >
7263
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007264 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00007265
7266When such a function is called, and it is not defined yet, Vim will search the
7267"autoload" directories in 'runtimepath' for a script file called
7268"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
7269then define the function like this: >
7270
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007271 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00007272 echo "Done!"
7273 endfunction
7274
Bram Moolenaar60a795a2005-09-16 21:55:43 +00007275The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00007276exactly, and the defined function must have the name exactly as it will be
7277called.
7278
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007279It is possible to use subdirectories. Every # in the function name works like
7280a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00007281
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007282 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00007283
7284Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
7285
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007286This also works when reading a variable that has not been set yet: >
7287
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007288 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007289
Bram Moolenaara5792f52005-11-23 21:25:05 +00007290However, when the autoload script was already loaded it won't be loaded again
7291for an unknown variable.
7292
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007293When assigning a value to such a variable nothing special happens. This can
7294be used to pass settings to the autoload script before it's loaded: >
7295
Bram Moolenaara7fc0102005-05-18 22:17:12 +00007296 :let foo#bar#toggle = 1
7297 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007298
Bram Moolenaar4399ef42005-02-12 14:29:27 +00007299Note that when you make a mistake and call a function that is supposed to be
7300defined in an autoload script, but the script doesn't actually define the
7301function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007302And you will get an error message every time.
7303
7304Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007305other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007306Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00007307
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007308Hint: If you distribute a bunch of scripts you can pack them together with the
7309|vimball| utility. Also read the user manual |distribute-script|.
7310
Bram Moolenaar071d4272004-06-13 20:20:40 +00007311==============================================================================
73126. Curly braces names *curly-braces-names*
7313
Bram Moolenaar84f72352012-03-11 15:57:40 +01007314In most places where you can use a variable, you can use a "curly braces name"
7315variable. This is a regular variable name with one or more expressions
7316wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007317 my_{adjective}_variable
7318
7319When Vim encounters this, it evaluates the expression inside the braces, puts
7320that in place of the expression, and re-interprets the whole as a variable
7321name. So in the above example, if the variable "adjective" was set to
7322"noisy", then the reference would be to "my_noisy_variable", whereas if
7323"adjective" was set to "quiet", then it would be to "my_quiet_variable".
7324
7325One application for this is to create a set of variables governed by an option
Bram Moolenaar446cb832008-06-24 21:56:24 +00007326value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007327 echo my_{&background}_message
7328
7329would output the contents of "my_dark_message" or "my_light_message" depending
7330on the current value of 'background'.
7331
7332You can use multiple brace pairs: >
7333 echo my_{adverb}_{adjective}_message
7334..or even nest them: >
7335 echo my_{ad{end_of_word}}_message
7336where "end_of_word" is either "verb" or "jective".
7337
7338However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007339variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007340 :let foo='a + b'
7341 :echo c{foo}d
7342.. since the result of expansion is "ca + bd", which is not a variable name.
7343
7344 *curly-braces-function-names*
7345You can call and define functions by an evaluated name in a similar way.
7346Example: >
7347 :let func_end='whizz'
7348 :call my_func_{func_end}(parameter)
7349
7350This would call the function "my_func_whizz(parameter)".
7351
Bram Moolenaar84f72352012-03-11 15:57:40 +01007352This does NOT work: >
7353 :let i = 3
7354 :let @{i} = '' " error
7355 :echo @{i} " error
7356
Bram Moolenaar071d4272004-06-13 20:20:40 +00007357==============================================================================
73587. Commands *expression-commands*
7359
7360:let {var-name} = {expr1} *:let* *E18*
7361 Set internal variable {var-name} to the result of the
7362 expression {expr1}. The variable will get the type
7363 from the {expr}. If {var-name} didn't exist yet, it
7364 is created.
7365
Bram Moolenaar13065c42005-01-08 16:08:21 +00007366:let {var-name}[{idx}] = {expr1} *E689*
7367 Set a list item to the result of the expression
7368 {expr1}. {var-name} must refer to a list and {idx}
7369 must be a valid index in that list. For nested list
7370 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007371 This cannot be used to add an item to a |List|.
7372 This cannot be used to set a byte in a String. You
7373 can do that like this: >
7374 :let var = var[0:2] . 'X' . var[4:]
7375<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007376 *E711* *E719*
7377:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007378 Set a sequence of items in a |List| to the result of
7379 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007380 correct number of items.
7381 {idx1} can be omitted, zero is used instead.
7382 {idx2} can be omitted, meaning the end of the list.
7383 When the selected range of items is partly past the
7384 end of the list, items will be added.
7385
Bram Moolenaar748bf032005-02-02 23:04:36 +00007386 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007387:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
7388:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
7389:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
7390 These fail if {var} was not set yet and when the type
7391 of {var} and {expr1} don't fit the operator.
7392
7393
Bram Moolenaar071d4272004-06-13 20:20:40 +00007394:let ${env-name} = {expr1} *:let-environment* *:let-$*
7395 Set environment variable {env-name} to the result of
7396 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007397:let ${env-name} .= {expr1}
7398 Append {expr1} to the environment variable {env-name}.
7399 If the environment variable didn't exist yet this
7400 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007401
7402:let @{reg-name} = {expr1} *:let-register* *:let-@*
7403 Write the result of the expression {expr1} in register
7404 {reg-name}. {reg-name} must be a single letter, and
7405 must be the name of a writable register (see
7406 |registers|). "@@" can be used for the unnamed
7407 register, "@/" for the search pattern.
7408 If the result of {expr1} ends in a <CR> or <NL>, the
7409 register will be linewise, otherwise it will be set to
7410 characterwise.
7411 This can be used to clear the last search pattern: >
7412 :let @/ = ""
7413< This is different from searching for an empty string,
7414 that would match everywhere.
7415
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007416:let @{reg-name} .= {expr1}
Bram Moolenaar446cb832008-06-24 21:56:24 +00007417 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007418 register was empty it's like setting it to {expr1}.
7419
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007420:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007421 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007422 expression {expr1}. A String or Number value is
7423 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007424 For an option local to a window or buffer the effect
7425 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00007426 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007427 Example: >
7428 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00007429
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007430:let &{option-name} .= {expr1}
7431 For a string option: Append {expr1} to the value.
7432 Does not insert a comma like |:set+=|.
7433
7434:let &{option-name} += {expr1}
7435:let &{option-name} -= {expr1}
7436 For a number or boolean option: Add or subtract
7437 {expr1}.
7438
Bram Moolenaar071d4272004-06-13 20:20:40 +00007439:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007440:let &l:{option-name} .= {expr1}
7441:let &l:{option-name} += {expr1}
7442:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007443 Like above, but only set the local value of an option
7444 (if there is one). Works like |:setlocal|.
7445
7446:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007447:let &g:{option-name} .= {expr1}
7448:let &g:{option-name} += {expr1}
7449:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007450 Like above, but only set the global value of an option
7451 (if there is one). Works like |:setglobal|.
7452
Bram Moolenaar13065c42005-01-08 16:08:21 +00007453:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007454 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007455 the list is assigned to {name1}, the second item to
7456 {name2}, etc.
7457 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007458 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007459 Each name can be one of the items of the ":let"
7460 command as mentioned above.
7461 Example: >
7462 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007463< Detail: {expr1} is evaluated first, then the
7464 assignments are done in sequence. This matters if
7465 {name2} depends on {name1}. Example: >
7466 :let x = [0, 1]
7467 :let i = 0
7468 :let [i, x[i]] = [1, 2]
7469 :echo x
7470< The result is [0, 2].
7471
7472:let [{name1}, {name2}, ...] .= {expr1}
7473:let [{name1}, {name2}, ...] += {expr1}
7474:let [{name1}, {name2}, ...] -= {expr1}
7475 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007476 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007477
7478:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007479 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007480 items than there are names. A list of the remaining
7481 items is assigned to {lastname}. If there are no
7482 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00007483 Example: >
7484 :let [a, b; rest] = ["aval", "bval", 3, 4]
7485<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007486:let [{name}, ..., ; {lastname}] .= {expr1}
7487:let [{name}, ..., ; {lastname}] += {expr1}
7488:let [{name}, ..., ; {lastname}] -= {expr1}
7489 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007490 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02007491
7492 *E121*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007493:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00007494 variable names may be given. Special names recognized
7495 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00007496 g: global variables
7497 b: local buffer variables
7498 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007499 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00007500 s: script-local variables
7501 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00007502 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007503
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007504:let List the values of all variables. The type of the
7505 variable is indicated before the value:
7506 <nothing> String
7507 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007508 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00007509
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007510
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007511:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007512 Remove the internal variable {name}. Several variable
7513 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007514 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007515 With [!] no error message is given for non-existing
7516 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007517 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00007518 :unlet list[3] " remove fourth item
7519 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007520< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00007521 :unlet dict['two']
7522 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00007523< This is especially useful to clean up used global
7524 variables and script-local variables (these are not
7525 deleted when the script ends). Function-local
7526 variables are automatically deleted when the function
7527 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007528
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007529:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
7530 Lock the internal variable {name}. Locking means that
7531 it can no longer be changed (until it is unlocked).
7532 A locked variable can be deleted: >
7533 :lockvar v
7534 :let v = 'asdf' " fails!
7535 :unlet v
7536< *E741*
7537 If you try to change a locked variable you get an
Bram Moolenaar8a94d872015-01-25 13:02:57 +01007538 error message: "E741: Value is locked: {name}"
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007539
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007540 [depth] is relevant when locking a |List| or
7541 |Dictionary|. It specifies how deep the locking goes:
7542 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007543 cannot add or remove items, but can
7544 still change their values.
7545 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007546 the items. If an item is a |List| or
7547 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007548 items, but can still change the
7549 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007550 3 Like 2 but for the |List| /
7551 |Dictionary| in the |List| /
7552 |Dictionary|, one level deeper.
7553 The default [depth] is 2, thus when {name} is a |List|
7554 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007555 *E743*
7556 For unlimited depth use [!] and omit [depth].
7557 However, there is a maximum depth of 100 to catch
7558 loops.
7559
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007560 Note that when two variables refer to the same |List|
7561 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007562 locked when used through the other variable.
7563 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007564 :let l = [0, 1, 2, 3]
7565 :let cl = l
7566 :lockvar l
7567 :let cl[1] = 99 " won't work!
7568< You may want to make a copy of a list to avoid this.
7569 See |deepcopy()|.
7570
7571
7572:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
7573 Unlock the internal variable {name}. Does the
7574 opposite of |:lockvar|.
7575
7576
Bram Moolenaar071d4272004-06-13 20:20:40 +00007577:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
7578:en[dif] Execute the commands until the next matching ":else"
7579 or ":endif" if {expr1} evaluates to non-zero.
7580
7581 From Vim version 4.5 until 5.0, every Ex command in
7582 between the ":if" and ":endif" is ignored. These two
7583 commands were just to allow for future expansions in a
7584 backwards compatible way. Nesting was allowed. Note
7585 that any ":else" or ":elseif" was ignored, the "else"
7586 part was not executed either.
7587
7588 You can use this to remain compatible with older
7589 versions: >
7590 :if version >= 500
7591 : version-5-specific-commands
7592 :endif
7593< The commands still need to be parsed to find the
7594 "endif". Sometimes an older Vim has a problem with a
7595 new command. For example, ":silent" is recognized as
7596 a ":substitute" command. In that case ":execute" can
7597 avoid problems: >
7598 :if version >= 600
7599 : execute "silent 1,$delete"
7600 :endif
7601<
7602 NOTE: The ":append" and ":insert" commands don't work
7603 properly in between ":if" and ":endif".
7604
7605 *:else* *:el* *E581* *E583*
7606:el[se] Execute the commands until the next matching ":else"
7607 or ":endif" if they previously were not being
7608 executed.
7609
7610 *:elseif* *:elsei* *E582* *E584*
7611:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
7612 is no extra ":endif".
7613
7614:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007615 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007616:endw[hile] Repeat the commands between ":while" and ":endwhile",
7617 as long as {expr1} evaluates to non-zero.
7618 When an error is detected from a command inside the
7619 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00007620 Example: >
7621 :let lnum = 1
7622 :while lnum <= line("$")
7623 :call FixLine(lnum)
7624 :let lnum = lnum + 1
7625 :endwhile
7626<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007627 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00007628 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007629
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007630:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00007631:endfo[r] *:endfo* *:endfor*
7632 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007633 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007634 value of each item.
7635 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00007636 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00007637 Changing {list} inside the loop affects what items are
7638 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007639 :for item in copy(mylist)
7640< When not making a copy, Vim stores a reference to the
7641 next item in the list, before executing the commands
Bram Moolenaar446cb832008-06-24 21:56:24 +00007642 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007643 removed without effect. Removing any later item means
7644 it will not be found. Thus the following example
7645 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007646 for item in mylist
7647 call remove(mylist, 0)
7648 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007649< Note that reordering the list (e.g., with sort() or
7650 reverse()) may have unexpected effects.
7651 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00007652 identical to avoid errors for the type of {var}
7653 changing. Unlet the variable at the end of the loop
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007654 to allow multiple item types: >
7655 for item in ["foo", ["bar"]]
7656 echo item
7657 unlet item " E706 without this
7658 endfor
Bram Moolenaar12805862005-01-05 22:16:17 +00007659
Bram Moolenaar12805862005-01-05 22:16:17 +00007660:for [{var1}, {var2}, ...] in {listlist}
7661:endfo[r]
7662 Like ":for" above, but each item in {listlist} must be
7663 a list, of which each item is assigned to {var1},
7664 {var2}, etc. Example: >
7665 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
7666 :echo getline(lnum)[col]
7667 :endfor
7668<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007669 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00007670:con[tinue] When used inside a ":while" or ":for" loop, jumps back
7671 to the start of the loop.
7672 If it is used after a |:try| inside the loop but
7673 before the matching |:finally| (if present), the
7674 commands following the ":finally" up to the matching
7675 |:endtry| are executed first. This process applies to
7676 all nested ":try"s inside the loop. The outermost
7677 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007678
7679 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00007680:brea[k] When used inside a ":while" or ":for" loop, skips to
7681 the command after the matching ":endwhile" or
7682 ":endfor".
7683 If it is used after a |:try| inside the loop but
7684 before the matching |:finally| (if present), the
7685 commands following the ":finally" up to the matching
7686 |:endtry| are executed first. This process applies to
7687 all nested ":try"s inside the loop. The outermost
7688 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007689
7690:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
7691:endt[ry] Change the error handling for the commands between
7692 ":try" and ":endtry" including everything being
7693 executed across ":source" commands, function calls,
7694 or autocommand invocations.
7695
7696 When an error or interrupt is detected and there is
7697 a |:finally| command following, execution continues
7698 after the ":finally". Otherwise, or when the
7699 ":endtry" is reached thereafter, the next
7700 (dynamically) surrounding ":try" is checked for
7701 a corresponding ":finally" etc. Then the script
7702 processing is terminated. (Whether a function
7703 definition has an "abort" argument does not matter.)
7704 Example: >
7705 :try | edit too much | finally | echo "cleanup" | endtry
7706 :echo "impossible" " not reached, script terminated above
7707<
7708 Moreover, an error or interrupt (dynamically) inside
7709 ":try" and ":endtry" is converted to an exception. It
7710 can be caught as if it were thrown by a |:throw|
7711 command (see |:catch|). In this case, the script
7712 processing is not terminated.
7713
7714 The value "Vim:Interrupt" is used for an interrupt
7715 exception. An error in a Vim command is converted
7716 to a value of the form "Vim({command}):{errmsg}",
7717 other errors are converted to a value of the form
7718 "Vim:{errmsg}". {command} is the full command name,
7719 and {errmsg} is the message that is displayed if the
7720 error exception is not caught, always beginning with
7721 the error number.
7722 Examples: >
7723 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
7724 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
7725<
7726 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007727:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007728 |:finally|, or |:endtry| that belongs to the same
7729 |:try| as the ":catch" are executed when an exception
7730 matching {pattern} is being thrown and has not yet
7731 been caught by a previous ":catch". Otherwise, these
7732 commands are skipped.
7733 When {pattern} is omitted all errors are caught.
7734 Examples: >
7735 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
7736 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
7737 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
7738 :catch /^Vim(write):/ " catch all errors in :write
7739 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
7740 :catch /my-exception/ " catch user exception
7741 :catch /.*/ " catch everything
7742 :catch " same as /.*/
7743<
7744 Another character can be used instead of / around the
7745 {pattern}, so long as it does not have a special
7746 meaning (e.g., '|' or '"') and doesn't occur inside
7747 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007748 Information about the exception is available in
7749 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007750 NOTE: It is not reliable to ":catch" the TEXT of
7751 an error message because it may vary in different
7752 locales.
7753
7754 *:fina* *:finally* *E606* *E607*
7755:fina[lly] The following commands until the matching |:endtry|
7756 are executed whenever the part between the matching
7757 |:try| and the ":finally" is left: either by falling
7758 through to the ":finally" or by a |:continue|,
7759 |:break|, |:finish|, or |:return|, or by an error or
7760 interrupt or exception (see |:throw|).
7761
7762 *:th* *:throw* *E608*
7763:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
7764 If the ":throw" is used after a |:try| but before the
7765 first corresponding |:catch|, commands are skipped
7766 until the first ":catch" matching {expr1} is reached.
7767 If there is no such ":catch" or if the ":throw" is
7768 used after a ":catch" but before the |:finally|, the
7769 commands following the ":finally" (if present) up to
7770 the matching |:endtry| are executed. If the ":throw"
7771 is after the ":finally", commands up to the ":endtry"
7772 are skipped. At the ":endtry", this process applies
7773 again for the next dynamically surrounding ":try"
7774 (which may be found in a calling function or sourcing
7775 script), until a matching ":catch" has been found.
7776 If the exception is not caught, the command processing
7777 is terminated.
7778 Example: >
7779 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01007780< Note that "catch" may need to be on a separate line
7781 for when an error causes the parsing to skip the whole
7782 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007783
7784 *:ec* *:echo*
7785:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
7786 first {expr1} starts on a new line.
7787 Also see |:comment|.
7788 Use "\n" to start a new line. Use "\r" to move the
7789 cursor to the first column.
7790 Uses the highlighting set by the |:echohl| command.
7791 Cannot be followed by a comment.
7792 Example: >
7793 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007794< *:echo-redraw*
7795 A later redraw may make the message disappear again.
7796 And since Vim mostly postpones redrawing until it's
7797 finished with a sequence of commands this happens
7798 quite often. To avoid that a command from before the
7799 ":echo" causes a redraw afterwards (redraws are often
7800 postponed until you type something), force a redraw
7801 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007802 :new | redraw | echo "there is a new window"
7803<
7804 *:echon*
7805:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
7806 |:comment|.
7807 Uses the highlighting set by the |:echohl| command.
7808 Cannot be followed by a comment.
7809 Example: >
7810 :echon "the value of 'shell' is " &shell
7811<
7812 Note the difference between using ":echo", which is a
7813 Vim command, and ":!echo", which is an external shell
7814 command: >
7815 :!echo % --> filename
7816< The arguments of ":!" are expanded, see |:_%|. >
7817 :!echo "%" --> filename or "filename"
7818< Like the previous example. Whether you see the double
7819 quotes or not depends on your 'shell'. >
7820 :echo % --> nothing
7821< The '%' is an illegal character in an expression. >
7822 :echo "%" --> %
7823< This just echoes the '%' character. >
7824 :echo expand("%") --> filename
7825< This calls the expand() function to expand the '%'.
7826
7827 *:echoh* *:echohl*
7828:echoh[l] {name} Use the highlight group {name} for the following
7829 |:echo|, |:echon| and |:echomsg| commands. Also used
7830 for the |input()| prompt. Example: >
7831 :echohl WarningMsg | echo "Don't panic!" | echohl None
7832< Don't forget to set the group back to "None",
7833 otherwise all following echo's will be highlighted.
7834
7835 *:echom* *:echomsg*
7836:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
7837 message in the |message-history|.
7838 Spaces are placed between the arguments as with the
7839 |:echo| command. But unprintable characters are
7840 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007841 The parsing works slightly different from |:echo|,
7842 more like |:execute|. All the expressions are first
7843 evaluated and concatenated before echoing anything.
7844 The expressions must evaluate to a Number or String, a
7845 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007846 Uses the highlighting set by the |:echohl| command.
7847 Example: >
7848 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007849< See |:echo-redraw| to avoid the message disappearing
7850 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007851 *:echoe* *:echoerr*
7852:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
7853 message in the |message-history|. When used in a
7854 script or function the line number will be added.
7855 Spaces are placed between the arguments as with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007856 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007857 the message is raised as an error exception instead
7858 (see |try-echoerr|).
7859 Example: >
7860 :echoerr "This script just failed!"
7861< If you just want a highlighted message use |:echohl|.
7862 And to get a beep: >
7863 :exe "normal \<Esc>"
7864<
7865 *:exe* *:execute*
7866:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007867 of {expr1} as an Ex command.
7868 Multiple arguments are concatenated, with a space in
7869 between. To avoid the extra space use the "."
7870 operator to concatenate strings into one argument.
7871 {expr1} is used as the processed command, command line
7872 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007873 Cannot be followed by a comment.
7874 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007875 :execute "buffer" nextbuf
7876 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007877<
7878 ":execute" can be used to append a command to commands
7879 that don't accept a '|'. Example: >
7880 :execute '!ls' | echo "theend"
7881
7882< ":execute" is also a nice way to avoid having to type
7883 control characters in a Vim script for a ":normal"
7884 command: >
7885 :execute "normal ixxx\<Esc>"
7886< This has an <Esc> character, see |expr-string|.
7887
Bram Moolenaar446cb832008-06-24 21:56:24 +00007888 Be careful to correctly escape special characters in
7889 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007890 for Vim commands, |shellescape()| for |:!| commands.
7891 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00007892 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +01007893 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00007894<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007895 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007896 starting or ending "if", "while" and "for" does not
7897 always work, because when commands are skipped the
7898 ":execute" is not evaluated and Vim loses track of
7899 where blocks start and end. Also "break" and
7900 "continue" should not be inside ":execute".
7901 This example does not work, because the ":execute" is
7902 not evaluated and Vim does not see the "while", and
7903 gives an error for finding an ":endwhile": >
7904 :if 0
7905 : execute 'while i > 5'
7906 : echo "test"
7907 : endwhile
7908 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00007909<
7910 It is allowed to have a "while" or "if" command
7911 completely in the executed string: >
7912 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
7913<
7914
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007915 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007916 ":execute", ":echo" and ":echon" cannot be followed by
7917 a comment directly, because they see the '"' as the
7918 start of a string. But, you can use '|' followed by a
7919 comment. Example: >
7920 :echo "foo" | "this is a comment
7921
7922==============================================================================
79238. Exception handling *exception-handling*
7924
7925The Vim script language comprises an exception handling feature. This section
7926explains how it can be used in a Vim script.
7927
7928Exceptions may be raised by Vim on an error or on interrupt, see
7929|catch-errors| and |catch-interrupt|. You can also explicitly throw an
7930exception by using the ":throw" command, see |throw-catch|.
7931
7932
7933TRY CONDITIONALS *try-conditionals*
7934
7935Exceptions can be caught or can cause cleanup code to be executed. You can
7936use a try conditional to specify catch clauses (that catch exceptions) and/or
7937a finally clause (to be executed for cleanup).
7938 A try conditional begins with a |:try| command and ends at the matching
7939|:endtry| command. In between, you can use a |:catch| command to start
7940a catch clause, or a |:finally| command to start a finally clause. There may
7941be none or multiple catch clauses, but there is at most one finally clause,
7942which must not be followed by any catch clauses. The lines before the catch
7943clauses and the finally clause is called a try block. >
7944
7945 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00007946 : ...
7947 : ... TRY BLOCK
7948 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007949 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00007950 : ...
7951 : ... CATCH CLAUSE
7952 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007953 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00007954 : ...
7955 : ... CATCH CLAUSE
7956 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007957 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00007958 : ...
7959 : ... FINALLY CLAUSE
7960 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007961 :endtry
7962
7963The try conditional allows to watch code for exceptions and to take the
7964appropriate actions. Exceptions from the try block may be caught. Exceptions
7965from the try block and also the catch clauses may cause cleanup actions.
7966 When no exception is thrown during execution of the try block, the control
7967is transferred to the finally clause, if present. After its execution, the
7968script continues with the line following the ":endtry".
7969 When an exception occurs during execution of the try block, the remaining
7970lines in the try block are skipped. The exception is matched against the
7971patterns specified as arguments to the ":catch" commands. The catch clause
7972after the first matching ":catch" is taken, other catch clauses are not
7973executed. The catch clause ends when the next ":catch", ":finally", or
7974":endtry" command is reached - whatever is first. Then, the finally clause
7975(if present) is executed. When the ":endtry" is reached, the script execution
7976continues in the following line as usual.
7977 When an exception that does not match any of the patterns specified by the
7978":catch" commands is thrown in the try block, the exception is not caught by
7979that try conditional and none of the catch clauses is executed. Only the
7980finally clause, if present, is taken. The exception pends during execution of
7981the finally clause. It is resumed at the ":endtry", so that commands after
7982the ":endtry" are not executed and the exception might be caught elsewhere,
7983see |try-nesting|.
7984 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007985remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00007986not matched against the patterns in any of the ":catch" commands of the same
7987try conditional and none of its catch clauses is taken. If there is, however,
7988a finally clause, it is executed, and the exception pends during its
7989execution. The commands following the ":endtry" are not executed. The new
7990exception might, however, be caught elsewhere, see |try-nesting|.
7991 When during execution of the finally clause (if present) an exception is
Bram Moolenaar446cb832008-06-24 21:56:24 +00007992thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00007993clause has been taken because of an exception from the try block or one of the
7994catch clauses, the original (pending) exception is discarded. The commands
7995following the ":endtry" are not executed, and the exception from the finally
7996clause is propagated and can be caught elsewhere, see |try-nesting|.
7997
7998The finally clause is also executed, when a ":break" or ":continue" for
7999a ":while" loop enclosing the complete try conditional is executed from the
8000try block or a catch clause. Or when a ":return" or ":finish" is executed
8001from the try block or a catch clause of a try conditional in a function or
8002sourced script, respectively. The ":break", ":continue", ":return", or
8003":finish" pends during execution of the finally clause and is resumed when the
8004":endtry" is reached. It is, however, discarded when an exception is thrown
8005from the finally clause.
8006 When a ":break" or ":continue" for a ":while" loop enclosing the complete
8007try conditional or when a ":return" or ":finish" is encountered in the finally
8008clause, the rest of the finally clause is skipped, and the ":break",
8009":continue", ":return" or ":finish" is executed as usual. If the finally
8010clause has been taken because of an exception or an earlier ":break",
8011":continue", ":return", or ":finish" from the try block or a catch clause,
8012this pending exception or command is discarded.
8013
8014For examples see |throw-catch| and |try-finally|.
8015
8016
8017NESTING OF TRY CONDITIONALS *try-nesting*
8018
8019Try conditionals can be nested arbitrarily. That is, a complete try
8020conditional can be put into the try block, a catch clause, or the finally
8021clause of another try conditional. If the inner try conditional does not
8022catch an exception thrown in its try block or throws a new exception from one
8023of its catch clauses or its finally clause, the outer try conditional is
8024checked according to the rules above. If the inner try conditional is in the
8025try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar446cb832008-06-24 21:56:24 +00008026otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00008027nesting, whether the inner try conditional is directly contained in the outer
8028one, or whether the outer one sources a script or calls a function containing
8029the inner try conditional.
8030
8031When none of the active try conditionals catches an exception, just their
8032finally clauses are executed. Thereafter, the script processing terminates.
8033An error message is displayed in case of an uncaught exception explicitly
8034thrown by a ":throw" command. For uncaught error and interrupt exceptions
8035implicitly raised by Vim, the error message(s) or interrupt message are shown
8036as usual.
8037
8038For examples see |throw-catch|.
8039
8040
8041EXAMINING EXCEPTION HANDLING CODE *except-examine*
8042
8043Exception handling code can get tricky. If you are in doubt what happens, set
8044'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
8045script file. Then you see when an exception is thrown, discarded, caught, or
8046finished. When using a verbosity level of at least 14, things pending in
8047a finally clause are also shown. This information is also given in debug mode
8048(see |debug-scripts|).
8049
8050
8051THROWING AND CATCHING EXCEPTIONS *throw-catch*
8052
8053You can throw any number or string as an exception. Use the |:throw| command
8054and pass the value to be thrown as argument: >
8055 :throw 4711
8056 :throw "string"
8057< *throw-expression*
8058You can also specify an expression argument. The expression is then evaluated
8059first, and the result is thrown: >
8060 :throw 4705 + strlen("string")
8061 :throw strpart("strings", 0, 6)
8062
8063An exception might be thrown during evaluation of the argument of the ":throw"
8064command. Unless it is caught there, the expression evaluation is abandoned.
8065The ":throw" command then does not throw a new exception.
8066 Example: >
8067
8068 :function! Foo(arg)
8069 : try
8070 : throw a:arg
8071 : catch /foo/
8072 : endtry
8073 : return 1
8074 :endfunction
8075 :
8076 :function! Bar()
8077 : echo "in Bar"
8078 : return 4710
8079 :endfunction
8080 :
8081 :throw Foo("arrgh") + Bar()
8082
8083This throws "arrgh", and "in Bar" is not displayed since Bar() is not
8084executed. >
8085 :throw Foo("foo") + Bar()
8086however displays "in Bar" and throws 4711.
8087
8088Any other command that takes an expression as argument might also be
Bram Moolenaar446cb832008-06-24 21:56:24 +00008089abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008090exception is then propagated to the caller of the command.
8091 Example: >
8092
8093 :if Foo("arrgh")
8094 : echo "then"
8095 :else
8096 : echo "else"
8097 :endif
8098
8099Here neither of "then" or "else" is displayed.
8100
8101 *catch-order*
8102Exceptions can be caught by a try conditional with one or more |:catch|
8103commands, see |try-conditionals|. The values to be caught by each ":catch"
8104command can be specified as a pattern argument. The subsequent catch clause
8105gets executed when a matching exception is caught.
8106 Example: >
8107
8108 :function! Foo(value)
8109 : try
8110 : throw a:value
8111 : catch /^\d\+$/
8112 : echo "Number thrown"
8113 : catch /.*/
8114 : echo "String thrown"
8115 : endtry
8116 :endfunction
8117 :
8118 :call Foo(0x1267)
8119 :call Foo('string')
8120
8121The first call to Foo() displays "Number thrown", the second "String thrown".
8122An exception is matched against the ":catch" commands in the order they are
8123specified. Only the first match counts. So you should place the more
8124specific ":catch" first. The following order does not make sense: >
8125
8126 : catch /.*/
8127 : echo "String thrown"
8128 : catch /^\d\+$/
8129 : echo "Number thrown"
8130
8131The first ":catch" here matches always, so that the second catch clause is
8132never taken.
8133
8134 *throw-variables*
8135If you catch an exception by a general pattern, you may access the exact value
8136in the variable |v:exception|: >
8137
8138 : catch /^\d\+$/
8139 : echo "Number thrown. Value is" v:exception
8140
8141You may also be interested where an exception was thrown. This is stored in
8142|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
8143exception most recently caught as long it is not finished.
8144 Example: >
8145
8146 :function! Caught()
8147 : if v:exception != ""
8148 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
8149 : else
8150 : echo 'Nothing caught'
8151 : endif
8152 :endfunction
8153 :
8154 :function! Foo()
8155 : try
8156 : try
8157 : try
8158 : throw 4711
8159 : finally
8160 : call Caught()
8161 : endtry
8162 : catch /.*/
8163 : call Caught()
8164 : throw "oops"
8165 : endtry
8166 : catch /.*/
8167 : call Caught()
8168 : finally
8169 : call Caught()
8170 : endtry
8171 :endfunction
8172 :
8173 :call Foo()
8174
8175This displays >
8176
8177 Nothing caught
8178 Caught "4711" in function Foo, line 4
8179 Caught "oops" in function Foo, line 10
8180 Nothing caught
8181
8182A practical example: The following command ":LineNumber" displays the line
8183number in the script or function where it has been used: >
8184
8185 :function! LineNumber()
8186 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
8187 :endfunction
8188 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
8189<
8190 *try-nested*
8191An exception that is not caught by a try conditional can be caught by
8192a surrounding try conditional: >
8193
8194 :try
8195 : try
8196 : throw "foo"
8197 : catch /foobar/
8198 : echo "foobar"
8199 : finally
8200 : echo "inner finally"
8201 : endtry
8202 :catch /foo/
8203 : echo "foo"
8204 :endtry
8205
8206The inner try conditional does not catch the exception, just its finally
8207clause is executed. The exception is then caught by the outer try
8208conditional. The example displays "inner finally" and then "foo".
8209
8210 *throw-from-catch*
8211You can catch an exception and throw a new one to be caught elsewhere from the
8212catch clause: >
8213
8214 :function! Foo()
8215 : throw "foo"
8216 :endfunction
8217 :
8218 :function! Bar()
8219 : try
8220 : call Foo()
8221 : catch /foo/
8222 : echo "Caught foo, throw bar"
8223 : throw "bar"
8224 : endtry
8225 :endfunction
8226 :
8227 :try
8228 : call Bar()
8229 :catch /.*/
8230 : echo "Caught" v:exception
8231 :endtry
8232
8233This displays "Caught foo, throw bar" and then "Caught bar".
8234
8235 *rethrow*
8236There is no real rethrow in the Vim script language, but you may throw
8237"v:exception" instead: >
8238
8239 :function! Bar()
8240 : try
8241 : call Foo()
8242 : catch /.*/
8243 : echo "Rethrow" v:exception
8244 : throw v:exception
8245 : endtry
8246 :endfunction
8247< *try-echoerr*
8248Note that this method cannot be used to "rethrow" Vim error or interrupt
8249exceptions, because it is not possible to fake Vim internal exceptions.
8250Trying so causes an error exception. You should throw your own exception
8251denoting the situation. If you want to cause a Vim error exception containing
8252the original error exception value, you can use the |:echoerr| command: >
8253
8254 :try
8255 : try
8256 : asdf
8257 : catch /.*/
8258 : echoerr v:exception
8259 : endtry
8260 :catch /.*/
8261 : echo v:exception
8262 :endtry
8263
8264This code displays
8265
Bram Moolenaar446cb832008-06-24 21:56:24 +00008266 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008267
8268
8269CLEANUP CODE *try-finally*
8270
8271Scripts often change global settings and restore them at their end. If the
8272user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar446cb832008-06-24 21:56:24 +00008273an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00008274a script when an error occurs or you explicitly throw an exception without
8275catching it. You can solve these problems by using a try conditional with
8276a finally clause for restoring the settings. Its execution is guaranteed on
8277normal control flow, on error, on an explicit ":throw", and on interrupt.
8278(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar446cb832008-06-24 21:56:24 +00008279to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00008280clause has been executed.)
8281Example: >
8282
8283 :try
8284 : let s:saved_ts = &ts
8285 : set ts=17
8286 :
8287 : " Do the hard work here.
8288 :
8289 :finally
8290 : let &ts = s:saved_ts
8291 : unlet s:saved_ts
8292 :endtry
8293
8294This method should be used locally whenever a function or part of a script
8295changes global settings which need to be restored on failure or normal exit of
8296that function or script part.
8297
8298 *break-finally*
8299Cleanup code works also when the try block or a catch clause is left by
8300a ":continue", ":break", ":return", or ":finish".
8301 Example: >
8302
8303 :let first = 1
8304 :while 1
8305 : try
8306 : if first
8307 : echo "first"
8308 : let first = 0
8309 : continue
8310 : else
8311 : throw "second"
8312 : endif
8313 : catch /.*/
8314 : echo v:exception
8315 : break
8316 : finally
8317 : echo "cleanup"
8318 : endtry
8319 : echo "still in while"
8320 :endwhile
8321 :echo "end"
8322
8323This displays "first", "cleanup", "second", "cleanup", and "end". >
8324
8325 :function! Foo()
8326 : try
8327 : return 4711
8328 : finally
8329 : echo "cleanup\n"
8330 : endtry
8331 : echo "Foo still active"
8332 :endfunction
8333 :
8334 :echo Foo() "returned by Foo"
8335
8336This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar446cb832008-06-24 21:56:24 +00008337extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00008338return value.)
8339
8340 *except-from-finally*
8341Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
8342a finally clause is possible, but not recommended since it abandons the
8343cleanup actions for the try conditional. But, of course, interrupt and error
8344exceptions might get raised from a finally clause.
8345 Example where an error in the finally clause stops an interrupt from
8346working correctly: >
8347
8348 :try
8349 : try
8350 : echo "Press CTRL-C for interrupt"
8351 : while 1
8352 : endwhile
8353 : finally
8354 : unlet novar
8355 : endtry
8356 :catch /novar/
8357 :endtry
8358 :echo "Script still running"
8359 :sleep 1
8360
8361If you need to put commands that could fail into a finally clause, you should
8362think about catching or ignoring the errors in these commands, see
8363|catch-errors| and |ignore-errors|.
8364
8365
8366CATCHING ERRORS *catch-errors*
8367
8368If you want to catch specific errors, you just have to put the code to be
8369watched in a try block and add a catch clause for the error message. The
8370presence of the try conditional causes all errors to be converted to an
8371exception. No message is displayed and |v:errmsg| is not set then. To find
8372the right pattern for the ":catch" command, you have to know how the format of
8373the error exception is.
8374 Error exceptions have the following format: >
8375
8376 Vim({cmdname}):{errmsg}
8377or >
8378 Vim:{errmsg}
8379
8380{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar446cb832008-06-24 21:56:24 +00008381the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00008382when the error occurs outside try conditionals. It always begins with
8383a capital "E", followed by a two or three-digit error number, a colon, and
8384a space.
8385
8386Examples:
8387
8388The command >
8389 :unlet novar
8390normally produces the error message >
8391 E108: No such variable: "novar"
8392which is converted inside try conditionals to an exception >
8393 Vim(unlet):E108: No such variable: "novar"
8394
8395The command >
8396 :dwim
8397normally produces the error message >
8398 E492: Not an editor command: dwim
8399which is converted inside try conditionals to an exception >
8400 Vim:E492: Not an editor command: dwim
8401
8402You can catch all ":unlet" errors by a >
8403 :catch /^Vim(unlet):/
8404or all errors for misspelled command names by a >
8405 :catch /^Vim:E492:/
8406
8407Some error messages may be produced by different commands: >
8408 :function nofunc
8409and >
8410 :delfunction nofunc
8411both produce the error message >
8412 E128: Function name must start with a capital: nofunc
8413which is converted inside try conditionals to an exception >
8414 Vim(function):E128: Function name must start with a capital: nofunc
8415or >
8416 Vim(delfunction):E128: Function name must start with a capital: nofunc
8417respectively. You can catch the error by its number independently on the
8418command that caused it if you use the following pattern: >
8419 :catch /^Vim(\a\+):E128:/
8420
8421Some commands like >
8422 :let x = novar
8423produce multiple error messages, here: >
8424 E121: Undefined variable: novar
8425 E15: Invalid expression: novar
8426Only the first is used for the exception value, since it is the most specific
8427one (see |except-several-errors|). So you can catch it by >
8428 :catch /^Vim(\a\+):E121:/
8429
8430You can catch all errors related to the name "nofunc" by >
8431 :catch /\<nofunc\>/
8432
8433You can catch all Vim errors in the ":write" and ":read" commands by >
8434 :catch /^Vim(\(write\|read\)):E\d\+:/
8435
8436You can catch all Vim errors by the pattern >
8437 :catch /^Vim\((\a\+)\)\=:E\d\+:/
8438<
8439 *catch-text*
8440NOTE: You should never catch the error message text itself: >
8441 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01008442only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +00008443a different language by the |:language| command. It is however helpful to
8444cite the message text in a comment: >
8445 :catch /^Vim(\a\+):E108:/ " No such variable
8446
8447
8448IGNORING ERRORS *ignore-errors*
8449
8450You can ignore errors in a specific Vim command by catching them locally: >
8451
8452 :try
8453 : write
8454 :catch
8455 :endtry
8456
8457But you are strongly recommended NOT to use this simple form, since it could
8458catch more than you want. With the ":write" command, some autocommands could
8459be executed and cause errors not related to writing, for instance: >
8460
8461 :au BufWritePre * unlet novar
8462
8463There could even be such errors you are not responsible for as a script
8464writer: a user of your script might have defined such autocommands. You would
8465then hide the error from the user.
8466 It is much better to use >
8467
8468 :try
8469 : write
8470 :catch /^Vim(write):/
8471 :endtry
8472
8473which only catches real write errors. So catch only what you'd like to ignore
8474intentionally.
8475
8476For a single command that does not cause execution of autocommands, you could
8477even suppress the conversion of errors to exceptions by the ":silent!"
8478command: >
8479 :silent! nunmap k
8480This works also when a try conditional is active.
8481
8482
8483CATCHING INTERRUPTS *catch-interrupt*
8484
8485When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar446cb832008-06-24 21:56:24 +00008486the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008487script is not terminated, then.
8488 Example: >
8489
8490 :function! TASK1()
8491 : sleep 10
8492 :endfunction
8493
8494 :function! TASK2()
8495 : sleep 20
8496 :endfunction
8497
8498 :while 1
8499 : let command = input("Type a command: ")
8500 : try
8501 : if command == ""
8502 : continue
8503 : elseif command == "END"
8504 : break
8505 : elseif command == "TASK1"
8506 : call TASK1()
8507 : elseif command == "TASK2"
8508 : call TASK2()
8509 : else
8510 : echo "\nIllegal command:" command
8511 : continue
8512 : endif
8513 : catch /^Vim:Interrupt$/
8514 : echo "\nCommand interrupted"
8515 : " Caught the interrupt. Continue with next prompt.
8516 : endtry
8517 :endwhile
8518
8519You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar446cb832008-06-24 21:56:24 +00008520a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008521
8522For testing what happens when CTRL-C would be pressed on a specific line in
8523your script, use the debug mode and execute the |>quit| or |>interrupt|
8524command on that line. See |debug-scripts|.
8525
8526
8527CATCHING ALL *catch-all*
8528
8529The commands >
8530
8531 :catch /.*/
8532 :catch //
8533 :catch
8534
8535catch everything, error exceptions, interrupt exceptions and exceptions
8536explicitly thrown by the |:throw| command. This is useful at the top level of
8537a script in order to catch unexpected things.
8538 Example: >
8539
8540 :try
8541 :
8542 : " do the hard work here
8543 :
8544 :catch /MyException/
8545 :
8546 : " handle known problem
8547 :
8548 :catch /^Vim:Interrupt$/
8549 : echo "Script interrupted"
8550 :catch /.*/
8551 : echo "Internal error (" . v:exception . ")"
8552 : echo " - occurred at " . v:throwpoint
8553 :endtry
8554 :" end of script
8555
8556Note: Catching all might catch more things than you want. Thus, you are
8557strongly encouraged to catch only for problems that you can really handle by
8558specifying a pattern argument to the ":catch".
8559 Example: Catching all could make it nearly impossible to interrupt a script
8560by pressing CTRL-C: >
8561
8562 :while 1
8563 : try
8564 : sleep 1
8565 : catch
8566 : endtry
8567 :endwhile
8568
8569
8570EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
8571
8572Exceptions may be used during execution of autocommands. Example: >
8573
8574 :autocmd User x try
8575 :autocmd User x throw "Oops!"
8576 :autocmd User x catch
8577 :autocmd User x echo v:exception
8578 :autocmd User x endtry
8579 :autocmd User x throw "Arrgh!"
8580 :autocmd User x echo "Should not be displayed"
8581 :
8582 :try
8583 : doautocmd User x
8584 :catch
8585 : echo v:exception
8586 :endtry
8587
8588This displays "Oops!" and "Arrgh!".
8589
8590 *except-autocmd-Pre*
8591For some commands, autocommands get executed before the main action of the
8592command takes place. If an exception is thrown and not caught in the sequence
8593of autocommands, the sequence and the command that caused its execution are
8594abandoned and the exception is propagated to the caller of the command.
8595 Example: >
8596
8597 :autocmd BufWritePre * throw "FAIL"
8598 :autocmd BufWritePre * echo "Should not be displayed"
8599 :
8600 :try
8601 : write
8602 :catch
8603 : echo "Caught:" v:exception "from" v:throwpoint
8604 :endtry
8605
8606Here, the ":write" command does not write the file currently being edited (as
8607you can see by checking 'modified'), since the exception from the BufWritePre
8608autocommand abandons the ":write". The exception is then caught and the
8609script displays: >
8610
8611 Caught: FAIL from BufWrite Auto commands for "*"
8612<
8613 *except-autocmd-Post*
8614For some commands, autocommands get executed after the main action of the
8615command has taken place. If this main action fails and the command is inside
8616an active try conditional, the autocommands are skipped and an error exception
8617is thrown that can be caught by the caller of the command.
8618 Example: >
8619
8620 :autocmd BufWritePost * echo "File successfully written!"
8621 :
8622 :try
8623 : write /i/m/p/o/s/s/i/b/l/e
8624 :catch
8625 : echo v:exception
8626 :endtry
8627
8628This just displays: >
8629
8630 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
8631
8632If you really need to execute the autocommands even when the main action
8633fails, trigger the event from the catch clause.
8634 Example: >
8635
8636 :autocmd BufWritePre * set noreadonly
8637 :autocmd BufWritePost * set readonly
8638 :
8639 :try
8640 : write /i/m/p/o/s/s/i/b/l/e
8641 :catch
8642 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
8643 :endtry
8644<
8645You can also use ":silent!": >
8646
8647 :let x = "ok"
8648 :let v:errmsg = ""
8649 :autocmd BufWritePost * if v:errmsg != ""
8650 :autocmd BufWritePost * let x = "after fail"
8651 :autocmd BufWritePost * endif
8652 :try
8653 : silent! write /i/m/p/o/s/s/i/b/l/e
8654 :catch
8655 :endtry
8656 :echo x
8657
8658This displays "after fail".
8659
8660If the main action of the command does not fail, exceptions from the
8661autocommands will be catchable by the caller of the command: >
8662
8663 :autocmd BufWritePost * throw ":-("
8664 :autocmd BufWritePost * echo "Should not be displayed"
8665 :
8666 :try
8667 : write
8668 :catch
8669 : echo v:exception
8670 :endtry
8671<
8672 *except-autocmd-Cmd*
8673For some commands, the normal action can be replaced by a sequence of
8674autocommands. Exceptions from that sequence will be catchable by the caller
8675of the command.
8676 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar446cb832008-06-24 21:56:24 +00008677had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00008678some way. >
8679
8680 :if !exists("cnt")
8681 : let cnt = 0
8682 :
8683 : autocmd BufWriteCmd * if &modified
8684 : autocmd BufWriteCmd * let cnt = cnt + 1
8685 : autocmd BufWriteCmd * if cnt % 3 == 2
8686 : autocmd BufWriteCmd * throw "BufWriteCmdError"
8687 : autocmd BufWriteCmd * endif
8688 : autocmd BufWriteCmd * write | set nomodified
8689 : autocmd BufWriteCmd * if cnt % 3 == 0
8690 : autocmd BufWriteCmd * throw "BufWriteCmdError"
8691 : autocmd BufWriteCmd * endif
8692 : autocmd BufWriteCmd * echo "File successfully written!"
8693 : autocmd BufWriteCmd * endif
8694 :endif
8695 :
8696 :try
8697 : write
8698 :catch /^BufWriteCmdError$/
8699 : if &modified
8700 : echo "Error on writing (file contents not changed)"
8701 : else
8702 : echo "Error after writing"
8703 : endif
8704 :catch /^Vim(write):/
8705 : echo "Error on writing"
8706 :endtry
8707
8708When this script is sourced several times after making changes, it displays
8709first >
8710 File successfully written!
8711then >
8712 Error on writing (file contents not changed)
8713then >
8714 Error after writing
8715etc.
8716
8717 *except-autocmd-ill*
8718You cannot spread a try conditional over autocommands for different events.
8719The following code is ill-formed: >
8720
8721 :autocmd BufWritePre * try
8722 :
8723 :autocmd BufWritePost * catch
8724 :autocmd BufWritePost * echo v:exception
8725 :autocmd BufWritePost * endtry
8726 :
8727 :write
8728
8729
8730EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
8731
8732Some programming languages allow to use hierarchies of exception classes or to
8733pass additional information with the object of an exception class. You can do
8734similar things in Vim.
8735 In order to throw an exception from a hierarchy, just throw the complete
8736class name with the components separated by a colon, for instance throw the
8737string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
8738 When you want to pass additional information with your exception class, add
8739it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
8740for an error when writing "myfile".
8741 With the appropriate patterns in the ":catch" command, you can catch for
8742base classes or derived classes of your hierarchy. Additional information in
8743parentheses can be cut out from |v:exception| with the ":substitute" command.
8744 Example: >
8745
8746 :function! CheckRange(a, func)
8747 : if a:a < 0
8748 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
8749 : endif
8750 :endfunction
8751 :
8752 :function! Add(a, b)
8753 : call CheckRange(a:a, "Add")
8754 : call CheckRange(a:b, "Add")
8755 : let c = a:a + a:b
8756 : if c < 0
8757 : throw "EXCEPT:MATHERR:OVERFLOW"
8758 : endif
8759 : return c
8760 :endfunction
8761 :
8762 :function! Div(a, b)
8763 : call CheckRange(a:a, "Div")
8764 : call CheckRange(a:b, "Div")
8765 : if (a:b == 0)
8766 : throw "EXCEPT:MATHERR:ZERODIV"
8767 : endif
8768 : return a:a / a:b
8769 :endfunction
8770 :
8771 :function! Write(file)
8772 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008773 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008774 : catch /^Vim(write):/
8775 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
8776 : endtry
8777 :endfunction
8778 :
8779 :try
8780 :
8781 : " something with arithmetics and I/O
8782 :
8783 :catch /^EXCEPT:MATHERR:RANGE/
8784 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
8785 : echo "Range error in" function
8786 :
8787 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
8788 : echo "Math error"
8789 :
8790 :catch /^EXCEPT:IO/
8791 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
8792 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
8793 : if file !~ '^/'
8794 : let file = dir . "/" . file
8795 : endif
8796 : echo 'I/O error for "' . file . '"'
8797 :
8798 :catch /^EXCEPT/
8799 : echo "Unspecified error"
8800 :
8801 :endtry
8802
8803The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
8804a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
8805exceptions with the "Vim" prefix; they are reserved for Vim.
8806 Vim error exceptions are parameterized with the name of the command that
8807failed, if known. See |catch-errors|.
8808
8809
8810PECULIARITIES
8811 *except-compat*
8812The exception handling concept requires that the command sequence causing the
8813exception is aborted immediately and control is transferred to finally clauses
8814and/or a catch clause.
8815
8816In the Vim script language there are cases where scripts and functions
8817continue after an error: in functions without the "abort" flag or in a command
8818after ":silent!", control flow goes to the following line, and outside
8819functions, control flow goes to the line following the outermost ":endwhile"
8820or ":endif". On the other hand, errors should be catchable as exceptions
8821(thus, requiring the immediate abortion).
8822
8823This problem has been solved by converting errors to exceptions and using
8824immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008825conditional is active. This is no restriction since an (error) exception can
8826be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00008827termination without catching the error, just use a try conditional without
8828catch clause. (You can cause cleanup code being executed before termination
8829by specifying a finally clause.)
8830
8831When no try conditional is active, the usual abortion and continuation
8832behavior is used instead of immediate abortion. This ensures compatibility of
8833scripts written for Vim 6.1 and earlier.
8834
8835However, when sourcing an existing script that does not use exception handling
8836commands (or when calling one of its functions) from inside an active try
8837conditional of a new script, you might change the control flow of the existing
8838script on error. You get the immediate abortion on error and can catch the
8839error in the new script. If however the sourced script suppresses error
8840messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar446cb832008-06-24 21:56:24 +00008841|v:errmsg| if appropriate), its execution path is not changed. The error is
8842not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00008843where this happens is for scripts that don't care about errors and produce
8844error messages. You probably won't want to use such code from your new
8845scripts.
8846
8847 *except-syntax-err*
8848Syntax errors in the exception handling commands are never caught by any of
8849the ":catch" commands of the try conditional they belong to. Its finally
8850clauses, however, is executed.
8851 Example: >
8852
8853 :try
8854 : try
8855 : throw 4711
8856 : catch /\(/
8857 : echo "in catch with syntax error"
8858 : catch
8859 : echo "inner catch-all"
8860 : finally
8861 : echo "inner finally"
8862 : endtry
8863 :catch
8864 : echo 'outer catch-all caught "' . v:exception . '"'
8865 : finally
8866 : echo "outer finally"
8867 :endtry
8868
8869This displays: >
8870 inner finally
8871 outer catch-all caught "Vim(catch):E54: Unmatched \("
8872 outer finally
8873The original exception is discarded and an error exception is raised, instead.
8874
8875 *except-single-line*
8876The ":try", ":catch", ":finally", and ":endtry" commands can be put on
8877a single line, but then syntax errors may make it difficult to recognize the
8878"catch" line, thus you better avoid this.
8879 Example: >
8880 :try | unlet! foo # | catch | endtry
8881raises an error exception for the trailing characters after the ":unlet!"
8882argument, but does not see the ":catch" and ":endtry" commands, so that the
8883error exception is discarded and the "E488: Trailing characters" message gets
8884displayed.
8885
8886 *except-several-errors*
8887When several errors appear in a single command, the first error message is
8888usually the most specific one and therefor converted to the error exception.
8889 Example: >
8890 echo novar
8891causes >
8892 E121: Undefined variable: novar
8893 E15: Invalid expression: novar
8894The value of the error exception inside try conditionals is: >
8895 Vim(echo):E121: Undefined variable: novar
8896< *except-syntax-error*
8897But when a syntax error is detected after a normal error in the same command,
8898the syntax error is used for the exception being thrown.
8899 Example: >
8900 unlet novar #
8901causes >
8902 E108: No such variable: "novar"
8903 E488: Trailing characters
8904The value of the error exception inside try conditionals is: >
8905 Vim(unlet):E488: Trailing characters
8906This is done because the syntax error might change the execution path in a way
8907not intended by the user. Example: >
8908 try
8909 try | unlet novar # | catch | echo v:exception | endtry
8910 catch /.*/
8911 echo "outer catch:" v:exception
8912 endtry
8913This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
8914a "E600: Missing :endtry" error message is given, see |except-single-line|.
8915
8916==============================================================================
89179. Examples *eval-examples*
8918
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008919Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008920>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008921 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008922 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008923 : let n = a:nr
8924 : let r = ""
8925 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008926 : let r = '01'[n % 2] . r
8927 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00008928 : endwhile
8929 : return r
8930 :endfunc
8931
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008932 :" The function String2Bin() converts each character in a string to a
8933 :" binary string, separated with dashes.
8934 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008935 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008936 : for ix in range(strlen(a:str))
8937 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
8938 : endfor
8939 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00008940 :endfunc
8941
8942Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008943 :echo Nr2Bin(32)
8944result: "100000" >
8945 :echo String2Bin("32")
8946result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008947
8948
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008949Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008950
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008951This example sorts lines with a specific compare function. >
8952
8953 :func SortBuffer()
8954 : let lines = getline(1, '$')
8955 : call sort(lines, function("Strcmp"))
8956 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008957 :endfunction
8958
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008959As a one-liner: >
8960 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00008961
Bram Moolenaar071d4272004-06-13 20:20:40 +00008962
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008963scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008964 *sscanf*
8965There is no sscanf() function in Vim. If you need to extract parts from a
8966line, you can use matchstr() and substitute() to do it. This example shows
8967how to get the file name, line number and column number out of a line like
8968"foobar.txt, 123, 45". >
8969 :" Set up the match bit
8970 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
8971 :"get the part matching the whole expression
8972 :let l = matchstr(line, mx)
8973 :"get each item out of the match
8974 :let file = substitute(l, mx, '\1', '')
8975 :let lnum = substitute(l, mx, '\2', '')
8976 :let col = substitute(l, mx, '\3', '')
8977
8978The input is in the variable "line", the results in the variables "file",
8979"lnum" and "col". (idea from Michael Geddes)
8980
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008981
8982getting the scriptnames in a Dictionary ~
8983 *scriptnames-dictionary*
8984The |:scriptnames| command can be used to get a list of all script files that
8985have been sourced. There is no equivalent function or variable for this
8986(because it's rarely needed). In case you need to manipulate the list this
8987code can be used: >
8988 " Get the output of ":scriptnames" in the scriptnames_output variable.
8989 let scriptnames_output = ''
8990 redir => scriptnames_output
8991 silent scriptnames
8992 redir END
8993
Bram Moolenaar446cb832008-06-24 21:56:24 +00008994 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008995 " "scripts" dictionary.
8996 let scripts = {}
8997 for line in split(scriptnames_output, "\n")
8998 " Only do non-blank lines.
8999 if line =~ '\S'
9000 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009001 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009002 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00009003 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009004 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00009005 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009006 endif
9007 endfor
9008 unlet scriptnames_output
9009
Bram Moolenaar071d4272004-06-13 20:20:40 +00009010==============================================================================
901110. No +eval feature *no-eval-feature*
9012
9013When the |+eval| feature was disabled at compile time, none of the expression
9014evaluation commands are available. To prevent this from causing Vim scripts
9015to generate all kinds of errors, the ":if" and ":endif" commands are still
9016recognized, though the argument of the ":if" and everything between the ":if"
9017and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
9018only if the commands are at the start of the line. The ":else" command is not
9019recognized.
9020
9021Example of how to avoid executing commands when the |+eval| feature is
9022missing: >
9023
9024 :if 1
9025 : echo "Expression evaluation is compiled in"
9026 :else
9027 : echo "You will _never_ see this message"
9028 :endif
9029
9030==============================================================================
903111. The sandbox *eval-sandbox* *sandbox* *E48*
9032
Bram Moolenaar368373e2010-07-19 20:46:22 +02009033The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
9034'foldtext' options may be evaluated in a sandbox. This means that you are
9035protected from these expressions having nasty side effects. This gives some
9036safety for when these options are set from a modeline. It is also used when
9037the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009038The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009039
9040These items are not allowed in the sandbox:
9041 - changing the buffer text
9042 - defining or changing mapping, autocommands, functions, user commands
9043 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009044 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009045 - executing a shell command
9046 - reading or writing a file
9047 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00009048 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009049This is not guaranteed 100% secure, but it should block most attacks.
9050
9051 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00009052:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009053 option that may have been set from a modeline, e.g.
9054 'foldexpr'.
9055
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009056 *sandbox-option*
9057A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00009058have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009059restrictive, thus this only happens when the option was set from an insecure
9060location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00009061- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009062- while executing in the sandbox
9063- value coming from a modeline
9064
9065Note that when in the sandbox and saving an option value and restoring it, the
9066option will still be marked as it was set in the sandbox.
9067
9068==============================================================================
906912. Textlock *textlock*
9070
9071In a few situations it is not allowed to change the text in the buffer, jump
9072to another window and some other things that might confuse or break what Vim
9073is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar446cb832008-06-24 21:56:24 +00009074actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009075happen any moment the mouse cursor is resting at some position.
9076
9077This is not allowed when the textlock is active:
9078 - changing the buffer text
9079 - jumping to another buffer or window
9080 - editing another file
9081 - closing a window or quitting Vim
9082 - etc.
9083
Bram Moolenaar071d4272004-06-13 20:20:40 +00009084
9085 vim:tw=78:ts=8:ft=help:norl: