blob: 295fe4a3c6dfa8aa27399de36a542e0f5a2bf849 [file] [log] [blame]
Bram Moolenaar446beb42011-05-10 17:18:44 +02001*eval.txt* For Vim version 7.3. Last change: 2011 May 10
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 Moolenaar446cb832008-06-24 21:56:24 +000042Number A 32 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,
94use strlen(): >
95 :if strlen("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
126cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000127
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000128A special case is defining a function and directly assigning its Funcref to a
129Dictionary entry. Example: >
130 :function dict.init() dict
131 : let self.val = 0
132 :endfunction
133
134The key of the Dictionary can start with a lower case letter. The actual
135function name is not used here. Also see |numbered-function|.
136
137A Funcref can also be used with the |:call| command: >
138 :call Fn()
139 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000140
141The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000142 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000143
144You can use |call()| to invoke a Funcref and use a list variable for the
145arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000146 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000147
148
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001491.3 Lists ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000150 *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000151A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar446cb832008-06-24 21:56:24 +0000152can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000153position in the sequence.
154
Bram Moolenaar13065c42005-01-08 16:08:21 +0000155
156List creation ~
157 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000158A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000159Examples: >
160 :let mylist = [1, two, 3, "four"]
161 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000162
Bram Moolenaar446cb832008-06-24 21:56:24 +0000163An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000164List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000165 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000166
167An extra comma after the last item is ignored.
168
Bram Moolenaar13065c42005-01-08 16:08:21 +0000169
170List index ~
171 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000172An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000173after the List. Indexes are zero-based, thus the first item has index zero. >
174 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000175 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000176
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000177When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000178 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000179<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000180A negative index is counted from the end. Index -1 refers to the last item in
181the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000182 :let last = mylist[-1] " get the last item: "four"
183
Bram Moolenaar13065c42005-01-08 16:08:21 +0000184To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000185is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000186 :echo get(mylist, idx)
187 :echo get(mylist, idx, "NONE")
188
189
190List concatenation ~
191
192Two lists can be concatenated with the "+" operator: >
193 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000194 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000195
196To prepend or append an item turn the item into a list by putting [] around
197it. To change a list in-place see |list-modification| below.
198
199
200Sublist ~
201
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000202A part of the List can be obtained by specifying the first and last index,
203separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000204 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000205
206Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000207similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000208 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
209 :let shortlist = mylist[2:2] " List with one item: [3]
210 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000211
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000212If the first index is beyond the last item of the List or the second item is
213before the first item, the result is an empty list. There is no error
214message.
215
216If the second index is equal to or greater than the length of the list the
217length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000218 :let mylist = [0, 1, 2, 3]
219 :echo mylist[2:8] " result: [2, 3]
220
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000221NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar446cb832008-06-24 21:56:24 +0000222using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000223mylist[s : e].
224
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000225
Bram Moolenaar13065c42005-01-08 16:08:21 +0000226List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000227 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000228When variable "aa" is a list and you assign it to another variable "bb", both
229variables refer to the same list. Thus changing the list "aa" will also
230change "bb": >
231 :let aa = [1, 2, 3]
232 :let bb = aa
233 :call add(aa, 4)
234 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000235< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000236
237Making a copy of a list is done with the |copy()| function. Using [:] also
238works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000239a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000240 :let aa = [[1, 'a'], 2, 3]
241 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000242 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000243 :let aa[0][1] = 'aaa'
244 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000245< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000246 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000247< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000248
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000249To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000250copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000251
252The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000253List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000254the same value. >
255 :let alist = [1, 2, 3]
256 :let blist = [1, 2, 3]
257 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000258< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000259 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000260< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000261
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000262Note about comparing lists: Two lists are considered equal if they have the
263same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000264exception: When comparing a number with a string they are considered
265different. There is no automatic type conversion, as with using "==" on
266variables. Example: >
267 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000268< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000269 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000270< 0
271
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000272Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000273can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000274
275 :let a = 5
276 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000277 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000278< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000279 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000280< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000281
Bram Moolenaar13065c42005-01-08 16:08:21 +0000282
283List unpack ~
284
285To unpack the items in a list to individual variables, put the variables in
286square brackets, like list items: >
287 :let [var1, var2] = mylist
288
289When the number of variables does not match the number of items in the list
290this produces an error. To handle any extra items from the list append ";"
291and a variable name: >
292 :let [var1, var2; rest] = mylist
293
294This works like: >
295 :let var1 = mylist[0]
296 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000297 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000298
299Except that there is no error if there are only two items. "rest" will be an
300empty list then.
301
302
303List modification ~
304 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000305To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000306 :let list[4] = "four"
307 :let listlist[0][3] = item
308
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000309To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000310modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000311 :let list[3:5] = [3, 4, 5]
312
Bram Moolenaar13065c42005-01-08 16:08:21 +0000313Adding and removing items from a list is done with functions. Here are a few
314examples: >
315 :call insert(list, 'a') " prepend item 'a'
316 :call insert(list, 'a', 3) " insert item 'a' before list[3]
317 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000318 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000319 :call extend(list, [1, 2]) " extend the list with two more items
320 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000321 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000322 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000323 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000324 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000325
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000326Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000327 :call sort(list) " sort a list alphabetically
328 :call reverse(list) " reverse the order of items
329
Bram Moolenaar13065c42005-01-08 16:08:21 +0000330
331For loop ~
332
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000333The |:for| loop executes commands for each item in a list. A variable is set
334to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000335 :for item in mylist
336 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000337 :endfor
338
339This works like: >
340 :let index = 0
341 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000342 : let item = mylist[index]
343 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000344 : let index = index + 1
345 :endwhile
346
347Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000348results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000349the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000350
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000351If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000352function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000353
Bram Moolenaar446cb832008-06-24 21:56:24 +0000354Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000355requires the argument to be a list of lists. >
356 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
357 : call Doit(lnum, col)
358 :endfor
359
360This works like a |:let| command is done for each list item. Again, the types
361must remain the same to avoid an error.
362
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000363It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000364 :for [i, j; rest] in listlist
365 : call Doit(i, j)
366 : if !empty(rest)
367 : echo "remainder: " . string(rest)
368 : endif
369 :endfor
370
371
372List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000373 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000374Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000375 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000376 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000377 :let l = len(list) " number of items in list
378 :let big = max(list) " maximum value in list
379 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000380 :let xs = count(list, 'x') " count nr of times 'x' appears in list
381 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000382 :let lines = getline(1, 10) " get ten text lines from buffer
383 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000384 :let list = split("a b c") " create list from items in a string
385 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000386 :let s = string(list) " String representation of list
387 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000388
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000389Don't forget that a combination of features can make things simple. For
390example, to add up all the numbers in a list: >
391 :exe 'let sum = ' . join(nrlist, '+')
392
Bram Moolenaar13065c42005-01-08 16:08:21 +0000393
Bram Moolenaard8b02732005-01-14 21:48:43 +00003941.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000395 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000396A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000397entry can be located with the key. The entries are stored without a specific
398ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000399
400
401Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000402 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000403A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000404braces. Each entry has a key and a value, separated by a colon. Each key can
405only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000406 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
407 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000408< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000409A key is always a String. You can use a Number, it will be converted to a
410String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar446cb832008-06-24 21:56:24 +0000411entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000412Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000413
Bram Moolenaar446cb832008-06-24 21:56:24 +0000414A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000415nested Dictionary: >
416 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
417
418An extra comma after the last entry is ignored.
419
420
421Accessing entries ~
422
423The normal way to access an entry is by putting the key in square brackets: >
424 :let val = mydict["one"]
425 :let mydict["four"] = 4
426
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000427You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000428
429For keys that consist entirely of letters, digits and underscore the following
430form can be used |expr-entry|: >
431 :let val = mydict.one
432 :let mydict.four = 4
433
434Since an entry can be any type, also a List and a Dictionary, the indexing and
435key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000436 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000437
438
439Dictionary to List conversion ~
440
Bram Moolenaar446cb832008-06-24 21:56:24 +0000441You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000442turn the Dictionary into a List and pass it to |:for|.
443
444Most often you want to loop over the keys, using the |keys()| function: >
445 :for key in keys(mydict)
446 : echo key . ': ' . mydict[key]
447 :endfor
448
449The List of keys is unsorted. You may want to sort them first: >
450 :for key in sort(keys(mydict))
451
452To loop over the values use the |values()| function: >
453 :for v in values(mydict)
454 : echo "value: " . v
455 :endfor
456
457If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000458a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000459 :for [key, value] in items(mydict)
460 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000461 :endfor
462
463
464Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000465 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000466Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
467Dictionary. Otherwise, assignment results in referring to the same
468Dictionary: >
469 :let onedict = {'a': 1, 'b': 2}
470 :let adict = onedict
471 :let adict['a'] = 11
472 :echo onedict['a']
473 11
474
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000475Two Dictionaries compare equal if all the key-value pairs compare equal. For
476more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000477
478
479Dictionary modification ~
480 *dict-modification*
481To change an already existing entry of a Dictionary, or to add a new entry,
482use |:let| this way: >
483 :let dict[4] = "four"
484 :let dict['one'] = item
485
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000486Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
487Three ways to remove the entry with key "aaa" from dict: >
488 :let i = remove(dict, 'aaa')
489 :unlet dict.aaa
490 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000491
492Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000493 :call extend(adict, bdict)
494This extends adict with all entries from bdict. Duplicate keys cause entries
495in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000496Note that the order of entries in a Dictionary is irrelevant, thus don't
497expect ":echo adict" to show the items from bdict after the older entries in
498adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000499
500Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000501 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000502This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000503
504
505Dictionary function ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000506 *Dictionary-function* *self* *E725*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000507When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000508special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000509 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000510 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000511 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000512 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
513 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000514
515This is like a method in object oriented programming. The entry in the
516Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
517the function was invoked from.
518
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000519It is also possible to add a function without the "dict" attribute as a
520Funcref to a Dictionary, but the "self" variable is not available then.
521
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000522 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000523To avoid the extra name for the function it can be defined and directly
524assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000525 :let mydict = {'data': [0, 1, 2, 3]}
526 :function mydict.len() dict
527 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000528 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000529 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000530
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000531The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar446cb832008-06-24 21:56:24 +0000532that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000533|Funcref|. It will automatically be deleted when there is no |Funcref|
534remaining that refers to it.
535
536It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000537
Bram Moolenaar1affd722010-08-04 17:49:30 +0200538If you get an error for a numbered function, you can find out what it is with
539a trick. Assuming the function is 42, the command is: >
540 :function {42}
541
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000542
543Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000544 *E715*
545Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000546 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
547 :if empty(dict) " TRUE if dict is empty
548 :let l = len(dict) " number of items in dict
549 :let big = max(dict) " maximum value in dict
550 :let small = min(dict) " minimum value in dict
551 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
552 :let s = string(dict) " String representation of dict
553 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000554
555
5561.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000557 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000558If you need to know the type of a variable or expression, use the |type()|
559function.
560
561When the '!' flag is included in the 'viminfo' option, global variables that
562start with an uppercase letter, and don't contain a lowercase letter, are
563stored in the viminfo file |viminfo-file|.
564
565When the 'sessionoptions' option contains "global", global variables that
566start with an uppercase letter and contain at least one lowercase letter are
567stored in the session file |session-file|.
568
569variable name can be stored where ~
570my_var_6 not
571My_Var_6 session file
572MY_VAR_6 viminfo file
573
574
575It's possible to form a variable name with curly braces, see
576|curly-braces-names|.
577
578==============================================================================
5792. Expression syntax *expression-syntax*
580
581Expression syntax summary, from least to most significant:
582
583|expr1| expr2 ? expr1 : expr1 if-then-else
584
585|expr2| expr3 || expr3 .. logical OR
586
587|expr3| expr4 && expr4 .. logical AND
588
589|expr4| expr5 == expr5 equal
590 expr5 != expr5 not equal
591 expr5 > expr5 greater than
592 expr5 >= expr5 greater than or equal
593 expr5 < expr5 smaller than
594 expr5 <= expr5 smaller than or equal
595 expr5 =~ expr5 regexp matches
596 expr5 !~ expr5 regexp doesn't match
597
598 expr5 ==? expr5 equal, ignoring case
599 expr5 ==# expr5 equal, match case
600 etc. As above, append ? for ignoring case, # for
601 matching case
602
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000603 expr5 is expr5 same |List| instance
604 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000605
606|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000607 expr6 - expr6 .. number subtraction
608 expr6 . expr6 .. string concatenation
609
610|expr6| expr7 * expr7 .. number multiplication
611 expr7 / expr7 .. number division
612 expr7 % expr7 .. number modulo
613
614|expr7| ! expr7 logical NOT
615 - expr7 unary minus
616 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000617
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000619|expr8| expr8[expr1] byte of a String or item of a |List|
620 expr8[expr1 : expr1] substring of a String or sublist of a |List|
621 expr8.name entry in a |Dictionary|
622 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000623
624|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000625 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000626 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000627 [expr1, ...] |List|
628 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000629 &option option value
630 (expr1) nested expression
631 variable internal variable
632 va{ria}ble internal variable with curly braces
633 $VAR environment variable
634 @r contents of register 'r'
635 function(expr1, ...) function call
636 func{ti}on(expr1, ...) function call with curly braces
637
638
639".." indicates that the operations in this level can be concatenated.
640Example: >
641 &nu || &list && &shell == "csh"
642
643All expressions within one level are parsed from left to right.
644
645
646expr1 *expr1* *E109*
647-----
648
649expr2 ? expr1 : expr1
650
651The expression before the '?' is evaluated to a number. If it evaluates to
652non-zero, the result is the value of the expression between the '?' and ':',
653otherwise the result is the value of the expression after the ':'.
654Example: >
655 :echo lnum == 1 ? "top" : lnum
656
657Since the first expression is an "expr2", it cannot contain another ?:. The
658other two expressions can, thus allow for recursive use of ?:.
659Example: >
660 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
661
662To keep this readable, using |line-continuation| is suggested: >
663 :echo lnum == 1
664 :\ ? "top"
665 :\ : lnum == 1000
666 :\ ? "last"
667 :\ : lnum
668
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000669You should always put a space before the ':', otherwise it can be mistaken for
670use in a variable such as "a:1".
671
Bram Moolenaar071d4272004-06-13 20:20:40 +0000672
673expr2 and expr3 *expr2* *expr3*
674---------------
675
676 *expr-barbar* *expr-&&*
677The "||" and "&&" operators take one argument on each side. The arguments
678are (converted to) Numbers. The result is:
679
680 input output ~
681n1 n2 n1 || n2 n1 && n2 ~
682zero zero zero zero
683zero non-zero non-zero zero
684non-zero zero non-zero zero
685non-zero non-zero non-zero non-zero
686
687The operators can be concatenated, for example: >
688
689 &nu || &list && &shell == "csh"
690
691Note that "&&" takes precedence over "||", so this has the meaning of: >
692
693 &nu || (&list && &shell == "csh")
694
695Once the result is known, the expression "short-circuits", that is, further
696arguments are not evaluated. This is like what happens in C. For example: >
697
698 let a = 1
699 echo a || b
700
701This is valid even if there is no variable called "b" because "a" is non-zero,
702so the result must be non-zero. Similarly below: >
703
704 echo exists("b") && b == "yes"
705
706This is valid whether "b" has been defined or not. The second clause will
707only be evaluated if "b" has been defined.
708
709
710expr4 *expr4*
711-----
712
713expr5 {cmp} expr5
714
715Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
716if it evaluates to true.
717
Bram Moolenaar446cb832008-06-24 21:56:24 +0000718 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000719 *expr-<* *expr-<=* *expr-=~* *expr-!~*
720 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
721 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
722 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
723 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000724 *expr-is*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000725 use 'ignorecase' match case ignore case ~
726equal == ==# ==?
727not equal != !=# !=?
728greater than > ># >?
729greater than or equal >= >=# >=?
730smaller than < <# <?
731smaller than or equal <= <=# <=?
732regexp matches =~ =~# =~?
733regexp doesn't match !~ !~# !~?
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000734same instance is
735different instance isnot
Bram Moolenaar071d4272004-06-13 20:20:40 +0000736
737Examples:
738"abc" ==# "Abc" evaluates to 0
739"abc" ==? "Abc" evaluates to 1
740"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
741
Bram Moolenaar13065c42005-01-08 16:08:21 +0000742 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000743A |List| can only be compared with a |List| and only "equal", "not equal" and
744"is" can be used. This compares the values of the list, recursively.
745Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000746
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000747 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000748A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
749equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000750recursively. Ignoring case means case is ignored when comparing item values.
751
Bram Moolenaar13065c42005-01-08 16:08:21 +0000752 *E693* *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000753A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
754equal" can be used. Case is never ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000755
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000756When using "is" or "isnot" with a |List| this checks if the expressions are
Bram Moolenaar446cb832008-06-24 21:56:24 +0000757referring to the same |List| instance. A copy of a |List| is different from
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000758the original |List|. When using "is" without a |List| it is equivalent to
759using "equal", using "isnot" equivalent to using "not equal". Except that a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000760different type means the values are different. "4 == '4'" is true, "4 is '4'"
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000761is false.
762
Bram Moolenaar071d4272004-06-13 20:20:40 +0000763When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +0000764and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
Bram Moolenaar071d4272004-06-13 20:20:40 +0000765because 'x' converted to a Number is zero.
766
767When comparing two Strings, this is done with strcmp() or stricmp(). This
768results in the mathematical difference (comparing byte values), not
769necessarily the alphabetical difference in the local language.
770
Bram Moolenaar446cb832008-06-24 21:56:24 +0000771When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000772'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000773
774When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000775'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
776
777'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000778
779The "=~" and "!~" operators match the lefthand argument with the righthand
780argument, which is used as a pattern. See |pattern| for what a pattern is.
781This matching is always done like 'magic' was set and 'cpoptions' is empty, no
782matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
783portable. To avoid backslashes in the regexp pattern to be doubled, use a
784single-quote string, see |literal-string|.
785Since a string is considered to be a single line, a multi-line pattern
786(containing \n, backslash-n) will not match. However, a literal NL character
787can be matched like an ordinary character. Examples:
788 "foo\nbar" =~ "\n" evaluates to 1
789 "foo\nbar" =~ "\\n" evaluates to 0
790
791
792expr5 and expr6 *expr5* *expr6*
793---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000794expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000795expr6 - expr6 .. Number subtraction *expr--*
796expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000798For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000799result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000800
801expr7 * expr7 .. number multiplication *expr-star*
802expr7 / expr7 .. number division *expr-/*
803expr7 % expr7 .. number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000804
805For all, except ".", Strings are converted to Numbers.
806
807Note the difference between "+" and ".":
808 "123" + "456" = 579
809 "123" . "456" = "123456"
810
Bram Moolenaar446cb832008-06-24 21:56:24 +0000811Since '.' has the same precedence as '+' and '-', you need to read: >
812 1 . 90 + 90.0
813As: >
814 (1 . 90) + 90.0
815That works, since the String "190" is automatically converted to the Number
816190, which can be added to the Float 90.0. However: >
817 1 . 90 * 90.0
818Should be read as: >
819 1 . (90 * 90.0)
820Since '.' has lower precedence than '*'. This does NOT work, since this
821attempts to concatenate a Float and a String.
822
823When dividing a Number by zero the result depends on the value:
824 0 / 0 = -0x80000000 (like NaN for Float)
825 >0 / 0 = 0x7fffffff (like positive infinity)
826 <0 / 0 = -0x7fffffff (like negative infinity)
827 (before Vim 7.2 it was always 0x7fffffff)
828
Bram Moolenaar071d4272004-06-13 20:20:40 +0000829When the righthand side of '%' is zero, the result is 0.
830
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000831None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000832
Bram Moolenaar446cb832008-06-24 21:56:24 +0000833. and % do not work for Float. *E804*
834
Bram Moolenaar071d4272004-06-13 20:20:40 +0000835
836expr7 *expr7*
837-----
838! expr7 logical NOT *expr-!*
839- expr7 unary minus *expr-unary--*
840+ expr7 unary plus *expr-unary-+*
841
842For '!' non-zero becomes zero, zero becomes one.
843For '-' the sign of the number is changed.
844For '+' the number is unchanged.
845
846A String will be converted to a Number first.
847
Bram Moolenaar446cb832008-06-24 21:56:24 +0000848These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000849 !-1 == 0
850 !!8 == 1
851 --9 == 9
852
853
854expr8 *expr8*
855-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000856expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000858If expr8 is a Number or String this results in a String that contains the
859expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100860Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
861an alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000862
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000863Index zero gives the first character. This is like it works in C. Careful:
864text column numbers start with one! Example, to get the character under the
865cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000866 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000867
868If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000869String. A negative index always results in an empty string (reason: backwards
870compatibility). Use [-1:] to get the last byte.
871
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000872If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000873for possible index values. If the index is out of range this results in an
Bram Moolenaar446cb832008-06-24 21:56:24 +0000874error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000875 :let item = mylist[-1] " get last item
876
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000877Generally, if a |List| index is equal to or higher than the length of the
878|List|, or more negative than the length of the |List|, this results in an
879error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000880
Bram Moolenaard8b02732005-01-14 21:48:43 +0000881
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000882expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000883
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000884If expr8 is a Number or String this results in the substring with the bytes
885from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100886expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
887|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000888
889If expr1a is omitted zero is used. If expr1b is omitted the length of the
890string minus one is used.
891
892A negative number can be used to measure from the end of the string. -1 is
893the last character, -2 the last but one, etc.
894
895If an index goes out of range for the string characters are omitted. If
896expr1b is smaller than expr1a the result is an empty string.
897
898Examples: >
899 :let c = name[-1:] " last byte of a string
900 :let c = name[-2:-2] " last but one byte of a string
901 :let s = line(".")[4:] " from the fifth byte to the end
902 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100903<
904 *sublist* *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000905If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar446cb832008-06-24 21:56:24 +0000906the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000907just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000908 :let l = mylist[:3] " first four items
909 :let l = mylist[4:4] " List with one item
910 :let l = mylist[:] " shallow copy of a List
911
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000912Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
913error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000914
Bram Moolenaard8b02732005-01-14 21:48:43 +0000915
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000916expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000917
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000918If expr8 is a |Dictionary| and it is followed by a dot, then the following
919name will be used as a key in the |Dictionary|. This is just like:
920expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000921
922The name must consist of alphanumeric characters, just like a variable name,
923but it may start with a number. Curly braces cannot be used.
924
925There must not be white space before or after the dot.
926
927Examples: >
928 :let dict = {"one": 1, 2: "two"}
929 :echo dict.one
930 :echo dict .2
931
932Note that the dot is also used for String concatenation. To avoid confusion
933always put spaces around the dot for String concatenation.
934
935
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000936expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000937
938When expr8 is a |Funcref| type variable, invoke the function it refers to.
939
940
941
942 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000943number
944------
945number number constant *expr-number*
946
947Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
948
Bram Moolenaar446cb832008-06-24 21:56:24 +0000949 *floating-point-format*
950Floating point numbers can be written in two forms:
951
952 [-+]{N}.{M}
953 [-+]{N}.{M}e[-+]{exp}
954
955{N} and {M} are numbers. Both {N} and {M} must be present and can only
956contain digits.
957[-+] means there is an optional plus or minus sign.
958{exp} is the exponent, power of 10.
959Only a decimal point is accepted, not a comma. No matter what the current
960locale is.
961{only when compiled with the |+float| feature}
962
963Examples:
964 123.456
965 +0.0001
966 55.0
967 -0.123
968 1.234e03
969 1.0E-6
970 -3.1416e+88
971
972These are INVALID:
973 3. empty {M}
974 1e40 missing .{M}
975
Bram Moolenaare37d50a2008-08-06 17:06:04 +0000976 *float-pi* *float-e*
977A few useful values to copy&paste: >
978 :let pi = 3.14159265359
979 :let e = 2.71828182846
980
Bram Moolenaar446cb832008-06-24 21:56:24 +0000981Rationale:
982Before floating point was introduced, the text "123.456" was interpreted as
983the two numbers "123" and "456", both converted to a string and concatenated,
984resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +0000985could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +0000986incompatibility was accepted in favor of being able to use the normal notation
987for floating point numbers.
988
989 *floating-point-precision*
990The precision and range of floating points numbers depends on what "double"
991means in the library Vim was compiled with. There is no way to change this at
992runtime.
993
994The default for displaying a |Float| is to use 6 decimal places, like using
995printf("%g", f). You can select something else when using the |printf()|
996function. Example: >
997 :echo printf('%.15e', atan(1))
998< 7.853981633974483e-01
999
1000
Bram Moolenaar071d4272004-06-13 20:20:40 +00001001
1002string *expr-string* *E114*
1003------
1004"string" string constant *expr-quote*
1005
1006Note that double quotes are used.
1007
1008A string constant accepts these special characters:
1009\... three-digit octal number (e.g., "\316")
1010\.. two-digit octal number (must be followed by non-digit)
1011\. one-digit octal number (must be followed by non-digit)
1012\x.. byte specified with two hex numbers (e.g., "\x1f")
1013\x. byte specified with one hex number (must be followed by non-hex char)
1014\X.. same as \x..
1015\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001016\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001017 current value of 'encoding' (e.g., "\u02a4")
1018\U.... same as \u....
1019\b backspace <BS>
1020\e escape <Esc>
1021\f formfeed <FF>
1022\n newline <NL>
1023\r return <CR>
1024\t tab <Tab>
1025\\ backslash
1026\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001027\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
1028 in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a
1029 utf-8 character, use \uxxxx as mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001030
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001031Note that "\xff" is stored as the byte 255, which may be invalid in some
1032encodings. Use "\u00ff" to store character 255 according to the current value
1033of 'encoding'.
1034
Bram Moolenaar071d4272004-06-13 20:20:40 +00001035Note that "\000" and "\x00" force the end of the string.
1036
1037
1038literal-string *literal-string* *E115*
1039---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001040'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001041
1042Note that single quotes are used.
1043
Bram Moolenaar446cb832008-06-24 21:56:24 +00001044This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001045meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001046
1047Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar446cb832008-06-24 21:56:24 +00001048to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001049 if a =~ "\\s*"
1050 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001051
1052
1053option *expr-option* *E112* *E113*
1054------
1055&option option value, local value if possible
1056&g:option global option value
1057&l:option local option value
1058
1059Examples: >
1060 echo "tabstop is " . &tabstop
1061 if &insertmode
1062
1063Any option name can be used here. See |options|. When using the local value
1064and there is no buffer-local or window-local value, the global value is used
1065anyway.
1066
1067
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001068register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001069--------
1070@r contents of register 'r'
1071
1072The result is the contents of the named register, as a single string.
1073Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar446cb832008-06-24 21:56:24 +00001074register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001075registers.
1076
1077When using the '=' register you get the expression itself, not what it
1078evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001079
1080
1081nesting *expr-nesting* *E110*
1082-------
1083(expr1) nested expression
1084
1085
1086environment variable *expr-env*
1087--------------------
1088$VAR environment variable
1089
1090The String value of any environment variable. When it is not defined, the
1091result is an empty string.
1092 *expr-env-expand*
1093Note that there is a difference between using $VAR directly and using
1094expand("$VAR"). Using it directly will only expand environment variables that
1095are known inside the current Vim session. Using expand() will first try using
1096the environment variables known inside the current Vim session. If that
1097fails, a shell will be used to expand the variable. This can be slow, but it
1098does expand all variables that the shell knows about. Example: >
1099 :echo $version
1100 :echo expand("$version")
1101The first one probably doesn't echo anything, the second echoes the $version
1102variable (if your shell supports it).
1103
1104
1105internal variable *expr-variable*
1106-----------------
1107variable internal variable
1108See below |internal-variables|.
1109
1110
Bram Moolenaar05159a02005-02-26 23:04:13 +00001111function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001112-------------
1113function(expr1, ...) function call
1114See below |functions|.
1115
1116
1117==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020011183. Internal variable *internal-variables* *E461*
1119
Bram Moolenaar071d4272004-06-13 20:20:40 +00001120An internal variable name can be made up of letters, digits and '_'. But it
1121cannot start with a digit. It's also possible to use curly braces, see
1122|curly-braces-names|.
1123
1124An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001125An internal variable is explicitly destroyed with the ":unlet" command
1126|:unlet|.
1127Using a name that is not an internal variable or refers to a variable that has
1128been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001129
1130There are several name spaces for variables. Which one is to be used is
1131specified by what is prepended:
1132
1133 (nothing) In a function: local to a function; otherwise: global
1134|buffer-variable| b: Local to the current buffer.
1135|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001136|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001137|global-variable| g: Global.
1138|local-variable| l: Local to a function.
1139|script-variable| s: Local to a |:source|'ed Vim script.
1140|function-argument| a: Function argument (only inside a function).
Bram Moolenaar446cb832008-06-24 21:56:24 +00001141|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001142
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001143The scope name by itself can be used as a |Dictionary|. For example, to
1144delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001145 :for k in keys(s:)
1146 : unlet s:[k]
1147 :endfor
1148<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001149 *buffer-variable* *b:var*
1150A variable name that is preceded with "b:" is local to the current buffer.
1151Thus you can have several "b:foo" variables, one for each buffer.
1152This kind of variable is deleted when the buffer is wiped out or deleted with
1153|:bdelete|.
1154
1155One local buffer variable is predefined:
1156 *b:changedtick-variable* *changetick*
1157b:changedtick The total number of changes to the current buffer. It is
1158 incremented for each change. An undo command is also a change
1159 in this case. This can be used to perform an action only when
1160 the buffer has changed. Example: >
1161 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001162 : let my_changedtick = b:changedtick
1163 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001164 :endif
1165<
1166 *window-variable* *w:var*
1167A variable name that is preceded with "w:" is local to the current window. It
1168is deleted when the window is closed.
1169
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001170 *tabpage-variable* *t:var*
1171A variable name that is preceded with "t:" is local to the current tab page,
1172It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001173without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001174
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175 *global-variable* *g:var*
1176Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar446cb832008-06-24 21:56:24 +00001177access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001178place if you like.
1179
1180 *local-variable* *l:var*
1181Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001182But you can also prepend "l:" if you like. However, without prepending "l:"
1183you may run into reserved variable names. For example "count". By itself it
1184refers to "v:count". Using "l:count" you can have a local variable with the
1185same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001186
1187 *script-variable* *s:var*
1188In a Vim script variables starting with "s:" can be used. They cannot be
1189accessed from outside of the scripts, thus are local to the script.
1190
1191They can be used in:
1192- commands executed while the script is sourced
1193- functions defined in the script
1194- autocommands defined in the script
1195- functions and autocommands defined in functions and autocommands which were
1196 defined in the script (recursively)
1197- user defined commands defined in the script
1198Thus not in:
1199- other scripts sourced from this one
1200- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001201- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001202- etc.
1203
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001204Script variables can be used to avoid conflicts with global variable names.
1205Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001206
1207 let s:counter = 0
1208 function MyCounter()
1209 let s:counter = s:counter + 1
1210 echo s:counter
1211 endfunction
1212 command Tick call MyCounter()
1213
1214You can now invoke "Tick" from any script, and the "s:counter" variable in
1215that script will not be changed, only the "s:counter" in the script where
1216"Tick" was defined is used.
1217
1218Another example that does the same: >
1219
1220 let s:counter = 0
1221 command Tick let s:counter = s:counter + 1 | echo s:counter
1222
1223When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001224script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001225defined.
1226
1227The script variables are also available when a function is defined inside a
1228function that is defined in a script. Example: >
1229
1230 let s:counter = 0
1231 function StartCounting(incr)
1232 if a:incr
1233 function MyCounter()
1234 let s:counter = s:counter + 1
1235 endfunction
1236 else
1237 function MyCounter()
1238 let s:counter = s:counter - 1
1239 endfunction
1240 endif
1241 endfunction
1242
1243This defines the MyCounter() function either for counting up or counting down
1244when calling StartCounting(). It doesn't matter from where StartCounting() is
1245called, the s:counter variable will be accessible in MyCounter().
1246
1247When the same script is sourced again it will use the same script variables.
1248They will remain valid as long as Vim is running. This can be used to
1249maintain a counter: >
1250
1251 if !exists("s:counter")
1252 let s:counter = 1
1253 echo "script executed for the first time"
1254 else
1255 let s:counter = s:counter + 1
1256 echo "script executed " . s:counter . " times now"
1257 endif
1258
1259Note that this means that filetype plugins don't get a different set of script
1260variables for each buffer. Use local buffer variables instead |b:var|.
1261
1262
1263Predefined Vim variables: *vim-variable* *v:var*
1264
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001265 *v:beval_col* *beval_col-variable*
1266v:beval_col The number of the column, over which the mouse pointer is.
1267 This is the byte index in the |v:beval_lnum| line.
1268 Only valid while evaluating the 'balloonexpr' option.
1269
1270 *v:beval_bufnr* *beval_bufnr-variable*
1271v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1272 valid while evaluating the 'balloonexpr' option.
1273
1274 *v:beval_lnum* *beval_lnum-variable*
1275v:beval_lnum The number of the line, over which the mouse pointer is. Only
1276 valid while evaluating the 'balloonexpr' option.
1277
1278 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001279v:beval_text The text under or after the mouse pointer. Usually a word as
1280 it is useful for debugging a C program. 'iskeyword' applies,
1281 but a dot and "->" before the position is included. When on a
1282 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001283 word before it. When on a Visual area within one line the
1284 highlighted text is used.
1285 Only valid while evaluating the 'balloonexpr' option.
1286
1287 *v:beval_winnr* *beval_winnr-variable*
1288v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001289 valid while evaluating the 'balloonexpr' option. The first
1290 window has number zero (unlike most other places where a
1291 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001292
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001293 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001294v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001295 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001296
Bram Moolenaar071d4272004-06-13 20:20:40 +00001297 *v:charconvert_from* *charconvert_from-variable*
1298v:charconvert_from
1299 The name of the character encoding of a file to be converted.
1300 Only valid while evaluating the 'charconvert' option.
1301
1302 *v:charconvert_to* *charconvert_to-variable*
1303v:charconvert_to
1304 The name of the character encoding of a file after conversion.
1305 Only valid while evaluating the 'charconvert' option.
1306
1307 *v:cmdarg* *cmdarg-variable*
1308v:cmdarg This variable is used for two purposes:
1309 1. The extra arguments given to a file read/write command.
1310 Currently these are "++enc=" and "++ff=". This variable is
1311 set before an autocommand event for a file read/write
1312 command is triggered. There is a leading space to make it
1313 possible to append this variable directly after the
Bram Moolenaar446cb832008-06-24 21:56:24 +00001314 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001315 included here, because it will be executed anyway.
1316 2. When printing a PostScript file with ":hardcopy" this is
1317 the argument for the ":hardcopy" command. This can be used
1318 in 'printexpr'.
1319
1320 *v:cmdbang* *cmdbang-variable*
1321v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1322 was used the value is 1, otherwise it is 0. Note that this
1323 can only be used in autocommands. For user commands |<bang>|
1324 can be used.
1325
1326 *v:count* *count-variable*
1327v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar446cb832008-06-24 21:56:24 +00001328 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001329 :map _x :<C-U>echo "the count is " . v:count<CR>
1330< Note: The <C-U> is required to remove the line range that you
1331 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001332 When there are two counts, as in "3d2w", they are multiplied,
1333 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001334 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001335 "count" also works, for backwards compatibility.
1336
1337 *v:count1* *count1-variable*
1338v:count1 Just like "v:count", but defaults to one when no count is
1339 used.
1340
1341 *v:ctype* *ctype-variable*
1342v:ctype The current locale setting for characters of the runtime
1343 environment. This allows Vim scripts to be aware of the
1344 current locale encoding. Technical: it's the value of
1345 LC_CTYPE. When not using a locale the value is "C".
1346 This variable can not be set directly, use the |:language|
1347 command.
1348 See |multi-lang|.
1349
1350 *v:dying* *dying-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001351v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001352 one. When multiple signals are caught the number increases.
1353 Can be used in an autocommand to check if Vim didn't
1354 terminate normally. {only works on Unix}
1355 Example: >
1356 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001357< Note: if another deadly signal is caught when v:dying is one,
1358 VimLeave autocommands will not be executed.
1359
Bram Moolenaar071d4272004-06-13 20:20:40 +00001360 *v:errmsg* *errmsg-variable*
1361v:errmsg Last given error message. It's allowed to set this variable.
1362 Example: >
1363 :let v:errmsg = ""
1364 :silent! next
1365 :if v:errmsg != ""
1366 : ... handle error
1367< "errmsg" also works, for backwards compatibility.
1368
1369 *v:exception* *exception-variable*
1370v:exception The value of the exception most recently caught and not
1371 finished. See also |v:throwpoint| and |throw-variables|.
1372 Example: >
1373 :try
1374 : throw "oops"
1375 :catch /.*/
1376 : echo "caught" v:exception
1377 :endtry
1378< Output: "caught oops".
1379
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001380 *v:fcs_reason* *fcs_reason-variable*
1381v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1382 Can be used in an autocommand to decide what to do and/or what
1383 to set v:fcs_choice to. Possible values:
1384 deleted file no longer exists
1385 conflict file contents, mode or timestamp was
1386 changed and buffer is modified
1387 changed file contents has changed
1388 mode mode of file changed
1389 time only file timestamp changed
1390
1391 *v:fcs_choice* *fcs_choice-variable*
1392v:fcs_choice What should happen after a |FileChangedShell| event was
1393 triggered. Can be used in an autocommand to tell Vim what to
1394 do with the affected buffer:
1395 reload Reload the buffer (does not work if
1396 the file was deleted).
1397 ask Ask the user what to do, as if there
1398 was no autocommand. Except that when
1399 only the timestamp changed nothing
1400 will happen.
1401 <empty> Nothing, the autocommand should do
1402 everything that needs to be done.
1403 The default is empty. If another (invalid) value is used then
1404 Vim behaves like it is empty, there is no warning message.
1405
Bram Moolenaar071d4272004-06-13 20:20:40 +00001406 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001407v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001408 option used for ~
1409 'charconvert' file to be converted
1410 'diffexpr' original file
1411 'patchexpr' original file
1412 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001413 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001414
1415 *v:fname_out* *fname_out-variable*
1416v:fname_out The name of the output file. Only valid while
1417 evaluating:
1418 option used for ~
1419 'charconvert' resulting converted file (*)
1420 'diffexpr' output of diff
1421 'patchexpr' resulting patched file
1422 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar446cb832008-06-24 21:56:24 +00001423 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424 for a read command (e.g., ":e file") it will be a temporary
1425 file and different from v:fname_in.
1426
1427 *v:fname_new* *fname_new-variable*
1428v:fname_new The name of the new version of the file. Only valid while
1429 evaluating 'diffexpr'.
1430
1431 *v:fname_diff* *fname_diff-variable*
1432v:fname_diff The name of the diff (patch) file. Only valid while
1433 evaluating 'patchexpr'.
1434
1435 *v:folddashes* *folddashes-variable*
1436v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1437 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001438 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001439
1440 *v:foldlevel* *foldlevel-variable*
1441v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001442 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001443
1444 *v:foldend* *foldend-variable*
1445v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001446 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001447
1448 *v:foldstart* *foldstart-variable*
1449v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001450 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001451
Bram Moolenaar843ee412004-06-30 16:16:41 +00001452 *v:insertmode* *insertmode-variable*
1453v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1454 events. Values:
1455 i Insert mode
1456 r Replace mode
1457 v Virtual Replace mode
1458
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001459 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001460v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001461 evaluating the expression used with |map()| and |filter()|.
1462 Read-only.
1463
Bram Moolenaar071d4272004-06-13 20:20:40 +00001464 *v:lang* *lang-variable*
1465v:lang The current locale setting for messages of the runtime
1466 environment. This allows Vim scripts to be aware of the
1467 current language. Technical: it's the value of LC_MESSAGES.
1468 The value is system dependent.
1469 This variable can not be set directly, use the |:language|
1470 command.
1471 It can be different from |v:ctype| when messages are desired
1472 in a different language than what is used for character
1473 encoding. See |multi-lang|.
1474
1475 *v:lc_time* *lc_time-variable*
1476v:lc_time The current locale setting for time messages of the runtime
1477 environment. This allows Vim scripts to be aware of the
1478 current language. Technical: it's the value of LC_TIME.
1479 This variable can not be set directly, use the |:language|
1480 command. See |multi-lang|.
1481
1482 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001483v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1484 'indentexpr' expressions, tab page number for 'guitablabel'
1485 and 'guitabtooltip'. Only valid while one of these
1486 expressions is being evaluated. Read-only when in the
1487 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001488
Bram Moolenaar219b8702006-11-01 14:32:36 +00001489 *v:mouse_win* *mouse_win-variable*
1490v:mouse_win Window number for a mouse click obtained with |getchar()|.
1491 First window has number 1, like with |winnr()|. The value is
1492 zero when there was no mouse button click.
1493
1494 *v:mouse_lnum* *mouse_lnum-variable*
1495v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1496 This is the text line number, not the screen line number. The
1497 value is zero when there was no mouse button click.
1498
1499 *v:mouse_col* *mouse_col-variable*
1500v:mouse_col Column number for a mouse click obtained with |getchar()|.
1501 This is the screen column number, like with |virtcol()|. The
1502 value is zero when there was no mouse button click.
1503
Bram Moolenaard812df62008-11-09 12:46:09 +00001504 *v:oldfiles* *oldfiles-variable*
1505v:oldfiles List of file names that is loaded from the |viminfo| file on
1506 startup. These are the files that Vim remembers marks for.
1507 The length of the List is limited by the ' argument of the
1508 'viminfo' option (default is 100).
1509 Also see |:oldfiles| and |c_#<|.
1510 The List can be modified, but this has no effect on what is
1511 stored in the |viminfo| file later. If you use values other
1512 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001513 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001514
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001515 *v:operator* *operator-variable*
1516v:operator The last operator given in Normal mode. This is a single
1517 character except for commands starting with <g> or <z>,
1518 in which case it is two characters. Best used alongside
1519 |v:prevcount| and |v:register|. Useful if you want to cancel
1520 Operator-pending mode and then use the operator, e.g.: >
1521 :omap O <Esc>:call MyMotion(v:operator)<CR>
1522< The value remains set until another operator is entered, thus
1523 don't expect it to be empty.
1524 v:operator is not set for |:delete|, |:yank| or other Ex
1525 commands.
1526 Read-only.
1527
Bram Moolenaar071d4272004-06-13 20:20:40 +00001528 *v:prevcount* *prevcount-variable*
1529v:prevcount The count given for the last but one Normal mode command.
1530 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001531 you want to cancel Visual or Operator-pending mode and then
1532 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001533 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1534< Read-only.
1535
Bram Moolenaar05159a02005-02-26 23:04:13 +00001536 *v:profiling* *profiling-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001537v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001538 See |profiling|.
1539
Bram Moolenaar071d4272004-06-13 20:20:40 +00001540 *v:progname* *progname-variable*
1541v:progname Contains the name (with path removed) with which Vim was
1542 invoked. Allows you to do special initialisations for "view",
1543 "evim" etc., or any other name you might symlink to Vim.
1544 Read-only.
1545
1546 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001547v:register The name of the register in effect for the current normal mode
Bram Moolenaar446beb42011-05-10 17:18:44 +02001548 command. If none is supplied it is the default register '"',
1549 unless 'clipboard' contains "unnamed" or "unnamedplus", then
1550 it is '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001551 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001552
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001553 *v:scrollstart* *scrollstart-variable*
1554v:scrollstart String describing the script or function that caused the
1555 screen to scroll up. It's only set when it is empty, thus the
1556 first reason is remembered. It is set to "Unknown" for a
1557 typed command.
1558 This can be used to find out why your script causes the
1559 hit-enter prompt.
1560
Bram Moolenaar071d4272004-06-13 20:20:40 +00001561 *v:servername* *servername-variable*
1562v:servername The resulting registered |x11-clientserver| name if any.
1563 Read-only.
1564
Bram Moolenaar446cb832008-06-24 21:56:24 +00001565
1566v:searchforward *v:searchforward* *searchforward-variable*
1567 Search direction: 1 after a forward search, 0 after a
1568 backward search. It is reset to forward when directly setting
1569 the last search pattern, see |quote/|.
1570 Note that the value is restored when returning from a
1571 function. |function-search-undo|.
1572 Read-write.
1573
Bram Moolenaar071d4272004-06-13 20:20:40 +00001574 *v:shell_error* *shell_error-variable*
1575v:shell_error Result of the last shell command. When non-zero, the last
1576 shell command had an error. When zero, there was no problem.
1577 This only works when the shell returns the error code to Vim.
1578 The value -1 is often used when the command could not be
1579 executed. Read-only.
1580 Example: >
1581 :!mv foo bar
1582 :if v:shell_error
1583 : echo 'could not rename "foo" to "bar"!'
1584 :endif
1585< "shell_error" also works, for backwards compatibility.
1586
1587 *v:statusmsg* *statusmsg-variable*
1588v:statusmsg Last given status message. It's allowed to set this variable.
1589
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001590 *v:swapname* *swapname-variable*
1591v:swapname Only valid when executing |SwapExists| autocommands: Name of
1592 the swap file found. Read-only.
1593
1594 *v:swapchoice* *swapchoice-variable*
1595v:swapchoice |SwapExists| autocommands can set this to the selected choice
1596 for handling an existing swap file:
1597 'o' Open read-only
1598 'e' Edit anyway
1599 'r' Recover
1600 'd' Delete swapfile
1601 'q' Quit
1602 'a' Abort
Bram Moolenaar446cb832008-06-24 21:56:24 +00001603 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001604 results in the user being asked, as would happen when there is
1605 no SwapExists autocommand. The default is empty.
1606
Bram Moolenaarb3480382005-12-11 21:33:32 +00001607 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001608v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001609 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar446cb832008-06-24 21:56:24 +00001610 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001611 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001612 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001613
Bram Moolenaar071d4272004-06-13 20:20:40 +00001614 *v:termresponse* *termresponse-variable*
1615v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar446cb832008-06-24 21:56:24 +00001616 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001617 that starts with ESC [ or CSI and ends in a 'c', with only
1618 digits, ';' and '.' in between.
1619 When this option is set, the TermResponse autocommand event is
1620 fired, so that you can react to the response from the
1621 terminal.
1622 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1623 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1624 patch level (since this was introduced in patch 95, it's
1625 always 95 or bigger). Pc is always zero.
1626 {only when compiled with |+termresponse| feature}
1627
1628 *v:this_session* *this_session-variable*
1629v:this_session Full filename of the last loaded or saved session file. See
1630 |:mksession|. It is allowed to set this variable. When no
1631 session file has been saved, this variable is empty.
1632 "this_session" also works, for backwards compatibility.
1633
1634 *v:throwpoint* *throwpoint-variable*
1635v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001636 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001637 also |v:exception| and |throw-variables|.
1638 Example: >
1639 :try
1640 : throw "oops"
1641 :catch /.*/
1642 : echo "Exception from" v:throwpoint
1643 :endtry
1644< Output: "Exception from test.vim, line 2"
1645
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001646 *v:val* *val-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001647v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001648 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001649 |filter()|. Read-only.
1650
Bram Moolenaar071d4272004-06-13 20:20:40 +00001651 *v:version* *version-variable*
1652v:version Version number of Vim: Major version number times 100 plus
1653 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1654 is 501. Read-only. "version" also works, for backwards
1655 compatibility.
1656 Use |has()| to check if a certain patch was included, e.g.: >
1657 if has("patch123")
1658< Note that patch numbers are specific to the version, thus both
1659 version 5.0 and 5.1 may have a patch 123, but these are
1660 completely different.
1661
1662 *v:warningmsg* *warningmsg-variable*
1663v:warningmsg Last given warning message. It's allowed to set this variable.
1664
Bram Moolenaar727c8762010-10-20 19:17:48 +02001665 *v:windowid* *windowid-variable*
1666v:windowid When any X11 based GUI is running or when running in a
1667 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001668 set to the window ID.
1669 When an MS-Windows GUI is running this will be set to the
1670 window handle.
1671 Otherwise the value is zero.
1672 Note: for windows inside Vim use |winnr()|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001673
Bram Moolenaar071d4272004-06-13 20:20:40 +00001674==============================================================================
16754. Builtin Functions *functions*
1676
1677See |function-list| for a list grouped by what the function is used for.
1678
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001679(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001680
1681USAGE RESULT DESCRIPTION ~
1682
Bram Moolenaar446cb832008-06-24 21:56:24 +00001683abs( {expr}) Float or Number absolute value of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001684acos( {expr}) Float arc cosine of {expr}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001685add( {list}, {item}) List append {item} to |List| {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001686append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001687append( {lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001688argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001689argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001690argv( {nr}) String {nr} entry of the argument list
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001691argv( ) List the argument list
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001692asin( {expr}) Float arc sine of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001693atan( {expr}) Float arc tangent of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001694atan2( {expr}, {expr}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001695browse( {save}, {title}, {initdir}, {default})
1696 String put up a file requester
Bram Moolenaar446cb832008-06-24 21:56:24 +00001697browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001698bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001699buflisted( {expr}) Number TRUE if buffer {expr} is listed
1700bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001701bufname( {expr}) String Name of the buffer {expr}
1702bufnr( {expr}) Number Number of the buffer {expr}
1703bufwinnr( {expr}) Number window number of buffer {expr}
1704byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001705byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001706call( {func}, {arglist} [, {dict}])
1707 any call {func} with arguments {arglist}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001708ceil( {expr}) Float round {expr} up
1709changenr() Number current change number
Bram Moolenaar071d4272004-06-13 20:20:40 +00001710char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001711cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001712clearmatches() none clear all matches
Bram Moolenaar071d4272004-06-13 20:20:40 +00001713col( {expr}) Number column nr of cursor or mark
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001714complete( {startcol}, {matches}) none set Insert mode completion
Bram Moolenaar572cb562005-08-05 21:35:02 +00001715complete_add( {expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00001716complete_check() Number check for key typed during completion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001717confirm( {msg} [, {choices} [, {default} [, {type}]]])
1718 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001719copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001720cos( {expr}) Float cosine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001721cosh( {expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001722count( {list}, {expr} [, {start} [, {ic}]])
1723 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001724cscope_connection( [{num} , {dbpath} [, {prepend}]])
1725 Number checks existence of cscope connection
Bram Moolenaar0b238792006-03-02 22:49:12 +00001726cursor( {lnum}, {col} [, {coladd}])
1727 Number move cursor to {lnum}, {col}, {coladd}
1728cursor( {list}) Number move cursor to position in {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001729deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001730delete( {fname}) Number delete file {fname}
1731did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001732diff_filler( {lnum}) Number diff filler lines about {lnum}
1733diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001734empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001735escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaare2cc9702005-03-15 22:43:58 +00001736eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001737eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001738executable( {expr}) Number 1 if executable {expr} exists
1739exists( {expr}) Number TRUE if {expr} exists
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001740extend( {expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001741 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001742exp( {expr}) Float exponential of {expr}
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00001743expand( {expr} [, {flag}]) String expand special keywords in {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001744feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001745filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001746filewritable( {file}) Number TRUE if {file} is a writable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001747filter( {expr}, {string}) List/Dict remove items from {expr} where
1748 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001749finddir( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001750 String find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001751findfile( {name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001752 String find file {name} in {path}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001753float2nr( {expr}) Number convert Float {expr} to a Number
1754floor( {expr}) Float round {expr} down
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001755fmod( {expr1}, {expr2}) Float remainder of {expr1} / {expr2}
Bram Moolenaaraebaf892008-05-28 14:49:58 +00001756fnameescape( {fname}) String escape special characters in {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001757fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001758foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1759foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001760foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001761foldtext( ) String line displayed for closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001762foldtextresult( {lnum}) String text for closed fold at {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001763foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001764function( {name}) Funcref reference to function {name}
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00001765garbagecollect( [at_exit]) none free memory, breaking cyclic references
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001766get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001767get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar45360022005-07-21 21:08:21 +00001768getbufline( {expr}, {lnum} [, {end}])
1769 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001770getbufvar( {expr}, {varname}) any variable {varname} in buffer {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001771getchar( [expr]) Number get one character from the user
1772getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001773getcmdline() String return the current command-line
1774getcmdpos() Number return cursor position in command-line
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001775getcmdtype() String return the current command-line type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001776getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001777getfperm( {fname}) String file permissions of file {fname}
1778getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001779getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001780getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001781getftype( {fname}) String description of type of file {fname}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001782getline( {lnum}) String line {lnum} of current buffer
1783getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001784getloclist( {nr}) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001785getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00001786getpid() Number process ID of Vim
Bram Moolenaar0b238792006-03-02 22:49:12 +00001787getpos( {expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001788getqflist() List list of quickfix items
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001789getreg( [{regname} [, 1]]) String contents of register
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001790getregtype( [{regname}]) String type of register
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001791gettabvar( {nr}, {varname}) any variable {varname} in tab {nr}
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001792gettabwinvar( {tabnr}, {winnr}, {name})
1793 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001794getwinposx() Number X coord in pixels of GUI Vim window
1795getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001796getwinvar( {nr}, {varname}) any variable {varname} in window {nr}
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00001797glob( {expr} [, {flag}]) String expand file wildcards in {expr}
1798globpath( {path}, {expr} [, {flag}])
1799 String do glob({expr}) for all dirs in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001800has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001801has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaard267b9c2007-04-26 15:06:45 +00001802haslocaldir() Number TRUE if current window executed |:lcd|
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001803hasmapto( {what} [, {mode} [, {abbr}]])
1804 Number TRUE if mapping to {what} exists
Bram Moolenaar071d4272004-06-13 20:20:40 +00001805histadd( {history},{item}) String add an item to a history
1806histdel( {history} [, {item}]) String remove an item from a history
1807histget( {history} [, {index}]) String get the item {index} from a history
1808histnr( {history}) Number highest index of a history
1809hlexists( {name}) Number TRUE if highlight group {name} exists
1810hlID( {name}) Number syntax ID of highlight group {name}
1811hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001812iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1813indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001814index( {list}, {expr} [, {start} [, {ic}]])
1815 Number index in {list} where {expr} appears
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001816input( {prompt} [, {text} [, {completion}]])
1817 String get input from the user
Bram Moolenaar071d4272004-06-13 20:20:40 +00001818inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001819inputlist( {textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001820inputrestore() Number restore typeahead
1821inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001822inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001823insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001824isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001825islocked( {expr}) Number TRUE if {expr} is locked
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001826items( {dict}) List key-value pairs in {dict}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001827join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001828keys( {dict}) List keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001829len( {expr}) Number the length of {expr}
1830libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001831libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1832line( {expr}) Number line nr of cursor, last line or mark
1833line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001834lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001835localtime() Number current time
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001836log( {expr}) Float natural logarithm (base e) of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001837log10( {expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001838map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaarbd743252010-10-20 21:23:33 +02001839maparg( {name}[, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001840 String rhs of mapping {name} in mode {mode}
1841mapcheck( {name}[, {mode} [, {abbr}]])
1842 String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001843match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001844 Number position where {pat} matches in {expr}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001845matchadd( {group}, {pattern}[, {priority}[, {id}]])
1846 Number highlight {pattern} with {group}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001847matcharg( {nr}) List arguments of |:match|
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001848matchdelete( {id}) Number delete match identified by {id}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001849matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001850 Number position where {pat} ends in {expr}
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001851matchlist( {expr}, {pat}[, {start}[, {count}]])
1852 List match and submatches of {pat} in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001853matchstr( {expr}, {pat}[, {start}[, {count}]])
1854 String {count}'th match of {pat} in {expr}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001855max( {list}) Number maximum value of items in {list}
1856min( {list}) Number minimum value of items in {list}
1857mkdir( {name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001858 Number create directory {name}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001859mode( [expr]) String current editing mode
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001860mzeval( {expr}) any evaluate |MzScheme| expression
Bram Moolenaar071d4272004-06-13 20:20:40 +00001861nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1862nr2char( {expr}) String single char with ASCII value {expr}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001863pathshorten( {expr}) String shorten directory names in a path
Bram Moolenaar446cb832008-06-24 21:56:24 +00001864pow( {x}, {y}) Float {x} to the power of {y}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001865prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001866printf( {fmt}, {expr1}...) String format text
1867pumvisible() Number whether popup menu is visible
Bram Moolenaard8b02732005-01-14 21:48:43 +00001868range( {expr} [, {max} [, {stride}]])
1869 List items from {expr} to {max}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001870readfile( {fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00001871 List get list of lines from file {fname}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001872reltime( [{start} [, {end}]]) List get time value
1873reltimestr( {time}) String turn time value into a String
Bram Moolenaar071d4272004-06-13 20:20:40 +00001874remote_expr( {server}, {string} [, {idvar}])
1875 String send expression
1876remote_foreground( {server}) Number bring Vim server to the foreground
1877remote_peek( {serverid} [, {retvar}])
1878 Number check for reply string
1879remote_read( {serverid}) String read reply string
1880remote_send( {server}, {string} [, {idvar}])
1881 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001882remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001883remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001884rename( {from}, {to}) Number rename (move) file from {from} to {to}
1885repeat( {expr}, {count}) String repeat {expr} {count} times
1886resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001887reverse( {list}) List reverse {list} in-place
Bram Moolenaar446cb832008-06-24 21:56:24 +00001888round( {expr}) Float round off {expr}
Bram Moolenaar76929292008-01-06 19:07:36 +00001889search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1890 Number search for {pattern}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001891searchdecl( {name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00001892 Number search for variable declaration
Bram Moolenaar76929292008-01-06 19:07:36 +00001893searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001894 Number search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00001895searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001896 List search for other end of start/end pair
Bram Moolenaar76929292008-01-06 19:07:36 +00001897searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001898 List search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001899server2client( {clientid}, {string})
1900 Number send reply string
1901serverlist() String get a list of available servers
1902setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1903setcmdpos( {pos}) Number set cursor position in command-line
1904setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001905setloclist( {nr}, {list}[, {action}])
1906 Number modify location list using {list}
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001907setmatches( {list}) Number restore a list of matches
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001908setpos( {expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaar17c7c012006-01-26 22:25:15 +00001909setqflist( {list}[, {action}]) Number modify quickfix list using {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001910setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001911settabvar( {nr}, {varname}, {val}) set {varname} in tab page {nr} to {val}
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001912settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1913 {winnr} in tab page {tabnr} to {val}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001914setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaar05bb9532008-07-04 09:44:11 +00001915shellescape( {string} [, {special}])
1916 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00001917 command argument
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001918simplify( {filename}) String simplify filename as much as possible
Bram Moolenaar446cb832008-06-24 21:56:24 +00001919sin( {expr}) Float sine of {expr}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001920sinh( {expr}) Float hyperbolic sine of {expr}
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001921sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001922soundfold( {word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00001923spellbadword() String badly spelled word at cursor
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00001924spellsuggest( {word} [, {max} [, {capital}]])
1925 List spelling suggestions
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00001926split( {expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001927 List make |List| from {pat} separated {expr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01001928sqrt( {expr}) Float square root of {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001929str2float( {expr}) Float convert String to Float
1930str2nr( {expr} [, {base}]) Number convert String to Number
Bram Moolenaar72597a52010-07-18 15:31:08 +02001931strchars( {expr}) Number character length of the String {expr}
Bram Moolenaardc536092010-07-18 15:45:49 +02001932strdisplaywidth( {expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001933strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001934stridx( {haystack}, {needle}[, {start}])
1935 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001936string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001937strlen( {expr}) Number length of the String {expr}
1938strpart( {src}, {start}[, {len}])
1939 String {len} characters of {src} at {start}
Bram Moolenaar677ee682005-01-27 14:41:15 +00001940strridx( {haystack}, {needle} [, {start}])
1941 Number last index of {needle} in {haystack}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001942strtrans( {expr}) String translate string to make it printable
Bram Moolenaar72597a52010-07-18 15:31:08 +02001943strwidth( {expr}) Number display cell length of the String {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001944submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001945substitute( {expr}, {pat}, {sub}, {flags})
1946 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001947synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001948synIDattr( {synID}, {what} [, {mode}])
1949 String attribute {what} of syntax ID {synID}
1950synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001951synconcealed( {lnum}, {col}) List info about concealing
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001952synstack( {lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001953system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001954tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1955tabpagenr( [{arg}]) Number number of current or last tab page
1956tabpagewinnr( {tabarg}[, {arg}])
1957 Number number of current window in tab page
1958taglist( {expr}) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001959tagfiles() List tags files used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001960tempname() String name for a temporary file
Bram Moolenaardb7c6862010-05-21 16:33:48 +02001961tan( {expr}) Float tangent of {expr}
1962tanh( {expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001963tolower( {expr}) String the String {expr} switched to lowercase
1964toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001965tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1966 to chars in {tostr}
Bram Moolenaard58e9292011-02-09 17:07:58 +01001967trunc( {expr}) Float truncate Float {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001968type( {name}) Number type of variable {name}
Bram Moolenaara17d4c12010-05-30 18:30:36 +02001969undofile( {name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02001970undotree() List undo file tree
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001971values( {dict}) List values in {dict}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001972virtcol( {expr}) Number screen column of cursor or mark
1973visualmode( [expr]) String last visual mode used
1974winbufnr( {nr}) Number buffer number of window {nr}
1975wincol() Number window column of the cursor
1976winheight( {nr}) Number height of window {nr}
1977winline() Number window line of the cursor
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00001978winnr( [{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001979winrestcmd() String returns command to restore window sizes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001980winrestview( {dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00001981winsaveview() Dict save view of current window
Bram Moolenaar071d4272004-06-13 20:20:40 +00001982winwidth( {nr}) Number width of window {nr}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001983writefile( {list}, {fname} [, {binary}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00001984 Number write list of lines to file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001985
Bram Moolenaar446cb832008-06-24 21:56:24 +00001986abs({expr}) *abs()*
1987 Return the absolute value of {expr}. When {expr} evaluates to
1988 a |Float| abs() returns a |Float|. When {expr} can be
1989 converted to a |Number| abs() returns a |Number|. Otherwise
1990 abs() gives an error message and returns -1.
1991 Examples: >
1992 echo abs(1.456)
1993< 1.456 >
1994 echo abs(-5.456)
1995< 5.456 >
1996 echo abs(-4)
1997< 4
1998 {only available when compiled with the |+float| feature}
1999
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002000
2001acos({expr}) *acos()*
2002 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002003 |Float| in the range of [0, pi].
2004 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002005 [-1, 1].
2006 Examples: >
2007 :echo acos(0)
2008< 1.570796 >
2009 :echo acos(-0.5)
2010< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002011 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002012
2013
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002014add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002015 Append the item {expr} to |List| {list}. Returns the
2016 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002017 :let alist = add([1, 2, 3], item)
2018 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002019< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002020 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002021 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002022
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002023
2024append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002025 When {expr} is a |List|: Append each item of the |List| as a
2026 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002027 Otherwise append {expr} as one text line below line {lnum} in
2028 the current buffer.
2029 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002030 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar446cb832008-06-24 21:56:24 +00002031 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002032 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002033 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002034<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002035 *argc()*
2036argc() The result is the number of files in the argument list of the
2037 current window. See |arglist|.
2038
2039 *argidx()*
2040argidx() The result is the current index in the argument list. 0 is
2041 the first file. argc() - 1 is the last one. See |arglist|.
2042
2043 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002044argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002045 current window. See |arglist|. "argv(0)" is the first one.
2046 Example: >
2047 :let i = 0
2048 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002049 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002050 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2051 : let i = i + 1
2052 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002053< Without the {nr} argument a |List| with the whole |arglist| is
2054 returned.
2055
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002056asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002057 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002058 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002059 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002060 [-1, 1].
2061 Examples: >
2062 :echo asin(0.8)
2063< 0.927295 >
2064 :echo asin(-0.5)
2065< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002066 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002067
2068
Bram Moolenaar446cb832008-06-24 21:56:24 +00002069atan({expr}) *atan()*
2070 Return the principal value of the arc tangent of {expr}, in
2071 the range [-pi/2, +pi/2] radians, as a |Float|.
2072 {expr} must evaluate to a |Float| or a |Number|.
2073 Examples: >
2074 :echo atan(100)
2075< 1.560797 >
2076 :echo atan(-4.01)
2077< -1.326405
2078 {only available when compiled with the |+float| feature}
2079
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002080
2081atan2({expr1}, {expr2}) *atan2()*
2082 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002083 radians, as a |Float| in the range [-pi, pi].
2084 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002085 Examples: >
2086 :echo atan2(-1, 1)
2087< -0.785398 >
2088 :echo atan2(1, -1)
2089< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002090 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002091
2092
Bram Moolenaar071d4272004-06-13 20:20:40 +00002093 *browse()*
2094browse({save}, {title}, {initdir}, {default})
2095 Put up a file requester. This only works when "has("browse")"
2096 returns non-zero (only in some GUI versions).
2097 The input fields are:
2098 {save} when non-zero, select file to write
2099 {title} title for the requester
2100 {initdir} directory to start browsing in
2101 {default} default file name
2102 When the "Cancel" button is hit, something went wrong, or
2103 browsing is not possible, an empty string is returned.
2104
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002105 *browsedir()*
2106browsedir({title}, {initdir})
2107 Put up a directory requester. This only works when
2108 "has("browse")" returns non-zero (only in some GUI versions).
2109 On systems where a directory browser is not supported a file
2110 browser is used. In that case: select a file in the directory
2111 to be used.
2112 The input fields are:
2113 {title} title for the requester
2114 {initdir} directory to start browsing in
2115 When the "Cancel" button is hit, something went wrong, or
2116 browsing is not possible, an empty string is returned.
2117
Bram Moolenaar071d4272004-06-13 20:20:40 +00002118bufexists({expr}) *bufexists()*
2119 The result is a Number, which is non-zero if a buffer called
2120 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002121 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002122 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002123 exactly. The name can be:
2124 - Relative to the current directory.
2125 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002126 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002127 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002128 Unlisted buffers will be found.
2129 Note that help files are listed by their short name in the
2130 output of |:buffers|, but bufexists() requires using their
2131 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002132 bufexists() may report a buffer exists, but to use the name
2133 with a |:buffer| command you may need to use |expand()|. Esp
2134 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002135 Use "bufexists(0)" to test for the existence of an alternate
2136 file name.
2137 *buffer_exists()*
2138 Obsolete name: buffer_exists().
2139
2140buflisted({expr}) *buflisted()*
2141 The result is a Number, which is non-zero if a buffer called
2142 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002143 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002144
2145bufloaded({expr}) *bufloaded()*
2146 The result is a Number, which is non-zero if a buffer called
2147 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002148 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002149
2150bufname({expr}) *bufname()*
2151 The result is the name of a buffer, as it is displayed by the
2152 ":ls" command.
2153 If {expr} is a Number, that buffer number's name is given.
2154 Number zero is the alternate buffer for the current window.
2155 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002156 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002157 set and 'cpoptions' is empty. When there is more than one
2158 match an empty string is returned.
2159 "" or "%" can be used for the current buffer, "#" for the
2160 alternate buffer.
2161 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002162 or middle of the buffer name is accepted. If you only want a
2163 full match then put "^" at the start and "$" at the end of the
2164 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002165 Listed buffers are found first. If there is a single match
2166 with a listed buffer, that one is returned. Next unlisted
2167 buffers are searched for.
2168 If the {expr} is a String, but you want to use it as a buffer
2169 number, force it to be a Number by adding zero to it: >
2170 :echo bufname("3" + 0)
2171< If the buffer doesn't exist, or doesn't have a name, an empty
2172 string is returned. >
2173 bufname("#") alternate buffer name
2174 bufname(3) name of buffer 3
2175 bufname("%") name of current buffer
2176 bufname("file2") name of buffer where "file2" matches.
2177< *buffer_name()*
2178 Obsolete name: buffer_name().
2179
2180 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002181bufnr({expr} [, {create}])
2182 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002183 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002184 above.
2185 If the buffer doesn't exist, -1 is returned. Or, if the
2186 {create} argument is present and not zero, a new, unlisted,
2187 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002188 bufnr("$") is the last buffer: >
2189 :let last_buffer = bufnr("$")
2190< The result is a Number, which is the highest buffer number
2191 of existing buffers. Note that not all buffers with a smaller
2192 number necessarily exist, because ":bwipeout" may have removed
2193 them. Use bufexists() to test for the existence of a buffer.
2194 *buffer_number()*
2195 Obsolete name: buffer_number().
2196 *last_buffer_nr()*
2197 Obsolete name for bufnr("$"): last_buffer_nr().
2198
2199bufwinnr({expr}) *bufwinnr()*
2200 The result is a Number, which is the number of the first
2201 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar446cb832008-06-24 21:56:24 +00002202 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002203 there is no such window, -1 is returned. Example: >
2204
2205 echo "A window containing buffer 1 is " . (bufwinnr(1))
2206
2207< The number can be used with |CTRL-W_w| and ":wincmd w"
2208 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002209 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002210
2211
2212byte2line({byte}) *byte2line()*
2213 Return the line number that contains the character at byte
2214 count {byte} in the current buffer. This includes the
2215 end-of-line character, depending on the 'fileformat' option
2216 for the current buffer. The first character has byte count
2217 one.
2218 Also see |line2byte()|, |go| and |:goto|.
2219 {not available when compiled without the |+byte_offset|
2220 feature}
2221
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002222byteidx({expr}, {nr}) *byteidx()*
2223 Return byte index of the {nr}'th character in the string
2224 {expr}. Use zero for the first character, it returns zero.
2225 This function is only useful when there are multibyte
2226 characters, otherwise the returned value is equal to {nr}.
2227 Composing characters are counted as a separate character.
2228 Example : >
2229 echo matchstr(str, ".", byteidx(str, 3))
2230< will display the fourth character. Another way to do the
2231 same: >
2232 let s = strpart(str, byteidx(str, 3))
2233 echo strpart(s, 0, byteidx(s, 1))
2234< If there are less than {nr} characters -1 is returned.
2235 If there are exactly {nr} characters the length of the string
2236 is returned.
2237
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002238call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002239 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002240 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002241 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002242 a:firstline and a:lastline are set to the cursor line.
2243 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002244 {dict} is for functions with the "dict" attribute. It will be
2245 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002246
Bram Moolenaar446cb832008-06-24 21:56:24 +00002247ceil({expr}) *ceil()*
2248 Return the smallest integral value greater than or equal to
2249 {expr} as a |Float| (round up).
2250 {expr} must evaluate to a |Float| or a |Number|.
2251 Examples: >
2252 echo ceil(1.456)
2253< 2.0 >
2254 echo ceil(-5.456)
2255< -5.0 >
2256 echo ceil(4.0)
2257< 4.0
2258 {only available when compiled with the |+float| feature}
2259
Bram Moolenaarca003e12006-03-17 23:19:38 +00002260changenr() *changenr()*
2261 Return the number of the most recent change. This is the same
2262 number as what is displayed with |:undolist| and can be used
2263 with the |:undo| command.
2264 When a change was made it is the number of that change. After
2265 redo it is the number of the redone change. After undo it is
2266 one less than the number of the undone change.
2267
Bram Moolenaar071d4272004-06-13 20:20:40 +00002268char2nr({expr}) *char2nr()*
2269 Return number value of the first char in {expr}. Examples: >
2270 char2nr(" ") returns 32
2271 char2nr("ABC") returns 65
2272< The current 'encoding' is used. Example for "utf-8": >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002273 char2nr("á") returns 225
2274 char2nr("á"[0]) returns 195
Bram Moolenaar446cb832008-06-24 21:56:24 +00002275< |nr2char()| does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002276
2277cindent({lnum}) *cindent()*
2278 Get the amount of indent for line {lnum} according the C
2279 indenting rules, as with 'cindent'.
2280 The indent is counted in spaces, the value of 'tabstop' is
2281 relevant. {lnum} is used just like in |getline()|.
2282 When {lnum} is invalid or Vim was not compiled the |+cindent|
2283 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00002284 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002285
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002286clearmatches() *clearmatches()*
2287 Clears all matches previously defined by |matchadd()| and the
2288 |:match| commands.
2289
Bram Moolenaar071d4272004-06-13 20:20:40 +00002290 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002291col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00002292 position given with {expr}. The accepted positions are:
2293 . the cursor position
2294 $ the end of the cursor line (the result is the
2295 number of characters in the cursor line plus one)
2296 'x position of mark x (if the mark is not set, 0 is
2297 returned)
Bram Moolenaar477933c2007-07-17 14:32:23 +00002298 Additionally {expr} can be [lnum, col]: a |List| with the line
2299 and column number. Most useful when the column is "$", to get
Bram Moolenaar446cb832008-06-24 21:56:24 +00002300 the last column of a specific line. When "lnum" or "col" is
Bram Moolenaar477933c2007-07-17 14:32:23 +00002301 out of range then col() returns zero.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002302 To get the line number use |line()|. To get both use
Bram Moolenaar0b238792006-03-02 22:49:12 +00002303 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002304 For the screen column position use |virtcol()|.
2305 Note that only marks in the current file can be used.
2306 Examples: >
2307 col(".") column of cursor
2308 col("$") length of cursor line plus one
2309 col("'t") column of mark t
2310 col("'" . markname) column of mark markname
Bram Moolenaar446cb832008-06-24 21:56:24 +00002311< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002312 For an uppercase mark the column may actually be in another
2313 buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002314 For the cursor position, when 'virtualedit' is active, the
2315 column is one higher if the cursor is after the end of the
2316 line. This can be used to obtain the column in Insert mode: >
2317 :imap <F2> <C-O>:let save_ve = &ve<CR>
2318 \<C-O>:set ve=all<CR>
2319 \<C-O>:echo col(".") . "\n" <Bar>
2320 \let &ve = save_ve<CR>
2321<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002322
Bram Moolenaara94bc432006-03-10 21:42:59 +00002323complete({startcol}, {matches}) *complete()* *E785*
2324 Set the matches for Insert mode completion.
2325 Can only be used in Insert mode. You need to use a mapping
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002326 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2327 with an expression mapping.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002328 {startcol} is the byte offset in the line where the completed
2329 text start. The text up to the cursor is the original text
2330 that will be replaced by the matches. Use col('.') for an
2331 empty string. "col('.') - 1" will replace one character by a
2332 match.
2333 {matches} must be a |List|. Each |List| item is one match.
2334 See |complete-items| for the kind of items that are possible.
2335 Note that the after calling this function you need to avoid
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002336 inserting anything that would cause completion to stop.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002337 The match can be selected with CTRL-N and CTRL-P as usual with
2338 Insert mode completion. The popup menu will appear if
2339 specified, see |ins-completion-menu|.
2340 Example: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002341 inoremap <F5> <C-R>=ListMonths()<CR>
Bram Moolenaara94bc432006-03-10 21:42:59 +00002342
2343 func! ListMonths()
2344 call complete(col('.'), ['January', 'February', 'March',
2345 \ 'April', 'May', 'June', 'July', 'August', 'September',
2346 \ 'October', 'November', 'December'])
2347 return ''
2348 endfunc
2349< This isn't very useful, but it shows how it works. Note that
2350 an empty string is returned to avoid a zero being inserted.
2351
Bram Moolenaar572cb562005-08-05 21:35:02 +00002352complete_add({expr}) *complete_add()*
2353 Add {expr} to the list of matches. Only to be used by the
2354 function specified with the 'completefunc' option.
2355 Returns 0 for failure (empty string or out of memory),
2356 1 when the match was added, 2 when the match was already in
2357 the list.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002358 See |complete-functions| for an explanation of {expr}. It is
Bram Moolenaar39f05632006-03-19 22:15:26 +00002359 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002360
2361complete_check() *complete_check()*
2362 Check for a key typed while looking for completion matches.
2363 This is to be used when looking for matches takes some time.
2364 Returns non-zero when searching for matches is to be aborted,
2365 zero otherwise.
2366 Only to be used by the function specified with the
2367 'completefunc' option.
2368
Bram Moolenaar071d4272004-06-13 20:20:40 +00002369 *confirm()*
2370confirm({msg} [, {choices} [, {default} [, {type}]]])
2371 Confirm() offers the user a dialog, from which a choice can be
2372 made. It returns the number of the choice. For the first
2373 choice this is 1.
2374 Note: confirm() is only supported when compiled with dialog
2375 support, see |+dialog_con| and |+dialog_gui|.
Bram Moolenaara800b422010-06-27 01:15:55 +02002376
Bram Moolenaar071d4272004-06-13 20:20:40 +00002377 {msg} is displayed in a |dialog| with {choices} as the
2378 alternatives. When {choices} is missing or empty, "&OK" is
2379 used (and translated).
2380 {msg} is a String, use '\n' to include a newline. Only on
2381 some systems the string is wrapped when it doesn't fit.
Bram Moolenaara800b422010-06-27 01:15:55 +02002382
Bram Moolenaar071d4272004-06-13 20:20:40 +00002383 {choices} is a String, with the individual choices separated
2384 by '\n', e.g. >
2385 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2386< The letter after the '&' is the shortcut key for that choice.
2387 Thus you can type 'c' to select "Cancel". The shortcut does
2388 not need to be the first letter: >
2389 confirm("file has been modified", "&Save\nSave &All")
2390< For the console, the first letter of each choice is used as
2391 the default shortcut key.
Bram Moolenaara800b422010-06-27 01:15:55 +02002392
Bram Moolenaar071d4272004-06-13 20:20:40 +00002393 The optional {default} argument is the number of the choice
2394 that is made if the user hits <CR>. Use 1 to make the first
2395 choice the default one. Use 0 to not set a default. If
2396 {default} is omitted, 1 is used.
Bram Moolenaara800b422010-06-27 01:15:55 +02002397
2398 The optional {type} argument gives the type of dialog. This
2399 is only used for the icon of the GTK, Mac, Motif and Win32
2400 GUI. It can be one of these values: "Error", "Question",
2401 "Info", "Warning" or "Generic". Only the first character is
2402 relevant. When {type} is omitted, "Generic" is used.
2403
Bram Moolenaar071d4272004-06-13 20:20:40 +00002404 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2405 or another valid interrupt key, confirm() returns 0.
2406
2407 An example: >
2408 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2409 :if choice == 0
2410 : echo "make up your mind!"
2411 :elseif choice == 3
2412 : echo "tasteful"
2413 :else
2414 : echo "I prefer bananas myself."
2415 :endif
2416< In a GUI dialog, buttons are used. The layout of the buttons
2417 depends on the 'v' flag in 'guioptions'. If it is included,
Bram Moolenaar446cb832008-06-24 21:56:24 +00002418 the buttons are always put vertically. Otherwise, confirm()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002419 tries to put the buttons in one horizontal line. If they
2420 don't fit, a vertical layout is used anyway. For some systems
2421 the horizontal layout is always used.
2422
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002423 *copy()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002424copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002425 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002426 When {expr} is a |List| a shallow copy is created. This means
2427 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002428 copy, and vice versa. But the items are identical, thus
2429 changing an item changes the contents of both |Lists|. Also
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002430 see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002431
Bram Moolenaar446cb832008-06-24 21:56:24 +00002432cos({expr}) *cos()*
2433 Return the cosine of {expr}, measured in radians, as a |Float|.
2434 {expr} must evaluate to a |Float| or a |Number|.
2435 Examples: >
2436 :echo cos(100)
2437< 0.862319 >
2438 :echo cos(-4.01)
2439< -0.646043
2440 {only available when compiled with the |+float| feature}
2441
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002442
2443cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002444 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002445 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002446 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002447 Examples: >
2448 :echo cosh(0.5)
2449< 1.127626 >
2450 :echo cosh(-0.5)
2451< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02002452 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002453
Bram Moolenaar446cb832008-06-24 21:56:24 +00002454
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002455count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002456 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002457 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002458 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002459 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002460 When {ic} is given and it's non-zero then case is ignored.
2461
2462
Bram Moolenaar071d4272004-06-13 20:20:40 +00002463 *cscope_connection()*
2464cscope_connection([{num} , {dbpath} [, {prepend}]])
2465 Checks for the existence of a |cscope| connection. If no
2466 parameters are specified, then the function returns:
2467 0, if cscope was not available (not compiled in), or
2468 if there are no cscope connections;
2469 1, if there is at least one cscope connection.
2470
2471 If parameters are specified, then the value of {num}
2472 determines how existence of a cscope connection is checked:
2473
2474 {num} Description of existence check
2475 ----- ------------------------------
2476 0 Same as no parameters (e.g., "cscope_connection()").
2477 1 Ignore {prepend}, and use partial string matches for
2478 {dbpath}.
2479 2 Ignore {prepend}, and use exact string matches for
2480 {dbpath}.
2481 3 Use {prepend}, use partial string matches for both
2482 {dbpath} and {prepend}.
2483 4 Use {prepend}, use exact string matches for both
2484 {dbpath} and {prepend}.
2485
2486 Note: All string comparisons are case sensitive!
2487
2488 Examples. Suppose we had the following (from ":cs show"): >
2489
2490 # pid database name prepend path
2491 0 27664 cscope.out /usr/local
2492<
2493 Invocation Return Val ~
2494 ---------- ---------- >
2495 cscope_connection() 1
2496 cscope_connection(1, "out") 1
2497 cscope_connection(2, "out") 0
2498 cscope_connection(3, "out") 0
2499 cscope_connection(3, "out", "local") 1
2500 cscope_connection(4, "out") 0
2501 cscope_connection(4, "out", "local") 0
2502 cscope_connection(4, "cscope.out", "/usr/local") 1
2503<
Bram Moolenaar0b238792006-03-02 22:49:12 +00002504cursor({lnum}, {col} [, {off}]) *cursor()*
2505cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002506 Positions the cursor at the column (byte count) {col} in the
2507 line {lnum}. The first column is one.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002508 When there is one argument {list} this is used as a |List|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002509 with two or three items {lnum}, {col} and {off}. This is like
2510 the return value of |getpos()|, but without the first item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002511 Does not change the jumplist.
2512 If {lnum} is greater than the number of lines in the buffer,
2513 the cursor will be positioned at the last line in the buffer.
2514 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00002515 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002516 the cursor will be positioned at the last character in the
2517 line.
2518 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar0b238792006-03-02 22:49:12 +00002519 When 'virtualedit' is used {off} specifies the offset in
2520 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00002521 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00002522 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002523
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002524
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002525deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002526 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002527 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002528 When {expr} is a |List| a full copy is created. This means
2529 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002530 copy, and vice versa. When an item is a |List|, a copy for it
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002531 is made, recursively. Thus changing an item in the copy does
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002532 not change the contents of the original |List|.
2533 When {noref} is omitted or zero a contained |List| or
2534 |Dictionary| is only copied once. All references point to
2535 this single copy. With {noref} set to 1 every occurrence of a
2536 |List| or |Dictionary| results in a new copy. This also means
2537 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002538 *E724*
2539 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002540 that refers back to a higher level making a deep copy with
2541 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002542 Also see |copy()|.
2543
2544delete({fname}) *delete()*
2545 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00002546 which is 0 if the file was deleted successfully, and non-zero
2547 when the deletion failed.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002548 Use |remove()| to delete an item from a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002549
2550 *did_filetype()*
2551did_filetype() Returns non-zero when autocommands are being executed and the
2552 FileType event has been triggered at least once. Can be used
2553 to avoid triggering the FileType event again in the scripts
2554 that detect the file type. |FileType|
2555 When editing another file, the counter is reset, thus this
2556 really checks if the FileType event has been triggered for the
2557 current buffer. This allows an autocommand that starts
2558 editing another buffer to set 'filetype' and load a syntax
2559 file.
2560
Bram Moolenaar47136d72004-10-12 20:02:24 +00002561diff_filler({lnum}) *diff_filler()*
2562 Returns the number of filler lines above line {lnum}.
2563 These are the lines that were inserted at this point in
2564 another diff'ed window. These filler lines are shown in the
2565 display but don't exist in the buffer.
2566 {lnum} is used like with |getline()|. Thus "." is the current
2567 line, "'m" mark m, etc.
2568 Returns 0 if the current window is not in diff mode.
2569
2570diff_hlID({lnum}, {col}) *diff_hlID()*
2571 Returns the highlight ID for diff mode at line {lnum} column
2572 {col} (byte index). When the current line does not have a
2573 diff change zero is returned.
2574 {lnum} is used like with |getline()|. Thus "." is the current
2575 line, "'m" mark m, etc.
2576 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2577 line.
2578 The highlight ID can be used with |synIDattr()| to obtain
2579 syntax information about the highlighting.
2580
Bram Moolenaar13065c42005-01-08 16:08:21 +00002581empty({expr}) *empty()*
2582 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002583 A |List| or |Dictionary| is empty when it does not have any
Bram Moolenaar446cb832008-06-24 21:56:24 +00002584 items. A Number is empty when its value is zero.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002585 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002586 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002587
Bram Moolenaar071d4272004-06-13 20:20:40 +00002588escape({string}, {chars}) *escape()*
2589 Escape the characters in {chars} that occur in {string} with a
2590 backslash. Example: >
2591 :echo escape('c:\program files\vim', ' \')
2592< results in: >
2593 c:\\program\ files\\vim
Bram Moolenaar446cb832008-06-24 21:56:24 +00002594< Also see |shellescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002595
Bram Moolenaar446cb832008-06-24 21:56:24 +00002596 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002597eval({string}) Evaluate {string} and return the result. Especially useful to
2598 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002599 This works for Numbers, Floats, Strings and composites of
2600 them. Also works for |Funcref|s that refer to existing
2601 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002602
Bram Moolenaar071d4272004-06-13 20:20:40 +00002603eventhandler() *eventhandler()*
2604 Returns 1 when inside an event handler. That is that Vim got
2605 interrupted while waiting for the user to type a character,
2606 e.g., when dropping a file on Vim. This means interactive
2607 commands cannot be used. Otherwise zero is returned.
2608
2609executable({expr}) *executable()*
2610 This function checks if an executable with the name {expr}
2611 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002612 arguments.
2613 executable() uses the value of $PATH and/or the normal
2614 searchpath for programs. *PATHEXT*
2615 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2616 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar446cb832008-06-24 21:56:24 +00002617 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2618 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002619 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar446cb832008-06-24 21:56:24 +00002620 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002621 Unix shell, then the name is also tried without adding an
2622 extension.
2623 On MS-DOS and MS-Windows it only checks if the file exists and
2624 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002625 On MS-Windows an executable in the same directory as Vim is
2626 always found. Since this directory is added to $PATH it
2627 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002628 The result is a Number:
2629 1 exists
2630 0 does not exist
2631 -1 not implemented on this system
2632
2633 *exists()*
2634exists({expr}) The result is a Number, which is non-zero if {expr} is
2635 defined, zero otherwise. The {expr} argument is a string,
2636 which contains one of these:
2637 &option-name Vim option (only checks if it exists,
2638 not if it really works)
2639 +option-name Vim option that works.
2640 $ENVNAME environment variable (could also be
2641 done by comparing with an empty
2642 string)
2643 *funcname built-in function (see |functions|)
2644 or user defined function (see
2645 |user-functions|).
2646 varname internal variable (see
Bram Moolenaar446cb832008-06-24 21:56:24 +00002647 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002648 for |curly-braces-names|, |Dictionary|
2649 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00002650 that evaluating an index may cause an
2651 error message for an invalid
2652 expression. E.g.: >
2653 :let l = [1, 2, 3]
2654 :echo exists("l[5]")
2655< 0 >
2656 :echo exists("l[xx]")
2657< E121: Undefined variable: xx
2658 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00002659 :cmdname Ex command: built-in command, user
2660 command or command modifier |:command|.
2661 Returns:
2662 1 for match with start of a command
2663 2 full match with a command
2664 3 matches several user commands
2665 To check for a supported command
2666 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00002667 :2match The |:2match| command.
2668 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002669 #event autocommand defined for this event
2670 #event#pattern autocommand defined for this event and
2671 pattern (the pattern is taken
2672 literally and compared to the
2673 autocommand patterns character by
2674 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002675 #group autocommand group exists
2676 #group#event autocommand defined for this group and
2677 event.
2678 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002679 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002680 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002681 ##event autocommand for this event is
2682 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002683 For checking for a supported feature use |has()|.
2684
2685 Examples: >
2686 exists("&shortname")
2687 exists("$HOSTNAME")
2688 exists("*strftime")
2689 exists("*s:MyFunc")
2690 exists("bufcount")
2691 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002692 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002693 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00002694 exists("#filetypeindent")
2695 exists("#filetypeindent#FileType")
2696 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00002697 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002698< There must be no space between the symbol (&/$/*/#) and the
2699 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00002700 There must be no extra characters after the name, although in
2701 a few cases this is ignored. That may become more strict in
2702 the future, thus don't count on it!
2703 Working example: >
2704 exists(":make")
2705< NOT working example: >
2706 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00002707
2708< Note that the argument must be a string, not the name of the
2709 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002710 exists(bufcount)
2711< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00002712 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002713
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002714exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002715 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002716 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002717 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002718 Examples: >
2719 :echo exp(2)
2720< 7.389056 >
2721 :echo exp(-1)
2722< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02002723 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002724
2725
Bram Moolenaar071d4272004-06-13 20:20:40 +00002726expand({expr} [, {flag}]) *expand()*
2727 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar81af9252010-12-10 20:35:50 +01002728 The result is a String. 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002729
2730 When there are several matches, they are separated by <NL>
2731 characters. [Note: in version 5.0 a space was used, which
2732 caused problems when a file name contains a space]
2733
Bram Moolenaar446cb832008-06-24 21:56:24 +00002734 If the expansion fails, the result is an empty string. A name
Bram Moolenaar071d4272004-06-13 20:20:40 +00002735 for a non-existing file is not included.
2736
2737 When {expr} starts with '%', '#' or '<', the expansion is done
2738 like for the |cmdline-special| variables with their associated
2739 modifiers. Here is a short overview:
2740
2741 % current file name
2742 # alternate file name
2743 #n alternate file name n
2744 <cfile> file name under the cursor
2745 <afile> autocmd file name
2746 <abuf> autocmd buffer number (as a String!)
2747 <amatch> autocmd matched name
2748 <sfile> sourced script file name
Bram Moolenaar81af9252010-12-10 20:35:50 +01002749 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00002750 <cword> word under the cursor
2751 <cWORD> WORD under the cursor
2752 <client> the {clientid} of the last received
2753 message |server2client()|
2754 Modifiers:
2755 :p expand to full path
2756 :h head (last path component removed)
2757 :t tail (last path component only)
2758 :r root (one extension removed)
2759 :e extension only
2760
2761 Example: >
2762 :let &tags = expand("%:p:h") . "/tags"
2763< Note that when expanding a string that starts with '%', '#' or
2764 '<', any following text is ignored. This does NOT work: >
2765 :let doesntwork = expand("%:h.bak")
2766< Use this: >
2767 :let doeswork = expand("%:h") . ".bak"
2768< Also note that expanding "<cfile>" and others only returns the
2769 referenced file name without further expansion. If "<cfile>"
2770 is "~/.cshrc", you need to do another expand() to have the
2771 "~/" expanded into the path of the home directory: >
2772 :echo expand(expand("<cfile>"))
2773<
2774 There cannot be white space between the variables and the
2775 following modifier. The |fnamemodify()| function can be used
2776 to modify normal file names.
2777
2778 When using '%' or '#', and the current or alternate file name
2779 is not defined, an empty string is used. Using "%:p" in a
2780 buffer with no name, results in the current directory, with a
2781 '/' added.
2782
2783 When {expr} does not start with '%', '#' or '<', it is
2784 expanded like a file name is expanded on the command line.
2785 'suffixes' and 'wildignore' are used, unless the optional
2786 {flag} argument is given and it is non-zero. Names for
Bram Moolenaar02743632005-07-25 20:42:36 +00002787 non-existing files are included. The "**" item can be used to
2788 search in a directory tree. For example, to find all "README"
2789 files in the current directory and below: >
2790 :echo expand("**/README")
2791<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002792 Expand() can also be used to expand variables and environment
2793 variables that are only known in a shell. But this can be
Bram Moolenaar446cb832008-06-24 21:56:24 +00002794 slow, because a shell must be started. See |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002795 The expanded variable is still handled like a list of file
Bram Moolenaar446cb832008-06-24 21:56:24 +00002796 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002797 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2798 "$FOOBAR".
2799
2800 See |glob()| for finding existing files. See |system()| for
2801 getting the raw output of an external command.
2802
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002803extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002804 {expr1} and {expr2} must be both |Lists| or both
2805 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002806
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002807 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002808 If {expr3} is given insert the items of {expr2} before item
2809 {expr3} in {expr1}. When {expr3} is zero insert before the
2810 first item. When {expr3} is equal to len({expr1}) then
2811 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002812 Examples: >
2813 :echo sort(extend(mylist, [7, 5]))
2814 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00002815< When {expr1} is the same List as {expr2} then the number of
2816 items copied is equal to the original length of the List.
2817 E.g., when {expr3} is 1 you get N new copies of the first item
2818 (where N is the original length of the List).
2819 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002820 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002821 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002822<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002823 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002824 Add all entries from {expr2} to {expr1}.
2825 If a key exists in both {expr1} and {expr2} then {expr3} is
2826 used to decide what to do:
2827 {expr3} = "keep": keep the value of {expr1}
2828 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002829 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002830 When {expr3} is omitted then "force" is assumed.
2831
2832 {expr1} is changed when {expr2} is not empty. If necessary
2833 make a copy of {expr1} first.
2834 {expr2} remains unchanged.
2835 Returns {expr1}.
2836
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002837
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002838feedkeys({string} [, {mode}]) *feedkeys()*
2839 Characters in {string} are queued for processing as if they
Bram Moolenaar446cb832008-06-24 21:56:24 +00002840 come from a mapping or were typed by the user. They are added
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002841 to the end of the typeahead buffer, thus if a mapping is still
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002842 being executed these characters come after them.
2843 The function does not wait for processing of keys contained in
2844 {string}.
2845 To include special keys into {string}, use double-quotes
2846 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00002847 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002848 feedkeys('\<CR>') pushes 5 characters.
2849 If {mode} is absent, keys are remapped.
2850 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00002851 'm' Remap keys. This is default.
2852 'n' Do not remap keys.
2853 't' Handle keys as if typed; otherwise they are handled as
2854 if coming from a mapping. This matters for undo,
2855 opening folds, etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00002856 Return value is always 0.
2857
Bram Moolenaar071d4272004-06-13 20:20:40 +00002858filereadable({file}) *filereadable()*
2859 The result is a Number, which is TRUE when a file with the
2860 name {file} exists, and can be read. If {file} doesn't exist,
2861 or is a directory, the result is FALSE. {file} is any
2862 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002863 If you don't care about the file being readable you can use
2864 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002865 *file_readable()*
2866 Obsolete name: file_readable().
2867
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002868
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002869filewritable({file}) *filewritable()*
2870 The result is a Number, which is 1 when a file with the
2871 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00002872 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002873 directory, and we can write to it, the result is 2.
2874
2875
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002876filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002877 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002878 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002879 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002880 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002881 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002882 Examples: >
2883 :call filter(mylist, 'v:val !~ "OLD"')
2884< Removes the items where "OLD" appears. >
2885 :call filter(mydict, 'v:key >= 8')
2886< Removes the items with a key below 8. >
2887 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002888< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002889
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002890 Note that {string} is the result of expression and is then
2891 used as an expression again. Often it is good to use a
2892 |literal-string| to avoid having to double backslashes.
2893
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002894 The operation is done in-place. If you want a |List| or
2895 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00002896 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002897
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002898< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00002899 When an error is encountered while evaluating {string} no
2900 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002901
2902
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002903finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00002904 Find directory {name} in {path}. Supports both downwards and
2905 upwards recursive directory searches. See |file-searching|
2906 for the syntax of {path}.
2907 Returns the path of the first found match. When the found
2908 directory is below the current directory a relative path is
2909 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002910 If {path} is omitted or empty then 'path' is used.
2911 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002912 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00002913 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002914 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02002915 {only available when compiled with the |+file_in_path|
2916 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002917
2918findfile({name}[, {path}[, {count}]]) *findfile()*
2919 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002920 Uses 'suffixesadd'.
2921 Example: >
2922 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002923< Searches from the directory of the current file upwards until
2924 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00002925
Bram Moolenaar446cb832008-06-24 21:56:24 +00002926float2nr({expr}) *float2nr()*
2927 Convert {expr} to a Number by omitting the part after the
2928 decimal point.
2929 {expr} must evaluate to a |Float| or a Number.
2930 When the value of {expr} is out of range for a |Number| the
2931 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
2932 in -0x80000000.
2933 Examples: >
2934 echo float2nr(3.95)
2935< 3 >
2936 echo float2nr(-23.45)
2937< -23 >
2938 echo float2nr(1.0e100)
2939< 2147483647 >
2940 echo float2nr(-1.0e150)
2941< -2147483647 >
2942 echo float2nr(1.0e-100)
2943< 0
2944 {only available when compiled with the |+float| feature}
2945
2946
2947floor({expr}) *floor()*
2948 Return the largest integral value less than or equal to
2949 {expr} as a |Float| (round down).
2950 {expr} must evaluate to a |Float| or a |Number|.
2951 Examples: >
2952 echo floor(1.856)
2953< 1.0 >
2954 echo floor(-5.456)
2955< -6.0 >
2956 echo floor(4.0)
2957< 4.0
2958 {only available when compiled with the |+float| feature}
2959
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002960
2961fmod({expr1}, {expr2}) *fmod()*
2962 Return the remainder of {expr1} / {expr2}, even if the
2963 division is not representable. Returns {expr1} - i * {expr2}
2964 for some integer i such that if {expr2} is non-zero, the
2965 result has the same sign as {expr1} and magnitude less than
2966 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002967 returned is zero. The value returned is a |Float|.
2968 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002969 Examples: >
2970 :echo fmod(12.33, 1.22)
2971< 0.13 >
2972 :echo fmod(-12.33, 1.22)
2973< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02002974 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002975
2976
Bram Moolenaaraebaf892008-05-28 14:49:58 +00002977fnameescape({string}) *fnameescape()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002978 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00002979 characters that have a special meaning, such as '%' and '|'
2980 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002981 For most systems the characters escaped are
2982 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2983 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00002984 A leading '+' and '>' is also escaped (special after |:edit|
2985 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00002986 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00002987 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00002988 :exe "edit " . fnameescape(fname)
2989< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00002990 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00002991
Bram Moolenaar071d4272004-06-13 20:20:40 +00002992fnamemodify({fname}, {mods}) *fnamemodify()*
2993 Modify file name {fname} according to {mods}. {mods} is a
2994 string of characters like it is used for file names on the
2995 command line. See |filename-modifiers|.
2996 Example: >
2997 :echo fnamemodify("main.c", ":p:h")
2998< results in: >
2999 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003000< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003001 |expand()| first then.
3002
3003foldclosed({lnum}) *foldclosed()*
3004 The result is a Number. If the line {lnum} is in a closed
3005 fold, the result is the number of the first line in that fold.
3006 If the line {lnum} is not in a closed fold, -1 is returned.
3007
3008foldclosedend({lnum}) *foldclosedend()*
3009 The result is a Number. If the line {lnum} is in a closed
3010 fold, the result is the number of the last line in that fold.
3011 If the line {lnum} is not in a closed fold, -1 is returned.
3012
3013foldlevel({lnum}) *foldlevel()*
3014 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003015 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003016 returned. If there is no fold at line {lnum}, zero is
3017 returned. It doesn't matter if the folds are open or closed.
3018 When used while updating folds (from 'foldexpr') -1 is
3019 returned for lines where folds are still to be updated and the
3020 foldlevel is unknown. As a special case the level of the
3021 previous line is usually available.
3022
3023 *foldtext()*
3024foldtext() Returns a String, to be displayed for a closed fold. This is
3025 the default function used for the 'foldtext' option and should
3026 only be called from evaluating 'foldtext'. It uses the
3027 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3028 The returned string looks like this: >
3029 +-- 45 lines: abcdef
Bram Moolenaar446cb832008-06-24 21:56:24 +00003030< The number of dashes depends on the foldlevel. The "45" is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003031 the number of lines in the fold. "abcdef" is the text in the
3032 first non-blank line of the fold. Leading white space, "//"
3033 or "/*" and the text from the 'foldmarker' and 'commentstring'
3034 options is removed.
3035 {not available when compiled without the |+folding| feature}
3036
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003037foldtextresult({lnum}) *foldtextresult()*
3038 Returns the text that is displayed for the closed fold at line
3039 {lnum}. Evaluates 'foldtext' in the appropriate context.
3040 When there is no closed fold at {lnum} an empty string is
3041 returned.
3042 {lnum} is used like with |getline()|. Thus "." is the current
3043 line, "'m" mark m, etc.
3044 Useful when exporting folded text, e.g., to HTML.
3045 {not available when compiled without the |+folding| feature}
3046
Bram Moolenaar071d4272004-06-13 20:20:40 +00003047 *foreground()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003048foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00003049 a client to a Vim server. |remote_send()|
3050 On Win32 systems this might not work, the OS does not always
3051 allow a window to bring itself to the foreground. Use
3052 |remote_foreground()| instead.
3053 {only in the Win32, Athena, Motif and GTK GUI versions and the
3054 Win32 console version}
3055
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003056
Bram Moolenaar13065c42005-01-08 16:08:21 +00003057function({name}) *function()* *E700*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003058 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003059 {name} can be a user defined function or an internal function.
3060
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003061
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003062garbagecollect([at_exit]) *garbagecollect()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003063 Cleanup unused |Lists| and |Dictionaries| that have circular
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003064 references. There is hardly ever a need to invoke this
3065 function, as it is automatically done when Vim runs out of
3066 memory or is waiting for the user to press a key after
3067 'updatetime'. Items without circular references are always
3068 freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003069 This is useful if you have deleted a very big |List| and/or
3070 |Dictionary| with circular references in a script that runs
3071 for a long time.
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003072 When the optional "at_exit" argument is one, garbage
3073 collection will also be done when exiting Vim, if it wasn't
3074 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003075
Bram Moolenaar677ee682005-01-27 14:41:15 +00003076get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003077 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003078 available return {default}. Return zero when {default} is
3079 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003080get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003081 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003082 item is not available return {default}. Return zero when
3083 {default} is omitted.
3084
Bram Moolenaar45360022005-07-21 21:08:21 +00003085 *getbufline()*
3086getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003087 Return a |List| with the lines starting from {lnum} to {end}
3088 (inclusive) in the buffer {expr}. If {end} is omitted, a
3089 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003090
3091 For the use of {expr}, see |bufname()| above.
3092
Bram Moolenaar661b1822005-07-28 22:36:45 +00003093 For {lnum} and {end} "$" can be used for the last line of the
3094 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00003095
3096 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003097 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003098
3099 When {end} is greater than the number of lines in the buffer,
3100 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003101 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00003102 returned.
3103
Bram Moolenaar661b1822005-07-28 22:36:45 +00003104 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003105 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003106
3107 Example: >
3108 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003109
3110getbufvar({expr}, {varname}) *getbufvar()*
3111 The result is the value of option or local buffer variable
3112 {varname} in buffer {expr}. Note that the name without "b:"
3113 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003114 When {varname} is empty returns a dictionary with all the
3115 buffer-local variables.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00003116 This also works for a global or buffer-local option, but it
3117 doesn't work for a global variable, window-local variable or
3118 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003119 For the use of {expr}, see |bufname()| above.
3120 When the buffer or variable doesn't exist an empty string is
3121 returned, there is no error message.
3122 Examples: >
3123 :let bufmodified = getbufvar(1, "&mod")
3124 :echo "todo myvar = " . getbufvar("todo", "myvar")
3125<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003126getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00003127 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003128 If [expr] is omitted, wait until a character is available.
3129 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003130 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003131 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00003132 not consumed. Return zero if no character available.
3133
3134 Without {expr} and when {expr} is 0 a whole character or
3135 special key is returned. If it is an 8-bit character, the
3136 result is a number. Use nr2char() to convert it to a String.
3137 Otherwise a String is returned with the encoded character.
3138 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003139 (decimal: 128). This is the same value as the string
3140 "\<Key>", e.g., "\<Left>". The returned value is also a
3141 String when a modifier (shift, control, alt) was used that is
3142 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003143
3144 When {expr} is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003145 one-byte character it is the character itself as a number.
3146 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003147
Bram Moolenaar219b8702006-11-01 14:32:36 +00003148 When the user clicks a mouse button, the mouse event will be
3149 returned. The position can then be found in |v:mouse_col|,
3150 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3151 mouse as it would normally happen: >
3152 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003153 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00003154 exe v:mouse_win . "wincmd w"
3155 exe v:mouse_lnum
3156 exe "normal " . v:mouse_col . "|"
3157 endif
3158<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003159 There is no prompt, you will somehow have to make clear to the
3160 user that a character has to be typed.
3161 There is no mapping for the character.
3162 Key codes are replaced, thus when the user presses the <Del>
3163 key you get the code for the <Del> key, not the raw character
3164 sequence. Examples: >
3165 getchar() == "\<Del>"
3166 getchar() == "\<S-Left>"
3167< This example redefines "f" to ignore case: >
3168 :nmap f :call FindChar()<CR>
3169 :function FindChar()
3170 : let c = nr2char(getchar())
3171 : while col('.') < col('$') - 1
3172 : normal l
3173 : if getline('.')[col('.') - 1] ==? c
3174 : break
3175 : endif
3176 : endwhile
3177 :endfunction
3178
3179getcharmod() *getcharmod()*
3180 The result is a Number which is the state of the modifiers for
3181 the last obtained character with getchar() or in another way.
3182 These values are added together:
3183 2 shift
3184 4 control
3185 8 alt (meta)
3186 16 mouse double click
3187 32 mouse triple click
3188 64 mouse quadruple click
3189 128 Macintosh only: command
3190 Only the modifiers that have not been included in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003191 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003192 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003193
Bram Moolenaar071d4272004-06-13 20:20:40 +00003194getcmdline() *getcmdline()*
3195 Return the current command-line. Only works when the command
3196 line is being edited, thus requires use of |c_CTRL-\_e| or
3197 |c_CTRL-R_=|.
3198 Example: >
3199 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003200< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003201
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003202getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003203 Return the position of the cursor in the command line as a
3204 byte count. The first column is 1.
3205 Only works when editing the command line, thus requires use of
3206 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003207 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3208
3209getcmdtype() *getcmdtype()*
3210 Return the current command-line type. Possible return values
3211 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00003212 : normal Ex command
3213 > debug mode command |debug-mode|
3214 / forward search command
3215 ? backward search command
3216 @ |input()| command
3217 - |:insert| or |:append| command
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003218 Only works when editing the command line, thus requires use of
3219 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
3220 otherwise.
3221 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003222
3223 *getcwd()*
3224getcwd() The result is a String, which is the name of the current
3225 working directory.
3226
3227getfsize({fname}) *getfsize()*
3228 The result is a Number, which is the size in bytes of the
3229 given file {fname}.
3230 If {fname} is a directory, 0 is returned.
3231 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00003232 If the size of {fname} is too big to fit in a Number then -2
3233 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003234
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003235getfontname([{name}]) *getfontname()*
3236 Without an argument returns the name of the normal font being
3237 used. Like what is used for the Normal highlight group
3238 |hl-Normal|.
3239 With an argument a check is done whether {name} is a valid
3240 font name. If not then an empty string is returned.
3241 Otherwise the actual font name is returned, or {name} if the
3242 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00003243 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003244 gvimrc file. Use the |GUIEnter| autocommand to use this
3245 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003246 Note that the GTK 2 GUI accepts any font name, thus checking
3247 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003248
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003249getfperm({fname}) *getfperm()*
3250 The result is a String, which is the read, write, and execute
3251 permissions of the given file {fname}.
3252 If {fname} does not exist or its directory cannot be read, an
3253 empty string is returned.
3254 The result is of the form "rwxrwxrwx", where each group of
3255 "rwx" flags represent, in turn, the permissions of the owner
3256 of the file, the group the file belongs to, and other users.
3257 If a user does not have a given permission the flag for this
3258 is replaced with the string "-". Example: >
3259 :echo getfperm("/etc/passwd")
3260< This will hopefully (from a security point of view) display
3261 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003262
Bram Moolenaar071d4272004-06-13 20:20:40 +00003263getftime({fname}) *getftime()*
3264 The result is a Number, which is the last modification time of
3265 the given file {fname}. The value is measured as seconds
3266 since 1st Jan 1970, and may be passed to strftime(). See also
3267 |localtime()| and |strftime()|.
3268 If the file {fname} can't be found -1 is returned.
3269
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003270getftype({fname}) *getftype()*
3271 The result is a String, which is a description of the kind of
3272 file of the given file {fname}.
3273 If {fname} does not exist an empty string is returned.
3274 Here is a table over different kinds of files and their
3275 results:
3276 Normal file "file"
3277 Directory "dir"
3278 Symbolic link "link"
3279 Block device "bdev"
3280 Character device "cdev"
3281 Socket "socket"
3282 FIFO "fifo"
3283 All other "other"
3284 Example: >
3285 getftype("/home")
3286< Note that a type such as "link" will only be returned on
3287 systems that support it. On some systems only "dir" and
3288 "file" are returned.
3289
Bram Moolenaar071d4272004-06-13 20:20:40 +00003290 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003291getline({lnum} [, {end}])
3292 Without {end} the result is a String, which is line {lnum}
3293 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003294 getline(1)
3295< When {lnum} is a String that doesn't start with a
3296 digit, line() is called to translate the String into a Number.
3297 To get the line under the cursor: >
3298 getline(".")
3299< When {lnum} is smaller than 1 or bigger than the number of
3300 lines in the buffer, an empty string is returned.
3301
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003302 When {end} is given the result is a |List| where each item is
3303 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003304 including line {end}.
3305 {end} is used in the same way as {lnum}.
3306 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003307 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003308 Example: >
3309 :let start = line('.')
3310 :let end = search("^$") - 1
3311 :let lines = getline(start, end)
3312
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003313< To get lines from another buffer see |getbufline()|
3314
Bram Moolenaar17c7c012006-01-26 22:25:15 +00003315getloclist({nr}) *getloclist()*
3316 Returns a list with all the entries in the location list for
3317 window {nr}. When {nr} is zero the current window is used.
3318 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00003319 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003320 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003321
Bram Moolenaar6ee10162007-07-26 20:58:42 +00003322getmatches() *getmatches()*
3323 Returns a |List| with all matches previously defined by
3324 |matchadd()| and the |:match| commands. |getmatches()| is
3325 useful in combination with |setmatches()|, as |setmatches()|
3326 can restore a list of matches saved by |getmatches()|.
3327 Example: >
3328 :echo getmatches()
3329< [{'group': 'MyGroup1', 'pattern': 'TODO',
3330 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3331 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3332 :let m = getmatches()
3333 :call clearmatches()
3334 :echo getmatches()
3335< [] >
3336 :call setmatches(m)
3337 :echo getmatches()
3338< [{'group': 'MyGroup1', 'pattern': 'TODO',
3339 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3340 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3341 :unlet m
3342<
3343
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003344getqflist() *getqflist()*
3345 Returns a list with all the current quickfix errors. Each
3346 list item is a dictionary with these entries:
3347 bufnr number of buffer that has the file name, use
3348 bufname() to get the name
3349 lnum line number in the buffer (first line is 1)
3350 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00003351 vcol non-zero: "col" is visual column
3352 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003353 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00003354 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003355 text description of the error
3356 type type of the error, 'E', '1', etc.
3357 valid non-zero: recognized error message
3358
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00003359 When there is no error list or it's empty an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00003360 returned. Quickfix list entries with non-existing buffer
3361 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00003362
Bram Moolenaar68b76a62005-03-25 21:53:48 +00003363 Useful application: Find pattern matches in multiple files and
3364 do something with them: >
3365 :vimgrep /theword/jg *.c
3366 :for d in getqflist()
3367 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3368 :endfor
3369
3370
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003371getreg([{regname} [, 1]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003372 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003373 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003374 :let cliptext = getreg('*')
3375< getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003376 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00003377 getreg('=', 1) returns the expression itself, so that it can
3378 be restored with |setreg()|. For other registers the extra
3379 argument is ignored, thus you can always give it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003380 If {regname} is not specified, |v:register| is used.
3381
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003382
Bram Moolenaar071d4272004-06-13 20:20:40 +00003383getregtype([{regname}]) *getregtype()*
3384 The result is a String, which is type of register {regname}.
3385 The value will be one of:
3386 "v" for |characterwise| text
3387 "V" for |linewise| text
3388 "<CTRL-V>{width}" for |blockwise-visual| text
3389 0 for an empty or unknown register
3390 <CTRL-V> is one character with value 0x16.
3391 If {regname} is not specified, |v:register| is used.
3392
Bram Moolenaar06b5d512010-05-22 15:37:44 +02003393gettabvar({tabnr}, {varname}) *gettabvar()*
3394 Get the value of a tab-local variable {varname} in tab page
3395 {tabnr}. |t:var|
3396 Tabs are numbered starting with one.
3397 Note that the name without "t:" must be used.
3398
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003399gettabwinvar({tabnr}, {winnr}, {varname}) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003400 Get the value of window-local variable {varname} in window
3401 {winnr} in tab page {tabnr}.
3402 When {varname} starts with "&" get the value of a window-local
3403 option.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003404 Tabs are numbered starting with one. For the current tabpage
3405 use |getwinvar()|.
3406 When {winnr} is zero the current window is used.
3407 This also works for a global option, buffer-local option and
3408 window-local option, but it doesn't work for a global variable
3409 or buffer-local variable.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003410 When {varname} is empty a dictionary with all window-local
3411 variables is returned.
3412 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003413 Examples: >
3414 :let list_is_on = gettabwinvar(1, 2, '&list')
3415 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003416<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003417 *getwinposx()*
3418getwinposx() The result is a Number, which is the X coordinate in pixels of
3419 the left hand side of the GUI Vim window. The result will be
3420 -1 if the information is not available.
3421
3422 *getwinposy()*
3423getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar446cb832008-06-24 21:56:24 +00003424 the top of the GUI Vim window. The result will be -1 if the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003425 information is not available.
3426
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00003427getwinvar({winnr}, {varname}) *getwinvar()*
3428 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003429 Examples: >
3430 :let list_is_on = getwinvar(2, '&list')
3431 :echo "myvar = " . getwinvar(1, 'myvar')
3432<
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003433glob({expr} [, {flag}]) *glob()*
3434 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003435 use of special characters.
3436 The result is a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003437 When there are several matches, they are separated by <NL>
3438 characters.
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003439 Unless the optional {flag} argument is given and is non-zero,
3440 the 'suffixes' and 'wildignore' options apply: Names matching
3441 one of the patterns in 'wildignore' will be skipped and
3442 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01003443 'wildignorecase' always applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003444 If the expansion fails, the result is an empty string.
3445 A name for a non-existing file is not included.
3446
3447 For most systems backticks can be used to get files names from
3448 any external command. Example: >
3449 :let tagfiles = glob("`find . -name tags -print`")
3450 :let &tags = substitute(tagfiles, "\n", ",", "g")
3451< The result of the program inside the backticks should be one
Bram Moolenaar446cb832008-06-24 21:56:24 +00003452 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003453
3454 See |expand()| for expanding special Vim variables. See
3455 |system()| for getting the raw output of an external command.
3456
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003457globpath({path}, {expr} [, {flag}]) *globpath()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003458 Perform glob() on all directories in {path} and concatenate
3459 the results. Example: >
3460 :echo globpath(&rtp, "syntax/c.vim")
3461< {path} is a comma-separated list of directory names. Each
3462 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003463 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003464 To add a comma inside a directory name escape it with a
3465 backslash. Note that on MS-Windows a directory may have a
3466 trailing backslash, remove it if you put a comma after it.
3467 If the expansion fails for one of the directories, there is no
3468 error message.
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00003469 Unless the optional {flag} argument is given and is non-zero,
3470 the 'suffixes' and 'wildignore' options apply: Names matching
3471 one of the patterns in 'wildignore' will be skipped and
3472 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003473
Bram Moolenaar02743632005-07-25 20:42:36 +00003474 The "**" item can be used to search in a directory tree.
3475 For example, to find all "README.txt" files in the directories
3476 in 'runtimepath' and below: >
3477 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00003478< Upwards search and limiting the depth of "**" is not
3479 supported, thus using 'path' will not always work properly.
3480
Bram Moolenaar071d4272004-06-13 20:20:40 +00003481 *has()*
3482has({feature}) The result is a Number, which is 1 if the feature {feature} is
3483 supported, zero otherwise. The {feature} argument is a
3484 string. See |feature-list| below.
3485 Also see |exists()|.
3486
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003487
3488has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003489 The result is a Number, which is 1 if |Dictionary| {dict} has
3490 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003491
Bram Moolenaard267b9c2007-04-26 15:06:45 +00003492haslocaldir() *haslocaldir()*
3493 The result is a Number, which is 1 when the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00003494 window has set a local path via |:lcd|, and 0 otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003495
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003496hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003497 The result is a Number, which is 1 if there is a mapping that
3498 contains {what} in somewhere in the rhs (what it is mapped to)
3499 and this mapping exists in one of the modes indicated by
3500 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003501 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00003502 instead of mappings. Don't forget to specify Insert and/or
3503 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003504 Both the global mappings and the mappings local to the current
3505 buffer are checked for a match.
3506 If no matching mapping is found 0 is returned.
3507 The following characters are recognized in {mode}:
3508 n Normal mode
3509 v Visual mode
3510 o Operator-pending mode
3511 i Insert mode
3512 l Language-Argument ("r", "f", "t", etc.)
3513 c Command-line mode
3514 When {mode} is omitted, "nvo" is used.
3515
3516 This function is useful to check if a mapping already exists
Bram Moolenaar446cb832008-06-24 21:56:24 +00003517 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003518 :if !hasmapto('\ABCdoit')
3519 : map <Leader>d \ABCdoit
3520 :endif
3521< This installs the mapping to "\ABCdoit" only if there isn't
3522 already a mapping to "\ABCdoit".
3523
3524histadd({history}, {item}) *histadd()*
3525 Add the String {item} to the history {history} which can be
3526 one of: *hist-names*
3527 "cmd" or ":" command line history
3528 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00003529 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00003530 "input" or "@" input line history
3531 If {item} does already exist in the history, it will be
3532 shifted to become the newest entry.
3533 The result is a Number: 1 if the operation was successful,
3534 otherwise 0 is returned.
3535
3536 Example: >
3537 :call histadd("input", strftime("%Y %b %d"))
3538 :let date=input("Enter date: ")
3539< This function is not available in the |sandbox|.
3540
3541histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003542 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003543 for the possible values of {history}.
3544
Bram Moolenaarc236c162008-07-13 17:41:49 +00003545 If the parameter {item} evaluates to a String, it is used as a
3546 regular expression. All entries matching that expression will
3547 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003548 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003549 If {item} evaluates to a Number, it will be interpreted as
3550 an index, see |:history-indexing|. The respective entry will
3551 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003552
3553 The result is a Number: 1 for a successful operation,
3554 otherwise 0 is returned.
3555
3556 Examples:
3557 Clear expression register history: >
3558 :call histdel("expr")
3559<
3560 Remove all entries starting with "*" from the search history: >
3561 :call histdel("/", '^\*')
3562<
3563 The following three are equivalent: >
3564 :call histdel("search", histnr("search"))
3565 :call histdel("search", -1)
3566 :call histdel("search", '^'.histget("search", -1).'$')
3567<
3568 To delete the last search pattern and use the last-but-one for
3569 the "n" command and 'hlsearch': >
3570 :call histdel("search", -1)
3571 :let @/ = histget("search", -1)
3572
3573histget({history} [, {index}]) *histget()*
3574 The result is a String, the entry with Number {index} from
3575 {history}. See |hist-names| for the possible values of
3576 {history}, and |:history-indexing| for {index}. If there is
3577 no such entry, an empty String is returned. When {index} is
3578 omitted, the most recent item from the history is used.
3579
3580 Examples:
3581 Redo the second last search from history. >
3582 :execute '/' . histget("search", -2)
3583
3584< Define an Ex command ":H {num}" that supports re-execution of
3585 the {num}th entry from the output of |:history|. >
3586 :command -nargs=1 H execute histget("cmd", 0+<args>)
3587<
3588histnr({history}) *histnr()*
3589 The result is the Number of the current entry in {history}.
3590 See |hist-names| for the possible values of {history}.
3591 If an error occurred, -1 is returned.
3592
3593 Example: >
3594 :let inp_index = histnr("expr")
3595<
3596hlexists({name}) *hlexists()*
3597 The result is a Number, which is non-zero if a highlight group
3598 called {name} exists. This is when the group has been
3599 defined in some way. Not necessarily when highlighting has
3600 been defined for it, it may also have been used for a syntax
3601 item.
3602 *highlight_exists()*
3603 Obsolete name: highlight_exists().
3604
3605 *hlID()*
3606hlID({name}) The result is a Number, which is the ID of the highlight group
3607 with name {name}. When the highlight group doesn't exist,
3608 zero is returned.
3609 This can be used to retrieve information about the highlight
Bram Moolenaar446cb832008-06-24 21:56:24 +00003610 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003611 "Comment" group: >
3612 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3613< *highlightID()*
3614 Obsolete name: highlightID().
3615
3616hostname() *hostname()*
3617 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003618 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00003619 256 characters long are truncated.
3620
3621iconv({expr}, {from}, {to}) *iconv()*
3622 The result is a String, which is the text {expr} converted
3623 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003624 When the conversion completely fails an empty string is
3625 returned. When some characters could not be converted they
3626 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003627 The encoding names are whatever the iconv() library function
3628 can accept, see ":!man 3 iconv".
3629 Most conversions require Vim to be compiled with the |+iconv|
3630 feature. Otherwise only UTF-8 to latin1 conversion and back
3631 can be done.
3632 This can be used to display messages with special characters,
3633 no matter what 'encoding' is set to. Write the message in
3634 UTF-8 and use: >
3635 echo iconv(utf8_str, "utf-8", &enc)
3636< Note that Vim uses UTF-8 for all Unicode encodings, conversion
3637 from/to UCS-2 is automatically changed to use UTF-8. You
3638 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003639 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003640
3641 *indent()*
3642indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3643 current buffer. The indent is counted in spaces, the value
3644 of 'tabstop' is relevant. {lnum} is used just like in
3645 |getline()|.
3646 When {lnum} is invalid -1 is returned.
3647
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003648
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003649index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003650 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003651 value equal to {expr}. There is no automatic conversion, so
3652 the String "4" is different from the Number 4. And the number
3653 4 is different from the Float 4.0. The value of 'ignorecase'
3654 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00003655 If {start} is given then start looking at the item with index
3656 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003657 When {ic} is given and it is non-zero, ignore case. Otherwise
3658 case must match.
3659 -1 is returned when {expr} is not found in {list}.
3660 Example: >
3661 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003662 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003663
3664
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003665input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003666 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003667 the command-line. The {prompt} argument is either a prompt
3668 string, or a blank string (for no prompt). A '\n' can be used
3669 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003670 The highlighting set with |:echohl| is used for the prompt.
3671 The input is entered just like a command-line, with the same
Bram Moolenaar446cb832008-06-24 21:56:24 +00003672 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003673 for lines typed for input().
3674 Example: >
3675 :if input("Coffee or beer? ") == "beer"
3676 : echo "Cheers!"
3677 :endif
3678<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003679 If the optional {text} argument is present and not empty, this
3680 is used for the default reply, as if the user typed this.
3681 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003682 :let color = input("Color? ", "white")
3683
3684< The optional {completion} argument specifies the type of
3685 completion supported for the input. Without it completion is
Bram Moolenaar446cb832008-06-24 21:56:24 +00003686 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003687 that can be supplied to a user-defined command using the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003688 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003689 more information. Example: >
3690 let fname = input("File: ", "", "file")
3691<
3692 NOTE: This function must not be used in a startup file, for
3693 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003694 Note: When input() is called from within a mapping it will
3695 consume remaining characters from that mapping, because a
3696 mapping is handled like the characters were typed.
3697 Use |inputsave()| before input() and |inputrestore()|
3698 after input() to avoid that. Another solution is to avoid
3699 that further characters follow in the mapping, e.g., by using
3700 |:execute| or |:normal|.
3701
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003702 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003703 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3704 :function GetFoo()
3705 : call inputsave()
3706 : let g:Foo = input("enter search pattern: ")
3707 : call inputrestore()
3708 :endfunction
3709
3710inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003711 Like |input()|, but when the GUI is running and text dialogs
3712 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003713 Example: >
3714 :let n = inputdialog("value for shiftwidth", &sw)
3715 :if n != ""
3716 : let &sw = n
3717 :endif
3718< When the dialog is cancelled {cancelreturn} is returned. When
3719 omitted an empty string is returned.
3720 Hitting <Enter> works like pressing the OK button. Hitting
3721 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003722 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003723
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003724inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003725 {textlist} must be a |List| of strings. This |List| is
3726 displayed, one string per line. The user will be prompted to
3727 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003728 The user can also select an item by clicking on it with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003729 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003730 above the first item a negative number is returned. When
3731 clicking on the prompt one more than the length of {textlist}
3732 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003733 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +00003734 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003735 the start of the string. And put a prompt in the first item.
3736 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00003737 let color = inputlist(['Select color:', '1. red',
3738 \ '2. green', '3. blue'])
3739
Bram Moolenaar071d4272004-06-13 20:20:40 +00003740inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003741 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003742 Should be called the same number of times inputsave() is
3743 called. Calling it more often is harmless though.
3744 Returns 1 when there is nothing to restore, 0 otherwise.
3745
3746inputsave() *inputsave()*
3747 Preserve typeahead (also from mappings) and clear it, so that
3748 a following prompt gets input from the user. Should be
3749 followed by a matching inputrestore() after the prompt. Can
3750 be used several times, in which case there must be just as
3751 many inputrestore() calls.
3752 Returns 1 when out of memory, 0 otherwise.
3753
3754inputsecret({prompt} [, {text}]) *inputsecret()*
3755 This function acts much like the |input()| function with but
3756 two exceptions:
3757 a) the user's response will be displayed as a sequence of
3758 asterisks ("*") thereby keeping the entry secret, and
3759 b) the user's response will not be recorded on the input
3760 |history| stack.
3761 The result is a String, which is whatever the user actually
3762 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003763 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003764
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003765insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003766 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003767 If {idx} is specified insert {item} before the item with index
Bram Moolenaar446cb832008-06-24 21:56:24 +00003768 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003769 like omitting {idx}. A negative {idx} is also possible, see
3770 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003771 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003772 :let mylist = insert([2, 3, 5], 1)
3773 :call insert(mylist, 4, -1)
3774 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003775< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003776 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003777 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003778
Bram Moolenaar071d4272004-06-13 20:20:40 +00003779isdirectory({directory}) *isdirectory()*
3780 The result is a Number, which is non-zero when a directory
3781 with the name {directory} exists. If {directory} doesn't
3782 exist, or isn't a directory, the result is FALSE. {directory}
3783 is any expression, which is used as a String.
3784
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003785islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003786 The result is a Number, which is non-zero when {expr} is the
3787 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003788 {expr} must be the name of a variable, |List| item or
3789 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003790 :let alist = [0, ['a', 'b'], 2, 3]
3791 :lockvar 1 alist
3792 :echo islocked('alist') " 1
3793 :echo islocked('alist[1]') " 0
3794
3795< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003796 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003797
Bram Moolenaar677ee682005-01-27 14:41:15 +00003798items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003799 Return a |List| with all the key-value pairs of {dict}. Each
3800 |List| item is a list with two items: the key of a {dict}
3801 entry and the value of this entry. The |List| is in arbitrary
3802 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00003803
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003804
3805join({list} [, {sep}]) *join()*
3806 Join the items in {list} together into one String.
3807 When {sep} is specified it is put in between the items. If
3808 {sep} is omitted a single space is used.
3809 Note that {sep} is not added at the end. You might want to
3810 add it there too: >
3811 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003812< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003813 converted into a string like with |string()|.
3814 The opposite function is |split()|.
3815
Bram Moolenaard8b02732005-01-14 21:48:43 +00003816keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003817 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00003818 arbitrary order.
3819
Bram Moolenaar13065c42005-01-08 16:08:21 +00003820 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003821len({expr}) The result is a Number, which is the length of the argument.
3822 When {expr} is a String or a Number the length in bytes is
3823 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003824 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003825 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003826 When {expr} is a |Dictionary| the number of entries in the
3827 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003828 Otherwise an error is given.
3829
Bram Moolenaar071d4272004-06-13 20:20:40 +00003830 *libcall()* *E364* *E368*
3831libcall({libname}, {funcname}, {argument})
3832 Call function {funcname} in the run-time library {libname}
3833 with single argument {argument}.
3834 This is useful to call functions in a library that you
3835 especially made to be used with Vim. Since only one argument
3836 is possible, calling standard library functions is rather
3837 limited.
3838 The result is the String returned by the function. If the
3839 function returns NULL, this will appear as an empty string ""
3840 to Vim.
3841 If the function returns a number, use libcallnr()!
3842 If {argument} is a number, it is passed to the function as an
3843 int; if {argument} is a string, it is passed as a
3844 null-terminated string.
3845 This function will fail in |restricted-mode|.
3846
3847 libcall() allows you to write your own 'plug-in' extensions to
3848 Vim without having to recompile the program. It is NOT a
3849 means to call system functions! If you try to do so Vim will
3850 very probably crash.
3851
3852 For Win32, the functions you write must be placed in a DLL
3853 and use the normal C calling convention (NOT Pascal which is
3854 used in Windows System DLLs). The function must take exactly
3855 one parameter, either a character pointer or a long integer,
3856 and must return a character pointer or NULL. The character
3857 pointer returned must point to memory that will remain valid
3858 after the function has returned (e.g. in static data in the
3859 DLL). If it points to allocated memory, that memory will
3860 leak away. Using a static buffer in the function should work,
3861 it's then freed when the DLL is unloaded.
3862
3863 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00003864 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003865 because Vim thinks it's a pointer.
3866 For Win32 systems, {libname} should be the filename of the DLL
3867 without the ".DLL" suffix. A full path is only required if
3868 the DLL is not in the usual places.
3869 For Unix: When compiling your own plugins, remember that the
3870 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003871 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003872 feature is present}
3873 Examples: >
3874 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003875<
3876 *libcallnr()*
3877libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003878 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00003879 int instead of a string.
3880 {only in Win32 on some Unix versions, when the |+libcall|
3881 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003882 Examples: >
3883 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003884 :call libcallnr("libc.so", "printf", "Hello World!\n")
3885 :call libcallnr("libc.so", "sleep", 10)
3886<
3887 *line()*
3888line({expr}) The result is a Number, which is the line number of the file
3889 position given with {expr}. The accepted positions are:
3890 . the cursor position
3891 $ the last line in the current buffer
3892 'x position of mark x (if the mark is not set, 0 is
3893 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00003894 w0 first line visible in current window
3895 w$ last line visible in current window
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00003896 v In Visual mode: the start of the Visual area (the
3897 cursor is the end). When not in Visual mode
3898 returns the cursor position. Differs from |'<| in
3899 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003900 Note that a mark in another file can be used. The line number
3901 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00003902 To get the column number use |col()|. To get both use
3903 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003904 Examples: >
3905 line(".") line number of the cursor
3906 line("'t") line number of mark t
3907 line("'" . marker) line number of mark marker
3908< *last-position-jump*
3909 This autocommand jumps to the last known position in a file
3910 just after opening it, if the '" mark is set: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003911 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003912
Bram Moolenaar071d4272004-06-13 20:20:40 +00003913line2byte({lnum}) *line2byte()*
3914 Return the byte count from the start of the buffer for line
3915 {lnum}. This includes the end-of-line character, depending on
3916 the 'fileformat' option for the current buffer. The first
3917 line returns 1.
3918 This can also be used to get the byte count for the line just
3919 below the last line: >
3920 line2byte(line("$") + 1)
3921< This is the file size plus one.
3922 When {lnum} is invalid, or the |+byte_offset| feature has been
3923 disabled at compile time, -1 is returned.
3924 Also see |byte2line()|, |go| and |:goto|.
3925
3926lispindent({lnum}) *lispindent()*
3927 Get the amount of indent for line {lnum} according the lisp
3928 indenting rules, as with 'lisp'.
3929 The indent is counted in spaces, the value of 'tabstop' is
3930 relevant. {lnum} is used just like in |getline()|.
3931 When {lnum} is invalid or Vim was not compiled the
3932 |+lispindent| feature, -1 is returned.
3933
3934localtime() *localtime()*
3935 Return the current time, measured as seconds since 1st Jan
3936 1970. See also |strftime()| and |getftime()|.
3937
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003938
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003939log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003940 Return the natural logarithm (base e) of {expr} as a |Float|.
3941 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003942 (0, inf].
3943 Examples: >
3944 :echo log(10)
3945< 2.302585 >
3946 :echo log(exp(5))
3947< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02003948 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003949
3950
Bram Moolenaar446cb832008-06-24 21:56:24 +00003951log10({expr}) *log10()*
3952 Return the logarithm of Float {expr} to base 10 as a |Float|.
3953 {expr} must evaluate to a |Float| or a |Number|.
3954 Examples: >
3955 :echo log10(1000)
3956< 3.0 >
3957 :echo log10(0.01)
3958< -2.0
3959 {only available when compiled with the |+float| feature}
3960
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003961map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003962 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003963 Replace each item in {expr} with the result of evaluating
3964 {string}.
3965 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar627b1d32009-11-17 11:20:35 +00003966 For a |Dictionary| |v:key| has the key of the current item
3967 and for a |List| |v:key| has the index of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003968 Example: >
3969 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003970< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003971
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003972 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003973 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00003974 |literal-string| to avoid having to double backslashes. You
3975 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003976
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003977 The operation is done in-place. If you want a |List| or
3978 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00003979 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003980
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003981< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00003982 When an error is encountered while evaluating {string} no
3983 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003984
3985
Bram Moolenaarbd743252010-10-20 21:23:33 +02003986maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
3987 When {dict} is omitted or zero: Return the rhs of mapping
3988 {name} in mode {mode}. The returned String has special
3989 characters translated like in the output of the ":map" command
3990 listing.
3991
3992 When there is no mapping for {name}, an empty String is
3993 returned.
3994
3995 The {name} can have special key names, like in the ":map"
3996 command.
3997
Bram Moolenaard12f5c12006-01-25 22:10:52 +00003998 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003999 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02004000 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004001 "o" Operator-pending
4002 "i" Insert
4003 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02004004 "s" Select
4005 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00004006 "l" langmap |language-mapping|
4007 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004008 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004009
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004010 When {abbr} is there and it is non-zero use abbreviations
4011 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004012
4013 When {dict} is there and it is non-zero return a dictionary
4014 containing all the information of the mapping with the
4015 following items:
4016 "lhs" The {lhs} of the mapping.
4017 "rhs" The {rhs} of the mapping as typed.
4018 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02004019 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004020 "expr" 1 for an expression mapping (|:map-<expr>|).
4021 "buffer" 1 for a buffer local mapping (|:map-local|).
4022 "mode" Modes for which the mapping is defined. In
4023 addition to the modes mentioned above, these
4024 characters will be used:
4025 " " Normal, Visual and Operator-pending
4026 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01004027 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02004028 "sid" The script local ID, used for <sid> mappings
4029 (|<SID>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02004030
Bram Moolenaar071d4272004-06-13 20:20:40 +00004031 The mappings local to the current buffer are checked first,
4032 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00004033 This function can be used to map a key even when it's already
4034 mapped, and have it do the original mapping too. Sketch: >
4035 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
4036
Bram Moolenaar071d4272004-06-13 20:20:40 +00004037
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004038mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004039 Check if there is a mapping that matches with {name} in mode
4040 {mode}. See |maparg()| for {mode} and special names in
4041 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004042 When {abbr} is there and it is non-zero use abbreviations
4043 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004044 A match happens with a mapping that starts with {name} and
4045 with a mapping which is equal to the start of {name}.
4046
Bram Moolenaar446cb832008-06-24 21:56:24 +00004047 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004048 mapcheck("a") yes yes yes
4049 mapcheck("abc") yes yes yes
4050 mapcheck("ax") yes no no
4051 mapcheck("b") no no no
4052
4053 The difference with maparg() is that mapcheck() finds a
4054 mapping that matches with {name}, while maparg() only finds a
4055 mapping for {name} exactly.
4056 When there is no mapping that starts with {name}, an empty
4057 String is returned. If there is one, the rhs of that mapping
4058 is returned. If there are several mappings that start with
4059 {name}, the rhs of one of them is returned.
4060 The mappings local to the current buffer are checked first,
4061 then the global mappings.
4062 This function can be used to check if a mapping can be added
4063 without being ambiguous. Example: >
4064 :if mapcheck("_vv") == ""
4065 : map _vv :set guifont=7x13<CR>
4066 :endif
4067< This avoids adding the "_vv" mapping when there already is a
4068 mapping for "_v" or for "_vvv".
4069
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004070match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004071 When {expr} is a |List| then this returns the index of the
4072 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004073 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004074 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004075 Number, which gives the index (byte offset) in {expr} where
4076 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004077 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004078 If there is no match -1 is returned.
4079 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004080 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004081 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004082< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00004083 *strpbrk()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004084 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00004085 :let sepidx = match(line, '[.,;: \t]')
4086< *strcasestr()*
4087 Vim doesn't have a strcasestr() function. But you can add
4088 "\c" to the pattern to ignore case: >
4089 :let idx = match(haystack, '\cneedle')
4090<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004091 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004092 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004093 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004094 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004095 :echo match("testing", "ing", 2)
4096< result is again "4". >
4097 :echo match("testing", "ing", 4)
4098< result is again "4". >
4099 :echo match("testing", "t", 2)
4100< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004101 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00004102 {start} bytes later, thus "^" will match at {start}. Except
4103 when {count} is given, then it's like matches before the
4104 {start} byte are ignored (this is a bit complicated to keep it
4105 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004106 For a String, if {start} < 0, it will be set to 0. For a list
4107 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004108 If {start} is out of range ({start} > strlen({expr}) for a
4109 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004110
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004111 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004112 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004113 character further. Thus this example results in 1: >
4114 echo match("testing", "..", 0, 2)
4115< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004116 Note that when {count} is added the way {start} works changes,
4117 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00004118
Bram Moolenaar071d4272004-06-13 20:20:40 +00004119 See |pattern| for the patterns that are accepted.
4120 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar446cb832008-06-24 21:56:24 +00004121 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00004122 done like 'magic' is set and 'cpoptions' is empty.
4123
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004124 *matchadd()* *E798* *E799* *E801*
4125matchadd({group}, {pattern}[, {priority}[, {id}]])
4126 Defines a pattern to be highlighted in the current window (a
4127 "match"). It will be highlighted with {group}. Returns an
4128 identification number (ID), which can be used to delete the
4129 match using |matchdelete()|.
4130
4131 The optional {priority} argument assigns a priority to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004132 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004133 highlighting overrule that of a match with a lower priority.
4134 A priority is specified as an integer (negative numbers are no
4135 exception). If the {priority} argument is not specified, the
4136 default priority is 10. The priority of 'hlsearch' is zero,
4137 hence all matches with a priority greater than zero will
4138 overrule it. Syntax highlighting (see 'syntax') is a separate
4139 mechanism, and regardless of the chosen priority a match will
4140 always overrule syntax highlighting.
4141
4142 The optional {id} argument allows the request for a specific
4143 match ID. If a specified ID is already taken, an error
4144 message will appear and the match will not be added. An ID
4145 is specified as a positive integer (zero excluded). IDs 1, 2
4146 and 3 are reserved for |:match|, |:2match| and |:3match|,
4147 respectively. If the {id} argument is not specified,
4148 |matchadd()| automatically chooses a free ID.
4149
4150 The number of matches is not limited, as it is the case with
4151 the |:match| commands.
4152
4153 Example: >
4154 :highlight MyGroup ctermbg=green guibg=green
4155 :let m = matchadd("MyGroup", "TODO")
4156< Deletion of the pattern: >
4157 :call matchdelete(m)
4158
4159< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar446cb832008-06-24 21:56:24 +00004160 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004161 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004162
4163matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004164 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004165 |:2match| or |:3match| command.
4166 Return a |List| with two elements:
4167 The name of the highlight group used
4168 The pattern used.
4169 When {nr} is not 1, 2 or 3 returns an empty |List|.
4170 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004171 This is useful to save and restore a |:match|.
4172 Highlighting matches using the |:match| commands are limited
4173 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004174
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004175matchdelete({id}) *matchdelete()* *E802* *E803*
4176 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00004177 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004178 otherwise -1. See example for |matchadd()|. All matches can
4179 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004180
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004181matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004182 Same as |match()|, but return the index of first character
4183 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004184 :echo matchend("testing", "ing")
4185< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00004186 *strspn()* *strcspn()*
4187 Vim doesn't have a strspn() or strcspn() function, but you can
4188 do it with matchend(): >
4189 :let span = matchend(line, '[a-zA-Z]')
4190 :let span = matchend(line, '[^a-zA-Z]')
4191< Except that -1 is returned when there are no matches.
4192
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004193 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004194 :echo matchend("testing", "ing", 2)
4195< results in "7". >
4196 :echo matchend("testing", "ing", 5)
4197< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004198 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004199
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004200matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004201 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004202 list is the matched string, same as what matchstr() would
4203 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004204 in |:substitute|. When an optional submatch didn't match an
4205 empty string is used. Example: >
4206 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
4207< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004208 When there is no match an empty list is returned.
4209
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004210matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004211 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004212 :echo matchstr("testing", "ing")
4213< results in "ing".
4214 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004215 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004216 :echo matchstr("testing", "ing", 2)
4217< results in "ing". >
4218 :echo matchstr("testing", "ing", 5)
4219< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004220 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004221 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004222
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004223 *max()*
4224max({list}) Return the maximum value of all items in {list}.
4225 If {list} is not a list or one of the items in {list} cannot
4226 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004227 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004228
4229 *min()*
Bram Moolenaar79166c42007-05-10 18:29:51 +00004230min({list}) Return the minimum value of all items in {list}.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004231 If {list} is not a list or one of the items in {list} cannot
4232 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004233 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004234
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004235 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004236mkdir({name} [, {path} [, {prot}]])
4237 Create directory {name}.
4238 If {path} is "p" then intermediate directories are created as
4239 necessary. Otherwise it must be "".
4240 If {prot} is given it is used to set the protection bits of
4241 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar446cb832008-06-24 21:56:24 +00004242 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00004243 for others. This is only used for the last part of {name}.
4244 Thus if you create /tmp/foo/bar then /tmp/foo will be created
4245 with 0755.
4246 Example: >
4247 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
4248< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004249 Not available on all systems. To check use: >
4250 :if exists("*mkdir")
4251<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004252 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004253mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00004254 If [expr] is supplied and it evaluates to a non-zero Number or
4255 a non-empty String (|non-zero-arg|), then the full mode is
4256 returned, otherwise only the first letter is returned. Note
4257 that " " and "0" are also non-empty strings.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004258
Bram Moolenaar071d4272004-06-13 20:20:40 +00004259 n Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00004260 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00004261 v Visual by character
4262 V Visual by line
4263 CTRL-V Visual blockwise
4264 s Select by character
4265 S Select by line
4266 CTRL-S Select blockwise
4267 i Insert
Bram Moolenaar446cb832008-06-24 21:56:24 +00004268 R Replace |R|
4269 Rv Virtual Replace |gR|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004270 c Command-line
Bram Moolenaar446cb832008-06-24 21:56:24 +00004271 cv Vim Ex mode |gQ|
4272 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004273 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00004274 rm The -- more -- prompt
4275 r? A |:confirm| query of some sort
4276 ! Shell or external command is executing
4277 This is useful in the 'statusline' option or when used
4278 with |remote_expr()| In most other places it always returns
4279 "c" or "n".
4280 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004281
Bram Moolenaar7e506b62010-01-19 15:55:06 +01004282mzeval({expr}) *mzeval()*
4283 Evaluate MzScheme expression {expr} and return its result
4284 convert to Vim data structures.
4285 Numbers and strings are returned as they are.
4286 Pairs (including lists and improper lists) and vectors are
4287 returned as Vim |Lists|.
4288 Hash tables are represented as Vim |Dictionary| type with keys
4289 converted to strings.
4290 All other types are converted to string with display function.
4291 Examples: >
4292 :mz (define l (list 1 2 3))
4293 :mz (define h (make-hash)) (hash-set! h "list" l)
4294 :echo mzeval("l")
4295 :echo mzeval("h")
4296<
4297 {only available when compiled with the |+mzscheme| feature}
4298
Bram Moolenaar071d4272004-06-13 20:20:40 +00004299nextnonblank({lnum}) *nextnonblank()*
4300 Return the line number of the first line at or below {lnum}
4301 that is not blank. Example: >
4302 if getline(nextnonblank(1)) =~ "Java"
4303< When {lnum} is invalid or there is no non-blank line at or
4304 below it, zero is returned.
4305 See also |prevnonblank()|.
4306
4307nr2char({expr}) *nr2char()*
4308 Return a string with a single character, which has the number
4309 value {expr}. Examples: >
4310 nr2char(64) returns "@"
4311 nr2char(32) returns " "
4312< The current 'encoding' is used. Example for "utf-8": >
4313 nr2char(300) returns I with bow character
4314< Note that a NUL character in the file is specified with
4315 nr2char(10), because NULs are represented with newline
4316 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004317 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004318
Bram Moolenaar18081e32008-02-20 19:11:07 +00004319 *getpid()*
4320getpid() Return a Number which is the process ID of the Vim process.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004321 On Unix and MS-Windows this is a unique number, until Vim
4322 exits. On MS-DOS it's always zero.
Bram Moolenaar18081e32008-02-20 19:11:07 +00004323
Bram Moolenaar0b238792006-03-02 22:49:12 +00004324 *getpos()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004325getpos({expr}) Get the position for {expr}. For possible values of {expr}
4326 see |line()|.
4327 The result is a |List| with four numbers:
4328 [bufnum, lnum, col, off]
4329 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4330 is the buffer number of the mark.
4331 "lnum" and "col" are the position in the buffer. The first
4332 column is 1.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004333 The "off" number is zero, unless 'virtualedit' is used. Then
4334 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004335 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar0b238792006-03-02 22:49:12 +00004336 character.
4337 This can be used to save and restore the cursor position: >
4338 let save_cursor = getpos(".")
4339 MoveTheCursorAround
Bram Moolenaardb552d602006-03-23 22:59:57 +00004340 call setpos('.', save_cursor)
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004341< Also see |setpos()|.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004342
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004343pathshorten({expr}) *pathshorten()*
4344 Shorten directory names in the path {expr} and return the
4345 result. The tail, the file name, is kept as-is. The other
4346 components in the path are reduced to single letters. Leading
4347 '~' and '.' characters are kept. Example: >
4348 :echo pathshorten('~/.vim/autoload/myfile.vim')
4349< ~/.v/a/myfile.vim ~
4350 It doesn't matter if the path exists or not.
4351
Bram Moolenaar446cb832008-06-24 21:56:24 +00004352pow({x}, {y}) *pow()*
4353 Return the power of {x} to the exponent {y} as a |Float|.
4354 {x} and {y} must evaluate to a |Float| or a |Number|.
4355 Examples: >
4356 :echo pow(3, 3)
4357< 27.0 >
4358 :echo pow(2, 16)
4359< 65536.0 >
4360 :echo pow(32, 0.20)
4361< 2.0
4362 {only available when compiled with the |+float| feature}
4363
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004364prevnonblank({lnum}) *prevnonblank()*
4365 Return the line number of the first line at or above {lnum}
4366 that is not blank. Example: >
4367 let ind = indent(prevnonblank(v:lnum - 1))
4368< When {lnum} is invalid or there is no non-blank line at or
4369 above it, zero is returned.
4370 Also see |nextnonblank()|.
4371
4372
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004373printf({fmt}, {expr1} ...) *printf()*
4374 Return a String with {fmt}, where "%" items are replaced by
4375 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004376 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004377< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004378 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004379
4380 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004381 %s string
Bram Moolenaar98692072006-02-04 00:57:42 +00004382 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00004383 %.9s string truncated to 9 bytes
4384 %c single byte
4385 %d decimal number
4386 %5d decimal number padded with spaces to 5 characters
4387 %x hex number
4388 %04x hex number padded with zeros to at least 4 characters
4389 %X hex number using upper case letters
4390 %o octal number
4391 %f floating point number in the form 123.456
4392 %e floating point number in the form 1.234e3
4393 %E floating point number in the form 1.234E3
4394 %g floating point number, as %f or %e depending on value
4395 %G floating point number, as %f or %E depending on value
4396 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004397
4398 Conversion specifications start with '%' and end with the
4399 conversion type. All other characters are copied unchanged to
4400 the result.
4401
4402 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004403 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004404
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004405 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004406
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004407 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004408 Zero or more of the following flags:
4409
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004410 # The value should be converted to an "alternate
4411 form". For c, d, and s conversions, this option
4412 has no effect. For o conversions, the precision
4413 of the number is increased to force the first
4414 character of the output string to a zero (except
4415 if a zero value is printed with an explicit
4416 precision of zero).
4417 For x and X conversions, a non-zero result has
4418 the string "0x" (or "0X" for X conversions)
4419 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004420
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004421 0 (zero) Zero padding. For all conversions the converted
4422 value is padded on the left with zeros rather
4423 than blanks. If a precision is given with a
4424 numeric conversion (d, o, x, and X), the 0 flag
4425 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004426
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004427 - A negative field width flag; the converted value
4428 is to be left adjusted on the field boundary.
4429 The converted value is padded on the right with
4430 blanks, rather than on the left with blanks or
4431 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004432
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004433 ' ' (space) A blank should be left before a positive
4434 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004435
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004436 + A sign must always be placed before a number
Bram Moolenaar446cb832008-06-24 21:56:24 +00004437 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004438 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004439
4440 field-width
4441 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00004442 field width. If the converted value has fewer bytes
4443 than the field width, it will be padded with spaces on
4444 the left (or right, if the left-adjustment flag has
4445 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004446
4447 .precision
4448 An optional precision, in the form of a period '.'
4449 followed by an optional digit string. If the digit
4450 string is omitted, the precision is taken as zero.
4451 This gives the minimum number of digits to appear for
4452 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00004453 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004454 For floating point it is the number of digits after
4455 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004456
4457 type
4458 A character that specifies the type of conversion to
4459 be applied, see below.
4460
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004461 A field width or precision, or both, may be indicated by an
4462 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar446cb832008-06-24 21:56:24 +00004463 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004464 negative field width is treated as a left adjustment flag
4465 followed by a positive field width; a negative precision is
4466 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004467 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004468< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004469 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004470
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004471 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004472
Bram Moolenaar446cb832008-06-24 21:56:24 +00004473 *printf-d* *printf-o* *printf-x* *printf-X*
4474 doxX The Number argument is converted to signed decimal
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004475 (d), unsigned octal (o), or unsigned hexadecimal (x
4476 and X) notation. The letters "abcdef" are used for
4477 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004478 conversions.
4479 The precision, if any, gives the minimum number of
4480 digits that must appear; if the converted value
4481 requires fewer digits, it is padded on the left with
4482 zeros.
4483 In no case does a non-existent or small field width
4484 cause truncation of a numeric field; if the result of
4485 a conversion is wider than the field width, the field
4486 is expanded to contain the conversion result.
4487
Bram Moolenaar446cb832008-06-24 21:56:24 +00004488 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004489 c The Number argument is converted to a byte, and the
4490 resulting character is written.
4491
Bram Moolenaar446cb832008-06-24 21:56:24 +00004492 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004493 s The text of the String argument is used. If a
4494 precision is specified, no more bytes than the number
4495 specified are used.
4496
Bram Moolenaar446cb832008-06-24 21:56:24 +00004497 *printf-f* *E807*
4498 f The Float argument is converted into a string of the
4499 form 123.456. The precision specifies the number of
4500 digits after the decimal point. When the precision is
4501 zero the decimal point is omitted. When the precision
4502 is not specified 6 is used. A really big number
4503 (out of range or dividing by zero) results in "inf".
4504 "0.0 / 0.0" results in "nan".
4505 Example: >
4506 echo printf("%.2f", 12.115)
4507< 12.12
4508 Note that roundoff depends on the system libraries.
4509 Use |round()| when in doubt.
4510
4511 *printf-e* *printf-E*
4512 e E The Float argument is converted into a string of the
4513 form 1.234e+03 or 1.234E+03 when using 'E'. The
4514 precision specifies the number of digits after the
4515 decimal point, like with 'f'.
4516
4517 *printf-g* *printf-G*
4518 g G The Float argument is converted like with 'f' if the
4519 value is between 0.001 (inclusive) and 10000000.0
4520 (exclusive). Otherwise 'e' is used for 'g' and 'E'
4521 for 'G'. When no precision is specified superfluous
4522 zeroes and '+' signs are removed, except for the zero
4523 immediately after the decimal point. Thus 10000000.0
4524 results in 1.0e7.
4525
4526 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004527 % A '%' is written. No argument is converted. The
4528 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004529
Bram Moolenaarc236c162008-07-13 17:41:49 +00004530 When a Number argument is expected a String argument is also
4531 accepted and automatically converted.
4532 When a Float or String argument is expected a Number argument
4533 is also accepted and automatically converted.
4534 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004535
Bram Moolenaar83bab712005-08-01 21:58:57 +00004536 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004537 The number of {exprN} arguments must exactly match the number
4538 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00004539 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00004540
4541
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004542pumvisible() *pumvisible()*
4543 Returns non-zero when the popup menu is visible, zero
4544 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004545 This can be used to avoid some things that would remove the
4546 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004547
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004548 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00004549range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004550 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00004551 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
4552 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
4553 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4554 {max}] (increasing {expr} with {stride} each time, not
4555 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00004556 When the maximum is one before the start the result is an
4557 empty list. When the maximum is more than one before the
4558 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004559 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004560 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00004561 range(2, 4) " [2, 3, 4]
4562 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004563 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00004564 range(0) " []
4565 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00004566<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004567 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004568readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004569 Read file {fname} and return a |List|, each line of the file
4570 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004571 separated with CR will result in a single long line (unless a
4572 NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02004573 All NUL characters are replaced with a NL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004574 When {binary} is equal to "b" binary mode is used:
4575 - When the last line ends in a NL an extra empty list item is
4576 added.
4577 - No CR characters are removed.
4578 Otherwise:
4579 - CR characters that appear before a NL are removed.
4580 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02004581 - When 'encoding' is Unicode any UTF-8 byte order mark is
4582 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004583 When {max} is given this specifies the maximum number of lines
4584 to be read. Useful if you only want to check the first ten
4585 lines of a file: >
4586 :for line in readfile(fname, '', 10)
4587 : if line =~ 'Date' | echo line | endif
4588 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00004589< When {max} is negative -{max} lines from the end of the file
4590 are returned, or as many as there are.
4591 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00004592 Note that without {max} the whole file is read into memory.
4593 Also note that there is no recognition of encoding. Read a
4594 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004595 When the file can't be opened an error message is given and
4596 the result is an empty list.
4597 Also see |writefile()|.
4598
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004599reltime([{start} [, {end}]]) *reltime()*
4600 Return an item that represents a time value. The format of
4601 the item depends on the system. It can be passed to
4602 |reltimestr()| to convert it to a string.
4603 Without an argument it returns the current time.
4604 With one argument is returns the time passed since the time
4605 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004606 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004607 and {end}.
4608 The {start} and {end} arguments must be values returned by
4609 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02004610 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004611
4612reltimestr({time}) *reltimestr()*
4613 Return a String that represents the time value of {time}.
4614 This is the number of seconds, a dot and the number of
4615 microseconds. Example: >
4616 let start = reltime()
4617 call MyFunction()
4618 echo reltimestr(reltime(start))
4619< Note that overhead for the commands will be added to the time.
4620 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004621 Leading spaces are used to make the string align nicely. You
4622 can use split() to remove it. >
4623 echo split(reltimestr(reltime(start)))[0]
4624< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004625 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004626
Bram Moolenaar071d4272004-06-13 20:20:40 +00004627 *remote_expr()* *E449*
4628remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00004629 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004630 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004631 The result must be a String or a |List|. A |List| is turned
4632 into a String by joining the items with a line break in
4633 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00004634 If {idvar} is present, it is taken as the name of a
4635 variable and a {serverid} for later use with
4636 remote_read() is stored there.
4637 See also |clientserver| |RemoteReply|.
4638 This function is not available in the |sandbox|.
4639 {only available when compiled with the |+clientserver| feature}
4640 Note: Any errors will cause a local error message to be issued
4641 and the result will be the empty string.
4642 Examples: >
4643 :echo remote_expr("gvim", "2+2")
4644 :echo remote_expr("gvim1", "b:current_syntax")
4645<
4646
4647remote_foreground({server}) *remote_foreground()*
4648 Move the Vim server with the name {server} to the foreground.
4649 This works like: >
4650 remote_expr({server}, "foreground()")
4651< Except that on Win32 systems the client does the work, to work
4652 around the problem that the OS doesn't always allow the server
4653 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00004654 Note: This does not restore the window if it was minimized,
4655 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004656 This function is not available in the |sandbox|.
4657 {only in the Win32, Athena, Motif and GTK GUI versions and the
4658 Win32 console version}
4659
4660
4661remote_peek({serverid} [, {retvar}]) *remote_peek()*
4662 Returns a positive number if there are available strings
4663 from {serverid}. Copies any reply string into the variable
Bram Moolenaar446cb832008-06-24 21:56:24 +00004664 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004665 name of a variable.
4666 Returns zero if none are available.
4667 Returns -1 if something is wrong.
4668 See also |clientserver|.
4669 This function is not available in the |sandbox|.
4670 {only available when compiled with the |+clientserver| feature}
4671 Examples: >
4672 :let repl = ""
4673 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
4674
4675remote_read({serverid}) *remote_read()*
4676 Return the oldest available reply from {serverid} and consume
4677 it. It blocks until a reply is available.
4678 See also |clientserver|.
4679 This function is not available in the |sandbox|.
4680 {only available when compiled with the |+clientserver| feature}
4681 Example: >
4682 :echo remote_read(id)
4683<
4684 *remote_send()* *E241*
4685remote_send({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00004686 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00004687 keys and the function returns immediately. At the Vim server
4688 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004689 If {idvar} is present, it is taken as the name of a variable
4690 and a {serverid} for later use with remote_read() is stored
4691 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004692 See also |clientserver| |RemoteReply|.
4693 This function is not available in the |sandbox|.
4694 {only available when compiled with the |+clientserver| feature}
4695 Note: Any errors will be reported in the server and may mess
4696 up the display.
4697 Examples: >
4698 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
4699 \ remote_read(serverid)
4700
4701 :autocmd NONE RemoteReply *
4702 \ echo remote_read(expand("<amatch>"))
4703 :echo remote_send("gvim", ":sleep 10 | echo ".
4704 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004705<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004706remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004707 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004708 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004709 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004710 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004711 item as {end} a list with one item is returned. When {end}
4712 points to an item before {idx} this is an error.
4713 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004714 Example: >
4715 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004716 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00004717remove({dict}, {key})
4718 Remove the entry from {dict} with key {key}. Example: >
4719 :echo "removed " . remove(dict, "one")
4720< If there is no {key} in {dict} this is an error.
4721
4722 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004723
Bram Moolenaar071d4272004-06-13 20:20:40 +00004724rename({from}, {to}) *rename()*
4725 Rename the file by the name {from} to the name {to}. This
4726 should also work to move files across file systems. The
4727 result is a Number, which is 0 if the file was renamed
4728 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00004729 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004730 This function is not available in the |sandbox|.
4731
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004732repeat({expr}, {count}) *repeat()*
4733 Repeat {expr} {count} times and return the concatenated
4734 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004735 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004736< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004737 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar446cb832008-06-24 21:56:24 +00004738 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004739 :let longlist = repeat(['a', 'b'], 3)
4740< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00004741
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004742
Bram Moolenaar071d4272004-06-13 20:20:40 +00004743resolve({filename}) *resolve()* *E655*
4744 On MS-Windows, when {filename} is a shortcut (a .lnk file),
4745 returns the path the shortcut points to in a simplified form.
4746 On Unix, repeat resolving symbolic links in all path
4747 components of {filename} and return the simplified result.
4748 To cope with link cycles, resolving of symbolic links is
4749 stopped after 100 iterations.
4750 On other systems, return the simplified {filename}.
4751 The simplification step is done as by |simplify()|.
4752 resolve() keeps a leading path component specifying the
4753 current directory (provided the result is still a relative
4754 path name) and also keeps a trailing path separator.
4755
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004756 *reverse()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00004757reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004758 {list}.
4759 If you want a list to remain unmodified make a copy first: >
4760 :let revlist = reverse(copy(mylist))
4761
Bram Moolenaar446cb832008-06-24 21:56:24 +00004762round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00004763 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00004764 as a |Float|. If {expr} lies halfway between two integral
4765 values, then use the larger one (away from zero).
4766 {expr} must evaluate to a |Float| or a |Number|.
4767 Examples: >
4768 echo round(0.456)
4769< 0.0 >
4770 echo round(4.5)
4771< 5.0 >
4772 echo round(-4.5)
4773< -5.0
4774 {only available when compiled with the |+float| feature}
4775
4776
Bram Moolenaar76929292008-01-06 19:07:36 +00004777search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004778 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004779 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00004780
Bram Moolenaar071d4272004-06-13 20:20:40 +00004781 {flags} is a String, which can contain these character flags:
4782 'b' search backward instead of forward
Bram Moolenaar446cb832008-06-24 21:56:24 +00004783 'c' accept a match at the cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004784 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004785 'n' do Not move the cursor
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004786 'p' return number of matching sub-pattern (see below)
4787 's' set the ' mark at the previous location of the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00004788 'w' wrap around the end of the file
4789 'W' don't wrap around the end of the file
4790 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
4791
Bram Moolenaar02743632005-07-25 20:42:36 +00004792 If the 's' flag is supplied, the ' mark is set, only if the
4793 cursor is moved. The 's' flag cannot be combined with the 'n'
4794 flag.
4795
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004796 'ignorecase', 'smartcase' and 'magic' are used.
4797
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004798 When the {stopline} argument is given then the search stops
4799 after searching this line. This is useful to restrict the
4800 search to a range of lines. Examples: >
4801 let match = search('(', 'b', line("w0"))
4802 let end = search('END', '', line("w$"))
4803< When {stopline} is used and it is not zero this also implies
4804 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00004805 A zero value is equal to not giving the argument.
4806
4807 When the {timeout} argument is given the search stops when
Bram Moolenaar446cb832008-06-24 21:56:24 +00004808 more than this many milli seconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00004809 {timeout} is 500 the search stops after half a second.
4810 The value must not be negative. A zero value is like not
4811 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004812 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004813
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004814 If there is no match a 0 is returned and the cursor doesn't
4815 move. No error message is given.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004816 When a match has been found its line number is returned.
4817 *search()-sub-match*
4818 With the 'p' flag the returned value is one more than the
4819 first sub-match in \(\). One if none of them matched but the
4820 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004821 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004822
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004823 The cursor will be positioned at the match, unless the 'n'
4824 flag is used.
4825
Bram Moolenaar071d4272004-06-13 20:20:40 +00004826 Example (goes over all files in the argument list): >
4827 :let n = 1
4828 :while n <= argc() " loop over all files in arglist
4829 : exe "argument " . n
4830 : " start at the last char in the file and wrap for the
4831 : " first search to find match at start of file
4832 : normal G$
4833 : let flags = "w"
4834 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00004835 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00004836 : let flags = "W"
4837 : endwhile
4838 : update " write the file if modified
4839 : let n = n + 1
4840 :endwhile
4841<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004842 Example for using some flags: >
4843 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
4844< This will search for the keywords "if", "else", and "endif"
4845 under or after the cursor. Because of the 'p' flag, it
4846 returns 1, 2, or 3 depending on which keyword is found, or 0
4847 if the search fails. With the cursor on the first word of the
4848 line:
4849 if (foo == 0) | let foo = foo + 1 | endif ~
4850 the function returns 1. Without the 'c' flag, the function
4851 finds the "endif" and returns 3. The same thing happens
4852 without the 'e' flag if the cursor is on the "f" of "if".
4853 The 'n' flag tells the function not to move the cursor.
4854
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004855
Bram Moolenaarf75a9632005-09-13 21:20:47 +00004856searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
4857 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004858
Bram Moolenaarf75a9632005-09-13 21:20:47 +00004859 With a non-zero {global} argument it works like |gD|, find
4860 first match in the file. Otherwise it works like |gd|, find
4861 first match in the function.
4862
4863 With a non-zero {thisblock} argument matches in a {} block
4864 that ends before the cursor position are ignored. Avoids
4865 finding variable declarations only valid in another scope.
4866
Bram Moolenaar92d640f2005-09-05 22:11:52 +00004867 Moves the cursor to the found match.
4868 Returns zero for success, non-zero for failure.
4869 Example: >
4870 if searchdecl('myvar') == 0
4871 echo getline('.')
4872 endif
4873<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004874 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00004875searchpair({start}, {middle}, {end} [, {flags} [, {skip}
4876 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004877 Search for the match of a nested start-end pair. This can be
4878 used to find the "endif" that matches an "if", while other
4879 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00004880 The search starts at the cursor. The default is to search
4881 forward, include 'b' in {flags} to search backward.
4882 If a match is found, the cursor is positioned at it and the
4883 line number is returned. If no match is found 0 or -1 is
4884 returned and the cursor doesn't move. No error message is
4885 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004886
4887 {start}, {middle} and {end} are patterns, see |pattern|. They
4888 must not contain \( \) pairs. Use of \%( \) is allowed. When
4889 {middle} is not empty, it is found when searching from either
4890 direction, but only when not in a nested start-end pair. A
4891 typical use is: >
4892 searchpair('\<if\>', '\<else\>', '\<endif\>')
4893< By leaving {middle} empty the "else" is skipped.
4894
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004895 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
4896 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004897 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004898 outer pair. Implies the 'W' flag.
4899 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00004900 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004901 Note: it's nearly always a good idea to use the 'W' flag, to
4902 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004903
4904 When a match for {start}, {middle} or {end} is found, the
4905 {skip} expression is evaluated with the cursor positioned on
4906 the start of the match. It should return non-zero if this
4907 match is to be skipped. E.g., because it is inside a comment
4908 or a string.
4909 When {skip} is omitted or empty, every match is accepted.
4910 When evaluating {skip} causes an error the search is aborted
4911 and -1 returned.
4912
Bram Moolenaar76929292008-01-06 19:07:36 +00004913 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004914
Bram Moolenaar071d4272004-06-13 20:20:40 +00004915 The value of 'ignorecase' is used. 'magic' is ignored, the
4916 patterns are used like it's on.
4917
4918 The search starts exactly at the cursor. A match with
4919 {start}, {middle} or {end} at the next character, in the
4920 direction of searching, is the first one found. Example: >
4921 if 1
4922 if 2
4923 endif 2
4924 endif 1
4925< When starting at the "if 2", with the cursor on the "i", and
4926 searching forwards, the "endif 2" is found. When starting on
4927 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar446cb832008-06-24 21:56:24 +00004928 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00004929 then this is considered to be a nested if/endif from "if 2" to
4930 "endif 2".
4931 When searching backwards and {end} is more than one character,
4932 it may be useful to put "\zs" at the end of the pattern, so
4933 that when the cursor is inside a match with the end it finds
4934 the matching start.
4935
4936 Example, to find the "endif" command in a Vim script: >
4937
4938 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
4939 \ 'getline(".") =~ "^\\s*\""')
4940
4941< The cursor must be at or after the "if" for which a match is
4942 to be found. Note that single-quote strings are used to avoid
4943 having to double the backslashes. The skip expression only
4944 catches comments at the start of a line, not after a command.
4945 Also, a word "en" or "if" halfway a line is considered a
4946 match.
4947 Another example, to search for the matching "{" of a "}": >
4948
4949 :echo searchpair('{', '', '}', 'bW')
4950
4951< This works when the cursor is at or before the "}" for which a
4952 match is to be found. To reject matches that syntax
4953 highlighting recognized as strings: >
4954
4955 :echo searchpair('{', '', '}', 'bW',
4956 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
4957<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004958 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00004959searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
4960 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004961 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004962 column position of the match. The first element of the |List|
4963 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004964 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004965 returns [0, 0]. >
4966
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00004967 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
4968<
4969 See |match-parens| for a bigger and more useful example.
4970
Bram Moolenaar76929292008-01-06 19:07:36 +00004971searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004972 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004973 column position of the match. The first element of the |List|
4974 is the line number and the second element is the byte index of
4975 the column position of the match. If no match is found,
4976 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004977 Example: >
4978 :let [lnum, col] = searchpos('mypattern', 'n')
4979
4980< When the 'p' flag is given then there is an extra item with
4981 the sub-pattern match number |search()-sub-match|. Example: >
4982 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
4983< In this example "submatch" is 2 when a lowercase letter is
4984 found |/\l|, 3 when an uppercase letter is found |/\u|.
4985
Bram Moolenaar071d4272004-06-13 20:20:40 +00004986server2client( {clientid}, {string}) *server2client()*
4987 Send a reply string to {clientid}. The most recent {clientid}
4988 that sent a string can be retrieved with expand("<client>").
4989 {only available when compiled with the |+clientserver| feature}
4990 Note:
4991 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004992 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00004993 before calling any commands that waits for input.
4994 See also |clientserver|.
4995 Example: >
4996 :echo server2client(expand("<client>"), "HELLO")
4997<
4998serverlist() *serverlist()*
4999 Return a list of available server names, one per line.
5000 When there are no servers or the information is not available
5001 an empty string is returned. See also |clientserver|.
5002 {only available when compiled with the |+clientserver| feature}
5003 Example: >
5004 :echo serverlist()
5005<
5006setbufvar({expr}, {varname}, {val}) *setbufvar()*
5007 Set option or local variable {varname} in buffer {expr} to
5008 {val}.
5009 This also works for a global or local window option, but it
5010 doesn't work for a global or local window variable.
5011 For a local window option the global value is unchanged.
5012 For the use of {expr}, see |bufname()| above.
5013 Note that the variable name without "b:" must be used.
5014 Examples: >
5015 :call setbufvar(1, "&mod", 1)
5016 :call setbufvar("todo", "myvar", "foobar")
5017< This function is not available in the |sandbox|.
5018
5019setcmdpos({pos}) *setcmdpos()*
5020 Set the cursor position in the command line to byte position
Bram Moolenaar446cb832008-06-24 21:56:24 +00005021 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005022 Use |getcmdpos()| to obtain the current position.
5023 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00005024 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
5025 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
5026 set after the command line is set to the expression. For
5027 |c_CTRL-R_=| it is set after evaluating the expression but
5028 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005029 When the number is too big the cursor is put at the end of the
5030 line. A number smaller than one has undefined results.
5031 Returns 0 when successful, 1 when not editing the command
5032 line.
5033
Bram Moolenaar446cb832008-06-24 21:56:24 +00005034setline({lnum}, {text}) *setline()*
5035 Set line {lnum} of the current buffer to {text}.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005036 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005037 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005038 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005039 If this succeeds, 0 is returned. If this fails (most likely
5040 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005041 :call setline(5, strftime("%c"))
Bram Moolenaar446cb832008-06-24 21:56:24 +00005042< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005043 will be set to the items in the list. Example: >
5044 :call setline(5, ['aaa', 'bbb', 'ccc'])
5045< This is equivalent to: >
5046 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
5047 : call setline(n, l)
5048 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00005049< Note: The '[ and '] marks are not set.
5050
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005051setloclist({nr}, {list} [, {action}]) *setloclist()*
5052 Create or replace or add to the location list for window {nr}.
5053 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00005054 list window, the displayed location list is modified. For an
5055 invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005056 Otherwise, same as |setqflist()|.
5057 Also see |location-list|.
5058
5059setmatches({list}) *setmatches()*
5060 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005061 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005062 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005063
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005064 *setpos()*
5065setpos({expr}, {list})
5066 Set the position for {expr}. Possible values:
5067 . the cursor
5068 'x mark x
5069
5070 {list} must be a |List| with four numbers:
5071 [bufnum, lnum, col, off]
5072
Bram Moolenaar446cb832008-06-24 21:56:24 +00005073 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005074 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005075 the current buffer. To set a mark in another buffer you can
5076 use the |bufnr()| function to turn a file name into a buffer
5077 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00005078 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005079
5080 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005081 column is 1. Use a zero "lnum" to delete a mark. If "col" is
5082 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005083
5084 The "off" number is only used when 'virtualedit' is set. Then
5085 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005086 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005087 character.
5088
Bram Moolenaar08250432008-02-13 11:42:46 +00005089 Returns 0 when the position could be set, -1 otherwise.
5090 An error message is given if {expr} is invalid.
5091
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005092 Also see |getpos()|
5093
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005094 This does not restore the preferred column for moving
5095 vertically. See |winrestview()| for that.
5096
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005097
Bram Moolenaar35c54e52005-05-20 21:25:31 +00005098setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005099 Create or replace or add to the quickfix list using the items
5100 in {list}. Each item in {list} is a dictionary.
5101 Non-dictionary items in {list} are ignored. Each dictionary
5102 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005103
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005104 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00005105 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005106 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00005107 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005108 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005109 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00005110 col column number
5111 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005112 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00005113 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005114 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00005115 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005116
Bram Moolenaar582fd852005-03-28 20:58:01 +00005117 The "col", "vcol", "nr", "type" and "text" entries are
5118 optional. Either "lnum" or "pattern" entry can be used to
5119 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005120 If the "filename" and "bufnr" entries are not present or
5121 neither the "lnum" or "pattern" entries are present, then the
5122 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005123 If both "pattern" and "lnum" are present then "pattern" will
5124 be used.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02005125 If you supply an empty {list}, the quickfix list will be
5126 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005127 Note that the list is not exactly the same as what
5128 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005129
Bram Moolenaar35c54e52005-05-20 21:25:31 +00005130 If {action} is set to 'a', then the items from {list} are
5131 added to the existing quickfix list. If there is no existing
5132 list, then a new list is created. If {action} is set to 'r',
5133 then the items from the current quickfix list are replaced
5134 with the items from {list}. If {action} is not present or is
5135 set to ' ', then a new list is created.
5136
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005137 Returns zero for success, -1 for failure.
5138
5139 This function can be used to create a quickfix list
5140 independent of the 'errorformat' setting. Use a command like
5141 ":cc 1" to jump to the first position.
5142
5143
Bram Moolenaar071d4272004-06-13 20:20:40 +00005144 *setreg()*
5145setreg({regname}, {value} [,{options}])
5146 Set the register {regname} to {value}.
5147 If {options} contains "a" or {regname} is upper case,
5148 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02005149 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005150 "c" or "v" |characterwise| mode
5151 "l" or "V" |linewise| mode
5152 "b" or "<CTRL-V>" |blockwise-visual| mode
5153 If a number immediately follows "b" or "<CTRL-V>" then this is
5154 used as the width of the selection - if it is not specified
5155 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005156 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005157
5158 If {options} contains no register settings, then the default
5159 is to use character mode unless {value} ends in a <NL>.
5160 Setting the '=' register is not possible.
5161 Returns zero for success, non-zero for failure.
5162
5163 Examples: >
5164 :call setreg(v:register, @*)
5165 :call setreg('*', @%, 'ac')
5166 :call setreg('a', "1\n2\n3", 'b5')
5167
5168< This example shows using the functions to save and restore a
5169 register. >
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005170 :let var_a = getreg('a', 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005171 :let var_amode = getregtype('a')
5172 ....
5173 :call setreg('a', var_a, var_amode)
5174
5175< You can also change the type of a register by appending
5176 nothing: >
5177 :call setreg('a', '', 'al')
5178
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005179settabvar({tabnr}, {varname}, {val}) *settabvar()*
5180 Set tab-local variable {varname} to {val} in tab page {tabnr}.
5181 |t:var|
5182 Note that the variable name without "t:" must be used.
5183 Tabs are numbered starting with one.
5184 Vim briefly goes to the tab page {tabnr}, this may trigger
5185 TabLeave and TabEnter autocommands.
5186 This function is not available in the |sandbox|.
5187
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005188settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
5189 Set option or local variable {varname} in window {winnr} to
5190 {val}.
5191 Tabs are numbered starting with one. For the current tabpage
5192 use |setwinvar()|.
5193 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005194 This also works for a global or local buffer option, but it
5195 doesn't work for a global or local buffer variable.
5196 For a local buffer option the global value is unchanged.
5197 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005198 Vim briefly goes to the tab page {tabnr}, this may trigger
5199 TabLeave and TabEnter autocommands.
5200 Examples: >
5201 :call settabwinvar(1, 1, "&list", 0)
5202 :call settabwinvar(3, 2, "myvar", "foobar")
5203< This function is not available in the |sandbox|.
5204
5205setwinvar({nr}, {varname}, {val}) *setwinvar()*
5206 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005207 Examples: >
5208 :call setwinvar(1, "&list", 0)
5209 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005210
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005211shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005212 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005213 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005214 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005215 quotes within {string}.
5216 For other systems, it will enclose {string} in single quotes
5217 and replace all "'" with "'\''".
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005218 When the {special} argument is present and it's a non-zero
5219 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00005220 items such as "!", "%", "#" and "<cword>" will be preceded by
5221 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005222 command.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00005223 The "!" character will be escaped (again with a |non-zero-arg|
5224 {special}) when 'shell' contains "csh" in the tail. That is
5225 because for csh and tcsh "!" is used for history replacement
5226 even when inside single quotes.
5227 The <NL> character is also escaped. With a |non-zero-arg|
5228 {special} and 'shell' containing "csh" in the tail it's
5229 escaped a second time.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005230 Example of use with a |:!| command: >
5231 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
5232< This results in a directory listing for the file under the
5233 cursor. Example of use with |system()|: >
5234 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar60a495f2006-10-03 12:44:42 +00005235
5236
Bram Moolenaar071d4272004-06-13 20:20:40 +00005237simplify({filename}) *simplify()*
5238 Simplify the file name as much as possible without changing
5239 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
5240 Unix) are not resolved. If the first path component in
5241 {filename} designates the current directory, this will be
5242 valid for the result as well. A trailing path separator is
5243 not removed either.
5244 Example: >
5245 simplify("./dir/.././/file/") == "./file/"
5246< Note: The combination "dir/.." is only removed if "dir" is
5247 a searchable directory or does not exist. On Unix, it is also
5248 removed when "dir" is a symbolic link within the same
5249 directory. In order to resolve all the involved symbolic
5250 links before simplifying the path name, use |resolve()|.
5251
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005252
Bram Moolenaar446cb832008-06-24 21:56:24 +00005253sin({expr}) *sin()*
5254 Return the sine of {expr}, measured in radians, as a |Float|.
5255 {expr} must evaluate to a |Float| or a |Number|.
5256 Examples: >
5257 :echo sin(100)
5258< -0.506366 >
5259 :echo sin(-4.01)
5260< 0.763301
5261 {only available when compiled with the |+float| feature}
5262
5263
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005264sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005265 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005266 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005267 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005268 Examples: >
5269 :echo sinh(0.5)
5270< 0.521095 >
5271 :echo sinh(-0.9)
5272< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02005273 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005274
5275
Bram Moolenaar13065c42005-01-08 16:08:21 +00005276sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005277 Sort the items in {list} in-place. Returns {list}. If you
5278 want a list to remain unmodified make a copy first: >
5279 :let sortedlist = sort(copy(mylist))
5280< Uses the string representation of each item to sort on.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005281 Numbers sort after Strings, |Lists| after Numbers.
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005282 For sorting text in the current buffer use |:sort|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005283 When {func} is given and it is one then case is ignored.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005284 When {func} is a |Funcref| or a function name, this function
5285 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005286 items as argument and must return zero if they are equal, 1 or
5287 bigger if the first one sorts after the second one, -1 or
5288 smaller if the first one sorts before the second one.
5289 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005290 func MyCompare(i1, i2)
5291 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
5292 endfunc
5293 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005294< A shorter compare version for this specific simple case, which
5295 ignores overflow: >
5296 func MyCompare(i1, i2)
5297 return a:i1 - a:i2
5298 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005299<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00005300 *soundfold()*
5301soundfold({word})
5302 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00005303 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00005304 soundfolding. 'spell' must be set. When no sound folding is
5305 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00005306 This can be used for making spelling suggestions. Note that
5307 the method can be quite slow.
5308
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005309 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00005310spellbadword([{sentence}])
5311 Without argument: The result is the badly spelled word under
5312 or after the cursor. The cursor is moved to the start of the
5313 bad word. When no bad word is found in the cursor line the
5314 result is an empty string and the cursor doesn't move.
5315
5316 With argument: The result is the first word in {sentence} that
5317 is badly spelled. If there are no spelling mistakes the
5318 result is an empty string.
5319
5320 The return value is a list with two items:
5321 - The badly spelled word or an empty string.
5322 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005323 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00005324 "rare" rare word
5325 "local" word only valid in another region
5326 "caps" word should start with Capital
5327 Example: >
5328 echo spellbadword("the quik brown fox")
5329< ['quik', 'bad'] ~
5330
5331 The spelling information for the current window is used. The
5332 'spell' option must be set and the value of 'spelllang' is
5333 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005334
5335 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005336spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005337 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005338 When {max} is given up to this number of suggestions are
5339 returned. Otherwise up to 25 suggestions are returned.
5340
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005341 When the {capital} argument is given and it's non-zero only
5342 suggestions with a leading capital will be given. Use this
5343 after a match with 'spellcapcheck'.
5344
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005345 {word} can be a badly spelled word followed by other text.
5346 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00005347 suggestions also include the following text, thus you can
5348 replace a line.
5349
5350 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00005351 returned. {word} itself is not included in the suggestions,
5352 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005353
5354 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00005355 'spell' option must be set and the values of 'spelllang' and
5356 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00005357
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005358
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005359split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005360 Make a |List| out of {expr}. When {pattern} is omitted or
5361 empty each white-separated sequence of characters becomes an
5362 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005363 Otherwise the string is split where {pattern} matches,
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005364 removing the matched characters.
5365 When the first or last item is empty it is omitted, unless the
5366 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00005367 Other empty items are kept when {pattern} matches at least one
5368 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005369 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005370 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005371< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005372 :for c in split(mystring, '\zs')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00005373< If you want to keep the separator you can also use '\zs': >
5374 :echo split('abc:def:ghi', ':\zs')
5375< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005376 Splitting a table where the first element can be empty: >
5377 :let items = split(line, ':', 1)
5378< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005379
5380
Bram Moolenaar446cb832008-06-24 21:56:24 +00005381sqrt({expr}) *sqrt()*
5382 Return the non-negative square root of Float {expr} as a
5383 |Float|.
5384 {expr} must evaluate to a |Float| or a |Number|. When {expr}
5385 is negative the result is NaN (Not a Number).
5386 Examples: >
5387 :echo sqrt(100)
5388< 10.0 >
5389 :echo sqrt(-4.01)
5390< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00005391 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005392 {only available when compiled with the |+float| feature}
5393
5394
5395str2float( {expr}) *str2float()*
5396 Convert String {expr} to a Float. This mostly works the same
5397 as when using a floating point number in an expression, see
5398 |floating-point-format|. But it's a bit more permissive.
5399 E.g., "1e40" is accepted, while in an expression you need to
5400 write "1.0e40".
5401 Text after the number is silently ignored.
5402 The decimal point is always '.', no matter what the locale is
5403 set to. A comma ends the number: "12,345.67" is converted to
5404 12.0. You can strip out thousands separators with
5405 |substitute()|: >
5406 let f = str2float(substitute(text, ',', '', 'g'))
5407< {only available when compiled with the |+float| feature}
5408
5409
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005410str2nr( {expr} [, {base}]) *str2nr()*
5411 Convert string {expr} to a number.
5412 {base} is the conversion base, it can be 8, 10 or 16.
5413 When {base} is omitted base 10 is used. This also means that
5414 a leading zero doesn't cause octal conversion to be used, as
5415 with the default String to Number conversion.
5416 When {base} is 16 a leading "0x" or "0X" is ignored. With a
5417 different base the result will be zero.
5418 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005419
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005420
Bram Moolenaar72597a52010-07-18 15:31:08 +02005421strchars({expr}) *strchars()*
5422 The result is a Number, which is the number of characters
5423 String {expr} occupies. Composing characters are counted
5424 separately.
Bram Moolenaardc536092010-07-18 15:45:49 +02005425 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
5426
5427strdisplaywidth({expr}[, {col}]) *strdisplaywidth()*
5428 The result is a Number, which is the number of display cells
5429 String {expr} occupies on the screen.
5430 When {col} is omitted zero is used. Otherwise it is the
5431 screen column where to start. This matters for Tab
5432 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02005433 The option settings of the current window are used. This
5434 matters for anything that's displayed differently, such as
5435 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02005436 When {expr} contains characters with East Asian Width Class
5437 Ambiguous, this function's return value depends on 'ambiwidth'.
5438 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02005439
Bram Moolenaar071d4272004-06-13 20:20:40 +00005440strftime({format} [, {time}]) *strftime()*
5441 The result is a String, which is a formatted date and time, as
5442 specified by the {format} string. The given {time} is used,
5443 or the current time if no time is given. The accepted
5444 {format} depends on your system, thus this is not portable!
5445 See the manual page of the C function strftime() for the
5446 format. The maximum length of the result is 80 characters.
5447 See also |localtime()| and |getftime()|.
5448 The language can be changed with the |:language| command.
5449 Examples: >
5450 :echo strftime("%c") Sun Apr 27 11:49:23 1997
5451 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
5452 :echo strftime("%y%m%d %T") 970427 11:53:55
5453 :echo strftime("%H:%M") 11:55
5454 :echo strftime("%c", getftime("file.c"))
5455 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005456< Not available on all systems. To check use: >
5457 :if exists("*strftime")
5458
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005459stridx({haystack}, {needle} [, {start}]) *stridx()*
5460 The result is a Number, which gives the byte index in
5461 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00005462 If {start} is specified, the search starts at index {start}.
5463 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01005464 :let colon1 = stridx(line, ":")
5465 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00005466< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005467 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005468 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00005469 See also |strridx()|.
5470 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005471 :echo stridx("An Example", "Example") 3
5472 :echo stridx("Starting point", "Start") 0
5473 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005474< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005475 stridx() works similar to the C function strstr(). When used
5476 with a single character it works similar to strchr().
5477
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005478 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005479string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00005480 Float, String or a composition of them, then the result can be
5481 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005482 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00005483 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005484 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00005485 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00005486 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005487 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00005488 Dictionary {key: value, key: value}
Bram Moolenaard8b02732005-01-14 21:48:43 +00005489 Note that in String values the ' character is doubled.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005490 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005491
Bram Moolenaar071d4272004-06-13 20:20:40 +00005492 *strlen()*
5493strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00005494 {expr} in bytes.
5495 If you want to count the number of multi-byte characters (not
5496 counting composing characters) use something like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005497
5498 :let len = strlen(substitute(str, ".", "x", "g"))
Bram Moolenaare344bea2005-09-01 20:46:49 +00005499<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005500 If the argument is a Number it is first converted to a String.
5501 For other types an error is given.
Bram Moolenaardc536092010-07-18 15:45:49 +02005502 Also see |len()|, |strchars()|, |strdisplaywidth()| and
5503 |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005504
5505strpart({src}, {start}[, {len}]) *strpart()*
5506 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00005507 byte {start}, with the byte length {len}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005508 When non-existing bytes are included, this doesn't result in
5509 an error, the bytes are simply omitted.
5510 If {len} is missing, the copy continues from {start} till the
5511 end of the {src}. >
5512 strpart("abcdefg", 3, 2) == "de"
5513 strpart("abcdefg", -2, 4) == "ab"
5514 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00005515 strpart("abcdefg", 3) == "defg"
Bram Moolenaar071d4272004-06-13 20:20:40 +00005516< Note: To get the first character, {start} must be 0. For
5517 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00005518 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005519<
Bram Moolenaar677ee682005-01-27 14:41:15 +00005520strridx({haystack}, {needle} [, {start}]) *strridx()*
5521 The result is a Number, which gives the byte index in
5522 {haystack} of the last occurrence of the String {needle}.
5523 When {start} is specified, matches beyond this index are
5524 ignored. This can be used to find a match before a previous
5525 match: >
5526 :let lastcomma = strridx(line, ",")
5527 :let comma2 = strridx(line, ",", lastcomma - 1)
5528< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00005529 For pattern searches use |match()|.
5530 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00005531 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005532 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005533 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005534< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00005535 When used with a single character it works similar to the C
5536 function strrchr().
5537
Bram Moolenaar071d4272004-06-13 20:20:40 +00005538strtrans({expr}) *strtrans()*
5539 The result is a String, which is {expr} with all unprintable
5540 characters translated into printable characters |'isprint'|.
5541 Like they are shown in a window. Example: >
5542 echo strtrans(@a)
5543< This displays a newline in register a as "^@" instead of
5544 starting a new line.
5545
Bram Moolenaar72597a52010-07-18 15:31:08 +02005546strwidth({expr}) *strwidth()*
5547 The result is a Number, which is the number of display cells
5548 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02005549 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02005550 When {expr} contains characters with East Asian Width Class
5551 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02005552 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02005553
Bram Moolenaar071d4272004-06-13 20:20:40 +00005554submatch({nr}) *submatch()*
5555 Only for an expression in a |:substitute| command. Returns
5556 the {nr}'th submatch of the matched text. When {nr} is 0
5557 the whole matched text is returned.
5558 Example: >
5559 :s/\d\+/\=submatch(0) + 1/
5560< This finds the first number in the line and adds one to it.
5561 A line break is included as a newline character.
5562
5563substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
5564 The result is a String, which is a copy of {expr}, in which
5565 the first match of {pat} is replaced with {sub}. This works
5566 like the ":substitute" command (without any flags). But the
5567 matching with {pat} is always done like the 'magic' option is
5568 set and 'cpoptions' is empty (to make scripts portable).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005569 'ignorecase' is still relevant. 'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005570 See |string-match| for how {pat} is used.
5571 And a "~" in {sub} is not replaced with the previous {sub}.
5572 Note that some codes in {sub} have a special meaning
Bram Moolenaar446cb832008-06-24 21:56:24 +00005573 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00005574 "\n" (two characters), use "\\\\n" or '\\n'.
5575 When {pat} does not match in {expr}, {expr} is returned
5576 unmodified.
5577 When {flags} is "g", all matches of {pat} in {expr} are
5578 replaced. Otherwise {flags} should be "".
5579 Example: >
5580 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
5581< This removes the last component of the 'path' option. >
5582 :echo substitute("testing", ".*", "\\U\\0", "")
5583< results in "TESTING".
5584
Bram Moolenaar47136d72004-10-12 20:02:24 +00005585synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005586 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00005587 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005588 The syntax ID can be used with |synIDattr()| and
5589 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00005590
Bram Moolenaar47136d72004-10-12 20:02:24 +00005591 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00005592 line. 'synmaxcol' applies, in a longer line zero is returned.
5593
Bram Moolenaar071d4272004-06-13 20:20:40 +00005594 When {trans} is non-zero, transparent items are reduced to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005595 item that they reveal. This is useful when wanting to know
Bram Moolenaar071d4272004-06-13 20:20:40 +00005596 the effective color. When {trans} is zero, the transparent
5597 item is returned. This is useful when wanting to know which
5598 syntax item is effective (e.g. inside parens).
5599 Warning: This function can be very slow. Best speed is
5600 obtained by going through the file in forward direction.
5601
5602 Example (echoes the name of the syntax item under the cursor): >
5603 :echo synIDattr(synID(line("."), col("."), 1), "name")
5604<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02005605
Bram Moolenaar071d4272004-06-13 20:20:40 +00005606synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
5607 The result is a String, which is the {what} attribute of
5608 syntax ID {synID}. This can be used to obtain information
5609 about a syntax item.
5610 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar446cb832008-06-24 21:56:24 +00005611 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00005612 used, the attributes for the currently active highlighting are
5613 used (GUI, cterm or term).
5614 Use synIDtrans() to follow linked highlight groups.
5615 {what} result
5616 "name" the name of the syntax item
5617 "fg" foreground color (GUI: color name used to set
5618 the color, cterm: color number as a string,
5619 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00005620 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01005621 "font" font name (only available in the GUI)
5622 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00005623 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005624 "fg#" like "fg", but for the GUI and the GUI is
5625 running the name in "#RRGGBB" form
5626 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00005627 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00005628 "bold" "1" if bold
5629 "italic" "1" if italic
5630 "reverse" "1" if reverse
5631 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01005632 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00005633 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005634 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00005635
5636 Example (echoes the color of the syntax item under the
5637 cursor): >
5638 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
5639<
5640synIDtrans({synID}) *synIDtrans()*
5641 The result is a Number, which is the translated syntax ID of
5642 {synID}. This is the syntax group ID of what is being used to
5643 highlight the character. Highlight links given with
5644 ":highlight link" are followed.
5645
Bram Moolenaar483c5d82010-10-20 18:45:33 +02005646synconcealed({lnum}, {col}) *synconcealed()*
5647 The result is a List. The first item in the list is 0 if the
5648 character at the position {lnum} and {col} is not part of a
5649 concealable region, 1 if it is. The second item in the list is
5650 a string. If the first item is 1, the second item contains the
5651 text which will be displayed in place of the concealed text,
5652 depending on the current setting of 'conceallevel'. The third
5653 and final item in the list is a unique number representing the
5654 specific syntax region matched. This allows detection of the
5655 beginning of a new concealable region if there are two
5656 consecutive regions with the same replacement character.
5657 For an example use see $VIMRUNTIME/syntax/2html.vim .
5658
5659
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00005660synstack({lnum}, {col}) *synstack()*
5661 Return a |List|, which is the stack of syntax items at the
5662 position {lnum} and {col} in the current window. Each item in
5663 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00005664 The first item in the List is the outer region, following are
5665 items contained in that one. The last one is what |synID()|
5666 returns, unless not the whole item is highlighted or it is a
5667 transparent item.
5668 This function is useful for debugging a syntax file.
5669 Example that shows the syntax stack under the cursor: >
5670 for id in synstack(line("."), col("."))
5671 echo synIDattr(id, "name")
5672 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02005673< When the position specified with {lnum} and {col} is invalid
5674 nothing is returned. The position just after the last
5675 character in a line and the first column in an empty line are
5676 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00005677
Bram Moolenaarc0197e22004-09-13 20:26:32 +00005678system({expr} [, {input}]) *system()* *E677*
5679 Get the output of the shell command {expr}.
5680 When {input} is given, this string is written to a file and
5681 passed as stdin to the command. The string is written as-is,
5682 you need to take care of using the correct line separators
Bram Moolenaar05159a02005-02-26 23:04:13 +00005683 yourself. Pipes are not used.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005684 Note: Use |shellescape()| to escape special characters in a
5685 command argument. Newlines in {expr} may cause the command to
5686 fail. The characters in 'shellquote' and 'shellxquote' may
5687 also cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005688 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005689
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005690 The result is a String. Example: >
5691 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar071d4272004-06-13 20:20:40 +00005692
5693< To make the result more system-independent, the shell output
5694 is filtered to replace <CR> with <NL> for Macintosh, and
5695 <CR><NL> with <NL> for DOS-like systems.
5696 The command executed is constructed using several options:
5697 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
5698 ({tmp} is an automatically generated file name).
5699 For Unix and OS/2 braces are put around {expr} to allow for
5700 concatenated commands.
5701
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005702 The command will be executed in "cooked" mode, so that a
5703 CTRL-C will interrupt the command (on Unix at least).
5704
Bram Moolenaar071d4272004-06-13 20:20:40 +00005705 The resulting error code can be found in |v:shell_error|.
5706 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00005707
5708 Note that any wrong value in the options mentioned above may
5709 make the function fail. It has also been reported to fail
5710 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005711 Unlike ":!cmd" there is no automatic check for changed files.
5712 Use |:checktime| to force a check.
5713
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005714
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005715tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005716 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005717 buffer associated with each window in the current tab page.
5718 {arg} specifies the number of tab page to be used. When
5719 omitted the current tab page is used.
5720 When {arg} is invalid the number zero is returned.
5721 To get a list of all buffers in all tabs use this: >
5722 tablist = []
5723 for i in range(tabpagenr('$'))
5724 call extend(tablist, tabpagebuflist(i + 1))
5725 endfor
5726< Note that a buffer may appear in more than one window.
5727
5728
5729tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00005730 The result is a Number, which is the number of the current
5731 tab page. The first tab page has number 1.
5732 When the optional argument is "$", the number of the last tab
5733 page is returned (the tab page count).
5734 The number can be used with the |:tab| command.
5735
5736
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005737tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02005738 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00005739 {tabarg} specifies the number of tab page to be used.
5740 {arg} is used like with |winnr()|:
5741 - When omitted the current window number is returned. This is
5742 the window which will be used when going to this tab page.
5743 - When "$" the number of windows is returned.
5744 - When "#" the previous window nr is returned.
5745 Useful examples: >
5746 tabpagewinnr(1) " current window of tab page 1
5747 tabpagewinnr(4, '$') " number of windows in tab page 4
5748< When {tabarg} is invalid zero is returned.
5749
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00005750 *tagfiles()*
5751tagfiles() Returns a |List| with the file names used to search for tags
5752 for the current buffer. This is the 'tags' option expanded.
5753
5754
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005755taglist({expr}) *taglist()*
5756 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00005757 Each list item is a dictionary with at least the following
5758 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00005759 name Name of the tag.
5760 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005761 defined. It is either relative to the
5762 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005763 cmd Ex command used to locate the tag in
5764 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00005765 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005766 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005767 kind values. Only available when
5768 using a tags file generated by
5769 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00005770 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005771 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005772 More entries may be present, depending on the content of the
5773 tags file: access, implementation, inherits and signature.
5774 Refer to the ctags documentation for information about these
5775 fields. For C code the fields "struct", "class" and "enum"
5776 may appear, they give the name of the entity the tag is
5777 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005778
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00005779 The ex-command 'cmd' can be either an ex search pattern, a
5780 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005781
5782 If there are no matching tags, then an empty list is returned.
5783
5784 To get an exact tag match, the anchors '^' and '$' should be
5785 used in {expr}. Refer to |tag-regexp| for more information
5786 about the tag search regular expression pattern.
5787
5788 Refer to |'tags'| for information about how the tags file is
5789 located by Vim. Refer to |tags-file-format| for the format of
5790 the tags file generated by the different ctags tools.
5791
Bram Moolenaar071d4272004-06-13 20:20:40 +00005792tempname() *tempname()* *temp-file-name*
5793 The result is a String, which is the name of a file that
Bram Moolenaar446cb832008-06-24 21:56:24 +00005794 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar071d4272004-06-13 20:20:40 +00005795 is different for at least 26 consecutive calls. Example: >
5796 :let tmpfile = tempname()
5797 :exe "redir > " . tmpfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005798< For Unix, the file will be in a private directory |tempfile|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005799 For MS-Windows forward slashes are used when the 'shellslash'
5800 option is set or when 'shellcmdflag' starts with '-'.
5801
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005802
5803tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005804 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005805 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005806 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005807 Examples: >
5808 :echo tan(10)
5809< 0.648361 >
5810 :echo tan(-4.01)
5811< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02005812 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005813
5814
5815tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005816 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005817 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02005818 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005819 Examples: >
5820 :echo tanh(0.5)
5821< 0.462117 >
5822 :echo tanh(-1)
5823< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02005824 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02005825
5826
Bram Moolenaar071d4272004-06-13 20:20:40 +00005827tolower({expr}) *tolower()*
5828 The result is a copy of the String given, with all uppercase
5829 characters turned into lowercase (just like applying |gu| to
5830 the string).
5831
5832toupper({expr}) *toupper()*
5833 The result is a copy of the String given, with all lowercase
5834 characters turned into uppercase (just like applying |gU| to
5835 the string).
5836
Bram Moolenaar8299df92004-07-10 09:47:34 +00005837tr({src}, {fromstr}, {tostr}) *tr()*
5838 The result is a copy of the {src} string with all characters
5839 which appear in {fromstr} replaced by the character in that
5840 position in the {tostr} string. Thus the first character in
5841 {fromstr} is translated into the first character in {tostr}
5842 and so on. Exactly like the unix "tr" command.
5843 This code also deals with multibyte characters properly.
5844
5845 Examples: >
5846 echo tr("hello there", "ht", "HT")
5847< returns "Hello THere" >
5848 echo tr("<blob>", "<>", "{}")
5849< returns "{blob}"
5850
Bram Moolenaar446cb832008-06-24 21:56:24 +00005851trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00005852 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00005853 equal to {expr} as a |Float| (truncate towards zero).
5854 {expr} must evaluate to a |Float| or a |Number|.
5855 Examples: >
5856 echo trunc(1.456)
5857< 1.0 >
5858 echo trunc(-5.456)
5859< -5.0 >
5860 echo trunc(4.0)
5861< 4.0
5862 {only available when compiled with the |+float| feature}
5863
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005864 *type()*
5865type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00005866 Number: 0
5867 String: 1
5868 Funcref: 2
5869 List: 3
5870 Dictionary: 4
Bram Moolenaar446cb832008-06-24 21:56:24 +00005871 Float: 5
Bram Moolenaar748bf032005-02-02 23:04:36 +00005872 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005873 :if type(myvar) == type(0)
5874 :if type(myvar) == type("")
5875 :if type(myvar) == type(function("tr"))
5876 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00005877 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00005878 :if type(myvar) == type(0.0)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005879
Bram Moolenaara17d4c12010-05-30 18:30:36 +02005880undofile({name}) *undofile()*
5881 Return the name of the undo file that would be used for a file
5882 with name {name} when writing. This uses the 'undodir'
5883 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02005884 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02005885 {name} is always expanded to the full path, since that is what
5886 is used internally.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02005887 Useful in combination with |:wundo| and |:rundo|.
5888 When compiled without the +persistent_undo option this always
5889 returns an empty string.
5890
Bram Moolenaara800b422010-06-27 01:15:55 +02005891undotree() *undotree()*
5892 Return the current state of the undo tree in a dictionary with
5893 the following items:
5894 "seq_last" The highest undo sequence number used.
5895 "seq_cur" The sequence number of the current position in
5896 the undo tree. This differs from "seq_last"
5897 when some changes were undone.
5898 "time_cur" Time last used for |:earlier| and related
5899 commands. Use |strftime()| to convert to
5900 something readable.
5901 "save_last" Number of the last file write. Zero when no
5902 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02005903 "save_cur" Number of the current position in the undo
5904 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02005905 "synced" Non-zero when the last undo block was synced.
5906 This happens when waiting from input from the
5907 user. See |undo-blocks|.
5908 "entries" A list of dictionaries with information about
5909 undo blocks.
5910
5911 The first item in the "entries" list is the oldest undo item.
5912 Each List item is a Dictionary with these items:
5913 "seq" Undo sequence number. Same as what appears in
5914 |:undolist|.
5915 "time" Timestamp when the change happened. Use
5916 |strftime()| to convert to something readable.
5917 "newhead" Only appears in the item that is the last one
5918 that was added. This marks the last change
5919 and where further changes will be added.
5920 "curhead" Only appears in the item that is the last one
5921 that was undone. This marks the current
5922 position in the undo tree, the block that will
5923 be used by a redo command. When nothing was
5924 undone after the last change this item will
5925 not appear anywhere.
5926 "save" Only appears on the last block before a file
5927 write. The number is the write count. The
5928 first write has number 1, the last one the
5929 "save_last" mentioned above.
5930 "alt" Alternate entry. This is again a List of undo
5931 blocks. Each item may again have an "alt"
5932 item.
5933
Bram Moolenaar677ee682005-01-27 14:41:15 +00005934values({dict}) *values()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005935 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005936 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00005937
5938
Bram Moolenaar071d4272004-06-13 20:20:40 +00005939virtcol({expr}) *virtcol()*
5940 The result is a Number, which is the screen column of the file
5941 position given with {expr}. That is, the last screen position
5942 occupied by the character at that position, when the screen
5943 would be of unlimited width. When there is a <Tab> at the
5944 position, the returned Number will be the column at the end of
5945 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
5946 set to 8, it returns 8.
Bram Moolenaar477933c2007-07-17 14:32:23 +00005947 For the byte position use |col()|.
5948 For the use of {expr} see |col()|.
5949 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00005950 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005951 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar0b238792006-03-02 22:49:12 +00005952 character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005953 When Virtual editing is active in the current mode, a position
5954 beyond the end of the line can be returned. |'virtualedit'|
5955 The accepted positions are:
5956 . the cursor position
5957 $ the end of the cursor line (the result is the
5958 number of displayed characters in the cursor line
5959 plus one)
5960 'x position of mark x (if the mark is not set, 0 is
5961 returned)
5962 Note that only marks in the current file can be used.
5963 Examples: >
5964 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
5965 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00005966 virtcol("'t") with text " there", with 't at 'h', returns 6
5967< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005968 A more advanced example that echoes the maximum length of
5969 all lines: >
5970 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
5971
Bram Moolenaar071d4272004-06-13 20:20:40 +00005972
5973visualmode([expr]) *visualmode()*
5974 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005975 used in the current buffer. Initially it returns an empty
5976 string, but once Visual mode has been used, it returns "v",
5977 "V", or "<CTRL-V>" (a single CTRL-V character) for
5978 character-wise, line-wise, or block-wise Visual mode
5979 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005980 Example: >
5981 :exe "normal " . visualmode()
5982< This enters the same Visual mode as before. It is also useful
5983 in scripts if you wish to act differently depending on the
5984 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005985 If Visual mode is active, use |mode()| to get the Visual mode
5986 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005987 *non-zero-arg*
5988 If [expr] is supplied and it evaluates to a non-zero Number or
5989 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaar446cb832008-06-24 21:56:24 +00005990 the old value is returned. Note that " " and "0" are also
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005991 non-empty strings, thus cause the mode to be cleared. A List,
5992 Dictionary or Float is not a Number or String, thus does not
5993 cause the mode to be cleared.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005994
5995 *winbufnr()*
5996winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005997 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005998 the buffer in the current window is returned. When window
5999 {nr} doesn't exist, -1 is returned.
6000 Example: >
6001 :echo "The file in the current window is " . bufname(winbufnr(0))
6002<
6003 *wincol()*
6004wincol() The result is a Number, which is the virtual column of the
6005 cursor in the window. This is counting screen cells from the
6006 left side of the window. The leftmost column is one.
6007
6008winheight({nr}) *winheight()*
6009 The result is a Number, which is the height of window {nr}.
6010 When {nr} is zero, the height of the current window is
6011 returned. When window {nr} doesn't exist, -1 is returned.
6012 An existing window always has a height of zero or more.
6013 Examples: >
6014 :echo "The current window has " . winheight(0) . " lines."
6015<
6016 *winline()*
6017winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar446cb832008-06-24 21:56:24 +00006018 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00006019 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006020 If the cursor was moved the view on the file will be updated
6021 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006022
6023 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006024winnr([{arg}]) The result is a Number, which is the number of the current
6025 window. The top window has number 1.
6026 When the optional argument is "$", the number of the
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00006027 last window is returned (the window count).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006028 When the optional argument is "#", the number of the last
6029 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006030 If there is no previous window or it is in another tab page 0
6031 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00006032 The number can be used with |CTRL-W_w| and ":wincmd w"
6033 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006034 Also see |tabpagewinnr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006035
6036 *winrestcmd()*
6037winrestcmd() Returns a sequence of |:resize| commands that should restore
6038 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006039 are opened or closed and the current window and tab page is
6040 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006041 Example: >
6042 :let cmd = winrestcmd()
6043 :call MessWithWindowSizes()
6044 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006045<
6046 *winrestview()*
6047winrestview({dict})
6048 Uses the |Dictionary| returned by |winsaveview()| to restore
6049 the view of the current window.
6050 If you have changed the values the result is unpredictable.
6051 If the window size changed the result won't be the same.
6052
6053 *winsaveview()*
6054winsaveview() Returns a |Dictionary| that contains information to restore
6055 the view of the current window. Use |winrestview()| to
6056 restore the view.
6057 This is useful if you have a mapping that jumps around in the
6058 buffer and you want to go back to the original view.
6059 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00006060 option to temporarily switch off folding, so that folds are
6061 not opened when moving around.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006062 The return value includes:
6063 lnum cursor line number
6064 col cursor column
6065 coladd cursor column offset for 'virtualedit'
6066 curswant column for vertical movement
6067 topline first line in the window
6068 topfill filler lines, only in diff mode
6069 leftcol first column displayed
6070 skipcol columns skipped
6071 Note that no option values are saved.
6072
Bram Moolenaar071d4272004-06-13 20:20:40 +00006073
6074winwidth({nr}) *winwidth()*
6075 The result is a Number, which is the width of window {nr}.
6076 When {nr} is zero, the width of the current window is
6077 returned. When window {nr} doesn't exist, -1 is returned.
6078 An existing window always has a width of zero or more.
6079 Examples: >
6080 :echo "The current window has " . winwidth(0) . " columns."
6081 :if winwidth(0) <= 50
6082 : exe "normal 50\<C-W>|"
6083 :endif
6084<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006085 *writefile()*
6086writefile({list}, {fname} [, {binary}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006087 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006088 separated with a NL. Each list item must be a String or
6089 Number.
6090 When {binary} is equal to "b" binary mode is used: There will
6091 not be a NL after the last list item. An empty item at the
6092 end does cause the last line in the file to end in a NL.
6093 All NL characters are replaced with a NUL character.
6094 Inserting CR characters needs to be done before passing {list}
6095 to writefile().
6096 An existing file is overwritten, if possible.
6097 When the write fails -1 is returned, otherwise 0. There is an
6098 error message if the file can't be created or when writing
6099 fails.
6100 Also see |readfile()|.
6101 To copy a file byte for byte: >
6102 :let fl = readfile("foo", "b")
6103 :call writefile(fl, "foocopy", "b")
6104<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006105
6106 *feature-list*
6107There are three types of features:
61081. Features that are only supported when they have been enabled when Vim
6109 was compiled |+feature-list|. Example: >
6110 :if has("cindent")
61112. Features that are only supported when certain conditions have been met.
6112 Example: >
6113 :if has("gui_running")
6114< *has-patch*
61153. Included patches. First check |v:version| for the version of Vim.
6116 Then the "patch123" feature means that patch 123 has been included for
6117 this version. Example (checking version 6.2.148 or later): >
6118 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006119< Note that it's possible for patch 147 to be omitted even though 148 is
6120 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006121
6122all_builtin_terms Compiled with all builtin terminals enabled.
6123amiga Amiga version of Vim.
6124arabic Compiled with Arabic support |Arabic|.
6125arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00006126autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006127balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00006128balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006129beos BeOS version of Vim.
6130browse Compiled with |:browse| support, and browse() will
6131 work.
6132builtin_terms Compiled with some builtin terminals.
6133byte_offset Compiled with support for 'o' in 'statusline'
6134cindent Compiled with 'cindent' support.
6135clientserver Compiled with remote invocation support |clientserver|.
6136clipboard Compiled with 'clipboard' support.
6137cmdline_compl Compiled with |cmdline-completion| support.
6138cmdline_hist Compiled with |cmdline-history| support.
6139cmdline_info Compiled with 'showcmd' and 'ruler' support.
6140comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006141compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006142cryptv Compiled with encryption support |encryption|.
6143cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006144debug Compiled with "DEBUG" defined.
6145dialog_con Compiled with console dialog support.
6146dialog_gui Compiled with GUI dialog support.
6147diff Compiled with |vimdiff| and 'diff' support.
6148digraphs Compiled with support for digraphs.
6149dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006150dos16 16 bits DOS version of Vim.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006151dos32 32 bits DOS (DJGPP) version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006152ebcdic Compiled on a machine with ebcdic character set.
6153emacs_tags Compiled with support for Emacs tags.
6154eval Compiled with expression evaluation support. Always
6155 true, of course!
6156ex_extra Compiled with extra Ex commands |+ex_extra|.
6157extra_search Compiled with support for |'incsearch'| and
6158 |'hlsearch'|
6159farsi Compiled with Farsi support |farsi|.
6160file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006161filterpipe When 'shelltemp' is off pipes are used for shell
6162 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00006163find_in_path Compiled with support for include file searches
6164 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006165float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006166fname_case Case in file names matters (for Amiga, MS-DOS, and
6167 Windows this is not present).
6168folding Compiled with |folding| support.
6169footer Compiled with GUI footer support. |gui-footer|
6170fork Compiled to use fork()/exec() instead of system().
6171gettext Compiled with message translation |multi-lang|
6172gui Compiled with GUI enabled.
6173gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006174gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006175gui_gtk Compiled with GTK+ GUI (any version).
6176gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
6177gui_mac Compiled with Macintosh GUI.
6178gui_motif Compiled with Motif GUI.
6179gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006180gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006181gui_win32 Compiled with MS Windows Win32 GUI.
6182gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006183hangul_input Compiled with Hangul input support. |hangul|
6184iconv Can use iconv() for conversion.
6185insert_expand Compiled with support for CTRL-X expansion commands in
6186 Insert mode.
6187jumplist Compiled with |jumplist| support.
6188keymap Compiled with 'keymap' support.
6189langmap Compiled with 'langmap' support.
6190libcall Compiled with |libcall()| support.
6191linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
6192 support.
6193lispindent Compiled with support for lisp indenting.
6194listcmds Compiled with commands for the buffer list |:files|
6195 and the argument list |arglist|.
6196localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02006197lua Compiled with Lua interface |Lua|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006198mac Macintosh version of Vim.
6199macunix Macintosh version of Vim, using Unix files (OS-X).
6200menu Compiled with support for |:menu|.
6201mksession Compiled with support for |:mksession|.
6202modify_fname Compiled with file name modifiers. |filename-modifiers|
6203mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006204mouse_dec Compiled with support for Dec terminal mouse.
6205mouse_gpm Compiled with support for gpm (Linux console mouse)
6206mouse_netterm Compiled with support for netterm mouse.
6207mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006208mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006209mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006210mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00006211multi_byte Compiled with support for 'encoding'
6212multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006213multi_byte_ime Compiled with support for IME input method.
6214multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00006215mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02006216netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006217netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006218ole Compiled with OLE automation support for Win32.
6219os2 OS/2 version of Vim.
6220osfiletype Compiled with support for osfiletypes |+osfiletype|
6221path_extra Compiled with up/downwards search in 'path' and 'tags'
6222perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02006223persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006224postscript Compiled with PostScript file printing.
6225printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006226profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02006227python Compiled with Python 2.x interface. |has-python|
6228python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006229qnx QNX version of Vim.
6230quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00006231reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006232rightleft Compiled with 'rightleft' support.
6233ruby Compiled with Ruby interface |ruby|.
6234scrollbind Compiled with 'scrollbind' support.
6235showcmd Compiled with 'showcmd' support.
6236signs Compiled with |:sign| support.
6237smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006238sniff Compiled with SNiFF interface support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006239spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00006240startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006241statusline Compiled with support for 'statusline', 'rulerformat'
6242 and special formats of 'titlestring' and 'iconstring'.
6243sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006244syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006245syntax_items There are active syntax highlighting items for the
6246 current buffer.
6247system Compiled to use system() instead of fork()/exec().
6248tag_binary Compiled with binary searching in tags files
6249 |tag-binary-search|.
6250tag_old_static Compiled with support for old static tags
6251 |tag-old-static|.
6252tag_any_white Compiled with support for any white characters in tags
6253 files |tag-any-white|.
6254tcl Compiled with Tcl interface.
6255terminfo Compiled with terminfo instead of termcap.
6256termresponse Compiled with support for |t_RV| and |v:termresponse|.
6257textobjects Compiled with support for |text-objects|.
6258tgetent Compiled with tgetent support, able to use a termcap
6259 or terminfo file.
6260title Compiled with window title support |'title'|.
6261toolbar Compiled with support for |gui-toolbar|.
6262unix Unix version of Vim.
6263user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006264vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006265vim_starting True while initial source'ing takes place. |startup|
6266viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006267virtualedit Compiled with 'virtualedit' option.
6268visual Compiled with Visual mode.
6269visualextra Compiled with extra Visual mode commands.
6270 |blockwise-operators|.
6271vms VMS version of Vim.
6272vreplace Compiled with |gR| and |gr| commands.
6273wildignore Compiled with 'wildignore' option.
6274wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006275win16 Win16 version of Vim (MS-Windows 3.1).
Bram Moolenaard58e9292011-02-09 17:07:58 +01006276win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
6277 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006278win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006279win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006280win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01006281winaltkeys Compiled with 'winaltkeys' option.
6282windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006283writebackup Compiled with 'writebackup' default on.
6284xfontset Compiled with X fontset support |xfontset|.
6285xim Compiled with X input method support |xim|.
6286xsmp Compiled with X session management support.
6287xsmp_interact Compiled with interactive X session management support.
6288xterm_clipboard Compiled with support for xterm clipboard.
6289xterm_save Compiled with support for saving and restoring the
6290 xterm screen.
6291x11 Compiled with X11 support.
6292
6293 *string-match*
6294Matching a pattern in a String
6295
6296A regexp pattern as explained at |pattern| is normally used to find a match in
6297the buffer lines. When a pattern is used to find a match in a String, almost
6298everything works in the same way. The difference is that a String is handled
6299like it is one line. When it contains a "\n" character, this is not seen as a
6300line break for the pattern. It can be matched with a "\n" in the pattern, or
6301with ".". Example: >
6302 :let a = "aaaa\nxxxx"
6303 :echo matchstr(a, "..\n..")
6304 aa
6305 xx
6306 :echo matchstr(a, "a.x")
6307 a
6308 x
6309
6310Don't forget that "^" will only match at the first character of the String and
6311"$" at the last character of the string. They don't match after or before a
6312"\n".
6313
6314==============================================================================
63155. Defining functions *user-functions*
6316
6317New functions can be defined. These can be called just like builtin
6318functions. The function executes a sequence of Ex commands. Normal mode
6319commands can be executed with the |:normal| command.
6320
6321The function name must start with an uppercase letter, to avoid confusion with
6322builtin functions. To prevent from using the same name in different scripts
6323avoid obvious, short names. A good habit is to start the function name with
6324the name of the script, e.g., "HTMLcolor()".
6325
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006326It's also possible to use curly braces, see |curly-braces-names|. And the
6327|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006328
6329 *local-function*
6330A function local to a script must start with "s:". A local script function
6331can only be called from within the script and from functions, user commands
6332and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006333function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00006334instead of "s:" when the mapping is expanded outside of the script.
6335
6336 *:fu* *:function* *E128* *E129* *E123*
6337:fu[nction] List all functions and their arguments.
6338
6339:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006340 {name} can also be a |Dictionary| entry that is a
6341 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006342 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006343
6344:fu[nction] /{pattern} List functions with a name matching {pattern}.
6345 Example that lists all functions ending with "File": >
6346 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00006347<
6348 *:function-verbose*
6349When 'verbose' is non-zero, listing a function will also display where it was
6350last defined. Example: >
6351
6352 :verbose function SetFileTypeSH
6353 function SetFileTypeSH(name)
6354 Last set from /usr/share/vim/vim-7.0/filetype.vim
6355<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00006356See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00006357
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006358 *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006359:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00006360 Define a new function by the name {name}. The name
6361 must be made of alphanumeric characters and '_', and
6362 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006363
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006364 {name} can also be a |Dictionary| entry that is a
6365 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006366 :function dict.init(arg)
Bram Moolenaar446cb832008-06-24 21:56:24 +00006367< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006368 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar446cb832008-06-24 21:56:24 +00006369 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006370 result is a |Funcref| to a numbered function. The
6371 function can only be used with a |Funcref| and will be
6372 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006373 *E127* *E122*
6374 When a function by this name already exists and [!] is
6375 not used an error message is given. When [!] is used,
6376 an existing function is silently replaced. Unless it
6377 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006378
6379 For the {arguments} see |function-argument|.
6380
Bram Moolenaar071d4272004-06-13 20:20:40 +00006381 *a:firstline* *a:lastline*
6382 When the [range] argument is added, the function is
6383 expected to take care of a range itself. The range is
6384 passed as "a:firstline" and "a:lastline". If [range]
6385 is excluded, ":{range}call" will call the function for
6386 each line in the range, with the cursor on the start
6387 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006388
Bram Moolenaar071d4272004-06-13 20:20:40 +00006389 When the [abort] argument is added, the function will
6390 abort as soon as an error is detected.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006391
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006392 When the [dict] argument is added, the function must
Bram Moolenaar446cb832008-06-24 21:56:24 +00006393 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006394 local variable "self" will then be set to the
6395 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006396
Bram Moolenaar446cb832008-06-24 21:56:24 +00006397 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00006398 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00006399 will not be changed by the function. This also
6400 implies that the effect of |:nohlsearch| is undone
6401 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00006402
Bram Moolenaar071d4272004-06-13 20:20:40 +00006403 *:endf* *:endfunction* *E126* *E193*
6404:endf[unction] The end of a function definition. Must be on a line
6405 by its own, without other commands.
6406
6407 *:delf* *:delfunction* *E130* *E131*
6408:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006409 {name} can also be a |Dictionary| entry that is a
6410 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006411 :delfunc dict.init
Bram Moolenaar446cb832008-06-24 21:56:24 +00006412< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006413 function is deleted if there are no more references to
6414 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006415 *:retu* *:return* *E133*
6416:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
6417 evaluated and returned as the result of the function.
6418 If "[expr]" is not given, the number 0 is returned.
6419 When a function ends without an explicit ":return",
6420 the number 0 is returned.
6421 Note that there is no check for unreachable lines,
6422 thus there is no warning if commands follow ":return".
6423
6424 If the ":return" is used after a |:try| but before the
6425 matching |:finally| (if present), the commands
6426 following the ":finally" up to the matching |:endtry|
6427 are executed first. This process applies to all
6428 nested ":try"s inside the function. The function
6429 returns at the outermost ":endtry".
6430
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006431 *function-argument* *a:var*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006432An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006433be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006434 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006435Up to 20 arguments can be given, separated by commas. After the named
6436arguments an argument "..." can be specified, which means that more arguments
6437may optionally be following. In the function the extra arguments can be used
6438as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006439can be 0). "a:000" is set to a |List| that contains these arguments. Note
6440that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006441 *E742*
6442The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006443However, if a |List| or |Dictionary| is used, you can change their contents.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006444Thus you can pass a |List| to a function and have the function add an item to
6445it. If you want to make sure the function cannot change a |List| or
6446|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006447
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006448When not using "...", the number of arguments in a function call must be equal
6449to the number of named arguments. When using "...", the number of arguments
6450may be larger.
6451
6452It is also possible to define a function without any arguments. You must
6453still supply the () then. The body of the function follows in the next lines,
6454until the matching |:endfunction|. It is allowed to define another function
6455inside a function body.
6456
6457 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006458Inside a function variables can be used. These are local variables, which
6459will disappear when the function returns. Global variables need to be
6460accessed with "g:".
6461
6462Example: >
6463 :function Table(title, ...)
6464 : echohl Title
6465 : echo a:title
6466 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00006467 : echo a:0 . " items:"
6468 : for s in a:000
6469 : echon ' ' . s
6470 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00006471 :endfunction
6472
6473This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00006474 call Table("Table", "line1", "line2")
6475 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006476
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006477To return more than one value, return a |List|: >
6478 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006479 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006480 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00006481 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006482 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00006483 :endfunction
6484
6485This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006486 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006487 :if success == "ok"
6488 : echo div
6489 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006490<
Bram Moolenaar39f05632006-03-19 22:15:26 +00006491 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006492:[range]cal[l] {name}([arguments])
6493 Call a function. The name of the function and its arguments
6494 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006495 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006496 Without a range and for functions that accept a range, the
6497 function is called once. When a range is given the cursor is
6498 positioned at the start of the first line before executing the
6499 function.
6500 When a range is given and the function doesn't handle it
6501 itself, the function is executed for each line in the range,
6502 with the cursor in the first column of that line. The cursor
6503 is left at the last line (possibly moved by the last function
Bram Moolenaar446cb832008-06-24 21:56:24 +00006504 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00006505 this works:
6506 *function-range-example* >
6507 :function Mynumber(arg)
6508 : echo line(".") . " " . a:arg
6509 :endfunction
6510 :1,5call Mynumber(getline("."))
6511<
6512 The "a:firstline" and "a:lastline" are defined anyway, they
6513 can be used to do something different at the start or end of
6514 the range.
6515
6516 Example of a function that handles the range itself: >
6517
6518 :function Cont() range
6519 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
6520 :endfunction
6521 :4,8call Cont()
6522<
6523 This function inserts the continuation character "\" in front
6524 of all the lines in the range, except the first one.
6525
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006526 When the function returns a composite value it can be further
6527 dereferenced, but the range will not be used then. Example: >
6528 :4,8call GetDict().method()
6529< Here GetDict() gets the range but method() does not.
6530
Bram Moolenaar071d4272004-06-13 20:20:40 +00006531 *E132*
6532The recursiveness of user functions is restricted with the |'maxfuncdepth'|
6533option.
6534
Bram Moolenaar7c626922005-02-07 22:01:03 +00006535
6536AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00006537 *autoload-functions*
6538When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00006539only when they are used. There are two methods: with an autocommand and with
6540the "autoload" directory in 'runtimepath'.
6541
6542
6543Using an autocommand ~
6544
Bram Moolenaar05159a02005-02-26 23:04:13 +00006545This is introduced in the user manual, section |41.14|.
6546
Bram Moolenaar7c626922005-02-07 22:01:03 +00006547The autocommand is useful if you have a plugin that is a long Vim script file.
6548You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006549That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00006550again, setting a variable to skip the |:finish| command.
6551
6552Use the FuncUndefined autocommand event with a pattern that matches the
6553function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006554
6555 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
6556
6557The file "~/vim/bufnetfuncs.vim" should then define functions that start with
6558"BufNet". Also see |FuncUndefined|.
6559
Bram Moolenaar7c626922005-02-07 22:01:03 +00006560
6561Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006562 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006563This is introduced in the user manual, section |41.15|.
6564
Bram Moolenaar7c626922005-02-07 22:01:03 +00006565Using a script in the "autoload" directory is simpler, but requires using
6566exactly the right file name. A function that can be autoloaded has a name
6567like this: >
6568
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006569 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00006570
6571When such a function is called, and it is not defined yet, Vim will search the
6572"autoload" directories in 'runtimepath' for a script file called
6573"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
6574then define the function like this: >
6575
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006576 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00006577 echo "Done!"
6578 endfunction
6579
Bram Moolenaar60a795a2005-09-16 21:55:43 +00006580The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00006581exactly, and the defined function must have the name exactly as it will be
6582called.
6583
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006584It is possible to use subdirectories. Every # in the function name works like
6585a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00006586
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006587 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00006588
6589Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
6590
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006591This also works when reading a variable that has not been set yet: >
6592
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006593 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006594
Bram Moolenaara5792f52005-11-23 21:25:05 +00006595However, when the autoload script was already loaded it won't be loaded again
6596for an unknown variable.
6597
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006598When assigning a value to such a variable nothing special happens. This can
6599be used to pass settings to the autoload script before it's loaded: >
6600
Bram Moolenaara7fc0102005-05-18 22:17:12 +00006601 :let foo#bar#toggle = 1
6602 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006603
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006604Note that when you make a mistake and call a function that is supposed to be
6605defined in an autoload script, but the script doesn't actually define the
6606function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006607And you will get an error message every time.
6608
6609Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006610other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006611Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00006612
Bram Moolenaar433f7c82006-03-21 21:29:36 +00006613Hint: If you distribute a bunch of scripts you can pack them together with the
6614|vimball| utility. Also read the user manual |distribute-script|.
6615
Bram Moolenaar071d4272004-06-13 20:20:40 +00006616==============================================================================
66176. Curly braces names *curly-braces-names*
6618
6619Wherever you can use a variable, you can use a "curly braces name" variable.
6620This is a regular variable name with one or more expressions wrapped in braces
6621{} like this: >
6622 my_{adjective}_variable
6623
6624When Vim encounters this, it evaluates the expression inside the braces, puts
6625that in place of the expression, and re-interprets the whole as a variable
6626name. So in the above example, if the variable "adjective" was set to
6627"noisy", then the reference would be to "my_noisy_variable", whereas if
6628"adjective" was set to "quiet", then it would be to "my_quiet_variable".
6629
6630One application for this is to create a set of variables governed by an option
Bram Moolenaar446cb832008-06-24 21:56:24 +00006631value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006632 echo my_{&background}_message
6633
6634would output the contents of "my_dark_message" or "my_light_message" depending
6635on the current value of 'background'.
6636
6637You can use multiple brace pairs: >
6638 echo my_{adverb}_{adjective}_message
6639..or even nest them: >
6640 echo my_{ad{end_of_word}}_message
6641where "end_of_word" is either "verb" or "jective".
6642
6643However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006644variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006645 :let foo='a + b'
6646 :echo c{foo}d
6647.. since the result of expansion is "ca + bd", which is not a variable name.
6648
6649 *curly-braces-function-names*
6650You can call and define functions by an evaluated name in a similar way.
6651Example: >
6652 :let func_end='whizz'
6653 :call my_func_{func_end}(parameter)
6654
6655This would call the function "my_func_whizz(parameter)".
6656
6657==============================================================================
66587. Commands *expression-commands*
6659
6660:let {var-name} = {expr1} *:let* *E18*
6661 Set internal variable {var-name} to the result of the
6662 expression {expr1}. The variable will get the type
6663 from the {expr}. If {var-name} didn't exist yet, it
6664 is created.
6665
Bram Moolenaar13065c42005-01-08 16:08:21 +00006666:let {var-name}[{idx}] = {expr1} *E689*
6667 Set a list item to the result of the expression
6668 {expr1}. {var-name} must refer to a list and {idx}
6669 must be a valid index in that list. For nested list
6670 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006671 This cannot be used to add an item to a |List|.
6672 This cannot be used to set a byte in a String. You
6673 can do that like this: >
6674 :let var = var[0:2] . 'X' . var[4:]
6675<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006676 *E711* *E719*
6677:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006678 Set a sequence of items in a |List| to the result of
6679 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006680 correct number of items.
6681 {idx1} can be omitted, zero is used instead.
6682 {idx2} can be omitted, meaning the end of the list.
6683 When the selected range of items is partly past the
6684 end of the list, items will be added.
6685
Bram Moolenaar748bf032005-02-02 23:04:36 +00006686 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006687:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
6688:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
6689:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
6690 These fail if {var} was not set yet and when the type
6691 of {var} and {expr1} don't fit the operator.
6692
6693
Bram Moolenaar071d4272004-06-13 20:20:40 +00006694:let ${env-name} = {expr1} *:let-environment* *:let-$*
6695 Set environment variable {env-name} to the result of
6696 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006697:let ${env-name} .= {expr1}
6698 Append {expr1} to the environment variable {env-name}.
6699 If the environment variable didn't exist yet this
6700 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006701
6702:let @{reg-name} = {expr1} *:let-register* *:let-@*
6703 Write the result of the expression {expr1} in register
6704 {reg-name}. {reg-name} must be a single letter, and
6705 must be the name of a writable register (see
6706 |registers|). "@@" can be used for the unnamed
6707 register, "@/" for the search pattern.
6708 If the result of {expr1} ends in a <CR> or <NL>, the
6709 register will be linewise, otherwise it will be set to
6710 characterwise.
6711 This can be used to clear the last search pattern: >
6712 :let @/ = ""
6713< This is different from searching for an empty string,
6714 that would match everywhere.
6715
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006716:let @{reg-name} .= {expr1}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006717 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006718 register was empty it's like setting it to {expr1}.
6719
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006720:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006721 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006722 expression {expr1}. A String or Number value is
6723 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006724 For an option local to a window or buffer the effect
6725 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00006726 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006727 Example: >
6728 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00006729
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006730:let &{option-name} .= {expr1}
6731 For a string option: Append {expr1} to the value.
6732 Does not insert a comma like |:set+=|.
6733
6734:let &{option-name} += {expr1}
6735:let &{option-name} -= {expr1}
6736 For a number or boolean option: Add or subtract
6737 {expr1}.
6738
Bram Moolenaar071d4272004-06-13 20:20:40 +00006739:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006740:let &l:{option-name} .= {expr1}
6741:let &l:{option-name} += {expr1}
6742:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006743 Like above, but only set the local value of an option
6744 (if there is one). Works like |:setlocal|.
6745
6746:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006747:let &g:{option-name} .= {expr1}
6748:let &g:{option-name} += {expr1}
6749:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006750 Like above, but only set the global value of an option
6751 (if there is one). Works like |:setglobal|.
6752
Bram Moolenaar13065c42005-01-08 16:08:21 +00006753:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006754 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006755 the list is assigned to {name1}, the second item to
6756 {name2}, etc.
6757 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006758 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006759 Each name can be one of the items of the ":let"
6760 command as mentioned above.
6761 Example: >
6762 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006763< Detail: {expr1} is evaluated first, then the
6764 assignments are done in sequence. This matters if
6765 {name2} depends on {name1}. Example: >
6766 :let x = [0, 1]
6767 :let i = 0
6768 :let [i, x[i]] = [1, 2]
6769 :echo x
6770< The result is [0, 2].
6771
6772:let [{name1}, {name2}, ...] .= {expr1}
6773:let [{name1}, {name2}, ...] += {expr1}
6774:let [{name1}, {name2}, ...] -= {expr1}
6775 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006776 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006777
6778:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006779 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006780 items than there are names. A list of the remaining
6781 items is assigned to {lastname}. If there are no
6782 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00006783 Example: >
6784 :let [a, b; rest] = ["aval", "bval", 3, 4]
6785<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006786:let [{name}, ..., ; {lastname}] .= {expr1}
6787:let [{name}, ..., ; {lastname}] += {expr1}
6788:let [{name}, ..., ; {lastname}] -= {expr1}
6789 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006790 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02006791
6792 *E121*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006793:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00006794 variable names may be given. Special names recognized
6795 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00006796 g: global variables
6797 b: local buffer variables
6798 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006799 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00006800 s: script-local variables
6801 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00006802 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006803
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006804:let List the values of all variables. The type of the
6805 variable is indicated before the value:
6806 <nothing> String
6807 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006808 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00006809
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006810
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006811:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006812 Remove the internal variable {name}. Several variable
6813 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006814 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006815 With [!] no error message is given for non-existing
6816 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006817 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00006818 :unlet list[3] " remove fourth item
6819 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006820< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00006821 :unlet dict['two']
6822 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00006823< This is especially useful to clean up used global
6824 variables and script-local variables (these are not
6825 deleted when the script ends). Function-local
6826 variables are automatically deleted when the function
6827 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006828
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006829:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
6830 Lock the internal variable {name}. Locking means that
6831 it can no longer be changed (until it is unlocked).
6832 A locked variable can be deleted: >
6833 :lockvar v
6834 :let v = 'asdf' " fails!
6835 :unlet v
6836< *E741*
6837 If you try to change a locked variable you get an
6838 error message: "E741: Value of {name} is locked"
6839
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006840 [depth] is relevant when locking a |List| or
6841 |Dictionary|. It specifies how deep the locking goes:
6842 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006843 cannot add or remove items, but can
6844 still change their values.
6845 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006846 the items. If an item is a |List| or
6847 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006848 items, but can still change the
6849 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006850 3 Like 2 but for the |List| /
6851 |Dictionary| in the |List| /
6852 |Dictionary|, one level deeper.
6853 The default [depth] is 2, thus when {name} is a |List|
6854 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006855 *E743*
6856 For unlimited depth use [!] and omit [depth].
6857 However, there is a maximum depth of 100 to catch
6858 loops.
6859
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006860 Note that when two variables refer to the same |List|
6861 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006862 locked when used through the other variable.
6863 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006864 :let l = [0, 1, 2, 3]
6865 :let cl = l
6866 :lockvar l
6867 :let cl[1] = 99 " won't work!
6868< You may want to make a copy of a list to avoid this.
6869 See |deepcopy()|.
6870
6871
6872:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
6873 Unlock the internal variable {name}. Does the
6874 opposite of |:lockvar|.
6875
6876
Bram Moolenaar071d4272004-06-13 20:20:40 +00006877:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
6878:en[dif] Execute the commands until the next matching ":else"
6879 or ":endif" if {expr1} evaluates to non-zero.
6880
6881 From Vim version 4.5 until 5.0, every Ex command in
6882 between the ":if" and ":endif" is ignored. These two
6883 commands were just to allow for future expansions in a
6884 backwards compatible way. Nesting was allowed. Note
6885 that any ":else" or ":elseif" was ignored, the "else"
6886 part was not executed either.
6887
6888 You can use this to remain compatible with older
6889 versions: >
6890 :if version >= 500
6891 : version-5-specific-commands
6892 :endif
6893< The commands still need to be parsed to find the
6894 "endif". Sometimes an older Vim has a problem with a
6895 new command. For example, ":silent" is recognized as
6896 a ":substitute" command. In that case ":execute" can
6897 avoid problems: >
6898 :if version >= 600
6899 : execute "silent 1,$delete"
6900 :endif
6901<
6902 NOTE: The ":append" and ":insert" commands don't work
6903 properly in between ":if" and ":endif".
6904
6905 *:else* *:el* *E581* *E583*
6906:el[se] Execute the commands until the next matching ":else"
6907 or ":endif" if they previously were not being
6908 executed.
6909
6910 *:elseif* *:elsei* *E582* *E584*
6911:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
6912 is no extra ":endif".
6913
6914:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006915 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006916:endw[hile] Repeat the commands between ":while" and ":endwhile",
6917 as long as {expr1} evaluates to non-zero.
6918 When an error is detected from a command inside the
6919 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00006920 Example: >
6921 :let lnum = 1
6922 :while lnum <= line("$")
6923 :call FixLine(lnum)
6924 :let lnum = lnum + 1
6925 :endwhile
6926<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006927 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00006928 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006929
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00006930:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00006931:endfo[r] *:endfo* *:endfor*
6932 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006933 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006934 value of each item.
6935 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00006936 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00006937 Changing {list} inside the loop affects what items are
6938 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006939 :for item in copy(mylist)
6940< When not making a copy, Vim stores a reference to the
6941 next item in the list, before executing the commands
Bram Moolenaar446cb832008-06-24 21:56:24 +00006942 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006943 removed without effect. Removing any later item means
6944 it will not be found. Thus the following example
6945 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006946 for item in mylist
6947 call remove(mylist, 0)
6948 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006949< Note that reordering the list (e.g., with sort() or
6950 reverse()) may have unexpected effects.
6951 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00006952 identical to avoid errors for the type of {var}
6953 changing. Unlet the variable at the end of the loop
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006954 to allow multiple item types: >
6955 for item in ["foo", ["bar"]]
6956 echo item
6957 unlet item " E706 without this
6958 endfor
Bram Moolenaar12805862005-01-05 22:16:17 +00006959
Bram Moolenaar12805862005-01-05 22:16:17 +00006960:for [{var1}, {var2}, ...] in {listlist}
6961:endfo[r]
6962 Like ":for" above, but each item in {listlist} must be
6963 a list, of which each item is assigned to {var1},
6964 {var2}, etc. Example: >
6965 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
6966 :echo getline(lnum)[col]
6967 :endfor
6968<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006969 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00006970:con[tinue] When used inside a ":while" or ":for" loop, jumps back
6971 to the start of the loop.
6972 If it is used after a |:try| inside the loop but
6973 before the matching |:finally| (if present), the
6974 commands following the ":finally" up to the matching
6975 |:endtry| are executed first. This process applies to
6976 all nested ":try"s inside the loop. The outermost
6977 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006978
6979 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00006980:brea[k] When used inside a ":while" or ":for" loop, skips to
6981 the command after the matching ":endwhile" or
6982 ":endfor".
6983 If it is used after a |:try| inside the loop but
6984 before the matching |:finally| (if present), the
6985 commands following the ":finally" up to the matching
6986 |:endtry| are executed first. This process applies to
6987 all nested ":try"s inside the loop. The outermost
6988 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006989
6990:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
6991:endt[ry] Change the error handling for the commands between
6992 ":try" and ":endtry" including everything being
6993 executed across ":source" commands, function calls,
6994 or autocommand invocations.
6995
6996 When an error or interrupt is detected and there is
6997 a |:finally| command following, execution continues
6998 after the ":finally". Otherwise, or when the
6999 ":endtry" is reached thereafter, the next
7000 (dynamically) surrounding ":try" is checked for
7001 a corresponding ":finally" etc. Then the script
7002 processing is terminated. (Whether a function
7003 definition has an "abort" argument does not matter.)
7004 Example: >
7005 :try | edit too much | finally | echo "cleanup" | endtry
7006 :echo "impossible" " not reached, script terminated above
7007<
7008 Moreover, an error or interrupt (dynamically) inside
7009 ":try" and ":endtry" is converted to an exception. It
7010 can be caught as if it were thrown by a |:throw|
7011 command (see |:catch|). In this case, the script
7012 processing is not terminated.
7013
7014 The value "Vim:Interrupt" is used for an interrupt
7015 exception. An error in a Vim command is converted
7016 to a value of the form "Vim({command}):{errmsg}",
7017 other errors are converted to a value of the form
7018 "Vim:{errmsg}". {command} is the full command name,
7019 and {errmsg} is the message that is displayed if the
7020 error exception is not caught, always beginning with
7021 the error number.
7022 Examples: >
7023 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
7024 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
7025<
7026 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007027:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007028 |:finally|, or |:endtry| that belongs to the same
7029 |:try| as the ":catch" are executed when an exception
7030 matching {pattern} is being thrown and has not yet
7031 been caught by a previous ":catch". Otherwise, these
7032 commands are skipped.
7033 When {pattern} is omitted all errors are caught.
7034 Examples: >
7035 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
7036 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
7037 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
7038 :catch /^Vim(write):/ " catch all errors in :write
7039 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
7040 :catch /my-exception/ " catch user exception
7041 :catch /.*/ " catch everything
7042 :catch " same as /.*/
7043<
7044 Another character can be used instead of / around the
7045 {pattern}, so long as it does not have a special
7046 meaning (e.g., '|' or '"') and doesn't occur inside
7047 {pattern}.
7048 NOTE: It is not reliable to ":catch" the TEXT of
7049 an error message because it may vary in different
7050 locales.
7051
7052 *:fina* *:finally* *E606* *E607*
7053:fina[lly] The following commands until the matching |:endtry|
7054 are executed whenever the part between the matching
7055 |:try| and the ":finally" is left: either by falling
7056 through to the ":finally" or by a |:continue|,
7057 |:break|, |:finish|, or |:return|, or by an error or
7058 interrupt or exception (see |:throw|).
7059
7060 *:th* *:throw* *E608*
7061:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
7062 If the ":throw" is used after a |:try| but before the
7063 first corresponding |:catch|, commands are skipped
7064 until the first ":catch" matching {expr1} is reached.
7065 If there is no such ":catch" or if the ":throw" is
7066 used after a ":catch" but before the |:finally|, the
7067 commands following the ":finally" (if present) up to
7068 the matching |:endtry| are executed. If the ":throw"
7069 is after the ":finally", commands up to the ":endtry"
7070 are skipped. At the ":endtry", this process applies
7071 again for the next dynamically surrounding ":try"
7072 (which may be found in a calling function or sourcing
7073 script), until a matching ":catch" has been found.
7074 If the exception is not caught, the command processing
7075 is terminated.
7076 Example: >
7077 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01007078< Note that "catch" may need to be on a separate line
7079 for when an error causes the parsing to skip the whole
7080 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007081
7082 *:ec* *:echo*
7083:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
7084 first {expr1} starts on a new line.
7085 Also see |:comment|.
7086 Use "\n" to start a new line. Use "\r" to move the
7087 cursor to the first column.
7088 Uses the highlighting set by the |:echohl| command.
7089 Cannot be followed by a comment.
7090 Example: >
7091 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007092< *:echo-redraw*
7093 A later redraw may make the message disappear again.
7094 And since Vim mostly postpones redrawing until it's
7095 finished with a sequence of commands this happens
7096 quite often. To avoid that a command from before the
7097 ":echo" causes a redraw afterwards (redraws are often
7098 postponed until you type something), force a redraw
7099 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007100 :new | redraw | echo "there is a new window"
7101<
7102 *:echon*
7103:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
7104 |:comment|.
7105 Uses the highlighting set by the |:echohl| command.
7106 Cannot be followed by a comment.
7107 Example: >
7108 :echon "the value of 'shell' is " &shell
7109<
7110 Note the difference between using ":echo", which is a
7111 Vim command, and ":!echo", which is an external shell
7112 command: >
7113 :!echo % --> filename
7114< The arguments of ":!" are expanded, see |:_%|. >
7115 :!echo "%" --> filename or "filename"
7116< Like the previous example. Whether you see the double
7117 quotes or not depends on your 'shell'. >
7118 :echo % --> nothing
7119< The '%' is an illegal character in an expression. >
7120 :echo "%" --> %
7121< This just echoes the '%' character. >
7122 :echo expand("%") --> filename
7123< This calls the expand() function to expand the '%'.
7124
7125 *:echoh* *:echohl*
7126:echoh[l] {name} Use the highlight group {name} for the following
7127 |:echo|, |:echon| and |:echomsg| commands. Also used
7128 for the |input()| prompt. Example: >
7129 :echohl WarningMsg | echo "Don't panic!" | echohl None
7130< Don't forget to set the group back to "None",
7131 otherwise all following echo's will be highlighted.
7132
7133 *:echom* *:echomsg*
7134:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
7135 message in the |message-history|.
7136 Spaces are placed between the arguments as with the
7137 |:echo| command. But unprintable characters are
7138 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007139 The parsing works slightly different from |:echo|,
7140 more like |:execute|. All the expressions are first
7141 evaluated and concatenated before echoing anything.
7142 The expressions must evaluate to a Number or String, a
7143 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007144 Uses the highlighting set by the |:echohl| command.
7145 Example: >
7146 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007147< See |:echo-redraw| to avoid the message disappearing
7148 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007149 *:echoe* *:echoerr*
7150:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
7151 message in the |message-history|. When used in a
7152 script or function the line number will be added.
7153 Spaces are placed between the arguments as with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007154 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007155 the message is raised as an error exception instead
7156 (see |try-echoerr|).
7157 Example: >
7158 :echoerr "This script just failed!"
7159< If you just want a highlighted message use |:echohl|.
7160 And to get a beep: >
7161 :exe "normal \<Esc>"
7162<
7163 *:exe* *:execute*
7164:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007165 of {expr1} as an Ex command.
7166 Multiple arguments are concatenated, with a space in
7167 between. To avoid the extra space use the "."
7168 operator to concatenate strings into one argument.
7169 {expr1} is used as the processed command, command line
7170 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007171 Cannot be followed by a comment.
7172 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007173 :execute "buffer" nextbuf
7174 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007175<
7176 ":execute" can be used to append a command to commands
7177 that don't accept a '|'. Example: >
7178 :execute '!ls' | echo "theend"
7179
7180< ":execute" is also a nice way to avoid having to type
7181 control characters in a Vim script for a ":normal"
7182 command: >
7183 :execute "normal ixxx\<Esc>"
7184< This has an <Esc> character, see |expr-string|.
7185
Bram Moolenaar446cb832008-06-24 21:56:24 +00007186 Be careful to correctly escape special characters in
7187 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007188 for Vim commands, |shellescape()| for |:!| commands.
7189 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00007190 :execute "e " . fnameescape(filename)
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007191 :execute "!ls " . shellescape(expand('%:h'), 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00007192<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007193 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00007194 you cannot start or end a "while", "for" or "if"
7195 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007196 :execute 'while i > 5'
7197 :execute 'echo "test" | break'
7198<
7199 It is allowed to have a "while" or "if" command
7200 completely in the executed string: >
7201 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
7202<
7203
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007204 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007205 ":execute", ":echo" and ":echon" cannot be followed by
7206 a comment directly, because they see the '"' as the
7207 start of a string. But, you can use '|' followed by a
7208 comment. Example: >
7209 :echo "foo" | "this is a comment
7210
7211==============================================================================
72128. Exception handling *exception-handling*
7213
7214The Vim script language comprises an exception handling feature. This section
7215explains how it can be used in a Vim script.
7216
7217Exceptions may be raised by Vim on an error or on interrupt, see
7218|catch-errors| and |catch-interrupt|. You can also explicitly throw an
7219exception by using the ":throw" command, see |throw-catch|.
7220
7221
7222TRY CONDITIONALS *try-conditionals*
7223
7224Exceptions can be caught or can cause cleanup code to be executed. You can
7225use a try conditional to specify catch clauses (that catch exceptions) and/or
7226a finally clause (to be executed for cleanup).
7227 A try conditional begins with a |:try| command and ends at the matching
7228|:endtry| command. In between, you can use a |:catch| command to start
7229a catch clause, or a |:finally| command to start a finally clause. There may
7230be none or multiple catch clauses, but there is at most one finally clause,
7231which must not be followed by any catch clauses. The lines before the catch
7232clauses and the finally clause is called a try block. >
7233
7234 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00007235 : ...
7236 : ... TRY BLOCK
7237 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007238 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00007239 : ...
7240 : ... CATCH CLAUSE
7241 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007242 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00007243 : ...
7244 : ... CATCH CLAUSE
7245 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007246 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00007247 : ...
7248 : ... FINALLY CLAUSE
7249 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00007250 :endtry
7251
7252The try conditional allows to watch code for exceptions and to take the
7253appropriate actions. Exceptions from the try block may be caught. Exceptions
7254from the try block and also the catch clauses may cause cleanup actions.
7255 When no exception is thrown during execution of the try block, the control
7256is transferred to the finally clause, if present. After its execution, the
7257script continues with the line following the ":endtry".
7258 When an exception occurs during execution of the try block, the remaining
7259lines in the try block are skipped. The exception is matched against the
7260patterns specified as arguments to the ":catch" commands. The catch clause
7261after the first matching ":catch" is taken, other catch clauses are not
7262executed. The catch clause ends when the next ":catch", ":finally", or
7263":endtry" command is reached - whatever is first. Then, the finally clause
7264(if present) is executed. When the ":endtry" is reached, the script execution
7265continues in the following line as usual.
7266 When an exception that does not match any of the patterns specified by the
7267":catch" commands is thrown in the try block, the exception is not caught by
7268that try conditional and none of the catch clauses is executed. Only the
7269finally clause, if present, is taken. The exception pends during execution of
7270the finally clause. It is resumed at the ":endtry", so that commands after
7271the ":endtry" are not executed and the exception might be caught elsewhere,
7272see |try-nesting|.
7273 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007274remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00007275not matched against the patterns in any of the ":catch" commands of the same
7276try conditional and none of its catch clauses is taken. If there is, however,
7277a finally clause, it is executed, and the exception pends during its
7278execution. The commands following the ":endtry" are not executed. The new
7279exception might, however, be caught elsewhere, see |try-nesting|.
7280 When during execution of the finally clause (if present) an exception is
Bram Moolenaar446cb832008-06-24 21:56:24 +00007281thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00007282clause has been taken because of an exception from the try block or one of the
7283catch clauses, the original (pending) exception is discarded. The commands
7284following the ":endtry" are not executed, and the exception from the finally
7285clause is propagated and can be caught elsewhere, see |try-nesting|.
7286
7287The finally clause is also executed, when a ":break" or ":continue" for
7288a ":while" loop enclosing the complete try conditional is executed from the
7289try block or a catch clause. Or when a ":return" or ":finish" is executed
7290from the try block or a catch clause of a try conditional in a function or
7291sourced script, respectively. The ":break", ":continue", ":return", or
7292":finish" pends during execution of the finally clause and is resumed when the
7293":endtry" is reached. It is, however, discarded when an exception is thrown
7294from the finally clause.
7295 When a ":break" or ":continue" for a ":while" loop enclosing the complete
7296try conditional or when a ":return" or ":finish" is encountered in the finally
7297clause, the rest of the finally clause is skipped, and the ":break",
7298":continue", ":return" or ":finish" is executed as usual. If the finally
7299clause has been taken because of an exception or an earlier ":break",
7300":continue", ":return", or ":finish" from the try block or a catch clause,
7301this pending exception or command is discarded.
7302
7303For examples see |throw-catch| and |try-finally|.
7304
7305
7306NESTING OF TRY CONDITIONALS *try-nesting*
7307
7308Try conditionals can be nested arbitrarily. That is, a complete try
7309conditional can be put into the try block, a catch clause, or the finally
7310clause of another try conditional. If the inner try conditional does not
7311catch an exception thrown in its try block or throws a new exception from one
7312of its catch clauses or its finally clause, the outer try conditional is
7313checked according to the rules above. If the inner try conditional is in the
7314try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar446cb832008-06-24 21:56:24 +00007315otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00007316nesting, whether the inner try conditional is directly contained in the outer
7317one, or whether the outer one sources a script or calls a function containing
7318the inner try conditional.
7319
7320When none of the active try conditionals catches an exception, just their
7321finally clauses are executed. Thereafter, the script processing terminates.
7322An error message is displayed in case of an uncaught exception explicitly
7323thrown by a ":throw" command. For uncaught error and interrupt exceptions
7324implicitly raised by Vim, the error message(s) or interrupt message are shown
7325as usual.
7326
7327For examples see |throw-catch|.
7328
7329
7330EXAMINING EXCEPTION HANDLING CODE *except-examine*
7331
7332Exception handling code can get tricky. If you are in doubt what happens, set
7333'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
7334script file. Then you see when an exception is thrown, discarded, caught, or
7335finished. When using a verbosity level of at least 14, things pending in
7336a finally clause are also shown. This information is also given in debug mode
7337(see |debug-scripts|).
7338
7339
7340THROWING AND CATCHING EXCEPTIONS *throw-catch*
7341
7342You can throw any number or string as an exception. Use the |:throw| command
7343and pass the value to be thrown as argument: >
7344 :throw 4711
7345 :throw "string"
7346< *throw-expression*
7347You can also specify an expression argument. The expression is then evaluated
7348first, and the result is thrown: >
7349 :throw 4705 + strlen("string")
7350 :throw strpart("strings", 0, 6)
7351
7352An exception might be thrown during evaluation of the argument of the ":throw"
7353command. Unless it is caught there, the expression evaluation is abandoned.
7354The ":throw" command then does not throw a new exception.
7355 Example: >
7356
7357 :function! Foo(arg)
7358 : try
7359 : throw a:arg
7360 : catch /foo/
7361 : endtry
7362 : return 1
7363 :endfunction
7364 :
7365 :function! Bar()
7366 : echo "in Bar"
7367 : return 4710
7368 :endfunction
7369 :
7370 :throw Foo("arrgh") + Bar()
7371
7372This throws "arrgh", and "in Bar" is not displayed since Bar() is not
7373executed. >
7374 :throw Foo("foo") + Bar()
7375however displays "in Bar" and throws 4711.
7376
7377Any other command that takes an expression as argument might also be
Bram Moolenaar446cb832008-06-24 21:56:24 +00007378abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00007379exception is then propagated to the caller of the command.
7380 Example: >
7381
7382 :if Foo("arrgh")
7383 : echo "then"
7384 :else
7385 : echo "else"
7386 :endif
7387
7388Here neither of "then" or "else" is displayed.
7389
7390 *catch-order*
7391Exceptions can be caught by a try conditional with one or more |:catch|
7392commands, see |try-conditionals|. The values to be caught by each ":catch"
7393command can be specified as a pattern argument. The subsequent catch clause
7394gets executed when a matching exception is caught.
7395 Example: >
7396
7397 :function! Foo(value)
7398 : try
7399 : throw a:value
7400 : catch /^\d\+$/
7401 : echo "Number thrown"
7402 : catch /.*/
7403 : echo "String thrown"
7404 : endtry
7405 :endfunction
7406 :
7407 :call Foo(0x1267)
7408 :call Foo('string')
7409
7410The first call to Foo() displays "Number thrown", the second "String thrown".
7411An exception is matched against the ":catch" commands in the order they are
7412specified. Only the first match counts. So you should place the more
7413specific ":catch" first. The following order does not make sense: >
7414
7415 : catch /.*/
7416 : echo "String thrown"
7417 : catch /^\d\+$/
7418 : echo "Number thrown"
7419
7420The first ":catch" here matches always, so that the second catch clause is
7421never taken.
7422
7423 *throw-variables*
7424If you catch an exception by a general pattern, you may access the exact value
7425in the variable |v:exception|: >
7426
7427 : catch /^\d\+$/
7428 : echo "Number thrown. Value is" v:exception
7429
7430You may also be interested where an exception was thrown. This is stored in
7431|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
7432exception most recently caught as long it is not finished.
7433 Example: >
7434
7435 :function! Caught()
7436 : if v:exception != ""
7437 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
7438 : else
7439 : echo 'Nothing caught'
7440 : endif
7441 :endfunction
7442 :
7443 :function! Foo()
7444 : try
7445 : try
7446 : try
7447 : throw 4711
7448 : finally
7449 : call Caught()
7450 : endtry
7451 : catch /.*/
7452 : call Caught()
7453 : throw "oops"
7454 : endtry
7455 : catch /.*/
7456 : call Caught()
7457 : finally
7458 : call Caught()
7459 : endtry
7460 :endfunction
7461 :
7462 :call Foo()
7463
7464This displays >
7465
7466 Nothing caught
7467 Caught "4711" in function Foo, line 4
7468 Caught "oops" in function Foo, line 10
7469 Nothing caught
7470
7471A practical example: The following command ":LineNumber" displays the line
7472number in the script or function where it has been used: >
7473
7474 :function! LineNumber()
7475 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
7476 :endfunction
7477 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
7478<
7479 *try-nested*
7480An exception that is not caught by a try conditional can be caught by
7481a surrounding try conditional: >
7482
7483 :try
7484 : try
7485 : throw "foo"
7486 : catch /foobar/
7487 : echo "foobar"
7488 : finally
7489 : echo "inner finally"
7490 : endtry
7491 :catch /foo/
7492 : echo "foo"
7493 :endtry
7494
7495The inner try conditional does not catch the exception, just its finally
7496clause is executed. The exception is then caught by the outer try
7497conditional. The example displays "inner finally" and then "foo".
7498
7499 *throw-from-catch*
7500You can catch an exception and throw a new one to be caught elsewhere from the
7501catch clause: >
7502
7503 :function! Foo()
7504 : throw "foo"
7505 :endfunction
7506 :
7507 :function! Bar()
7508 : try
7509 : call Foo()
7510 : catch /foo/
7511 : echo "Caught foo, throw bar"
7512 : throw "bar"
7513 : endtry
7514 :endfunction
7515 :
7516 :try
7517 : call Bar()
7518 :catch /.*/
7519 : echo "Caught" v:exception
7520 :endtry
7521
7522This displays "Caught foo, throw bar" and then "Caught bar".
7523
7524 *rethrow*
7525There is no real rethrow in the Vim script language, but you may throw
7526"v:exception" instead: >
7527
7528 :function! Bar()
7529 : try
7530 : call Foo()
7531 : catch /.*/
7532 : echo "Rethrow" v:exception
7533 : throw v:exception
7534 : endtry
7535 :endfunction
7536< *try-echoerr*
7537Note that this method cannot be used to "rethrow" Vim error or interrupt
7538exceptions, because it is not possible to fake Vim internal exceptions.
7539Trying so causes an error exception. You should throw your own exception
7540denoting the situation. If you want to cause a Vim error exception containing
7541the original error exception value, you can use the |:echoerr| command: >
7542
7543 :try
7544 : try
7545 : asdf
7546 : catch /.*/
7547 : echoerr v:exception
7548 : endtry
7549 :catch /.*/
7550 : echo v:exception
7551 :endtry
7552
7553This code displays
7554
Bram Moolenaar446cb832008-06-24 21:56:24 +00007555 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00007556
7557
7558CLEANUP CODE *try-finally*
7559
7560Scripts often change global settings and restore them at their end. If the
7561user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar446cb832008-06-24 21:56:24 +00007562an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007563a script when an error occurs or you explicitly throw an exception without
7564catching it. You can solve these problems by using a try conditional with
7565a finally clause for restoring the settings. Its execution is guaranteed on
7566normal control flow, on error, on an explicit ":throw", and on interrupt.
7567(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar446cb832008-06-24 21:56:24 +00007568to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00007569clause has been executed.)
7570Example: >
7571
7572 :try
7573 : let s:saved_ts = &ts
7574 : set ts=17
7575 :
7576 : " Do the hard work here.
7577 :
7578 :finally
7579 : let &ts = s:saved_ts
7580 : unlet s:saved_ts
7581 :endtry
7582
7583This method should be used locally whenever a function or part of a script
7584changes global settings which need to be restored on failure or normal exit of
7585that function or script part.
7586
7587 *break-finally*
7588Cleanup code works also when the try block or a catch clause is left by
7589a ":continue", ":break", ":return", or ":finish".
7590 Example: >
7591
7592 :let first = 1
7593 :while 1
7594 : try
7595 : if first
7596 : echo "first"
7597 : let first = 0
7598 : continue
7599 : else
7600 : throw "second"
7601 : endif
7602 : catch /.*/
7603 : echo v:exception
7604 : break
7605 : finally
7606 : echo "cleanup"
7607 : endtry
7608 : echo "still in while"
7609 :endwhile
7610 :echo "end"
7611
7612This displays "first", "cleanup", "second", "cleanup", and "end". >
7613
7614 :function! Foo()
7615 : try
7616 : return 4711
7617 : finally
7618 : echo "cleanup\n"
7619 : endtry
7620 : echo "Foo still active"
7621 :endfunction
7622 :
7623 :echo Foo() "returned by Foo"
7624
7625This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar446cb832008-06-24 21:56:24 +00007626extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007627return value.)
7628
7629 *except-from-finally*
7630Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
7631a finally clause is possible, but not recommended since it abandons the
7632cleanup actions for the try conditional. But, of course, interrupt and error
7633exceptions might get raised from a finally clause.
7634 Example where an error in the finally clause stops an interrupt from
7635working correctly: >
7636
7637 :try
7638 : try
7639 : echo "Press CTRL-C for interrupt"
7640 : while 1
7641 : endwhile
7642 : finally
7643 : unlet novar
7644 : endtry
7645 :catch /novar/
7646 :endtry
7647 :echo "Script still running"
7648 :sleep 1
7649
7650If you need to put commands that could fail into a finally clause, you should
7651think about catching or ignoring the errors in these commands, see
7652|catch-errors| and |ignore-errors|.
7653
7654
7655CATCHING ERRORS *catch-errors*
7656
7657If you want to catch specific errors, you just have to put the code to be
7658watched in a try block and add a catch clause for the error message. The
7659presence of the try conditional causes all errors to be converted to an
7660exception. No message is displayed and |v:errmsg| is not set then. To find
7661the right pattern for the ":catch" command, you have to know how the format of
7662the error exception is.
7663 Error exceptions have the following format: >
7664
7665 Vim({cmdname}):{errmsg}
7666or >
7667 Vim:{errmsg}
7668
7669{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar446cb832008-06-24 21:56:24 +00007670the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00007671when the error occurs outside try conditionals. It always begins with
7672a capital "E", followed by a two or three-digit error number, a colon, and
7673a space.
7674
7675Examples:
7676
7677The command >
7678 :unlet novar
7679normally produces the error message >
7680 E108: No such variable: "novar"
7681which is converted inside try conditionals to an exception >
7682 Vim(unlet):E108: No such variable: "novar"
7683
7684The command >
7685 :dwim
7686normally produces the error message >
7687 E492: Not an editor command: dwim
7688which is converted inside try conditionals to an exception >
7689 Vim:E492: Not an editor command: dwim
7690
7691You can catch all ":unlet" errors by a >
7692 :catch /^Vim(unlet):/
7693or all errors for misspelled command names by a >
7694 :catch /^Vim:E492:/
7695
7696Some error messages may be produced by different commands: >
7697 :function nofunc
7698and >
7699 :delfunction nofunc
7700both produce the error message >
7701 E128: Function name must start with a capital: nofunc
7702which is converted inside try conditionals to an exception >
7703 Vim(function):E128: Function name must start with a capital: nofunc
7704or >
7705 Vim(delfunction):E128: Function name must start with a capital: nofunc
7706respectively. You can catch the error by its number independently on the
7707command that caused it if you use the following pattern: >
7708 :catch /^Vim(\a\+):E128:/
7709
7710Some commands like >
7711 :let x = novar
7712produce multiple error messages, here: >
7713 E121: Undefined variable: novar
7714 E15: Invalid expression: novar
7715Only the first is used for the exception value, since it is the most specific
7716one (see |except-several-errors|). So you can catch it by >
7717 :catch /^Vim(\a\+):E121:/
7718
7719You can catch all errors related to the name "nofunc" by >
7720 :catch /\<nofunc\>/
7721
7722You can catch all Vim errors in the ":write" and ":read" commands by >
7723 :catch /^Vim(\(write\|read\)):E\d\+:/
7724
7725You can catch all Vim errors by the pattern >
7726 :catch /^Vim\((\a\+)\)\=:E\d\+:/
7727<
7728 *catch-text*
7729NOTE: You should never catch the error message text itself: >
7730 :catch /No such variable/
7731only works in the english locale, but not when the user has selected
7732a different language by the |:language| command. It is however helpful to
7733cite the message text in a comment: >
7734 :catch /^Vim(\a\+):E108:/ " No such variable
7735
7736
7737IGNORING ERRORS *ignore-errors*
7738
7739You can ignore errors in a specific Vim command by catching them locally: >
7740
7741 :try
7742 : write
7743 :catch
7744 :endtry
7745
7746But you are strongly recommended NOT to use this simple form, since it could
7747catch more than you want. With the ":write" command, some autocommands could
7748be executed and cause errors not related to writing, for instance: >
7749
7750 :au BufWritePre * unlet novar
7751
7752There could even be such errors you are not responsible for as a script
7753writer: a user of your script might have defined such autocommands. You would
7754then hide the error from the user.
7755 It is much better to use >
7756
7757 :try
7758 : write
7759 :catch /^Vim(write):/
7760 :endtry
7761
7762which only catches real write errors. So catch only what you'd like to ignore
7763intentionally.
7764
7765For a single command that does not cause execution of autocommands, you could
7766even suppress the conversion of errors to exceptions by the ":silent!"
7767command: >
7768 :silent! nunmap k
7769This works also when a try conditional is active.
7770
7771
7772CATCHING INTERRUPTS *catch-interrupt*
7773
7774When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar446cb832008-06-24 21:56:24 +00007775the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00007776script is not terminated, then.
7777 Example: >
7778
7779 :function! TASK1()
7780 : sleep 10
7781 :endfunction
7782
7783 :function! TASK2()
7784 : sleep 20
7785 :endfunction
7786
7787 :while 1
7788 : let command = input("Type a command: ")
7789 : try
7790 : if command == ""
7791 : continue
7792 : elseif command == "END"
7793 : break
7794 : elseif command == "TASK1"
7795 : call TASK1()
7796 : elseif command == "TASK2"
7797 : call TASK2()
7798 : else
7799 : echo "\nIllegal command:" command
7800 : continue
7801 : endif
7802 : catch /^Vim:Interrupt$/
7803 : echo "\nCommand interrupted"
7804 : " Caught the interrupt. Continue with next prompt.
7805 : endtry
7806 :endwhile
7807
7808You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar446cb832008-06-24 21:56:24 +00007809a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007810
7811For testing what happens when CTRL-C would be pressed on a specific line in
7812your script, use the debug mode and execute the |>quit| or |>interrupt|
7813command on that line. See |debug-scripts|.
7814
7815
7816CATCHING ALL *catch-all*
7817
7818The commands >
7819
7820 :catch /.*/
7821 :catch //
7822 :catch
7823
7824catch everything, error exceptions, interrupt exceptions and exceptions
7825explicitly thrown by the |:throw| command. This is useful at the top level of
7826a script in order to catch unexpected things.
7827 Example: >
7828
7829 :try
7830 :
7831 : " do the hard work here
7832 :
7833 :catch /MyException/
7834 :
7835 : " handle known problem
7836 :
7837 :catch /^Vim:Interrupt$/
7838 : echo "Script interrupted"
7839 :catch /.*/
7840 : echo "Internal error (" . v:exception . ")"
7841 : echo " - occurred at " . v:throwpoint
7842 :endtry
7843 :" end of script
7844
7845Note: Catching all might catch more things than you want. Thus, you are
7846strongly encouraged to catch only for problems that you can really handle by
7847specifying a pattern argument to the ":catch".
7848 Example: Catching all could make it nearly impossible to interrupt a script
7849by pressing CTRL-C: >
7850
7851 :while 1
7852 : try
7853 : sleep 1
7854 : catch
7855 : endtry
7856 :endwhile
7857
7858
7859EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
7860
7861Exceptions may be used during execution of autocommands. Example: >
7862
7863 :autocmd User x try
7864 :autocmd User x throw "Oops!"
7865 :autocmd User x catch
7866 :autocmd User x echo v:exception
7867 :autocmd User x endtry
7868 :autocmd User x throw "Arrgh!"
7869 :autocmd User x echo "Should not be displayed"
7870 :
7871 :try
7872 : doautocmd User x
7873 :catch
7874 : echo v:exception
7875 :endtry
7876
7877This displays "Oops!" and "Arrgh!".
7878
7879 *except-autocmd-Pre*
7880For some commands, autocommands get executed before the main action of the
7881command takes place. If an exception is thrown and not caught in the sequence
7882of autocommands, the sequence and the command that caused its execution are
7883abandoned and the exception is propagated to the caller of the command.
7884 Example: >
7885
7886 :autocmd BufWritePre * throw "FAIL"
7887 :autocmd BufWritePre * echo "Should not be displayed"
7888 :
7889 :try
7890 : write
7891 :catch
7892 : echo "Caught:" v:exception "from" v:throwpoint
7893 :endtry
7894
7895Here, the ":write" command does not write the file currently being edited (as
7896you can see by checking 'modified'), since the exception from the BufWritePre
7897autocommand abandons the ":write". The exception is then caught and the
7898script displays: >
7899
7900 Caught: FAIL from BufWrite Auto commands for "*"
7901<
7902 *except-autocmd-Post*
7903For some commands, autocommands get executed after the main action of the
7904command has taken place. If this main action fails and the command is inside
7905an active try conditional, the autocommands are skipped and an error exception
7906is thrown that can be caught by the caller of the command.
7907 Example: >
7908
7909 :autocmd BufWritePost * echo "File successfully written!"
7910 :
7911 :try
7912 : write /i/m/p/o/s/s/i/b/l/e
7913 :catch
7914 : echo v:exception
7915 :endtry
7916
7917This just displays: >
7918
7919 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
7920
7921If you really need to execute the autocommands even when the main action
7922fails, trigger the event from the catch clause.
7923 Example: >
7924
7925 :autocmd BufWritePre * set noreadonly
7926 :autocmd BufWritePost * set readonly
7927 :
7928 :try
7929 : write /i/m/p/o/s/s/i/b/l/e
7930 :catch
7931 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
7932 :endtry
7933<
7934You can also use ":silent!": >
7935
7936 :let x = "ok"
7937 :let v:errmsg = ""
7938 :autocmd BufWritePost * if v:errmsg != ""
7939 :autocmd BufWritePost * let x = "after fail"
7940 :autocmd BufWritePost * endif
7941 :try
7942 : silent! write /i/m/p/o/s/s/i/b/l/e
7943 :catch
7944 :endtry
7945 :echo x
7946
7947This displays "after fail".
7948
7949If the main action of the command does not fail, exceptions from the
7950autocommands will be catchable by the caller of the command: >
7951
7952 :autocmd BufWritePost * throw ":-("
7953 :autocmd BufWritePost * echo "Should not be displayed"
7954 :
7955 :try
7956 : write
7957 :catch
7958 : echo v:exception
7959 :endtry
7960<
7961 *except-autocmd-Cmd*
7962For some commands, the normal action can be replaced by a sequence of
7963autocommands. Exceptions from that sequence will be catchable by the caller
7964of the command.
7965 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar446cb832008-06-24 21:56:24 +00007966had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00007967some way. >
7968
7969 :if !exists("cnt")
7970 : let cnt = 0
7971 :
7972 : autocmd BufWriteCmd * if &modified
7973 : autocmd BufWriteCmd * let cnt = cnt + 1
7974 : autocmd BufWriteCmd * if cnt % 3 == 2
7975 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7976 : autocmd BufWriteCmd * endif
7977 : autocmd BufWriteCmd * write | set nomodified
7978 : autocmd BufWriteCmd * if cnt % 3 == 0
7979 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7980 : autocmd BufWriteCmd * endif
7981 : autocmd BufWriteCmd * echo "File successfully written!"
7982 : autocmd BufWriteCmd * endif
7983 :endif
7984 :
7985 :try
7986 : write
7987 :catch /^BufWriteCmdError$/
7988 : if &modified
7989 : echo "Error on writing (file contents not changed)"
7990 : else
7991 : echo "Error after writing"
7992 : endif
7993 :catch /^Vim(write):/
7994 : echo "Error on writing"
7995 :endtry
7996
7997When this script is sourced several times after making changes, it displays
7998first >
7999 File successfully written!
8000then >
8001 Error on writing (file contents not changed)
8002then >
8003 Error after writing
8004etc.
8005
8006 *except-autocmd-ill*
8007You cannot spread a try conditional over autocommands for different events.
8008The following code is ill-formed: >
8009
8010 :autocmd BufWritePre * try
8011 :
8012 :autocmd BufWritePost * catch
8013 :autocmd BufWritePost * echo v:exception
8014 :autocmd BufWritePost * endtry
8015 :
8016 :write
8017
8018
8019EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
8020
8021Some programming languages allow to use hierarchies of exception classes or to
8022pass additional information with the object of an exception class. You can do
8023similar things in Vim.
8024 In order to throw an exception from a hierarchy, just throw the complete
8025class name with the components separated by a colon, for instance throw the
8026string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
8027 When you want to pass additional information with your exception class, add
8028it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
8029for an error when writing "myfile".
8030 With the appropriate patterns in the ":catch" command, you can catch for
8031base classes or derived classes of your hierarchy. Additional information in
8032parentheses can be cut out from |v:exception| with the ":substitute" command.
8033 Example: >
8034
8035 :function! CheckRange(a, func)
8036 : if a:a < 0
8037 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
8038 : endif
8039 :endfunction
8040 :
8041 :function! Add(a, b)
8042 : call CheckRange(a:a, "Add")
8043 : call CheckRange(a:b, "Add")
8044 : let c = a:a + a:b
8045 : if c < 0
8046 : throw "EXCEPT:MATHERR:OVERFLOW"
8047 : endif
8048 : return c
8049 :endfunction
8050 :
8051 :function! Div(a, b)
8052 : call CheckRange(a:a, "Div")
8053 : call CheckRange(a:b, "Div")
8054 : if (a:b == 0)
8055 : throw "EXCEPT:MATHERR:ZERODIV"
8056 : endif
8057 : return a:a / a:b
8058 :endfunction
8059 :
8060 :function! Write(file)
8061 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008062 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008063 : catch /^Vim(write):/
8064 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
8065 : endtry
8066 :endfunction
8067 :
8068 :try
8069 :
8070 : " something with arithmetics and I/O
8071 :
8072 :catch /^EXCEPT:MATHERR:RANGE/
8073 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
8074 : echo "Range error in" function
8075 :
8076 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
8077 : echo "Math error"
8078 :
8079 :catch /^EXCEPT:IO/
8080 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
8081 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
8082 : if file !~ '^/'
8083 : let file = dir . "/" . file
8084 : endif
8085 : echo 'I/O error for "' . file . '"'
8086 :
8087 :catch /^EXCEPT/
8088 : echo "Unspecified error"
8089 :
8090 :endtry
8091
8092The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
8093a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
8094exceptions with the "Vim" prefix; they are reserved for Vim.
8095 Vim error exceptions are parameterized with the name of the command that
8096failed, if known. See |catch-errors|.
8097
8098
8099PECULIARITIES
8100 *except-compat*
8101The exception handling concept requires that the command sequence causing the
8102exception is aborted immediately and control is transferred to finally clauses
8103and/or a catch clause.
8104
8105In the Vim script language there are cases where scripts and functions
8106continue after an error: in functions without the "abort" flag or in a command
8107after ":silent!", control flow goes to the following line, and outside
8108functions, control flow goes to the line following the outermost ":endwhile"
8109or ":endif". On the other hand, errors should be catchable as exceptions
8110(thus, requiring the immediate abortion).
8111
8112This problem has been solved by converting errors to exceptions and using
8113immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008114conditional is active. This is no restriction since an (error) exception can
8115be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00008116termination without catching the error, just use a try conditional without
8117catch clause. (You can cause cleanup code being executed before termination
8118by specifying a finally clause.)
8119
8120When no try conditional is active, the usual abortion and continuation
8121behavior is used instead of immediate abortion. This ensures compatibility of
8122scripts written for Vim 6.1 and earlier.
8123
8124However, when sourcing an existing script that does not use exception handling
8125commands (or when calling one of its functions) from inside an active try
8126conditional of a new script, you might change the control flow of the existing
8127script on error. You get the immediate abortion on error and can catch the
8128error in the new script. If however the sourced script suppresses error
8129messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar446cb832008-06-24 21:56:24 +00008130|v:errmsg| if appropriate), its execution path is not changed. The error is
8131not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00008132where this happens is for scripts that don't care about errors and produce
8133error messages. You probably won't want to use such code from your new
8134scripts.
8135
8136 *except-syntax-err*
8137Syntax errors in the exception handling commands are never caught by any of
8138the ":catch" commands of the try conditional they belong to. Its finally
8139clauses, however, is executed.
8140 Example: >
8141
8142 :try
8143 : try
8144 : throw 4711
8145 : catch /\(/
8146 : echo "in catch with syntax error"
8147 : catch
8148 : echo "inner catch-all"
8149 : finally
8150 : echo "inner finally"
8151 : endtry
8152 :catch
8153 : echo 'outer catch-all caught "' . v:exception . '"'
8154 : finally
8155 : echo "outer finally"
8156 :endtry
8157
8158This displays: >
8159 inner finally
8160 outer catch-all caught "Vim(catch):E54: Unmatched \("
8161 outer finally
8162The original exception is discarded and an error exception is raised, instead.
8163
8164 *except-single-line*
8165The ":try", ":catch", ":finally", and ":endtry" commands can be put on
8166a single line, but then syntax errors may make it difficult to recognize the
8167"catch" line, thus you better avoid this.
8168 Example: >
8169 :try | unlet! foo # | catch | endtry
8170raises an error exception for the trailing characters after the ":unlet!"
8171argument, but does not see the ":catch" and ":endtry" commands, so that the
8172error exception is discarded and the "E488: Trailing characters" message gets
8173displayed.
8174
8175 *except-several-errors*
8176When several errors appear in a single command, the first error message is
8177usually the most specific one and therefor converted to the error exception.
8178 Example: >
8179 echo novar
8180causes >
8181 E121: Undefined variable: novar
8182 E15: Invalid expression: novar
8183The value of the error exception inside try conditionals is: >
8184 Vim(echo):E121: Undefined variable: novar
8185< *except-syntax-error*
8186But when a syntax error is detected after a normal error in the same command,
8187the syntax error is used for the exception being thrown.
8188 Example: >
8189 unlet novar #
8190causes >
8191 E108: No such variable: "novar"
8192 E488: Trailing characters
8193The value of the error exception inside try conditionals is: >
8194 Vim(unlet):E488: Trailing characters
8195This is done because the syntax error might change the execution path in a way
8196not intended by the user. Example: >
8197 try
8198 try | unlet novar # | catch | echo v:exception | endtry
8199 catch /.*/
8200 echo "outer catch:" v:exception
8201 endtry
8202This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
8203a "E600: Missing :endtry" error message is given, see |except-single-line|.
8204
8205==============================================================================
82069. Examples *eval-examples*
8207
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008208Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008209>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008210 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008211 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008212 : let n = a:nr
8213 : let r = ""
8214 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008215 : let r = '01'[n % 2] . r
8216 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00008217 : endwhile
8218 : return r
8219 :endfunc
8220
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008221 :" The function String2Bin() converts each character in a string to a
8222 :" binary string, separated with dashes.
8223 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008224 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008225 : for ix in range(strlen(a:str))
8226 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
8227 : endfor
8228 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00008229 :endfunc
8230
8231Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008232 :echo Nr2Bin(32)
8233result: "100000" >
8234 :echo String2Bin("32")
8235result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008236
8237
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008238Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008239
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008240This example sorts lines with a specific compare function. >
8241
8242 :func SortBuffer()
8243 : let lines = getline(1, '$')
8244 : call sort(lines, function("Strcmp"))
8245 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008246 :endfunction
8247
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008248As a one-liner: >
8249 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00008250
Bram Moolenaar071d4272004-06-13 20:20:40 +00008251
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008252scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008253 *sscanf*
8254There is no sscanf() function in Vim. If you need to extract parts from a
8255line, you can use matchstr() and substitute() to do it. This example shows
8256how to get the file name, line number and column number out of a line like
8257"foobar.txt, 123, 45". >
8258 :" Set up the match bit
8259 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
8260 :"get the part matching the whole expression
8261 :let l = matchstr(line, mx)
8262 :"get each item out of the match
8263 :let file = substitute(l, mx, '\1', '')
8264 :let lnum = substitute(l, mx, '\2', '')
8265 :let col = substitute(l, mx, '\3', '')
8266
8267The input is in the variable "line", the results in the variables "file",
8268"lnum" and "col". (idea from Michael Geddes)
8269
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008270
8271getting the scriptnames in a Dictionary ~
8272 *scriptnames-dictionary*
8273The |:scriptnames| command can be used to get a list of all script files that
8274have been sourced. There is no equivalent function or variable for this
8275(because it's rarely needed). In case you need to manipulate the list this
8276code can be used: >
8277 " Get the output of ":scriptnames" in the scriptnames_output variable.
8278 let scriptnames_output = ''
8279 redir => scriptnames_output
8280 silent scriptnames
8281 redir END
8282
Bram Moolenaar446cb832008-06-24 21:56:24 +00008283 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008284 " "scripts" dictionary.
8285 let scripts = {}
8286 for line in split(scriptnames_output, "\n")
8287 " Only do non-blank lines.
8288 if line =~ '\S'
8289 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008290 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008291 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00008292 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008293 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00008294 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008295 endif
8296 endfor
8297 unlet scriptnames_output
8298
Bram Moolenaar071d4272004-06-13 20:20:40 +00008299==============================================================================
830010. No +eval feature *no-eval-feature*
8301
8302When the |+eval| feature was disabled at compile time, none of the expression
8303evaluation commands are available. To prevent this from causing Vim scripts
8304to generate all kinds of errors, the ":if" and ":endif" commands are still
8305recognized, though the argument of the ":if" and everything between the ":if"
8306and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
8307only if the commands are at the start of the line. The ":else" command is not
8308recognized.
8309
8310Example of how to avoid executing commands when the |+eval| feature is
8311missing: >
8312
8313 :if 1
8314 : echo "Expression evaluation is compiled in"
8315 :else
8316 : echo "You will _never_ see this message"
8317 :endif
8318
8319==============================================================================
832011. The sandbox *eval-sandbox* *sandbox* *E48*
8321
Bram Moolenaar368373e2010-07-19 20:46:22 +02008322The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
8323'foldtext' options may be evaluated in a sandbox. This means that you are
8324protected from these expressions having nasty side effects. This gives some
8325safety for when these options are set from a modeline. It is also used when
8326the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00008327The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008328
8329These items are not allowed in the sandbox:
8330 - changing the buffer text
8331 - defining or changing mapping, autocommands, functions, user commands
8332 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008333 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008334 - executing a shell command
8335 - reading or writing a file
8336 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00008337 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00008338This is not guaranteed 100% secure, but it should block most attacks.
8339
8340 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00008341:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00008342 option that may have been set from a modeline, e.g.
8343 'foldexpr'.
8344
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008345 *sandbox-option*
8346A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00008347have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008348restrictive, thus this only happens when the option was set from an insecure
8349location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00008350- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008351- while executing in the sandbox
8352- value coming from a modeline
8353
8354Note that when in the sandbox and saving an option value and restoring it, the
8355option will still be marked as it was set in the sandbox.
8356
8357==============================================================================
835812. Textlock *textlock*
8359
8360In a few situations it is not allowed to change the text in the buffer, jump
8361to another window and some other things that might confuse or break what Vim
8362is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar446cb832008-06-24 21:56:24 +00008363actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00008364happen any moment the mouse cursor is resting at some position.
8365
8366This is not allowed when the textlock is active:
8367 - changing the buffer text
8368 - jumping to another buffer or window
8369 - editing another file
8370 - closing a window or quitting Vim
8371 - etc.
8372
Bram Moolenaar071d4272004-06-13 20:20:40 +00008373
8374 vim:tw=78:ts=8:ft=help:norl: