blob: 3e9985843b8a564dd79f738115062b920d146e8d [file] [log] [blame]
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001*eval.txt* For Vim version 7.4. Last change: 2016 Apr 20
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
Bram Moolenaar446cb832008-06-24 21:56:24 +00004 VIM REFERENCE MANUAL by Bram Moolenaar
Bram Moolenaar071d4272004-06-13 20:20:40 +00005
6
7Expression evaluation *expression* *expr* *E15* *eval*
8
9Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|.
10
11Note: Expression evaluation can be disabled at compile time. If this has been
Bram Moolenaar446cb832008-06-24 21:56:24 +000012done, the features in this document are not available. See |+eval| and
Bram Moolenaard8b02732005-01-14 21:48:43 +000013|no-eval-feature|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000014
Bram Moolenaar13065c42005-01-08 16:08:21 +0000151. Variables |variables|
16 1.1 Variable types
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000017 1.2 Function references |Funcref|
Bram Moolenaar7c626922005-02-07 22:01:03 +000018 1.3 Lists |Lists|
Bram Moolenaard8b02732005-01-14 21:48:43 +000019 1.4 Dictionaries |Dictionaries|
20 1.5 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000212. Expression syntax |expression-syntax|
223. Internal variable |internal-variables|
234. Builtin Functions |functions|
245. Defining functions |user-functions|
256. Curly braces names |curly-braces-names|
267. Commands |expression-commands|
278. Exception handling |exception-handling|
289. Examples |eval-examples|
2910. No +eval feature |no-eval-feature|
3011. The sandbox |eval-sandbox|
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003112. Textlock |textlock|
Bram Moolenaar071d4272004-06-13 20:20:40 +000032
33{Vi does not have any of these commands}
34
35==============================================================================
361. Variables *variables*
37
Bram Moolenaar13065c42005-01-08 16:08:21 +0000381.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000039 *E712*
Bram Moolenaar38a55632016-02-15 22:07:32 +010040There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000041
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020042Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaard8b02732005-01-14 21:48:43 +000043 Examples: -123 0x10 0177
44
Bram Moolenaar446cb832008-06-24 21:56:24 +000045Float A floating point number. |floating-point-format| *Float*
46 {only when compiled with the |+float| feature}
47 Examples: 123.456 1.15e-6 -1.1e3
48
Bram Moolenaard8b02732005-01-14 21:48:43 +000049String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000050 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000051
Bram Moolenaard8b02732005-01-14 21:48:43 +000052List An ordered sequence of items |List|.
53 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000054
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000055Dictionary An associative, unordered array: Each entry has a key and a
56 value. |Dictionary|
57 Example: {'blue': "#0000ff", 'red': "#ff0000"}
58
Bram Moolenaar835dc632016-02-07 14:27:38 +010059Funcref A reference to a function |Funcref|.
60 Example: function("strlen")
61
Bram Moolenaar02e83b42016-02-21 20:10:26 +010062Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010063
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020064Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010065
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020066Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010067
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000068The Number and String types are converted automatically, depending on how they
69are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000070
71Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020072the Number. Examples:
73 Number 123 --> String "123" ~
74 Number 0 --> String "0" ~
75 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020076 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010077Conversion from a String to a Number is done by converting the first digits to
78a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
79recognized. If the String doesn't start with digits, the result is zero.
80Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020081 String "456" --> Number 456 ~
82 String "6bar" --> Number 6 ~
83 String "foo" --> Number 0 ~
84 String "0xf1" --> Number 241 ~
85 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +010086 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020087 String "-8" --> Number -8 ~
88 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000089
90To force conversion from String to Number, add zero to it: >
91 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000092< 64 ~
93
94To avoid a leading zero to cause octal conversion, or for using a different
95base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000096
97For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
98
99Note that in the command >
100 :if "foo"
101"foo" is converted to 0, which means FALSE. To test for a non-empty string,
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200102use empty(): >
103 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100104<
Bram Moolenaar38a55632016-02-15 22:07:32 +0100105 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar835dc632016-02-07 14:27:38 +0100106List, Dictionary, Funcref and Job types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000107
Bram Moolenaar446cb832008-06-24 21:56:24 +0000108 *E805* *E806* *E808*
109When mixing Number and Float the Number is converted to Float. Otherwise
110there is no automatic conversion of Float. You can use str2float() for String
111to Float, printf() for Float to String and float2nr() for Float to Number.
112
Bram Moolenaar38a55632016-02-15 22:07:32 +0100113 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100114When expecting a Float a Number can also be used, but nothing else.
115
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100116 *no-type-checking*
117You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000118
Bram Moolenaar13065c42005-01-08 16:08:21 +0000119
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001201.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000121 *Funcref* *E695* *E718*
Bram Moolenaar446cb832008-06-24 21:56:24 +0000122A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000123in an expression in the place of a function name, before the parenthesis
124around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000125
126 :let Fn = function("MyFunc")
127 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000128< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000129A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200130can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000131cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000132
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000133A special case is defining a function and directly assigning its Funcref to a
134Dictionary entry. Example: >
135 :function dict.init() dict
136 : let self.val = 0
137 :endfunction
138
139The key of the Dictionary can start with a lower case letter. The actual
140function name is not used here. Also see |numbered-function|.
141
142A Funcref can also be used with the |:call| command: >
143 :call Fn()
144 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000145
146The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000147 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000148
149You can use |call()| to invoke a Funcref and use a list variable for the
150arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000151 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000152
153
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001541.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200155 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000156A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar446cb832008-06-24 21:56:24 +0000157can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000158position in the sequence.
159
Bram Moolenaar13065c42005-01-08 16:08:21 +0000160
161List creation ~
162 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000163A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000164Examples: >
165 :let mylist = [1, two, 3, "four"]
166 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000167
Bram Moolenaar446cb832008-06-24 21:56:24 +0000168An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000169List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000170 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000171
172An extra comma after the last item is ignored.
173
Bram Moolenaar13065c42005-01-08 16:08:21 +0000174
175List index ~
176 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000177An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000178after the List. Indexes are zero-based, thus the first item has index zero. >
179 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000180 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000181
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000182When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000183 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000184<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000185A negative index is counted from the end. Index -1 refers to the last item in
186the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000187 :let last = mylist[-1] " get the last item: "four"
188
Bram Moolenaar13065c42005-01-08 16:08:21 +0000189To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000190is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000191 :echo get(mylist, idx)
192 :echo get(mylist, idx, "NONE")
193
194
195List concatenation ~
196
197Two lists can be concatenated with the "+" operator: >
198 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000199 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000200
201To prepend or append an item turn the item into a list by putting [] around
202it. To change a list in-place see |list-modification| below.
203
204
205Sublist ~
206
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000207A part of the List can be obtained by specifying the first and last index,
208separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000209 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000210
211Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000212similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000213 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
214 :let shortlist = mylist[2:2] " List with one item: [3]
215 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000216
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000217If the first index is beyond the last item of the List or the second item is
218before the first item, the result is an empty list. There is no error
219message.
220
221If the second index is equal to or greater than the length of the list the
222length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000223 :let mylist = [0, 1, 2, 3]
224 :echo mylist[2:8] " result: [2, 3]
225
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000226NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar446cb832008-06-24 21:56:24 +0000227using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000228mylist[s : e].
229
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000230
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000232 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000233When variable "aa" is a list and you assign it to another variable "bb", both
234variables refer to the same list. Thus changing the list "aa" will also
235change "bb": >
236 :let aa = [1, 2, 3]
237 :let bb = aa
238 :call add(aa, 4)
239 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000240< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241
242Making a copy of a list is done with the |copy()| function. Using [:] also
243works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000244a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000245 :let aa = [[1, 'a'], 2, 3]
246 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000247 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000248 :let aa[0][1] = 'aaa'
249 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000250< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000251 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000252< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000253
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000254To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000255copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000256
257The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000258List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000259the same value. >
260 :let alist = [1, 2, 3]
261 :let blist = [1, 2, 3]
262 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000263< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000264 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000265< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000266
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000267Note about comparing lists: Two lists are considered equal if they have the
268same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000269exception: When comparing a number with a string they are considered
270different. There is no automatic type conversion, as with using "==" on
271variables. Example: >
272 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000273< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000274 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000275< 0
276
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000277Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000278can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000279
280 :let a = 5
281 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000282 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000283< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000284 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000285< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000286
Bram Moolenaar13065c42005-01-08 16:08:21 +0000287
288List unpack ~
289
290To unpack the items in a list to individual variables, put the variables in
291square brackets, like list items: >
292 :let [var1, var2] = mylist
293
294When the number of variables does not match the number of items in the list
295this produces an error. To handle any extra items from the list append ";"
296and a variable name: >
297 :let [var1, var2; rest] = mylist
298
299This works like: >
300 :let var1 = mylist[0]
301 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000302 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000303
304Except that there is no error if there are only two items. "rest" will be an
305empty list then.
306
307
308List modification ~
309 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000310To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000311 :let list[4] = "four"
312 :let listlist[0][3] = item
313
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000314To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000315modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000316 :let list[3:5] = [3, 4, 5]
317
Bram Moolenaar13065c42005-01-08 16:08:21 +0000318Adding and removing items from a list is done with functions. Here are a few
319examples: >
320 :call insert(list, 'a') " prepend item 'a'
321 :call insert(list, 'a', 3) " insert item 'a' before list[3]
322 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000323 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000324 :call extend(list, [1, 2]) " extend the list with two more items
325 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000326 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000327 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000328 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000329 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000330
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000331Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000332 :call sort(list) " sort a list alphabetically
333 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100334 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000335
Bram Moolenaar13065c42005-01-08 16:08:21 +0000336
337For loop ~
338
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000339The |:for| loop executes commands for each item in a list. A variable is set
340to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000341 :for item in mylist
342 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000343 :endfor
344
345This works like: >
346 :let index = 0
347 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000348 : let item = mylist[index]
349 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000350 : let index = index + 1
351 :endwhile
352
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000353If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000354function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000355
Bram Moolenaar446cb832008-06-24 21:56:24 +0000356Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000357requires the argument to be a list of lists. >
358 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
359 : call Doit(lnum, col)
360 :endfor
361
362This works like a |:let| command is done for each list item. Again, the types
363must remain the same to avoid an error.
364
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000365It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000366 :for [i, j; rest] in listlist
367 : call Doit(i, j)
368 : if !empty(rest)
369 : echo "remainder: " . string(rest)
370 : endif
371 :endfor
372
373
374List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000375 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000376Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000377 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000378 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000379 :let l = len(list) " number of items in list
380 :let big = max(list) " maximum value in list
381 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000382 :let xs = count(list, 'x') " count nr of times 'x' appears in list
383 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000384 :let lines = getline(1, 10) " get ten text lines from buffer
385 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000386 :let list = split("a b c") " create list from items in a string
387 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000388 :let s = string(list) " String representation of list
389 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000390
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000391Don't forget that a combination of features can make things simple. For
392example, to add up all the numbers in a list: >
393 :exe 'let sum = ' . join(nrlist, '+')
394
Bram Moolenaar13065c42005-01-08 16:08:21 +0000395
Bram Moolenaard8b02732005-01-14 21:48:43 +00003961.4 Dictionaries ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200397 *dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000398A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000399entry can be located with the key. The entries are stored without a specific
400ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000401
402
403Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000404 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000405A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000406braces. Each entry has a key and a value, separated by a colon. Each key can
407only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000408 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
409 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000410< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000411A key is always a String. You can use a Number, it will be converted to a
412String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar446cb832008-06-24 21:56:24 +0000413entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar03413f42016-04-12 21:07:15 +0200414Number will be converted to the String '4'. The empty string can be used as a
415key.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000416
Bram Moolenaar446cb832008-06-24 21:56:24 +0000417A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000418nested Dictionary: >
419 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
420
421An extra comma after the last entry is ignored.
422
423
424Accessing entries ~
425
426The normal way to access an entry is by putting the key in square brackets: >
427 :let val = mydict["one"]
428 :let mydict["four"] = 4
429
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000430You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000431
432For keys that consist entirely of letters, digits and underscore the following
433form can be used |expr-entry|: >
434 :let val = mydict.one
435 :let mydict.four = 4
436
437Since an entry can be any type, also a List and a Dictionary, the indexing and
438key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000439 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000440
441
442Dictionary to List conversion ~
443
Bram Moolenaar446cb832008-06-24 21:56:24 +0000444You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000445turn the Dictionary into a List and pass it to |:for|.
446
447Most often you want to loop over the keys, using the |keys()| function: >
448 :for key in keys(mydict)
449 : echo key . ': ' . mydict[key]
450 :endfor
451
452The List of keys is unsorted. You may want to sort them first: >
453 :for key in sort(keys(mydict))
454
455To loop over the values use the |values()| function: >
456 :for v in values(mydict)
457 : echo "value: " . v
458 :endfor
459
460If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar446cb832008-06-24 21:56:24 +0000461a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000462 :for [key, value] in items(mydict)
463 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000464 :endfor
465
466
467Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000468 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000469Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
470Dictionary. Otherwise, assignment results in referring to the same
471Dictionary: >
472 :let onedict = {'a': 1, 'b': 2}
473 :let adict = onedict
474 :let adict['a'] = 11
475 :echo onedict['a']
476 11
477
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000478Two Dictionaries compare equal if all the key-value pairs compare equal. For
479more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000480
481
482Dictionary modification ~
483 *dict-modification*
484To change an already existing entry of a Dictionary, or to add a new entry,
485use |:let| this way: >
486 :let dict[4] = "four"
487 :let dict['one'] = item
488
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000489Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
490Three ways to remove the entry with key "aaa" from dict: >
491 :let i = remove(dict, 'aaa')
492 :unlet dict.aaa
493 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000494
495Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000496 :call extend(adict, bdict)
497This extends adict with all entries from bdict. Duplicate keys cause entries
498in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000499Note that the order of entries in a Dictionary is irrelevant, thus don't
500expect ":echo adict" to show the items from bdict after the older entries in
501adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000502
503Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000504 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000505This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000506
507
508Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100509 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000510When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar446cb832008-06-24 21:56:24 +0000511special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000512 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000513 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000514 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000515 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
516 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000517
518This is like a method in object oriented programming. The entry in the
519Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
520the function was invoked from.
521
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000522It is also possible to add a function without the "dict" attribute as a
523Funcref to a Dictionary, but the "self" variable is not available then.
524
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000525 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000526To avoid the extra name for the function it can be defined and directly
527assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000528 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200529 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000530 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000531 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000532 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000533
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000534The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar446cb832008-06-24 21:56:24 +0000535that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000536|Funcref|. It will automatically be deleted when there is no |Funcref|
537remaining that refers to it.
538
539It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000540
Bram Moolenaar1affd722010-08-04 17:49:30 +0200541If you get an error for a numbered function, you can find out what it is with
542a trick. Assuming the function is 42, the command is: >
543 :function {42}
544
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000545
546Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000547 *E715*
548Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000549 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
550 :if empty(dict) " TRUE if dict is empty
551 :let l = len(dict) " number of items in dict
552 :let big = max(dict) " maximum value in dict
553 :let small = min(dict) " minimum value in dict
554 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
555 :let s = string(dict) " String representation of dict
556 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000557
558
5591.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000560 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000561If you need to know the type of a variable or expression, use the |type()|
562function.
563
564When the '!' flag is included in the 'viminfo' option, global variables that
565start with an uppercase letter, and don't contain a lowercase letter, are
566stored in the viminfo file |viminfo-file|.
567
568When the 'sessionoptions' option contains "global", global variables that
569start with an uppercase letter and contain at least one lowercase letter are
570stored in the session file |session-file|.
571
572variable name can be stored where ~
573my_var_6 not
574My_Var_6 session file
575MY_VAR_6 viminfo file
576
577
578It's possible to form a variable name with curly braces, see
579|curly-braces-names|.
580
581==============================================================================
5822. Expression syntax *expression-syntax*
583
584Expression syntax summary, from least to most significant:
585
586|expr1| expr2 ? expr1 : expr1 if-then-else
587
588|expr2| expr3 || expr3 .. logical OR
589
590|expr3| expr4 && expr4 .. logical AND
591
592|expr4| expr5 == expr5 equal
593 expr5 != expr5 not equal
594 expr5 > expr5 greater than
595 expr5 >= expr5 greater than or equal
596 expr5 < expr5 smaller than
597 expr5 <= expr5 smaller than or equal
598 expr5 =~ expr5 regexp matches
599 expr5 !~ expr5 regexp doesn't match
600
601 expr5 ==? expr5 equal, ignoring case
602 expr5 ==# expr5 equal, match case
603 etc. As above, append ? for ignoring case, # for
604 matching case
605
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000606 expr5 is expr5 same |List| instance
607 expr5 isnot expr5 different |List| instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000608
609|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000610 expr6 - expr6 .. number subtraction
611 expr6 . expr6 .. string concatenation
612
613|expr6| expr7 * expr7 .. number multiplication
614 expr7 / expr7 .. number division
615 expr7 % expr7 .. number modulo
616
617|expr7| ! expr7 logical NOT
618 - expr7 unary minus
619 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000620
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000621|expr8| expr8[expr1] byte of a String or item of a |List|
622 expr8[expr1 : expr1] substring of a String or sublist of a |List|
623 expr8.name entry in a |Dictionary|
624 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000625
626|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000627 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000628 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000629 [expr1, ...] |List|
630 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000631 &option option value
632 (expr1) nested expression
633 variable internal variable
634 va{ria}ble internal variable with curly braces
635 $VAR environment variable
636 @r contents of register 'r'
637 function(expr1, ...) function call
638 func{ti}on(expr1, ...) function call with curly braces
639
640
641".." indicates that the operations in this level can be concatenated.
642Example: >
643 &nu || &list && &shell == "csh"
644
645All expressions within one level are parsed from left to right.
646
647
648expr1 *expr1* *E109*
649-----
650
651expr2 ? expr1 : expr1
652
653The expression before the '?' is evaluated to a number. If it evaluates to
654non-zero, the result is the value of the expression between the '?' and ':',
655otherwise the result is the value of the expression after the ':'.
656Example: >
657 :echo lnum == 1 ? "top" : lnum
658
659Since the first expression is an "expr2", it cannot contain another ?:. The
660other two expressions can, thus allow for recursive use of ?:.
661Example: >
662 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
663
664To keep this readable, using |line-continuation| is suggested: >
665 :echo lnum == 1
666 :\ ? "top"
667 :\ : lnum == 1000
668 :\ ? "last"
669 :\ : lnum
670
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000671You should always put a space before the ':', otherwise it can be mistaken for
672use in a variable such as "a:1".
673
Bram Moolenaar071d4272004-06-13 20:20:40 +0000674
675expr2 and expr3 *expr2* *expr3*
676---------------
677
678 *expr-barbar* *expr-&&*
679The "||" and "&&" operators take one argument on each side. The arguments
680are (converted to) Numbers. The result is:
681
682 input output ~
683n1 n2 n1 || n2 n1 && n2 ~
684zero zero zero zero
685zero non-zero non-zero zero
686non-zero zero non-zero zero
687non-zero non-zero non-zero non-zero
688
689The operators can be concatenated, for example: >
690
691 &nu || &list && &shell == "csh"
692
693Note that "&&" takes precedence over "||", so this has the meaning of: >
694
695 &nu || (&list && &shell == "csh")
696
697Once the result is known, the expression "short-circuits", that is, further
698arguments are not evaluated. This is like what happens in C. For example: >
699
700 let a = 1
701 echo a || b
702
703This is valid even if there is no variable called "b" because "a" is non-zero,
704so the result must be non-zero. Similarly below: >
705
706 echo exists("b") && b == "yes"
707
708This is valid whether "b" has been defined or not. The second clause will
709only be evaluated if "b" has been defined.
710
711
712expr4 *expr4*
713-----
714
715expr5 {cmp} expr5
716
717Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
718if it evaluates to true.
719
Bram Moolenaar446cb832008-06-24 21:56:24 +0000720 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000721 *expr-<* *expr-<=* *expr-=~* *expr-!~*
722 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
723 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
724 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
725 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200726 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
727 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000728 use 'ignorecase' match case ignore case ~
729equal == ==# ==?
730not equal != !=# !=?
731greater than > ># >?
732greater than or equal >= >=# >=?
733smaller than < <# <?
734smaller than or equal <= <=# <=?
735regexp matches =~ =~# =~?
736regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200737same instance is is# is?
738different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000739
740Examples:
741"abc" ==# "Abc" evaluates to 0
742"abc" ==? "Abc" evaluates to 1
743"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
744
Bram Moolenaar13065c42005-01-08 16:08:21 +0000745 *E691* *E692*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000746A |List| can only be compared with a |List| and only "equal", "not equal" and
747"is" can be used. This compares the values of the list, recursively.
748Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000749
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000750 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000751A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
752equal" and "is" can be used. This compares the key/values of the |Dictionary|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000753recursively. Ignoring case means case is ignored when comparing item values.
754
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200755 *E694*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000756A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
Bram Moolenaar03602ec2016-03-20 20:57:45 +0100757equal" can be used. Case is never ignored. Whether arguments or a Dictionary
758are bound (with a partial) is ignored. This is so that when a function is
759made a member of a Dictionary it is still considered to be the same function.
760To compare partials to see if they bind the same argument and Dictionary
761values use string(): >
762 echo string(Partial1) == string(Partial2)
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000763
Bram Moolenaar251e1912011-06-19 05:09:16 +0200764When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the
765expressions are referring to the same |List| or |Dictionary| instance. A copy
766of a |List| is different from the original |List|. When using "is" without
767a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot"
768equivalent to using "not equal". Except that a different type means the
Bram Moolenaar86edef62016-03-13 18:07:30 +0100769values are different: >
770 echo 4 == '4'
771 1
772 echo 4 is '4'
773 0
774 echo 0 is []
775 0
776"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000777
Bram Moolenaar071d4272004-06-13 20:20:40 +0000778When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar86edef62016-03-13 18:07:30 +0100779and the comparison is done on Numbers. This means that: >
780 echo 0 == 'x'
781 1
782because 'x' converted to a Number is zero. However: >
783 echo [0] == ['x']
784 0
785Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000786
787When comparing two Strings, this is done with strcmp() or stricmp(). This
788results in the mathematical difference (comparing byte values), not
789necessarily the alphabetical difference in the local language.
790
Bram Moolenaar446cb832008-06-24 21:56:24 +0000791When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000792'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000793
794When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000795'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
796
797'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000798
799The "=~" and "!~" operators match the lefthand argument with the righthand
800argument, which is used as a pattern. See |pattern| for what a pattern is.
801This matching is always done like 'magic' was set and 'cpoptions' is empty, no
802matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
803portable. To avoid backslashes in the regexp pattern to be doubled, use a
804single-quote string, see |literal-string|.
805Since a string is considered to be a single line, a multi-line pattern
806(containing \n, backslash-n) will not match. However, a literal NL character
807can be matched like an ordinary character. Examples:
808 "foo\nbar" =~ "\n" evaluates to 1
809 "foo\nbar" =~ "\\n" evaluates to 0
810
811
812expr5 and expr6 *expr5* *expr6*
813---------------
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000814expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000815expr6 - expr6 .. Number subtraction *expr--*
816expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000817
Bram Moolenaara23ccb82006-02-27 00:08:02 +0000818For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000819result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000820
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100821expr7 * expr7 .. Number multiplication *expr-star*
822expr7 / expr7 .. Number division *expr-/*
823expr7 % expr7 .. Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824
825For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +0100826For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000827
828Note the difference between "+" and ".":
829 "123" + "456" = 579
830 "123" . "456" = "123456"
831
Bram Moolenaar446cb832008-06-24 21:56:24 +0000832Since '.' has the same precedence as '+' and '-', you need to read: >
833 1 . 90 + 90.0
834As: >
835 (1 . 90) + 90.0
836That works, since the String "190" is automatically converted to the Number
837190, which can be added to the Float 90.0. However: >
838 1 . 90 * 90.0
839Should be read as: >
840 1 . (90 * 90.0)
841Since '.' has lower precedence than '*'. This does NOT work, since this
842attempts to concatenate a Float and a String.
843
844When dividing a Number by zero the result depends on the value:
845 0 / 0 = -0x80000000 (like NaN for Float)
846 >0 / 0 = 0x7fffffff (like positive infinity)
847 <0 / 0 = -0x7fffffff (like negative infinity)
848 (before Vim 7.2 it was always 0x7fffffff)
849
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850When the righthand side of '%' is zero, the result is 0.
851
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000852None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000853
Bram Moolenaar446cb832008-06-24 21:56:24 +0000854. and % do not work for Float. *E804*
855
Bram Moolenaar071d4272004-06-13 20:20:40 +0000856
857expr7 *expr7*
858-----
859! expr7 logical NOT *expr-!*
860- expr7 unary minus *expr-unary--*
861+ expr7 unary plus *expr-unary-+*
862
863For '!' non-zero becomes zero, zero becomes one.
864For '-' the sign of the number is changed.
865For '+' the number is unchanged.
866
867A String will be converted to a Number first.
868
Bram Moolenaar446cb832008-06-24 21:56:24 +0000869These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000870 !-1 == 0
871 !!8 == 1
872 --9 == 9
873
874
875expr8 *expr8*
876-----
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000877expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +0200878 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000879If expr8 is a Number or String this results in a String that contains the
880expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100881Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
Bram Moolenaar03413f42016-04-12 21:07:15 +0200882an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000883
Bram Moolenaar256972a2015-12-29 19:10:25 +0100884Index zero gives the first byte. This is like it works in C. Careful:
885text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000886cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000887 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000888
889If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +0100890String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000891compatibility). Use [-1:] to get the last byte.
892
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000893If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000894for possible index values. If the index is out of range this results in an
Bram Moolenaar446cb832008-06-24 21:56:24 +0000895error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000896 :let item = mylist[-1] " get last item
897
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000898Generally, if a |List| index is equal to or higher than the length of the
899|List|, or more negative than the length of the |List|, this results in an
900error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000901
Bram Moolenaard8b02732005-01-14 21:48:43 +0000902
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000903expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000904
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000905If expr8 is a Number or String this results in the substring with the bytes
906from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100907expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
908|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000909
910If expr1a is omitted zero is used. If expr1b is omitted the length of the
911string minus one is used.
912
913A negative number can be used to measure from the end of the string. -1 is
914the last character, -2 the last but one, etc.
915
916If an index goes out of range for the string characters are omitted. If
917expr1b is smaller than expr1a the result is an empty string.
918
919Examples: >
920 :let c = name[-1:] " last byte of a string
921 :let c = name[-2:-2] " last but one byte of a string
922 :let s = line(".")[4:] " from the fifth byte to the end
923 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100924<
925 *sublist* *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000926If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar446cb832008-06-24 21:56:24 +0000927the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000928just above, except that indexes out of range cause an error. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000929 :let l = mylist[:3] " first four items
930 :let l = mylist[4:4] " List with one item
931 :let l = mylist[:] " shallow copy of a List
932
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000933Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
934error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000935
Bram Moolenaarda440d22016-01-16 21:27:23 +0100936Watch out for confusion between a namespace and a variable followed by a colon
937for a sublist: >
938 mylist[n:] " uses variable n
939 mylist[s:] " uses namespace s:, error!
940
Bram Moolenaard8b02732005-01-14 21:48:43 +0000941
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000942expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000943
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000944If expr8 is a |Dictionary| and it is followed by a dot, then the following
945name will be used as a key in the |Dictionary|. This is just like:
946expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000947
948The name must consist of alphanumeric characters, just like a variable name,
949but it may start with a number. Curly braces cannot be used.
950
951There must not be white space before or after the dot.
952
953Examples: >
954 :let dict = {"one": 1, 2: "two"}
955 :echo dict.one
956 :echo dict .2
957
958Note that the dot is also used for String concatenation. To avoid confusion
959always put spaces around the dot for String concatenation.
960
961
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000962expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000963
964When expr8 is a |Funcref| type variable, invoke the function it refers to.
965
966
967
968 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000969number
970------
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100971number number constant *expr-number*
972 *hex-number* *octal-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000973
974Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
975
Bram Moolenaar446cb832008-06-24 21:56:24 +0000976 *floating-point-format*
977Floating point numbers can be written in two forms:
978
979 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +0100980 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +0000981
982{N} and {M} are numbers. Both {N} and {M} must be present and can only
983contain digits.
984[-+] means there is an optional plus or minus sign.
985{exp} is the exponent, power of 10.
986Only a decimal point is accepted, not a comma. No matter what the current
987locale is.
988{only when compiled with the |+float| feature}
989
990Examples:
991 123.456
992 +0.0001
993 55.0
994 -0.123
995 1.234e03
996 1.0E-6
997 -3.1416e+88
998
999These are INVALID:
1000 3. empty {M}
1001 1e40 missing .{M}
1002
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001003 *float-pi* *float-e*
1004A few useful values to copy&paste: >
1005 :let pi = 3.14159265359
1006 :let e = 2.71828182846
1007
Bram Moolenaar446cb832008-06-24 21:56:24 +00001008Rationale:
1009Before floating point was introduced, the text "123.456" was interpreted as
1010the two numbers "123" and "456", both converted to a string and concatenated,
1011resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001012could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001013incompatibility was accepted in favor of being able to use the normal notation
1014for floating point numbers.
1015
1016 *floating-point-precision*
1017The precision and range of floating points numbers depends on what "double"
1018means in the library Vim was compiled with. There is no way to change this at
1019runtime.
1020
1021The default for displaying a |Float| is to use 6 decimal places, like using
1022printf("%g", f). You can select something else when using the |printf()|
1023function. Example: >
1024 :echo printf('%.15e', atan(1))
1025< 7.853981633974483e-01
1026
1027
Bram Moolenaar071d4272004-06-13 20:20:40 +00001028
Bram Moolenaar979243b2015-06-26 19:35:49 +02001029string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001030------
1031"string" string constant *expr-quote*
1032
1033Note that double quotes are used.
1034
1035A string constant accepts these special characters:
1036\... three-digit octal number (e.g., "\316")
1037\.. two-digit octal number (must be followed by non-digit)
1038\. one-digit octal number (must be followed by non-digit)
1039\x.. byte specified with two hex numbers (e.g., "\x1f")
1040\x. byte specified with one hex number (must be followed by non-hex char)
1041\X.. same as \x..
1042\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001043\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001044 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001045\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001046\b backspace <BS>
1047\e escape <Esc>
1048\f formfeed <FF>
1049\n newline <NL>
1050\r return <CR>
1051\t tab <Tab>
1052\\ backslash
1053\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001054\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
1055 in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a
1056 utf-8 character, use \uxxxx as mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001057
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001058Note that "\xff" is stored as the byte 255, which may be invalid in some
1059encodings. Use "\u00ff" to store character 255 according to the current value
1060of 'encoding'.
1061
Bram Moolenaar071d4272004-06-13 20:20:40 +00001062Note that "\000" and "\x00" force the end of the string.
1063
1064
1065literal-string *literal-string* *E115*
1066---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001067'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001068
1069Note that single quotes are used.
1070
Bram Moolenaar446cb832008-06-24 21:56:24 +00001071This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001072meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001073
1074Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar446cb832008-06-24 21:56:24 +00001075to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001076 if a =~ "\\s*"
1077 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001078
1079
1080option *expr-option* *E112* *E113*
1081------
1082&option option value, local value if possible
1083&g:option global option value
1084&l:option local option value
1085
1086Examples: >
1087 echo "tabstop is " . &tabstop
1088 if &insertmode
1089
1090Any option name can be used here. See |options|. When using the local value
1091and there is no buffer-local or window-local value, the global value is used
1092anyway.
1093
1094
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001095register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001096--------
1097@r contents of register 'r'
1098
1099The result is the contents of the named register, as a single string.
1100Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar446cb832008-06-24 21:56:24 +00001101register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001102registers.
1103
1104When using the '=' register you get the expression itself, not what it
1105evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001106
1107
1108nesting *expr-nesting* *E110*
1109-------
1110(expr1) nested expression
1111
1112
1113environment variable *expr-env*
1114--------------------
1115$VAR environment variable
1116
1117The String value of any environment variable. When it is not defined, the
1118result is an empty string.
1119 *expr-env-expand*
1120Note that there is a difference between using $VAR directly and using
1121expand("$VAR"). Using it directly will only expand environment variables that
1122are known inside the current Vim session. Using expand() will first try using
1123the environment variables known inside the current Vim session. If that
1124fails, a shell will be used to expand the variable. This can be slow, but it
1125does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001126 :echo $shell
1127 :echo expand("$shell")
1128The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001129variable (if your shell supports it).
1130
1131
1132internal variable *expr-variable*
1133-----------------
1134variable internal variable
1135See below |internal-variables|.
1136
1137
Bram Moolenaar05159a02005-02-26 23:04:13 +00001138function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001139-------------
1140function(expr1, ...) function call
1141See below |functions|.
1142
1143
1144==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020011453. Internal variable *internal-variables* *E461*
1146
Bram Moolenaar071d4272004-06-13 20:20:40 +00001147An internal variable name can be made up of letters, digits and '_'. But it
1148cannot start with a digit. It's also possible to use curly braces, see
1149|curly-braces-names|.
1150
1151An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001152An internal variable is explicitly destroyed with the ":unlet" command
1153|:unlet|.
1154Using a name that is not an internal variable or refers to a variable that has
1155been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001156
1157There are several name spaces for variables. Which one is to be used is
1158specified by what is prepended:
1159
1160 (nothing) In a function: local to a function; otherwise: global
1161|buffer-variable| b: Local to the current buffer.
1162|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001163|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001164|global-variable| g: Global.
1165|local-variable| l: Local to a function.
1166|script-variable| s: Local to a |:source|'ed Vim script.
1167|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001168|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001170The scope name by itself can be used as a |Dictionary|. For example, to
1171delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001172 :for k in keys(s:)
1173 : unlet s:[k]
1174 :endfor
1175<
Bram Moolenaar531da592013-05-06 05:58:55 +02001176 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001177A variable name that is preceded with "b:" is local to the current buffer.
1178Thus you can have several "b:foo" variables, one for each buffer.
1179This kind of variable is deleted when the buffer is wiped out or deleted with
1180|:bdelete|.
1181
1182One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001183 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001184b:changedtick The total number of changes to the current buffer. It is
1185 incremented for each change. An undo command is also a change
1186 in this case. This can be used to perform an action only when
1187 the buffer has changed. Example: >
1188 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001189 : let my_changedtick = b:changedtick
1190 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001191 :endif
1192<
Bram Moolenaar531da592013-05-06 05:58:55 +02001193 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001194A variable name that is preceded with "w:" is local to the current window. It
1195is deleted when the window is closed.
1196
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001197 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001198A variable name that is preceded with "t:" is local to the current tab page,
1199It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001200without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001201
Bram Moolenaar531da592013-05-06 05:58:55 +02001202 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001203Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar446cb832008-06-24 21:56:24 +00001204access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001205place if you like.
1206
Bram Moolenaar531da592013-05-06 05:58:55 +02001207 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001208Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001209But you can also prepend "l:" if you like. However, without prepending "l:"
1210you may run into reserved variable names. For example "count". By itself it
1211refers to "v:count". Using "l:count" you can have a local variable with the
1212same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001213
1214 *script-variable* *s:var*
1215In a Vim script variables starting with "s:" can be used. They cannot be
1216accessed from outside of the scripts, thus are local to the script.
1217
1218They can be used in:
1219- commands executed while the script is sourced
1220- functions defined in the script
1221- autocommands defined in the script
1222- functions and autocommands defined in functions and autocommands which were
1223 defined in the script (recursively)
1224- user defined commands defined in the script
1225Thus not in:
1226- other scripts sourced from this one
1227- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001228- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001229- etc.
1230
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001231Script variables can be used to avoid conflicts with global variable names.
1232Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001233
1234 let s:counter = 0
1235 function MyCounter()
1236 let s:counter = s:counter + 1
1237 echo s:counter
1238 endfunction
1239 command Tick call MyCounter()
1240
1241You can now invoke "Tick" from any script, and the "s:counter" variable in
1242that script will not be changed, only the "s:counter" in the script where
1243"Tick" was defined is used.
1244
1245Another example that does the same: >
1246
1247 let s:counter = 0
1248 command Tick let s:counter = s:counter + 1 | echo s:counter
1249
1250When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001251script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001252defined.
1253
1254The script variables are also available when a function is defined inside a
1255function that is defined in a script. Example: >
1256
1257 let s:counter = 0
1258 function StartCounting(incr)
1259 if a:incr
1260 function MyCounter()
1261 let s:counter = s:counter + 1
1262 endfunction
1263 else
1264 function MyCounter()
1265 let s:counter = s:counter - 1
1266 endfunction
1267 endif
1268 endfunction
1269
1270This defines the MyCounter() function either for counting up or counting down
1271when calling StartCounting(). It doesn't matter from where StartCounting() is
1272called, the s:counter variable will be accessible in MyCounter().
1273
1274When the same script is sourced again it will use the same script variables.
1275They will remain valid as long as Vim is running. This can be used to
1276maintain a counter: >
1277
1278 if !exists("s:counter")
1279 let s:counter = 1
1280 echo "script executed for the first time"
1281 else
1282 let s:counter = s:counter + 1
1283 echo "script executed " . s:counter . " times now"
1284 endif
1285
1286Note that this means that filetype plugins don't get a different set of script
1287variables for each buffer. Use local buffer variables instead |b:var|.
1288
1289
Bram Moolenaar531da592013-05-06 05:58:55 +02001290Predefined Vim variables: *vim-variable* *v:var* *v:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001291
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001292 *v:beval_col* *beval_col-variable*
1293v:beval_col The number of the column, over which the mouse pointer is.
1294 This is the byte index in the |v:beval_lnum| line.
1295 Only valid while evaluating the 'balloonexpr' option.
1296
1297 *v:beval_bufnr* *beval_bufnr-variable*
1298v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1299 valid while evaluating the 'balloonexpr' option.
1300
1301 *v:beval_lnum* *beval_lnum-variable*
1302v:beval_lnum The number of the line, over which the mouse pointer is. Only
1303 valid while evaluating the 'balloonexpr' option.
1304
1305 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001306v:beval_text The text under or after the mouse pointer. Usually a word as
1307 it is useful for debugging a C program. 'iskeyword' applies,
1308 but a dot and "->" before the position is included. When on a
1309 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001310 word before it. When on a Visual area within one line the
1311 highlighted text is used.
1312 Only valid while evaluating the 'balloonexpr' option.
1313
1314 *v:beval_winnr* *beval_winnr-variable*
1315v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001316 valid while evaluating the 'balloonexpr' option. The first
1317 window has number zero (unlike most other places where a
1318 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001319
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001320 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001321v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001322 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001323 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001324
Bram Moolenaar071d4272004-06-13 20:20:40 +00001325 *v:charconvert_from* *charconvert_from-variable*
1326v:charconvert_from
1327 The name of the character encoding of a file to be converted.
1328 Only valid while evaluating the 'charconvert' option.
1329
1330 *v:charconvert_to* *charconvert_to-variable*
1331v:charconvert_to
1332 The name of the character encoding of a file after conversion.
1333 Only valid while evaluating the 'charconvert' option.
1334
1335 *v:cmdarg* *cmdarg-variable*
1336v:cmdarg This variable is used for two purposes:
1337 1. The extra arguments given to a file read/write command.
1338 Currently these are "++enc=" and "++ff=". This variable is
1339 set before an autocommand event for a file read/write
1340 command is triggered. There is a leading space to make it
1341 possible to append this variable directly after the
Bram Moolenaar446cb832008-06-24 21:56:24 +00001342 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001343 included here, because it will be executed anyway.
1344 2. When printing a PostScript file with ":hardcopy" this is
1345 the argument for the ":hardcopy" command. This can be used
1346 in 'printexpr'.
1347
1348 *v:cmdbang* *cmdbang-variable*
1349v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1350 was used the value is 1, otherwise it is 0. Note that this
1351 can only be used in autocommands. For user commands |<bang>|
1352 can be used.
1353
Bram Moolenaar42a45122015-07-10 17:56:23 +02001354 *v:completed_item* *completed_item-variable*
1355v:completed_item
1356 |Dictionary| containing the |complete-items| for the most
1357 recently completed word after |CompleteDone|. The
1358 |Dictionary| is empty if the completion failed.
1359
Bram Moolenaar071d4272004-06-13 20:20:40 +00001360 *v:count* *count-variable*
1361v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar446cb832008-06-24 21:56:24 +00001362 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001363 :map _x :<C-U>echo "the count is " . v:count<CR>
1364< Note: The <C-U> is required to remove the line range that you
1365 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001366 When there are two counts, as in "3d2w", they are multiplied,
1367 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001368 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001369 "count" also works, for backwards compatibility.
1370
1371 *v:count1* *count1-variable*
1372v:count1 Just like "v:count", but defaults to one when no count is
1373 used.
1374
1375 *v:ctype* *ctype-variable*
1376v:ctype The current locale setting for characters of the runtime
1377 environment. This allows Vim scripts to be aware of the
1378 current locale encoding. Technical: it's the value of
1379 LC_CTYPE. When not using a locale the value is "C".
1380 This variable can not be set directly, use the |:language|
1381 command.
1382 See |multi-lang|.
1383
1384 *v:dying* *dying-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001385v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001386 one. When multiple signals are caught the number increases.
1387 Can be used in an autocommand to check if Vim didn't
1388 terminate normally. {only works on Unix}
1389 Example: >
1390 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001391< Note: if another deadly signal is caught when v:dying is one,
1392 VimLeave autocommands will not be executed.
1393
Bram Moolenaar071d4272004-06-13 20:20:40 +00001394 *v:errmsg* *errmsg-variable*
1395v:errmsg Last given error message. It's allowed to set this variable.
1396 Example: >
1397 :let v:errmsg = ""
1398 :silent! next
1399 :if v:errmsg != ""
1400 : ... handle error
1401< "errmsg" also works, for backwards compatibility.
1402
Bram Moolenaar43345542015-11-29 17:35:35 +01001403 *v:errors* *errors-variable*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001404v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001405 This is a list of strings.
1406 The assert functions append an item when an assert fails.
1407 To remove old results make it empty: >
1408 :let v:errors = []
1409< If v:errors is set to anything but a list it is made an empty
1410 list by the assert function.
1411
Bram Moolenaar071d4272004-06-13 20:20:40 +00001412 *v:exception* *exception-variable*
1413v:exception The value of the exception most recently caught and not
1414 finished. See also |v:throwpoint| and |throw-variables|.
1415 Example: >
1416 :try
1417 : throw "oops"
1418 :catch /.*/
1419 : echo "caught" v:exception
1420 :endtry
1421< Output: "caught oops".
1422
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001423 *v:false* *false-variable*
1424v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001425 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001426 When used as a string this evaluates to "false". >
1427 echo v:false
1428< false ~
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001429
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001430 *v:fcs_reason* *fcs_reason-variable*
1431v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1432 Can be used in an autocommand to decide what to do and/or what
1433 to set v:fcs_choice to. Possible values:
1434 deleted file no longer exists
1435 conflict file contents, mode or timestamp was
1436 changed and buffer is modified
1437 changed file contents has changed
1438 mode mode of file changed
1439 time only file timestamp changed
1440
1441 *v:fcs_choice* *fcs_choice-variable*
1442v:fcs_choice What should happen after a |FileChangedShell| event was
1443 triggered. Can be used in an autocommand to tell Vim what to
1444 do with the affected buffer:
1445 reload Reload the buffer (does not work if
1446 the file was deleted).
1447 ask Ask the user what to do, as if there
1448 was no autocommand. Except that when
1449 only the timestamp changed nothing
1450 will happen.
1451 <empty> Nothing, the autocommand should do
1452 everything that needs to be done.
1453 The default is empty. If another (invalid) value is used then
1454 Vim behaves like it is empty, there is no warning message.
1455
Bram Moolenaar071d4272004-06-13 20:20:40 +00001456 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001457v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001458 option used for ~
1459 'charconvert' file to be converted
1460 'diffexpr' original file
1461 'patchexpr' original file
1462 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001463 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001464
1465 *v:fname_out* *fname_out-variable*
1466v:fname_out The name of the output file. Only valid while
1467 evaluating:
1468 option used for ~
1469 'charconvert' resulting converted file (*)
1470 'diffexpr' output of diff
1471 'patchexpr' resulting patched file
1472 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar446cb832008-06-24 21:56:24 +00001473 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001474 for a read command (e.g., ":e file") it will be a temporary
1475 file and different from v:fname_in.
1476
1477 *v:fname_new* *fname_new-variable*
1478v:fname_new The name of the new version of the file. Only valid while
1479 evaluating 'diffexpr'.
1480
1481 *v:fname_diff* *fname_diff-variable*
1482v:fname_diff The name of the diff (patch) file. Only valid while
1483 evaluating 'patchexpr'.
1484
1485 *v:folddashes* *folddashes-variable*
1486v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1487 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001488 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001489
1490 *v:foldlevel* *foldlevel-variable*
1491v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001492 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001493
1494 *v:foldend* *foldend-variable*
1495v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001496 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001497
1498 *v:foldstart* *foldstart-variable*
1499v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001500 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001501
Bram Moolenaar817a8802013-11-09 01:44:43 +01001502 *v:hlsearch* *hlsearch-variable*
Bram Moolenaar76440e22014-11-27 19:14:49 +01001503v:hlsearch Variable that indicates whether search highlighting is on.
1504 Setting it makes sense only if 'hlsearch' is enabled which
1505 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001506 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001507 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001508< Note that the value is restored when returning from a
1509 function. |function-search-undo|.
1510
Bram Moolenaar843ee412004-06-30 16:16:41 +00001511 *v:insertmode* *insertmode-variable*
1512v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1513 events. Values:
1514 i Insert mode
1515 r Replace mode
1516 v Virtual Replace mode
1517
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001518 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001519v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001520 evaluating the expression used with |map()| and |filter()|.
1521 Read-only.
1522
Bram Moolenaar071d4272004-06-13 20:20:40 +00001523 *v:lang* *lang-variable*
1524v:lang The current locale setting for messages of the runtime
1525 environment. This allows Vim scripts to be aware of the
1526 current language. Technical: it's the value of LC_MESSAGES.
1527 The value is system dependent.
1528 This variable can not be set directly, use the |:language|
1529 command.
1530 It can be different from |v:ctype| when messages are desired
1531 in a different language than what is used for character
1532 encoding. See |multi-lang|.
1533
1534 *v:lc_time* *lc_time-variable*
1535v:lc_time The current locale setting for time messages of the runtime
1536 environment. This allows Vim scripts to be aware of the
1537 current language. Technical: it's the value of LC_TIME.
1538 This variable can not be set directly, use the |:language|
1539 command. See |multi-lang|.
1540
1541 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001542v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1543 'indentexpr' expressions, tab page number for 'guitablabel'
1544 and 'guitabtooltip'. Only valid while one of these
1545 expressions is being evaluated. Read-only when in the
1546 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001547
Bram Moolenaar219b8702006-11-01 14:32:36 +00001548 *v:mouse_win* *mouse_win-variable*
1549v:mouse_win Window number for a mouse click obtained with |getchar()|.
1550 First window has number 1, like with |winnr()|. The value is
1551 zero when there was no mouse button click.
1552
1553 *v:mouse_lnum* *mouse_lnum-variable*
1554v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1555 This is the text line number, not the screen line number. The
1556 value is zero when there was no mouse button click.
1557
1558 *v:mouse_col* *mouse_col-variable*
1559v:mouse_col Column number for a mouse click obtained with |getchar()|.
1560 This is the screen column number, like with |virtcol()|. The
1561 value is zero when there was no mouse button click.
1562
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001563 *v:none* *none-variable*
1564v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001565 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001566 When used as a number this evaluates to zero.
1567 When used as a string this evaluates to "none". >
1568 echo v:none
1569< none ~
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001570
1571 *v:null* *null-variable*
1572v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001573 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001574 When used as a number this evaluates to zero.
1575 When used as a string this evaluates to "null". >
1576 echo v:null
1577< null ~
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001578
Bram Moolenaard812df62008-11-09 12:46:09 +00001579 *v:oldfiles* *oldfiles-variable*
1580v:oldfiles List of file names that is loaded from the |viminfo| file on
1581 startup. These are the files that Vim remembers marks for.
1582 The length of the List is limited by the ' argument of the
1583 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001584 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001585 Also see |:oldfiles| and |c_#<|.
1586 The List can be modified, but this has no effect on what is
1587 stored in the |viminfo| file later. If you use values other
1588 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001589 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001590
Bram Moolenaar53744302015-07-17 17:38:22 +02001591 *v:option_new*
1592v:option_new New value of the option. Valid while executing an |OptionSet|
1593 autocommand.
1594 *v:option_old*
1595v:option_old Old value of the option. Valid while executing an |OptionSet|
1596 autocommand.
1597 *v:option_type*
1598v:option_type Scope of the set command. Valid while executing an
1599 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001600 *v:operator* *operator-variable*
1601v:operator The last operator given in Normal mode. This is a single
1602 character except for commands starting with <g> or <z>,
1603 in which case it is two characters. Best used alongside
1604 |v:prevcount| and |v:register|. Useful if you want to cancel
1605 Operator-pending mode and then use the operator, e.g.: >
1606 :omap O <Esc>:call MyMotion(v:operator)<CR>
1607< The value remains set until another operator is entered, thus
1608 don't expect it to be empty.
1609 v:operator is not set for |:delete|, |:yank| or other Ex
1610 commands.
1611 Read-only.
1612
Bram Moolenaar071d4272004-06-13 20:20:40 +00001613 *v:prevcount* *prevcount-variable*
1614v:prevcount The count given for the last but one Normal mode command.
1615 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001616 you want to cancel Visual or Operator-pending mode and then
1617 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001618 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1619< Read-only.
1620
Bram Moolenaar05159a02005-02-26 23:04:13 +00001621 *v:profiling* *profiling-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001622v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001623 See |profiling|.
1624
Bram Moolenaar071d4272004-06-13 20:20:40 +00001625 *v:progname* *progname-variable*
1626v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001627 invoked. Allows you to do special initialisations for |view|,
1628 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001629 Read-only.
1630
Bram Moolenaara1706c92014-04-01 19:55:49 +02001631 *v:progpath* *progpath-variable*
1632v:progpath Contains the command with which Vim was invoked, including the
1633 path. Useful if you want to message a Vim server using a
1634 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001635 To get the full path use: >
1636 echo exepath(v:progpath)
1637< NOTE: This does not work when the command is a relative path
1638 and the current directory has changed.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001639 Read-only.
1640
Bram Moolenaar071d4272004-06-13 20:20:40 +00001641 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001642v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001643 command (regardless of whether that command actually used a
1644 register). Or for the currently executing normal mode mapping
1645 (use this in custom commands that take a register).
1646 If none is supplied it is the default register '"', unless
1647 'clipboard' contains "unnamed" or "unnamedplus", then it is
1648 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001649 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001650
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001651 *v:scrollstart* *scrollstart-variable*
1652v:scrollstart String describing the script or function that caused the
1653 screen to scroll up. It's only set when it is empty, thus the
1654 first reason is remembered. It is set to "Unknown" for a
1655 typed command.
1656 This can be used to find out why your script causes the
1657 hit-enter prompt.
1658
Bram Moolenaar071d4272004-06-13 20:20:40 +00001659 *v:servername* *servername-variable*
1660v:servername The resulting registered |x11-clientserver| name if any.
1661 Read-only.
1662
Bram Moolenaar446cb832008-06-24 21:56:24 +00001663
1664v:searchforward *v:searchforward* *searchforward-variable*
1665 Search direction: 1 after a forward search, 0 after a
1666 backward search. It is reset to forward when directly setting
1667 the last search pattern, see |quote/|.
1668 Note that the value is restored when returning from a
1669 function. |function-search-undo|.
1670 Read-write.
1671
Bram Moolenaar071d4272004-06-13 20:20:40 +00001672 *v:shell_error* *shell_error-variable*
1673v:shell_error Result of the last shell command. When non-zero, the last
1674 shell command had an error. When zero, there was no problem.
1675 This only works when the shell returns the error code to Vim.
1676 The value -1 is often used when the command could not be
1677 executed. Read-only.
1678 Example: >
1679 :!mv foo bar
1680 :if v:shell_error
1681 : echo 'could not rename "foo" to "bar"!'
1682 :endif
1683< "shell_error" also works, for backwards compatibility.
1684
1685 *v:statusmsg* *statusmsg-variable*
1686v:statusmsg Last given status message. It's allowed to set this variable.
1687
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001688 *v:swapname* *swapname-variable*
1689v:swapname Only valid when executing |SwapExists| autocommands: Name of
1690 the swap file found. Read-only.
1691
1692 *v:swapchoice* *swapchoice-variable*
1693v:swapchoice |SwapExists| autocommands can set this to the selected choice
1694 for handling an existing swap file:
1695 'o' Open read-only
1696 'e' Edit anyway
1697 'r' Recover
1698 'd' Delete swapfile
1699 'q' Quit
1700 'a' Abort
Bram Moolenaar446cb832008-06-24 21:56:24 +00001701 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001702 results in the user being asked, as would happen when there is
1703 no SwapExists autocommand. The default is empty.
1704
Bram Moolenaarb3480382005-12-11 21:33:32 +00001705 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00001706v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00001707 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar446cb832008-06-24 21:56:24 +00001708 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00001709 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001710 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00001711
Bram Moolenaar071d4272004-06-13 20:20:40 +00001712 *v:termresponse* *termresponse-variable*
1713v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar446cb832008-06-24 21:56:24 +00001714 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00001715 that starts with ESC [ or CSI and ends in a 'c', with only
1716 digits, ';' and '.' in between.
1717 When this option is set, the TermResponse autocommand event is
1718 fired, so that you can react to the response from the
1719 terminal.
1720 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1721 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1722 patch level (since this was introduced in patch 95, it's
1723 always 95 or bigger). Pc is always zero.
1724 {only when compiled with |+termresponse| feature}
1725
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02001726 *v:testing* *testing-variable*
1727v:testing Must be set before using `garbagecollect_for_testing()`.
1728
Bram Moolenaar071d4272004-06-13 20:20:40 +00001729 *v:this_session* *this_session-variable*
1730v:this_session Full filename of the last loaded or saved session file. See
1731 |:mksession|. It is allowed to set this variable. When no
1732 session file has been saved, this variable is empty.
1733 "this_session" also works, for backwards compatibility.
1734
1735 *v:throwpoint* *throwpoint-variable*
1736v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001737 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001738 also |v:exception| and |throw-variables|.
1739 Example: >
1740 :try
1741 : throw "oops"
1742 :catch /.*/
1743 : echo "Exception from" v:throwpoint
1744 :endtry
1745< Output: "Exception from test.vim, line 2"
1746
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001747 *v:true* *true-variable*
1748v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001749 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001750 When used as a string this evaluates to "true". >
1751 echo v:true
1752< true ~
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001753 *v:val* *val-variable*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001754v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001755 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001756 |filter()|. Read-only.
1757
Bram Moolenaar071d4272004-06-13 20:20:40 +00001758 *v:version* *version-variable*
1759v:version Version number of Vim: Major version number times 100 plus
1760 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1761 is 501. Read-only. "version" also works, for backwards
1762 compatibility.
1763 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02001764 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001765< Note that patch numbers are specific to the version, thus both
1766 version 5.0 and 5.1 may have a patch 123, but these are
1767 completely different.
1768
Bram Moolenaar14735512016-03-26 21:00:08 +01001769 *v:vim_did_enter* *vim_did_enter-variable*
1770v:vim_did_enter Zero until most of startup is done. It is set to one just
1771 before |VimEnter| autocommands are triggered.
1772
Bram Moolenaar071d4272004-06-13 20:20:40 +00001773 *v:warningmsg* *warningmsg-variable*
1774v:warningmsg Last given warning message. It's allowed to set this variable.
1775
Bram Moolenaar727c8762010-10-20 19:17:48 +02001776 *v:windowid* *windowid-variable*
1777v:windowid When any X11 based GUI is running or when running in a
1778 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02001779 set to the window ID.
1780 When an MS-Windows GUI is running this will be set to the
1781 window handle.
1782 Otherwise the value is zero.
1783 Note: for windows inside Vim use |winnr()|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02001784
Bram Moolenaar071d4272004-06-13 20:20:40 +00001785==============================================================================
17864. Builtin Functions *functions*
1787
1788See |function-list| for a list grouped by what the function is used for.
1789
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001790(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001791
1792USAGE RESULT DESCRIPTION ~
1793
Bram Moolenaar81edd172016-04-14 13:51:37 +02001794abs({expr}) Float or Number absolute value of {expr}
1795acos({expr}) Float arc cosine of {expr}
1796add({list}, {item}) List append {item} to |List| {list}
1797alloc_fail({id}, {countdown}, {repeat})
Bram Moolenaaracb4f222016-01-10 15:59:26 +01001798 none make memory allocation fail
Bram Moolenaar81edd172016-04-14 13:51:37 +02001799and({expr}, {expr}) Number bitwise AND
1800append({lnum}, {string}) Number append {string} below line {lnum}
1801append({lnum}, {list}) Number append lines {list} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001802argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001803argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02001804arglistid([{winnr} [, {tabnr}]]) Number argument list id
1805argv({nr}) String {nr} entry of the argument list
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001806argv() List the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02001807assert_equal({exp}, {act} [, {msg}]) none assert {exp} is equal to {act}
1808assert_exception({error} [, {msg}]) none assert {error} is in v:exception
1809assert_fails({cmd} [, {error}]) none assert {cmd} fails
1810assert_false({actual} [, {msg}]) none assert {actual} is false
1811assert_match({pat}, {text} [, {msg}]) none assert {pat} matches {text}
1812assert_notequal({exp}, {act} [, {msg}]) none assert {exp} is not equal {act}
1813assert_notmatch({pat}, {text} [, {msg}]) none assert {pat} not matches {text}
1814assert_true({actual} [, {msg}]) none assert {actual} is true
1815asin({expr}) Float arc sine of {expr}
1816atan({expr}) Float arc tangent of {expr}
1817atan2({expr}, {expr}) Float arc tangent of {expr1} / {expr2}
1818browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00001819 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02001820browsedir({title}, {initdir}) String put up a directory requester
1821bufexists({expr}) Number TRUE if buffer {expr} exists
1822buflisted({expr}) Number TRUE if buffer {expr} is listed
1823bufloaded({expr}) Number TRUE if buffer {expr} is loaded
1824bufname({expr}) String Name of the buffer {expr}
1825bufnr({expr} [, {create}]) Number Number of the buffer {expr}
1826bufwinnr({expr}) Number window number of buffer {expr}
1827byte2line({byte}) Number line number at byte count {byte}
1828byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
1829byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
1830call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001831 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001832ceil({expr}) Float round {expr} up
1833ch_close({handle}) none close {handle}
1834ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001835 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001836ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001837 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001838ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
1839ch_getjob({channel}) Job get the Job of {channel}
1840ch_info({handle}) String info about channel {handle}
1841ch_log({msg} [, {handle}]) none write {msg} in the channel log file
1842ch_logfile({fname} [, {mode}]) none start logging channel activity
1843ch_open({address} [, {options}])
1844 Channel open a channel to {address}
1845ch_read({handle} [, {options}]) String read from {handle}
1846ch_readraw({handle} [, {options}])
1847 String read raw from {handle}
1848ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001849 any send {expr} over JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001850ch_sendraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001851 any send {string} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001852ch_setoptions({handle}, {options})
1853 none set options for {handle}
1854ch_status({handle}) String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001855changenr() Number current change number
Bram Moolenaar81edd172016-04-14 13:51:37 +02001856char2nr({expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
1857cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001858clearmatches() none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02001859col({expr}) Number column nr of cursor or mark
1860complete({startcol}, {matches}) none set Insert mode completion
1861complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00001862complete_check() Number check for key typed during completion
Bram Moolenaar81edd172016-04-14 13:51:37 +02001863confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001864 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02001865copy({expr}) any make a shallow copy of {expr}
1866cos({expr}) Float cosine of {expr}
1867cosh({expr}) Float hyperbolic cosine of {expr}
1868count({list}, {expr} [, {ic} [, {start}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001869 Number count how many {expr} are in {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001870cscope_connection([{num} , {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001871 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02001872cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01001873 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001874cursor({list}) Number move cursor to position in {list}
1875deepcopy({expr} [, {noref}]) any make a full copy of {expr}
1876delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001877did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02001878diff_filler({lnum}) Number diff filler lines about {lnum}
1879diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
1880disable_char_avail_for_testing({expr})
1881 none test without typeahead
1882empty({expr}) Number TRUE if {expr} is empty
1883escape({string}, {chars}) String escape {chars} in {string} with '\'
1884eval({string}) any evaluate {string} into its value
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001885eventhandler() Number TRUE if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02001886executable({expr}) Number 1 if executable {expr} exists
1887exepath({expr}) String full path of the command {expr}
1888exists({expr}) Number TRUE if {expr} exists
1889extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001890 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001891exp({expr}) Float exponential of {expr}
1892expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001893 any expand special keywords in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001894feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
1895filereadable({file}) Number TRUE if {file} is a readable file
1896filewritable({file}) Number TRUE if {file} is a writable file
1897filter({expr}, {string}) List/Dict remove items from {expr} where
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001898 {string} is 0
Bram Moolenaar81edd172016-04-14 13:51:37 +02001899finddir({name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001900 String find directory {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001901findfile({name}[, {path}[, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001902 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001903float2nr({expr}) Number convert Float {expr} to a Number
1904floor({expr}) Float round {expr} down
1905fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
1906fnameescape({fname}) String escape special characters in {fname}
1907fnamemodify({fname}, {mods}) String modify file name
1908foldclosed({lnum}) Number first line of fold at {lnum} if closed
1909foldclosedend({lnum}) Number last line of fold at {lnum} if closed
1910foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001911foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02001912foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001913foreground() Number bring the Vim window to the foreground
Bram Moolenaar81edd172016-04-14 13:51:37 +02001914function({name} [, {arglist}] [, {dict}])
Bram Moolenaar1735bc92016-03-14 23:05:14 +01001915 Funcref reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001916garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02001917garbagecollect_for_testing() none free memory right now
Bram Moolenaar81edd172016-04-14 13:51:37 +02001918get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
1919get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
1920getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00001921 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001922getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001923 any variable {varname} in buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001924getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01001925getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02001926getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00001927getcmdline() String return the current command-line
1928getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02001929getcmdtype() String return current command-line type
1930getcmdwintype() String return current command-line window type
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02001931getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02001932getcwd([{winnr} [, {tabnr}]]) String get the current working directory
1933getfontname([{name}]) String name of font being used
1934getfperm({fname}) String file permissions of file {fname}
1935getfsize({fname}) Number size in bytes of file {fname}
1936getftime({fname}) Number last modification time of file
1937getftype({fname}) String description of type of file {fname}
1938getline({lnum}) String line {lnum} of current buffer
1939getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
1940getloclist({nr}) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00001941getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00001942getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02001943getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00001944getqflist() List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02001945getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02001946 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02001947getregtype([{regname}]) String type of register
1948gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001949 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001950gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00001951 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001952getwinposx() Number X coord in pixels of GUI Vim window
1953getwinposy() Number Y coord in pixels of GUI Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02001954getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01001955 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001956glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01001957 any expand file wildcards in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001958glob2regpat({expr}) String convert a glob pat into a search pat
1959globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00001960 String do glob({expr}) for all dirs in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02001961has({feature}) Number TRUE if feature {feature} supported
1962has_key({dict}, {key}) Number TRUE if {dict} has entry {key}
1963haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaarc9703302016-01-17 21:49:33 +01001964 Number TRUE if the window executed |:lcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02001965hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001966 Number TRUE if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02001967histadd({history}, {item}) String add an item to a history
1968histdel({history} [, {item}]) String remove an item from a history
1969histget({history} [, {index}]) String get the item {index} from a history
1970histnr({history}) Number highest index of a history
1971hlexists({name}) Number TRUE if highlight group {name} exists
1972hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001973hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02001974iconv({expr}, {from}, {to}) String convert encoding of {expr}
1975indent({lnum}) Number indent of line {lnum}
1976index({list}, {expr} [, {start} [, {ic}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001977 Number index in {list} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02001978input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001979 String get input from the user
Bram Moolenaar81edd172016-04-14 13:51:37 +02001980inputdialog({prompt} [, {text} [, {completion}]]])
1981 String like input() but in a GUI dialog
1982inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001983inputrestore() Number restore typeahead
1984inputsave() Number save and clear typeahead
Bram Moolenaar81edd172016-04-14 13:51:37 +02001985inputsecret({prompt} [, {text}]) String like input() but hiding the text
1986insert({list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
1987invert({expr}) Number bitwise invert
1988isdirectory({directory}) Number TRUE if {directory} is a directory
1989islocked({expr}) Number TRUE if {expr} is locked
1990isnan({expr}) Number TRUE if {expr} is NaN
1991items({dict}) List key-value pairs in {dict}
1992job_getchannel({job}) Channel get the channel handle for {job}
1993job_info({job}) Dict get information about {job}
1994job_setoptions({job}, {options}) none set options for {job}
1995job_start({command} [, {options}])
1996 Job start a job
1997job_status({job}) String get the status of {job}
1998job_stop({job} [, {how}]) Number stop {job}
1999join({list} [, {sep}]) String join {list} items into one String
2000js_decode({string}) any decode JS style JSON
2001js_encode({expr}) String encode JS style JSON
2002json_decode({string}) any decode JSON
2003json_encode({expr}) String encode JSON
2004keys({dict}) List keys in {dict}
2005len({expr}) Number the length of {expr}
2006libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
2007libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
2008line({expr}) Number line nr of cursor, last line or mark
2009line2byte({lnum}) Number byte count of line {lnum}
2010lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002011localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002012log({expr}) Float natural logarithm (base e) of {expr}
2013log10({expr}) Float logarithm of Float {expr} to base 10
2014luaeval({expr}[, {expr}]) any evaluate |Lua| expression
2015map({expr}, {string}) List/Dict change each item in {expr} to {expr}
2016maparg({name}[, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002017 String or Dict
2018 rhs of mapping {name} in mode {mode}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002019mapcheck({name}[, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002020 String check for mappings matching {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002021match({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002022 Number position where {pat} matches in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002023matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002024 Number highlight {pattern} with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002025matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002026 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002027matcharg({nr}) List arguments of |:match|
2028matchdelete({id}) Number delete match identified by {id}
2029matchend({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002030 Number position where {pat} ends in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002031matchlist({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002032 List match and submatches of {pat} in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002033matchstr({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002034 String {count}'th match of {pat} in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002035matchstrpos({expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002036 List {count}'th match of {pat} in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002037max({list}) Number maximum value of items in {list}
2038min({list}) Number minimum value of items in {list}
2039mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002040 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002041mode([expr]) String current editing mode
2042mzeval({expr}) any evaluate |MzScheme| expression
2043nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
2044nr2char({expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr}
2045or({expr}, {expr}) Number bitwise OR
2046pathshorten({expr}) String shorten directory names in a path
2047perleval({expr}) any evaluate |Perl| expression
2048pow({x}, {y}) Float {x} to the power of {y}
2049prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2050printf({fmt}, {expr1}...) String format text
Bram Moolenaar446cb832008-06-24 21:56:24 +00002051pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002052pyeval({expr}) any evaluate |Python| expression
2053py3eval({expr}) any evaluate |python3| expression
2054range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002055 List items from {expr} to {max}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002056readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002057 List get list of lines from file {fname}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002058reltime([{start} [, {end}]]) List get time value
2059reltimefloat({time}) Float turn the time value into a Float
2060reltimestr({time}) String turn time value into a String
2061remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002062 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002063remote_foreground({server}) Number bring Vim server to the foreground
2064remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002065 Number check for reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002066remote_read({serverid}) String read reply string
2067remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002068 String send key sequence
Bram Moolenaar81edd172016-04-14 13:51:37 +02002069remove({list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
2070remove({dict}, {key}) any remove entry {key} from {dict}
2071rename({from}, {to}) Number rename (move) file from {from} to {to}
2072repeat({expr}, {count}) String repeat {expr} {count} times
2073resolve({filename}) String get filename a shortcut points to
2074reverse({list}) List reverse {list} in-place
2075round({expr}) Float round off {expr}
2076screenattr({row}, {col}) Number attribute at screen position
2077screenchar({row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002078screencol() Number current cursor column
2079screenrow() Number current cursor row
Bram Moolenaar81edd172016-04-14 13:51:37 +02002080search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002081 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002082searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002083 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002084searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002085 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002086searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002087 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002088searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002089 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002090server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002091 Number send reply string
2092serverlist() String get a list of available servers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002093setbufvar({expr}, {varname}, {val})
2094 none set {varname} in buffer {expr} to {val}
2095setcharsearch({dict}) Dict set character search from {dict}
2096setcmdpos({pos}) Number set cursor position in command-line
2097setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2098setline({lnum}, {line}) Number set line {lnum} to {line}
2099setloclist({nr}, {list}[, {action}])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002100 Number modify location list using {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002101setmatches({list}) Number restore a list of matches
2102setpos({expr}, {list}) Number set the {expr} position to {list}
2103setqflist({list}[, {action}]) Number modify quickfix list using {list}
2104setreg({n}, {v}[, {opt}]) Number set register to value and type
2105settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2106settabwinvar({tabnr}, {winnr}, {varname}, {val})
2107 none set {varname} in window {winnr} in tab
2108 page {tabnr} to {val}
2109setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2110sha256({string}) String SHA256 checksum of {string}
2111shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002112 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002113 command argument
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02002114shiftwidth() Number effective value of 'shiftwidth'
Bram Moolenaar81edd172016-04-14 13:51:37 +02002115simplify({filename}) String simplify filename as much as possible
2116sin({expr}) Float sine of {expr}
2117sinh({expr}) Float hyperbolic sine of {expr}
2118sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002119 List sort {list}, using {func} to compare
Bram Moolenaar81edd172016-04-14 13:51:37 +02002120soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002121spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002122spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002123 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002124split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002125 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002126sqrt({expr}) Float square root of {expr}
2127str2float({expr}) Float convert String to Float
2128str2nr({expr} [, {base}]) Number convert String to Number
2129strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002130strcharpart({str}, {start}[, {len}])
2131 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002132strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
2133strftime({format}[, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002134strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002135stridx({haystack}, {needle}[, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002136 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002137string({expr}) String String representation of {expr} value
2138strlen({expr}) Number length of the String {expr}
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002139strpart({str}, {start}[, {len}])
2140 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002141strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002142 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002143strtrans({expr}) String translate string to make it printable
2144strwidth({expr}) Number display cell length of the String {expr}
2145submatch({nr}[, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002146 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002147substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002148 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002149synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2150synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002151 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002152synIDtrans({synID}) Number translated syntax ID of {synID}
2153synconcealed({lnum}, {col}) List info about concealing
2154synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2155system({expr} [, {input}]) String output of shell command/filter {expr}
2156systemlist({expr} [, {input}]) List output of shell command/filter {expr}
2157tabpagebuflist([{arg}]) List list of buffer numbers in tab page
2158tabpagenr([{arg}]) Number number of current or last tab page
2159tabpagewinnr({tabarg}[, {arg}]) Number number of current window in tab page
2160taglist({expr}) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002161tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002162tan({expr}) Float tangent of {expr}
2163tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002164tempname() String name for a temporary file
Bram Moolenaar81edd172016-04-14 13:51:37 +02002165timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002166 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002167timer_stop({timer}) none stop a timer
2168tolower({expr}) String the String {expr} switched to lowercase
2169toupper({expr}) String the String {expr} switched to uppercase
2170tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002171 to chars in {tostr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002172trunc({expr}) Float truncate Float {expr}
2173type({name}) Number type of variable {name}
2174undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002175undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002176uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002177 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002178values({dict}) List values in {dict}
2179virtcol({expr}) Number screen column of cursor or mark
2180visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002181wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar81edd172016-04-14 13:51:37 +02002182win_findbuf({bufnr}) List find windows containing {bufnr}
2183win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2184win_gotoid({expr}) Number go to window with ID {expr}
2185win_id2tabwin({expr}) List get tab and window nr from window ID
2186win_id2win({expr}) Number get window nr from window ID
2187winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002188wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002189winheight({nr}) Number height of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002190winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002191winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002192winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002193winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002194winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002195winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002196wordcount() Dict get byte/char/word statistics
Bram Moolenaar81edd172016-04-14 13:51:37 +02002197writefile({list}, {fname} [, {flags}])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002198 Number write list of lines to file {fname}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002199xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002200
Bram Moolenaar03413f42016-04-12 21:07:15 +02002201
Bram Moolenaar446cb832008-06-24 21:56:24 +00002202abs({expr}) *abs()*
2203 Return the absolute value of {expr}. When {expr} evaluates to
2204 a |Float| abs() returns a |Float|. When {expr} can be
2205 converted to a |Number| abs() returns a |Number|. Otherwise
2206 abs() gives an error message and returns -1.
2207 Examples: >
2208 echo abs(1.456)
2209< 1.456 >
2210 echo abs(-5.456)
2211< 5.456 >
2212 echo abs(-4)
2213< 4
2214 {only available when compiled with the |+float| feature}
2215
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002216
2217acos({expr}) *acos()*
2218 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002219 |Float| in the range of [0, pi].
2220 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002221 [-1, 1].
2222 Examples: >
2223 :echo acos(0)
2224< 1.570796 >
2225 :echo acos(-0.5)
2226< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002227 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002228
2229
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002230add({list}, {expr}) *add()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002231 Append the item {expr} to |List| {list}. Returns the
2232 resulting |List|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002233 :let alist = add([1, 2, 3], item)
2234 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002235< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002236 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002237 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002238
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002239
Bram Moolenaar75bdf6a2016-01-07 21:25:08 +01002240alloc_fail({id}, {countdown}, {repeat}) *alloc_fail()*
2241 This is for testing: If the memory allocation with {id} is
2242 called, then decrement {countdown}, and when it reaches zero
2243 let memory allocation fail {repeat} times. When {repeat} is
2244 smaller than one it fails one time.
2245
2246
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002247and({expr}, {expr}) *and()*
2248 Bitwise AND on the two arguments. The arguments are converted
2249 to a number. A List, Dict or Float argument causes an error.
2250 Example: >
2251 :let flag = and(bits, 0x80)
2252
2253
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002254append({lnum}, {expr}) *append()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002255 When {expr} is a |List|: Append each item of the |List| as a
2256 text line below line {lnum} in the current buffer.
Bram Moolenaar748bf032005-02-02 23:04:36 +00002257 Otherwise append {expr} as one text line below line {lnum} in
2258 the current buffer.
2259 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002260 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar446cb832008-06-24 21:56:24 +00002261 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002262 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002263 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002264<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002265 *argc()*
2266argc() The result is the number of files in the argument list of the
2267 current window. See |arglist|.
2268
2269 *argidx()*
2270argidx() The result is the current index in the argument list. 0 is
2271 the first file. argc() - 1 is the last one. See |arglist|.
2272
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002273 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002274arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002275 Return the argument list ID. This is a number which
2276 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002277 global argument list. See |arglist|.
2278 Return -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002279
2280 Without arguments use the current window.
2281 With {winnr} only use this window in the current tab page.
2282 With {winnr} and {tabnr} use the window in the specified tab
2283 page.
2284
Bram Moolenaar071d4272004-06-13 20:20:40 +00002285 *argv()*
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002286argv([{nr}]) The result is the {nr}th file in the argument list of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002287 current window. See |arglist|. "argv(0)" is the first one.
2288 Example: >
2289 :let i = 0
2290 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002291 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002292 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2293 : let i = i + 1
2294 :endwhile
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002295< Without the {nr} argument a |List| with the whole |arglist| is
2296 returned.
2297
Bram Moolenaar683fa182015-11-30 21:38:24 +01002298 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002299assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002300 When {expected} and {actual} are not equal an error message is
2301 added to |v:errors|.
2302 There is no automatic conversion, the String "4" is different
2303 from the Number 4. And the number 4 is different from the
2304 Float 4.0. The value of 'ignorecase' is not used here, case
2305 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002306 When {msg} is omitted an error in the form "Expected
2307 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002308 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002309 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002310< Will result in a string to be added to |v:errors|:
2311 test.vim line 12: Expected 'foo' but got 'bar' ~
2312
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002313assert_exception({error} [, {msg}]) *assert_exception()*
2314 When v:exception does not contain the string {error} an error
2315 message is added to |v:errors|.
2316 This can be used to assert that a command throws an exception.
2317 Using the error number, followed by a colon, avoids problems
2318 with translations: >
2319 try
2320 commandthatfails
2321 call assert_false(1, 'command should have failed')
2322 catch
2323 call assert_exception('E492:')
2324 endtry
2325
Bram Moolenaara260b872016-01-15 20:48:22 +01002326assert_fails({cmd} [, {error}]) *assert_fails()*
2327 Run {cmd} and add an error message to |v:errors| if it does
2328 NOT produce an error.
2329 When {error} is given it must match |v:errmsg|.
2330
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002331assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002332 When {actual} is not false an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002333 |v:errors|, like with |assert_equal()|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002334 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002335 number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002336 When {msg} is omitted an error in the form "Expected False but
2337 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002338
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002339 *assert_match()*
2340assert_match({pattern}, {actual} [, {msg}])
2341 When {pattern} does not match {actual} an error message is
2342 added to |v:errors|.
2343
2344 {pattern} is used as with |=~|: The matching is always done
2345 like 'magic' was set and 'cpoptions' is empty, no matter what
2346 the actual value of 'magic' or 'cpoptions' is.
2347
2348 {actual} is used as a string, automatic conversion applies.
2349 Use "^" and "$" to match with the start and end of the text.
2350 Use both to match the whole text.
2351
2352 When {msg} is omitted an error in the form "Pattern {pattern}
2353 does not match {actual}" is produced.
2354 Example: >
2355 assert_match('^f.*o$', 'foobar')
2356< Will result in a string to be added to |v:errors|:
2357 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
2358
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002359 *assert_notequal()*
2360assert_notequal({expected}, {actual} [, {msg}])
2361 The opposite of `assert_equal()`: add an error message to
2362 |v:errors| when {expected} and {actual} are equal.
2363
2364 *assert_notmatch()*
2365assert_notmatch({pattern}, {actual} [, {msg}])
2366 The opposite of `assert_match()`: add an error message to
2367 |v:errors| when {pattern} matches {actual}.
2368
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002369assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002370 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002371 |v:errors|, like with |assert_equal()|.
2372 A value is true when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002373 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002374 When {msg} is omitted an error in the form "Expected True but
2375 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002376
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002377asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002378 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002379 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002380 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002381 [-1, 1].
2382 Examples: >
2383 :echo asin(0.8)
2384< 0.927295 >
2385 :echo asin(-0.5)
2386< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002387 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002388
2389
Bram Moolenaar446cb832008-06-24 21:56:24 +00002390atan({expr}) *atan()*
2391 Return the principal value of the arc tangent of {expr}, in
2392 the range [-pi/2, +pi/2] radians, as a |Float|.
2393 {expr} must evaluate to a |Float| or a |Number|.
2394 Examples: >
2395 :echo atan(100)
2396< 1.560797 >
2397 :echo atan(-4.01)
2398< -1.326405
2399 {only available when compiled with the |+float| feature}
2400
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002401
2402atan2({expr1}, {expr2}) *atan2()*
2403 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002404 radians, as a |Float| in the range [-pi, pi].
2405 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002406 Examples: >
2407 :echo atan2(-1, 1)
2408< -0.785398 >
2409 :echo atan2(1, -1)
2410< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002411 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002412
2413
Bram Moolenaar071d4272004-06-13 20:20:40 +00002414 *browse()*
2415browse({save}, {title}, {initdir}, {default})
2416 Put up a file requester. This only works when "has("browse")"
2417 returns non-zero (only in some GUI versions).
2418 The input fields are:
2419 {save} when non-zero, select file to write
2420 {title} title for the requester
2421 {initdir} directory to start browsing in
2422 {default} default file name
2423 When the "Cancel" button is hit, something went wrong, or
2424 browsing is not possible, an empty string is returned.
2425
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002426 *browsedir()*
2427browsedir({title}, {initdir})
2428 Put up a directory requester. This only works when
2429 "has("browse")" returns non-zero (only in some GUI versions).
2430 On systems where a directory browser is not supported a file
2431 browser is used. In that case: select a file in the directory
2432 to be used.
2433 The input fields are:
2434 {title} title for the requester
2435 {initdir} directory to start browsing in
2436 When the "Cancel" button is hit, something went wrong, or
2437 browsing is not possible, an empty string is returned.
2438
Bram Moolenaar071d4272004-06-13 20:20:40 +00002439bufexists({expr}) *bufexists()*
2440 The result is a Number, which is non-zero if a buffer called
2441 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002442 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002443 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002444 exactly. The name can be:
2445 - Relative to the current directory.
2446 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002447 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002448 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002449 Unlisted buffers will be found.
2450 Note that help files are listed by their short name in the
2451 output of |:buffers|, but bufexists() requires using their
2452 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002453 bufexists() may report a buffer exists, but to use the name
2454 with a |:buffer| command you may need to use |expand()|. Esp
2455 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002456 Use "bufexists(0)" to test for the existence of an alternate
2457 file name.
2458 *buffer_exists()*
2459 Obsolete name: buffer_exists().
2460
2461buflisted({expr}) *buflisted()*
2462 The result is a Number, which is non-zero if a buffer called
2463 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002464 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002465
2466bufloaded({expr}) *bufloaded()*
2467 The result is a Number, which is non-zero if a buffer called
2468 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002469 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002470
2471bufname({expr}) *bufname()*
2472 The result is the name of a buffer, as it is displayed by the
2473 ":ls" command.
2474 If {expr} is a Number, that buffer number's name is given.
2475 Number zero is the alternate buffer for the current window.
2476 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002477 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002478 set and 'cpoptions' is empty. When there is more than one
2479 match an empty string is returned.
2480 "" or "%" can be used for the current buffer, "#" for the
2481 alternate buffer.
2482 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002483 or middle of the buffer name is accepted. If you only want a
2484 full match then put "^" at the start and "$" at the end of the
2485 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002486 Listed buffers are found first. If there is a single match
2487 with a listed buffer, that one is returned. Next unlisted
2488 buffers are searched for.
2489 If the {expr} is a String, but you want to use it as a buffer
2490 number, force it to be a Number by adding zero to it: >
2491 :echo bufname("3" + 0)
2492< If the buffer doesn't exist, or doesn't have a name, an empty
2493 string is returned. >
2494 bufname("#") alternate buffer name
2495 bufname(3) name of buffer 3
2496 bufname("%") name of current buffer
2497 bufname("file2") name of buffer where "file2" matches.
2498< *buffer_name()*
2499 Obsolete name: buffer_name().
2500
2501 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002502bufnr({expr} [, {create}])
2503 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00002504 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002505 above.
2506 If the buffer doesn't exist, -1 is returned. Or, if the
2507 {create} argument is present and not zero, a new, unlisted,
2508 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002509 bufnr("$") is the last buffer: >
2510 :let last_buffer = bufnr("$")
2511< The result is a Number, which is the highest buffer number
2512 of existing buffers. Note that not all buffers with a smaller
2513 number necessarily exist, because ":bwipeout" may have removed
2514 them. Use bufexists() to test for the existence of a buffer.
2515 *buffer_number()*
2516 Obsolete name: buffer_number().
2517 *last_buffer_nr()*
2518 Obsolete name for bufnr("$"): last_buffer_nr().
2519
2520bufwinnr({expr}) *bufwinnr()*
2521 The result is a Number, which is the number of the first
2522 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar446cb832008-06-24 21:56:24 +00002523 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00002524 there is no such window, -1 is returned. Example: >
2525
2526 echo "A window containing buffer 1 is " . (bufwinnr(1))
2527
2528< The number can be used with |CTRL-W_w| and ":wincmd w"
2529 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002530 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002531
Bram Moolenaar071d4272004-06-13 20:20:40 +00002532byte2line({byte}) *byte2line()*
2533 Return the line number that contains the character at byte
2534 count {byte} in the current buffer. This includes the
2535 end-of-line character, depending on the 'fileformat' option
2536 for the current buffer. The first character has byte count
2537 one.
2538 Also see |line2byte()|, |go| and |:goto|.
2539 {not available when compiled without the |+byte_offset|
2540 feature}
2541
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002542byteidx({expr}, {nr}) *byteidx()*
2543 Return byte index of the {nr}'th character in the string
2544 {expr}. Use zero for the first character, it returns zero.
2545 This function is only useful when there are multibyte
2546 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002547 Composing characters are not counted separately, their byte
2548 length is added to the preceding base character. See
2549 |byteidxcomp()| below for counting composing characters
2550 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002551 Example : >
2552 echo matchstr(str, ".", byteidx(str, 3))
2553< will display the fourth character. Another way to do the
2554 same: >
2555 let s = strpart(str, byteidx(str, 3))
2556 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002557< Also see |strgetchar()| and |strcharpart()|.
2558
2559 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002560 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01002561 in bytes is returned.
2562
2563byteidxcomp({expr}, {nr}) *byteidxcomp()*
2564 Like byteidx(), except that a composing character is counted
2565 as a separate character. Example: >
2566 let s = 'e' . nr2char(0x301)
2567 echo byteidx(s, 1)
2568 echo byteidxcomp(s, 1)
2569 echo byteidxcomp(s, 2)
2570< The first and third echo result in 3 ('e' plus composing
2571 character is 3 bytes), the second echo results in 1 ('e' is
2572 one byte).
2573 Only works different from byteidx() when 'encoding' is set to
2574 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00002575
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002576call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002577 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002578 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002579 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002580 a:firstline and a:lastline are set to the cursor line.
2581 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002582 {dict} is for functions with the "dict" attribute. It will be
2583 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002584
Bram Moolenaar446cb832008-06-24 21:56:24 +00002585ceil({expr}) *ceil()*
2586 Return the smallest integral value greater than or equal to
2587 {expr} as a |Float| (round up).
2588 {expr} must evaluate to a |Float| or a |Number|.
2589 Examples: >
2590 echo ceil(1.456)
2591< 2.0 >
2592 echo ceil(-5.456)
2593< -5.0 >
2594 echo ceil(4.0)
2595< 4.0
2596 {only available when compiled with the |+float| feature}
2597
Bram Moolenaarca003e12006-03-17 23:19:38 +00002598changenr() *changenr()*
2599 Return the number of the most recent change. This is the same
2600 number as what is displayed with |:undolist| and can be used
2601 with the |:undo| command.
2602 When a change was made it is the number of that change. After
2603 redo it is the number of the redone change. After undo it is
2604 one less than the number of the undone change.
2605
Bram Moolenaard35d7842013-01-23 17:17:10 +01002606char2nr({expr}[, {utf8}]) *char2nr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002607 Return number value of the first char in {expr}. Examples: >
2608 char2nr(" ") returns 32
2609 char2nr("ABC") returns 65
Bram Moolenaard35d7842013-01-23 17:17:10 +01002610< When {utf8} is omitted or zero, the current 'encoding' is used.
2611 Example for "utf-8": >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002612 char2nr("á") returns 225
2613 char2nr("á"[0]) returns 195
Bram Moolenaard35d7842013-01-23 17:17:10 +01002614< With {utf8} set to 1, always treat as utf-8 characters.
2615 A combining character is a separate character.
Bram Moolenaar97293012011-07-18 19:40:27 +02002616 |nr2char()| does the opposite.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002617
2618cindent({lnum}) *cindent()*
2619 Get the amount of indent for line {lnum} according the C
2620 indenting rules, as with 'cindent'.
2621 The indent is counted in spaces, the value of 'tabstop' is
2622 relevant. {lnum} is used just like in |getline()|.
2623 When {lnum} is invalid or Vim was not compiled the |+cindent|
2624 feature, -1 is returned.
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +00002625 See |C-indenting|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002626
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002627clearmatches() *clearmatches()*
2628 Clears all matches previously defined by |matchadd()| and the
2629 |:match| commands.
2630
Bram Moolenaar071d4272004-06-13 20:20:40 +00002631 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00002632col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00002633 position given with {expr}. The accepted positions are:
2634 . the cursor position
2635 $ the end of the cursor line (the result is the
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02002636 number of bytes in the cursor line plus one)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002637 'x position of mark x (if the mark is not set, 0 is
2638 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01002639 v In Visual mode: the start of the Visual area (the
2640 cursor is the end). When not in Visual mode
2641 returns the cursor position. Differs from |'<| in
2642 that it's updated right away.
Bram Moolenaar477933c2007-07-17 14:32:23 +00002643 Additionally {expr} can be [lnum, col]: a |List| with the line
2644 and column number. Most useful when the column is "$", to get
Bram Moolenaar446cb832008-06-24 21:56:24 +00002645 the last column of a specific line. When "lnum" or "col" is
Bram Moolenaar477933c2007-07-17 14:32:23 +00002646 out of range then col() returns zero.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002647 To get the line number use |line()|. To get both use
Bram Moolenaar0b238792006-03-02 22:49:12 +00002648 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002649 For the screen column position use |virtcol()|.
2650 Note that only marks in the current file can be used.
2651 Examples: >
2652 col(".") column of cursor
2653 col("$") length of cursor line plus one
2654 col("'t") column of mark t
2655 col("'" . markname) column of mark markname
Bram Moolenaar446cb832008-06-24 21:56:24 +00002656< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002657 For an uppercase mark the column may actually be in another
2658 buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002659 For the cursor position, when 'virtualedit' is active, the
2660 column is one higher if the cursor is after the end of the
2661 line. This can be used to obtain the column in Insert mode: >
2662 :imap <F2> <C-O>:let save_ve = &ve<CR>
2663 \<C-O>:set ve=all<CR>
2664 \<C-O>:echo col(".") . "\n" <Bar>
2665 \let &ve = save_ve<CR>
2666<
Bram Moolenaar572cb562005-08-05 21:35:02 +00002667
Bram Moolenaara94bc432006-03-10 21:42:59 +00002668complete({startcol}, {matches}) *complete()* *E785*
2669 Set the matches for Insert mode completion.
2670 Can only be used in Insert mode. You need to use a mapping
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002671 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2672 with an expression mapping.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002673 {startcol} is the byte offset in the line where the completed
2674 text start. The text up to the cursor is the original text
2675 that will be replaced by the matches. Use col('.') for an
2676 empty string. "col('.') - 1" will replace one character by a
2677 match.
2678 {matches} must be a |List|. Each |List| item is one match.
2679 See |complete-items| for the kind of items that are possible.
2680 Note that the after calling this function you need to avoid
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002681 inserting anything that would cause completion to stop.
Bram Moolenaara94bc432006-03-10 21:42:59 +00002682 The match can be selected with CTRL-N and CTRL-P as usual with
2683 Insert mode completion. The popup menu will appear if
2684 specified, see |ins-completion-menu|.
2685 Example: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002686 inoremap <F5> <C-R>=ListMonths()<CR>
Bram Moolenaara94bc432006-03-10 21:42:59 +00002687
2688 func! ListMonths()
2689 call complete(col('.'), ['January', 'February', 'March',
2690 \ 'April', 'May', 'June', 'July', 'August', 'September',
2691 \ 'October', 'November', 'December'])
2692 return ''
2693 endfunc
2694< This isn't very useful, but it shows how it works. Note that
2695 an empty string is returned to avoid a zero being inserted.
2696
Bram Moolenaar572cb562005-08-05 21:35:02 +00002697complete_add({expr}) *complete_add()*
2698 Add {expr} to the list of matches. Only to be used by the
2699 function specified with the 'completefunc' option.
2700 Returns 0 for failure (empty string or out of memory),
2701 1 when the match was added, 2 when the match was already in
2702 the list.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002703 See |complete-functions| for an explanation of {expr}. It is
Bram Moolenaar39f05632006-03-19 22:15:26 +00002704 the same as one item in the list that 'omnifunc' would return.
Bram Moolenaar572cb562005-08-05 21:35:02 +00002705
2706complete_check() *complete_check()*
2707 Check for a key typed while looking for completion matches.
2708 This is to be used when looking for matches takes some time.
2709 Returns non-zero when searching for matches is to be aborted,
2710 zero otherwise.
2711 Only to be used by the function specified with the
2712 'completefunc' option.
2713
Bram Moolenaar071d4272004-06-13 20:20:40 +00002714 *confirm()*
2715confirm({msg} [, {choices} [, {default} [, {type}]]])
2716 Confirm() offers the user a dialog, from which a choice can be
2717 made. It returns the number of the choice. For the first
2718 choice this is 1.
2719 Note: confirm() is only supported when compiled with dialog
2720 support, see |+dialog_con| and |+dialog_gui|.
Bram Moolenaara800b422010-06-27 01:15:55 +02002721
Bram Moolenaar071d4272004-06-13 20:20:40 +00002722 {msg} is displayed in a |dialog| with {choices} as the
2723 alternatives. When {choices} is missing or empty, "&OK" is
2724 used (and translated).
2725 {msg} is a String, use '\n' to include a newline. Only on
2726 some systems the string is wrapped when it doesn't fit.
Bram Moolenaara800b422010-06-27 01:15:55 +02002727
Bram Moolenaar071d4272004-06-13 20:20:40 +00002728 {choices} is a String, with the individual choices separated
2729 by '\n', e.g. >
2730 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2731< The letter after the '&' is the shortcut key for that choice.
2732 Thus you can type 'c' to select "Cancel". The shortcut does
2733 not need to be the first letter: >
2734 confirm("file has been modified", "&Save\nSave &All")
2735< For the console, the first letter of each choice is used as
2736 the default shortcut key.
Bram Moolenaara800b422010-06-27 01:15:55 +02002737
Bram Moolenaar071d4272004-06-13 20:20:40 +00002738 The optional {default} argument is the number of the choice
2739 that is made if the user hits <CR>. Use 1 to make the first
2740 choice the default one. Use 0 to not set a default. If
2741 {default} is omitted, 1 is used.
Bram Moolenaara800b422010-06-27 01:15:55 +02002742
2743 The optional {type} argument gives the type of dialog. This
2744 is only used for the icon of the GTK, Mac, Motif and Win32
2745 GUI. It can be one of these values: "Error", "Question",
2746 "Info", "Warning" or "Generic". Only the first character is
2747 relevant. When {type} is omitted, "Generic" is used.
2748
Bram Moolenaar071d4272004-06-13 20:20:40 +00002749 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2750 or another valid interrupt key, confirm() returns 0.
2751
2752 An example: >
2753 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2754 :if choice == 0
2755 : echo "make up your mind!"
2756 :elseif choice == 3
2757 : echo "tasteful"
2758 :else
2759 : echo "I prefer bananas myself."
2760 :endif
2761< In a GUI dialog, buttons are used. The layout of the buttons
2762 depends on the 'v' flag in 'guioptions'. If it is included,
Bram Moolenaar446cb832008-06-24 21:56:24 +00002763 the buttons are always put vertically. Otherwise, confirm()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002764 tries to put the buttons in one horizontal line. If they
2765 don't fit, a vertical layout is used anyway. For some systems
2766 the horizontal layout is always used.
2767
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002768ch_close({handle}) *ch_close()*
2769 Close {handle}. See |channel-close|.
2770 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002771
Bram Moolenaar835dc632016-02-07 14:27:38 +01002772 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002773
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002774ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
2775 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002776 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01002777 with a raw channel. See |channel-use|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002778 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002779 *E917*
2780 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002781 entry. It can have a "timeout" entry to specify the timeout
2782 for this specific request.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002783
2784 ch_evalexpr() waits for a response and returns the decoded
2785 expression. When there is an error or timeout it returns an
2786 empty string.
2787
2788 {only available when compiled with the |+channel| feature}
2789
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002790ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
2791 Send {string} over {handle}.
2792 {handle} can be Channel or a Job that has a Channel.
2793
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01002794 Works like |ch_evalexpr()|, but does not encode the request or
2795 decode the response. The caller is responsible for the
2796 correct contents. Also does not add a newline for a channel
2797 in NL mode, the caller must do that. The NL in the response
2798 is removed.
2799 See |channel-use|.
2800
2801 {only available when compiled with the |+channel| feature}
2802
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002803ch_getbufnr({handle}, {what}) *ch_getbufnr()*
2804 Get the buffer number that {handle} is using for {what}.
2805 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01002806 {what} can be "err" for stderr, "out" for stdout or empty for
2807 socket output.
2808 Returns -1 when there is no buffer.
2809 {only available when compiled with the |+channel| feature}
2810
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002811ch_getjob({channel}) *ch_getjob()*
2812 Get the Job associated with {channel}.
2813 If there is no job calling |job_status()| on the returned Job
2814 will result in "fail".
2815
2816 {only available when compiled with the |+channel| and
2817 |+job| features}
2818
Bram Moolenaar03602ec2016-03-20 20:57:45 +01002819ch_info({handle}) *ch_info()*
2820 Returns a Dictionary with information about {handle}. The
2821 items are:
2822 "id" number of the channel
2823 "status" "open" (any part is open) or "closed"
2824 When opened with ch_open():
2825 "hostname" the hostname of the address
2826 "port" the port of the address
2827 "sock_status" "open" or "closed"
2828 "sock_mode" "NL", "RAW", "JSON" or "JS"
2829 "sock_io" "socket"
2830 "sock_timeout" timeout in msec
2831 When opened with job_start():
2832 "out_status" "open" or "closed"
2833 "out_mode" "NL", "RAW", "JSON" or "JS"
2834 "out_io" "null", "pipe", "file" or "buffer"
2835 "out_timeout" timeout in msec
2836 "err_status" "open" or "closed"
2837 "err_mode" "NL", "RAW", "JSON" or "JS"
2838 "err_io" "out", "null", "pipe", "file" or "buffer"
2839 "err_timeout" timeout in msec
2840 "in_status" "open" or "closed"
2841 "in_mode" "NL", "RAW", "JSON" or "JS"
2842 "in_io" "null", "pipe", "file" or "buffer"
2843 "in_timeout" timeout in msec
2844
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002845ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002846 Write {msg} in the channel log file, if it was opened with
2847 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002848 When {handle} is passed the channel number is used for the
2849 message.
2850 {handle} can be Channel or a Job that has a Channel. The
2851 Channel must open.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002852
2853ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002854 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002855 When {fname} is an empty string: stop logging.
2856
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002857 When {mode} is omitted or "a" append to the file.
2858 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002859
2860 The file is flushed after every message, on Unix you can use
2861 "tail -f" to see what is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002862
Bram Moolenaar328da0d2016-03-04 22:22:32 +01002863
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002864ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002865 Open a channel to {address}. See |channel|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002866 Returns a Channel. Use |ch_status()| to check for failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002867
2868 {address} has the form "hostname:port", e.g.,
2869 "localhost:8765".
2870
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002871 If {options} is given it must be a |Dictionary|.
2872 See |channel-open-options|.
2873
Bram Moolenaar835dc632016-02-07 14:27:38 +01002874 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002875
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002876ch_read({handle} [, {options}]) *ch_read()*
2877 Read from {handle} and return the received message.
2878 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002879 See |channel-more|.
2880 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002881
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002882ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002883 Like ch_read() but for a JS and JSON channel does not decode
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002884 the message. See |channel-more|.
2885 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002886
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002887ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
2888 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01002889 according to the type of channel. The function cannot be used
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002890 with a raw channel.
2891 See |channel-use|. *E912*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002892 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002893
Bram Moolenaar835dc632016-02-07 14:27:38 +01002894 {only available when compiled with the |+channel| feature}
2895
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002896ch_sendraw({handle}, {string} [, {options}]) *ch_sendraw()*
2897 Send {string} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01002898 Works like |ch_sendexpr()|, but does not encode the request or
2899 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01002900 correct contents. Also does not add a newline for a channel
2901 in NL mode, the caller must do that. The NL in the response
2902 is removed.
2903 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01002904
Bram Moolenaar835dc632016-02-07 14:27:38 +01002905 {only available when compiled with the |+channel| feature}
2906
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002907ch_setoptions({handle}, {options}) *ch_setoptions()*
2908 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002909 "callback" the channel callback
2910 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002911 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002912 See |ch_open()| for more explanation.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002913 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002914
Bram Moolenaar02e83b42016-02-21 20:10:26 +01002915 Note that changing the mode may cause queued messages to be
2916 lost.
2917
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002918 These options cannot be changed:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002919 "waittime" only applies to "ch_open()|
2920
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002921ch_status({handle}) *ch_status()*
2922 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01002923 "fail" failed to open the channel
2924 "open" channel can be used
2925 "closed" channel can not be used
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002926 {handle} can be Channel or a Job that has a Channel.
Bram Moolenaar38a55632016-02-15 22:07:32 +01002927
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002928 *copy()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00002929copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002930 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002931 When {expr} is a |List| a shallow copy is created. This means
2932 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002933 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01002934 changing an item changes the contents of both |Lists|.
2935 A |Dictionary| is copied in a similar way as a |List|.
2936 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002937
Bram Moolenaar446cb832008-06-24 21:56:24 +00002938cos({expr}) *cos()*
2939 Return the cosine of {expr}, measured in radians, as a |Float|.
2940 {expr} must evaluate to a |Float| or a |Number|.
2941 Examples: >
2942 :echo cos(100)
2943< 0.862319 >
2944 :echo cos(-4.01)
2945< -0.646043
2946 {only available when compiled with the |+float| feature}
2947
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002948
2949cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002950 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002951 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002952 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002953 Examples: >
2954 :echo cosh(0.5)
2955< 1.127626 >
2956 :echo cosh(-0.5)
2957< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02002958 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002959
Bram Moolenaar446cb832008-06-24 21:56:24 +00002960
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002961count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002962 Return the number of times an item with value {expr} appears
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002963 in |List| or |Dictionary| {comp}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002964 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002965 {start} can only be used with a |List|.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002966 When {ic} is given and it's non-zero then case is ignored.
2967
2968
Bram Moolenaar071d4272004-06-13 20:20:40 +00002969 *cscope_connection()*
2970cscope_connection([{num} , {dbpath} [, {prepend}]])
2971 Checks for the existence of a |cscope| connection. If no
2972 parameters are specified, then the function returns:
2973 0, if cscope was not available (not compiled in), or
2974 if there are no cscope connections;
2975 1, if there is at least one cscope connection.
2976
2977 If parameters are specified, then the value of {num}
2978 determines how existence of a cscope connection is checked:
2979
2980 {num} Description of existence check
2981 ----- ------------------------------
2982 0 Same as no parameters (e.g., "cscope_connection()").
2983 1 Ignore {prepend}, and use partial string matches for
2984 {dbpath}.
2985 2 Ignore {prepend}, and use exact string matches for
2986 {dbpath}.
2987 3 Use {prepend}, use partial string matches for both
2988 {dbpath} and {prepend}.
2989 4 Use {prepend}, use exact string matches for both
2990 {dbpath} and {prepend}.
2991
2992 Note: All string comparisons are case sensitive!
2993
2994 Examples. Suppose we had the following (from ":cs show"): >
2995
2996 # pid database name prepend path
2997 0 27664 cscope.out /usr/local
2998<
2999 Invocation Return Val ~
3000 ---------- ---------- >
3001 cscope_connection() 1
3002 cscope_connection(1, "out") 1
3003 cscope_connection(2, "out") 0
3004 cscope_connection(3, "out") 0
3005 cscope_connection(3, "out", "local") 1
3006 cscope_connection(4, "out") 0
3007 cscope_connection(4, "out", "local") 0
3008 cscope_connection(4, "cscope.out", "/usr/local") 1
3009<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003010cursor({lnum}, {col} [, {off}]) *cursor()*
3011cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003012 Positions the cursor at the column (byte count) {col} in the
3013 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003014
Bram Moolenaar0b238792006-03-02 22:49:12 +00003015 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003016 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003017 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003018 [{lnum}, {col}, {off}]
3019 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003020 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003021 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003022
Bram Moolenaar071d4272004-06-13 20:20:40 +00003023 Does not change the jumplist.
3024 If {lnum} is greater than the number of lines in the buffer,
3025 the cursor will be positioned at the last line in the buffer.
3026 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003027 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003028 the cursor will be positioned at the last character in the
3029 line.
3030 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003031 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003032 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003033
Bram Moolenaar0b238792006-03-02 22:49:12 +00003034 When 'virtualedit' is used {off} specifies the offset in
3035 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003036 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003037 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003038
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003039
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003040deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003041 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003042 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003043 When {expr} is a |List| a full copy is created. This means
3044 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003045 copy, and vice versa. When an item is a |List| or
3046 |Dictionary|, a copy for it is made, recursively. Thus
3047 changing an item in the copy does not change the contents of
3048 the original |List|.
3049 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003050 When {noref} is omitted or zero a contained |List| or
3051 |Dictionary| is only copied once. All references point to
3052 this single copy. With {noref} set to 1 every occurrence of a
3053 |List| or |Dictionary| results in a new copy. This also means
3054 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003055 *E724*
3056 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003057 that refers back to a higher level making a deep copy with
3058 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003059 Also see |copy()|.
3060
Bram Moolenaarda440d22016-01-16 21:27:23 +01003061delete({fname} [, {flags}]) *delete()*
3062 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003063 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003064
3065 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003066 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003067
3068 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003069 {fname} and everything in it, recursively. BE CAREFUL!
3070 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003071
3072 The result is a Number, which is 0 if the delete operation was
3073 successful and -1 when the deletion failed or partly failed.
3074
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003075 Use |remove()| to delete an item from a |List|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +01003076 To delete a line from the buffer use |:delete|. Use |:exe|
3077 when the line number is in a variable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003078
3079 *did_filetype()*
3080did_filetype() Returns non-zero when autocommands are being executed and the
3081 FileType event has been triggered at least once. Can be used
3082 to avoid triggering the FileType event again in the scripts
3083 that detect the file type. |FileType|
3084 When editing another file, the counter is reset, thus this
3085 really checks if the FileType event has been triggered for the
3086 current buffer. This allows an autocommand that starts
3087 editing another buffer to set 'filetype' and load a syntax
3088 file.
3089
Bram Moolenaar47136d72004-10-12 20:02:24 +00003090diff_filler({lnum}) *diff_filler()*
3091 Returns the number of filler lines above line {lnum}.
3092 These are the lines that were inserted at this point in
3093 another diff'ed window. These filler lines are shown in the
3094 display but don't exist in the buffer.
3095 {lnum} is used like with |getline()|. Thus "." is the current
3096 line, "'m" mark m, etc.
3097 Returns 0 if the current window is not in diff mode.
3098
3099diff_hlID({lnum}, {col}) *diff_hlID()*
3100 Returns the highlight ID for diff mode at line {lnum} column
3101 {col} (byte index). When the current line does not have a
3102 diff change zero is returned.
3103 {lnum} is used like with |getline()|. Thus "." is the current
3104 line, "'m" mark m, etc.
3105 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3106 line.
3107 The highlight ID can be used with |synIDattr()| to obtain
3108 syntax information about the highlighting.
3109
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003110 *disable_char_avail_for_testing()*
3111disable_char_avail_for_testing({expr})
3112 When {expr} is 1 the internal char_avail() function will
3113 return FALSE. When {expr} is 0 the char_avail() function will
3114 function normally.
3115 Only use this for a test where typeahead causes the test not
3116 to work. E.g., to trigger the CursorMovedI autocommand event.
3117
Bram Moolenaar13065c42005-01-08 16:08:21 +00003118empty({expr}) *empty()*
3119 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003120 - A |List| or |Dictionary| is empty when it does not have any
3121 items.
3122 - A Number and Float is empty when its value is zero.
3123 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
3124 - A Job is empty when it failed to start.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003125 - A Channel is empty when it is closed.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003126
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003127 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003128 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003129
Bram Moolenaar071d4272004-06-13 20:20:40 +00003130escape({string}, {chars}) *escape()*
3131 Escape the characters in {chars} that occur in {string} with a
3132 backslash. Example: >
3133 :echo escape('c:\program files\vim', ' \')
3134< results in: >
3135 c:\\program\ files\\vim
Bram Moolenaar446cb832008-06-24 21:56:24 +00003136< Also see |shellescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003137
Bram Moolenaar446cb832008-06-24 21:56:24 +00003138 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003139eval({string}) Evaluate {string} and return the result. Especially useful to
3140 turn the result of |string()| back into the original value.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003141 This works for Numbers, Floats, Strings and composites of
3142 them. Also works for |Funcref|s that refer to existing
3143 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003144
Bram Moolenaar071d4272004-06-13 20:20:40 +00003145eventhandler() *eventhandler()*
3146 Returns 1 when inside an event handler. That is that Vim got
3147 interrupted while waiting for the user to type a character,
3148 e.g., when dropping a file on Vim. This means interactive
3149 commands cannot be used. Otherwise zero is returned.
3150
3151executable({expr}) *executable()*
3152 This function checks if an executable with the name {expr}
3153 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003154 arguments.
3155 executable() uses the value of $PATH and/or the normal
3156 searchpath for programs. *PATHEXT*
3157 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3158 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar446cb832008-06-24 21:56:24 +00003159 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3160 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003161 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar446cb832008-06-24 21:56:24 +00003162 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003163 Unix shell, then the name is also tried without adding an
3164 extension.
3165 On MS-DOS and MS-Windows it only checks if the file exists and
3166 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003167 On MS-Windows an executable in the same directory as Vim is
3168 always found. Since this directory is added to $PATH it
3169 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003170 The result is a Number:
3171 1 exists
3172 0 does not exist
3173 -1 not implemented on this system
3174
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003175exepath({expr}) *exepath()*
3176 If {expr} is an executable and is either an absolute path, a
3177 relative path or found in $PATH, return the full path.
3178 Note that the current directory is used when {expr} starts
3179 with "./", which may be a problem for Vim: >
3180 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003181< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003182 an empty string is returned.
3183
Bram Moolenaar071d4272004-06-13 20:20:40 +00003184 *exists()*
3185exists({expr}) The result is a Number, which is non-zero if {expr} is
3186 defined, zero otherwise. The {expr} argument is a string,
3187 which contains one of these:
3188 &option-name Vim option (only checks if it exists,
3189 not if it really works)
3190 +option-name Vim option that works.
3191 $ENVNAME environment variable (could also be
3192 done by comparing with an empty
3193 string)
3194 *funcname built-in function (see |functions|)
3195 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02003196 |user-functions|). Also works for a
3197 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003198 varname internal variable (see
Bram Moolenaar446cb832008-06-24 21:56:24 +00003199 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003200 for |curly-braces-names|, |Dictionary|
3201 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00003202 that evaluating an index may cause an
3203 error message for an invalid
3204 expression. E.g.: >
3205 :let l = [1, 2, 3]
3206 :echo exists("l[5]")
3207< 0 >
3208 :echo exists("l[xx]")
3209< E121: Undefined variable: xx
3210 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00003211 :cmdname Ex command: built-in command, user
3212 command or command modifier |:command|.
3213 Returns:
3214 1 for match with start of a command
3215 2 full match with a command
3216 3 matches several user commands
3217 To check for a supported command
3218 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00003219 :2match The |:2match| command.
3220 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003221 #event autocommand defined for this event
3222 #event#pattern autocommand defined for this event and
3223 pattern (the pattern is taken
3224 literally and compared to the
3225 autocommand patterns character by
3226 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003227 #group autocommand group exists
3228 #group#event autocommand defined for this group and
3229 event.
3230 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003231 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003232 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003233 ##event autocommand for this event is
3234 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003235 For checking for a supported feature use |has()|.
3236
3237 Examples: >
3238 exists("&shortname")
3239 exists("$HOSTNAME")
3240 exists("*strftime")
3241 exists("*s:MyFunc")
3242 exists("bufcount")
3243 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003244 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003245 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003246 exists("#filetypeindent")
3247 exists("#filetypeindent#FileType")
3248 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003249 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003250< There must be no space between the symbol (&/$/*/#) and the
3251 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003252 There must be no extra characters after the name, although in
3253 a few cases this is ignored. That may become more strict in
3254 the future, thus don't count on it!
3255 Working example: >
3256 exists(":make")
3257< NOT working example: >
3258 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00003259
3260< Note that the argument must be a string, not the name of the
3261 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003262 exists(bufcount)
3263< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00003264 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003265
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003266exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003267 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003268 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003269 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003270 Examples: >
3271 :echo exp(2)
3272< 7.389056 >
3273 :echo exp(-1)
3274< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02003275 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003276
3277
Bram Moolenaar84f72352012-03-11 15:57:40 +01003278expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003279 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003280 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003281
Bram Moolenaar84f72352012-03-11 15:57:40 +01003282 If {list} is given and it is non-zero, a List will be returned.
3283 Otherwise the result is a String and when there are several
3284 matches, they are separated by <NL> characters. [Note: in
3285 version 5.0 a space was used, which caused problems when a
3286 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00003287
Bram Moolenaar446cb832008-06-24 21:56:24 +00003288 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02003289 for a non-existing file is not included, unless {expr} does
3290 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003291
3292 When {expr} starts with '%', '#' or '<', the expansion is done
3293 like for the |cmdline-special| variables with their associated
3294 modifiers. Here is a short overview:
3295
3296 % current file name
3297 # alternate file name
3298 #n alternate file name n
3299 <cfile> file name under the cursor
3300 <afile> autocmd file name
3301 <abuf> autocmd buffer number (as a String!)
3302 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01003303 <sfile> sourced script file or function name
Bram Moolenaar81af9252010-12-10 20:35:50 +01003304 <slnum> sourced script file line number
Bram Moolenaar071d4272004-06-13 20:20:40 +00003305 <cword> word under the cursor
3306 <cWORD> WORD under the cursor
3307 <client> the {clientid} of the last received
3308 message |server2client()|
3309 Modifiers:
3310 :p expand to full path
3311 :h head (last path component removed)
3312 :t tail (last path component only)
3313 :r root (one extension removed)
3314 :e extension only
3315
3316 Example: >
3317 :let &tags = expand("%:p:h") . "/tags"
3318< Note that when expanding a string that starts with '%', '#' or
3319 '<', any following text is ignored. This does NOT work: >
3320 :let doesntwork = expand("%:h.bak")
3321< Use this: >
3322 :let doeswork = expand("%:h") . ".bak"
3323< Also note that expanding "<cfile>" and others only returns the
3324 referenced file name without further expansion. If "<cfile>"
3325 is "~/.cshrc", you need to do another expand() to have the
3326 "~/" expanded into the path of the home directory: >
3327 :echo expand(expand("<cfile>"))
3328<
3329 There cannot be white space between the variables and the
3330 following modifier. The |fnamemodify()| function can be used
3331 to modify normal file names.
3332
3333 When using '%' or '#', and the current or alternate file name
3334 is not defined, an empty string is used. Using "%:p" in a
3335 buffer with no name, results in the current directory, with a
3336 '/' added.
3337
3338 When {expr} does not start with '%', '#' or '<', it is
3339 expanded like a file name is expanded on the command line.
3340 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaar146e9c32012-03-07 19:18:23 +01003341 {nosuf} argument is given and it is non-zero.
3342 Names for non-existing files are included. The "**" item can
3343 be used to search in a directory tree. For example, to find
3344 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00003345 :echo expand("**/README")
3346<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003347 Expand() can also be used to expand variables and environment
3348 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003349 slow, because a shell may be used to do the expansion. See
3350 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003351 The expanded variable is still handled like a list of file
Bram Moolenaar446cb832008-06-24 21:56:24 +00003352 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003353 left unchanged. Thus ":echo expand('$FOOBAR')" results in
3354 "$FOOBAR".
3355
3356 See |glob()| for finding existing files. See |system()| for
3357 getting the raw output of an external command.
3358
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003359extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003360 {expr1} and {expr2} must be both |Lists| or both
3361 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003362
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003363 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003364 If {expr3} is given insert the items of {expr2} before item
3365 {expr3} in {expr1}. When {expr3} is zero insert before the
3366 first item. When {expr3} is equal to len({expr1}) then
3367 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003368 Examples: >
3369 :echo sort(extend(mylist, [7, 5]))
3370 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00003371< When {expr1} is the same List as {expr2} then the number of
3372 items copied is equal to the original length of the List.
3373 E.g., when {expr3} is 1 you get N new copies of the first item
3374 (where N is the original length of the List).
3375 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003376 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003377 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003378<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003379 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003380 Add all entries from {expr2} to {expr1}.
3381 If a key exists in both {expr1} and {expr2} then {expr3} is
3382 used to decide what to do:
3383 {expr3} = "keep": keep the value of {expr1}
3384 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003385 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003386 When {expr3} is omitted then "force" is assumed.
3387
3388 {expr1} is changed when {expr2} is not empty. If necessary
3389 make a copy of {expr1} first.
3390 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02003391 When {expr1} is locked and {expr2} is not empty the operation
3392 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003393 Returns {expr1}.
3394
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003395
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003396feedkeys({string} [, {mode}]) *feedkeys()*
3397 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003398 come from a mapping or were typed by the user.
3399 By default the string is added to the end of the typeahead
3400 buffer, thus if a mapping is still being executed the
3401 characters come after them. Use the 'i' flag to insert before
3402 other characters, they will be executed next, before any
3403 characters from a mapping.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003404 The function does not wait for processing of keys contained in
3405 {string}.
3406 To include special keys into {string}, use double-quotes
3407 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00003408 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003409 feedkeys('\<CR>') pushes 5 characters.
3410 If {mode} is absent, keys are remapped.
3411 {mode} is a String, which can contain these character flags:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00003412 'm' Remap keys. This is default.
3413 'n' Do not remap keys.
3414 't' Handle keys as if typed; otherwise they are handled as
3415 if coming from a mapping. This matters for undo,
3416 opening folds, etc.
Bram Moolenaar0a988df2015-01-27 15:19:24 +01003417 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01003418 'x' Execute commands until typeahead is empty. This is
3419 similar to using ":normal!". You can call feedkeys()
3420 several times without 'x' and then one time with 'x'
3421 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02003422 typeahead. Note that when Vim ends in Insert mode it
3423 will behave as if <Esc> is typed, to avoid getting
3424 stuck, waiting for a character to be typed before the
3425 script continues.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003426 '!' When used with 'x' will not end Insert mode. Can be
3427 used in a test when a timer is set to exit Insert mode
3428 a little later. Useful for testing CursorHoldI.
3429
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00003430 Return value is always 0.
3431
Bram Moolenaar071d4272004-06-13 20:20:40 +00003432filereadable({file}) *filereadable()*
3433 The result is a Number, which is TRUE when a file with the
3434 name {file} exists, and can be read. If {file} doesn't exist,
3435 or is a directory, the result is FALSE. {file} is any
3436 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003437 If you don't care about the file being readable you can use
3438 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003439 *file_readable()*
3440 Obsolete name: file_readable().
3441
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003442
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003443filewritable({file}) *filewritable()*
3444 The result is a Number, which is 1 when a file with the
3445 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00003446 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003447 directory, and we can write to it, the result is 2.
3448
3449
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003450filter({expr}, {string}) *filter()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003451 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003452 For each item in {expr} evaluate {string} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003453 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003454 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003455 For a |Dictionary| |v:key| has the key of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003456 Examples: >
3457 :call filter(mylist, 'v:val !~ "OLD"')
3458< Removes the items where "OLD" appears. >
3459 :call filter(mydict, 'v:key >= 8')
3460< Removes the items with a key below 8. >
3461 :call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003462< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00003463
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003464 Note that {string} is the result of expression and is then
3465 used as an expression again. Often it is good to use a
3466 |literal-string| to avoid having to double backslashes.
3467
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003468 The operation is done in-place. If you want a |List| or
3469 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00003470 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003471
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003472< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00003473 When an error is encountered while evaluating {string} no
3474 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003475
3476
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003477finddir({name}[, {path}[, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00003478 Find directory {name} in {path}. Supports both downwards and
3479 upwards recursive directory searches. See |file-searching|
3480 for the syntax of {path}.
3481 Returns the path of the first found match. When the found
3482 directory is below the current directory a relative path is
3483 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003484 If {path} is omitted or empty then 'path' is used.
3485 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003486 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00003487 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003488 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02003489 {only available when compiled with the |+file_in_path|
3490 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003491
3492findfile({name}[, {path}[, {count}]]) *findfile()*
3493 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003494 Uses 'suffixesadd'.
3495 Example: >
3496 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003497< Searches from the directory of the current file upwards until
3498 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003499
Bram Moolenaar446cb832008-06-24 21:56:24 +00003500float2nr({expr}) *float2nr()*
3501 Convert {expr} to a Number by omitting the part after the
3502 decimal point.
3503 {expr} must evaluate to a |Float| or a Number.
3504 When the value of {expr} is out of range for a |Number| the
3505 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
3506 in -0x80000000.
3507 Examples: >
3508 echo float2nr(3.95)
3509< 3 >
3510 echo float2nr(-23.45)
3511< -23 >
3512 echo float2nr(1.0e100)
3513< 2147483647 >
3514 echo float2nr(-1.0e150)
3515< -2147483647 >
3516 echo float2nr(1.0e-100)
3517< 0
3518 {only available when compiled with the |+float| feature}
3519
3520
3521floor({expr}) *floor()*
3522 Return the largest integral value less than or equal to
3523 {expr} as a |Float| (round down).
3524 {expr} must evaluate to a |Float| or a |Number|.
3525 Examples: >
3526 echo floor(1.856)
3527< 1.0 >
3528 echo floor(-5.456)
3529< -6.0 >
3530 echo floor(4.0)
3531< 4.0
3532 {only available when compiled with the |+float| feature}
3533
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003534
3535fmod({expr1}, {expr2}) *fmod()*
3536 Return the remainder of {expr1} / {expr2}, even if the
3537 division is not representable. Returns {expr1} - i * {expr2}
3538 for some integer i such that if {expr2} is non-zero, the
3539 result has the same sign as {expr1} and magnitude less than
3540 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003541 returned is zero. The value returned is a |Float|.
3542 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003543 Examples: >
3544 :echo fmod(12.33, 1.22)
3545< 0.13 >
3546 :echo fmod(-12.33, 1.22)
3547< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02003548 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003549
3550
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003551fnameescape({string}) *fnameescape()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003552 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003553 characters that have a special meaning, such as '%' and '|'
3554 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003555 For most systems the characters escaped are
3556 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
3557 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003558 A leading '+' and '>' is also escaped (special after |:edit|
3559 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003560 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003561 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003562 :exe "edit " . fnameescape(fname)
3563< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00003564 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00003565
Bram Moolenaar071d4272004-06-13 20:20:40 +00003566fnamemodify({fname}, {mods}) *fnamemodify()*
3567 Modify file name {fname} according to {mods}. {mods} is a
3568 string of characters like it is used for file names on the
3569 command line. See |filename-modifiers|.
3570 Example: >
3571 :echo fnamemodify("main.c", ":p:h")
3572< results in: >
3573 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00003574< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00003575 |expand()| first then.
3576
3577foldclosed({lnum}) *foldclosed()*
3578 The result is a Number. If the line {lnum} is in a closed
3579 fold, the result is the number of the first line in that fold.
3580 If the line {lnum} is not in a closed fold, -1 is returned.
3581
3582foldclosedend({lnum}) *foldclosedend()*
3583 The result is a Number. If the line {lnum} is in a closed
3584 fold, the result is the number of the last line in that fold.
3585 If the line {lnum} is not in a closed fold, -1 is returned.
3586
3587foldlevel({lnum}) *foldlevel()*
3588 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003589 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003590 returned. If there is no fold at line {lnum}, zero is
3591 returned. It doesn't matter if the folds are open or closed.
3592 When used while updating folds (from 'foldexpr') -1 is
3593 returned for lines where folds are still to be updated and the
3594 foldlevel is unknown. As a special case the level of the
3595 previous line is usually available.
3596
3597 *foldtext()*
3598foldtext() Returns a String, to be displayed for a closed fold. This is
3599 the default function used for the 'foldtext' option and should
3600 only be called from evaluating 'foldtext'. It uses the
3601 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
3602 The returned string looks like this: >
3603 +-- 45 lines: abcdef
Bram Moolenaar446cb832008-06-24 21:56:24 +00003604< The number of dashes depends on the foldlevel. The "45" is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003605 the number of lines in the fold. "abcdef" is the text in the
3606 first non-blank line of the fold. Leading white space, "//"
3607 or "/*" and the text from the 'foldmarker' and 'commentstring'
3608 options is removed.
3609 {not available when compiled without the |+folding| feature}
3610
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003611foldtextresult({lnum}) *foldtextresult()*
3612 Returns the text that is displayed for the closed fold at line
3613 {lnum}. Evaluates 'foldtext' in the appropriate context.
3614 When there is no closed fold at {lnum} an empty string is
3615 returned.
3616 {lnum} is used like with |getline()|. Thus "." is the current
3617 line, "'m" mark m, etc.
3618 Useful when exporting folded text, e.g., to HTML.
3619 {not available when compiled without the |+folding| feature}
3620
Bram Moolenaar071d4272004-06-13 20:20:40 +00003621 *foreground()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00003622foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00003623 a client to a Vim server. |remote_send()|
3624 On Win32 systems this might not work, the OS does not always
3625 allow a window to bring itself to the foreground. Use
3626 |remote_foreground()| instead.
3627 {only in the Win32, Athena, Motif and GTK GUI versions and the
3628 Win32 console version}
3629
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003630
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003631 *function()* *E700* *E922* *E923*
3632function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003633 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01003634 {name} can be the name of a user defined function or an
3635 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003636
Bram Moolenaar975b5272016-03-15 23:10:59 +01003637 {name} can also be a Funcref, also a partial. When it is a
3638 partial the dict stored in it will be used and the {dict}
3639 argument is not allowed. E.g.: >
3640 let FuncWithArg = function(dict.Func, [arg])
3641 let Broken = function(dict.Func, [arg], dict)
3642<
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003643 When {arglist} or {dict} is present this creates a partial.
3644 That mans the argument list and/or the dictionary is stored in
3645 the Funcref and will be used when the Funcref is called.
3646
3647 The arguments are passed to the function in front of other
3648 arguments. Example: >
3649 func Callback(arg1, arg2, name)
3650 ...
3651 let Func = function('Callback', ['one', 'two'])
3652 ...
3653 call Func('name')
3654< Invokes the function as with: >
3655 call Callback('one', 'two', 'name')
3656
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003657< The function() call can be nested to add more arguments to the
3658 Funcref. The extra arguments are appended to the list of
3659 arguments. Example: >
3660 func Callback(arg1, arg2, name)
3661 ...
3662 let Func = function('Callback', ['one'])
3663 let Func2 = function(Func, ['two'])
3664 ...
3665 call Func2('name')
3666< Invokes the function as with: >
3667 call Callback('one', 'two', 'name')
3668
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003669< The Dictionary is only useful when calling a "dict" function.
3670 In that case the {dict} is passed in as "self". Example: >
3671 function Callback() dict
3672 echo "called for " . self.name
3673 endfunction
3674 ...
3675 let context = {"name": "example"}
3676 let Func = function('Callback', context)
3677 ...
3678 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01003679< The use of function() is not needed when there are no extra
3680 arguments, these two are equivalent: >
3681 let Func = function('Callback', context)
3682 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01003683
3684< The argument list and the Dictionary can be combined: >
3685 function Callback(arg1, count) dict
3686 ...
3687 let context = {"name": "example"}
3688 let Func = function('Callback', ['one'], context)
3689 ...
3690 call Func(500)
3691< Invokes the function as with: >
3692 call context.Callback('one', 500)
3693
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003694
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003695garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02003696 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
3697 that have circular references.
3698
3699 There is hardly ever a need to invoke this function, as it is
3700 automatically done when Vim runs out of memory or is waiting
3701 for the user to press a key after 'updatetime'. Items without
3702 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003703 This is useful if you have deleted a very big |List| and/or
3704 |Dictionary| with circular references in a script that runs
3705 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02003706
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003707 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00003708 collection will also be done when exiting Vim, if it wasn't
3709 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00003710
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02003711garbagecollect_for_testing() *garbagecollect_for_testing()*
3712 Like garbagecollect(), but executed right away. This must
3713 only be called directly to avoid any structure to exist
3714 internally, and |v:testing| must have been set before calling
3715 any function.
3716
Bram Moolenaar677ee682005-01-27 14:41:15 +00003717get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003718 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003719 available return {default}. Return zero when {default} is
3720 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003721get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003722 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003723 item is not available return {default}. Return zero when
3724 {default} is omitted.
3725
Bram Moolenaar45360022005-07-21 21:08:21 +00003726 *getbufline()*
3727getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003728 Return a |List| with the lines starting from {lnum} to {end}
3729 (inclusive) in the buffer {expr}. If {end} is omitted, a
3730 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003731
3732 For the use of {expr}, see |bufname()| above.
3733
Bram Moolenaar661b1822005-07-28 22:36:45 +00003734 For {lnum} and {end} "$" can be used for the last line of the
3735 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00003736
3737 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003738 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003739
3740 When {end} is greater than the number of lines in the buffer,
3741 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003742 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00003743 returned.
3744
Bram Moolenaar661b1822005-07-28 22:36:45 +00003745 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003746 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00003747
3748 Example: >
3749 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003750
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003751getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003752 The result is the value of option or local buffer variable
3753 {varname} in buffer {expr}. Note that the name without "b:"
3754 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00003755 When {varname} is empty returns a dictionary with all the
3756 buffer-local variables.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00003757 This also works for a global or buffer-local option, but it
3758 doesn't work for a global variable, window-local variable or
3759 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003760 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01003761 When the buffer or variable doesn't exist {def} or an empty
3762 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003763 Examples: >
3764 :let bufmodified = getbufvar(1, "&mod")
3765 :echo "todo myvar = " . getbufvar("todo", "myvar")
3766<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003767getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00003768 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003769 If [expr] is omitted, wait until a character is available.
3770 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003771 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003772 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00003773 not consumed. Return zero if no character available.
3774
Bram Moolenaardfb18412013-12-11 18:53:29 +01003775 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaar91170f82006-05-05 21:15:17 +00003776 special key is returned. If it is an 8-bit character, the
3777 result is a number. Use nr2char() to convert it to a String.
3778 Otherwise a String is returned with the encoded character.
3779 For a special key it's a sequence of bytes starting with 0x80
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003780 (decimal: 128). This is the same value as the string
3781 "\<Key>", e.g., "\<Left>". The returned value is also a
3782 String when a modifier (shift, control, alt) was used that is
3783 not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003784
Bram Moolenaar822ff862014-06-12 21:46:14 +02003785 When [expr] is 0 and Esc is typed, there will be a short delay
3786 while Vim waits to see if this is the start of an escape
3787 sequence.
3788
Bram Moolenaardfb18412013-12-11 18:53:29 +01003789 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00003790 one-byte character it is the character itself as a number.
3791 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003792
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003793 Use getcharmod() to obtain any additional modifiers.
3794
Bram Moolenaar219b8702006-11-01 14:32:36 +00003795 When the user clicks a mouse button, the mouse event will be
3796 returned. The position can then be found in |v:mouse_col|,
3797 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3798 mouse as it would normally happen: >
3799 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003800 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00003801 exe v:mouse_win . "wincmd w"
3802 exe v:mouse_lnum
3803 exe "normal " . v:mouse_col . "|"
3804 endif
3805<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003806 There is no prompt, you will somehow have to make clear to the
3807 user that a character has to be typed.
3808 There is no mapping for the character.
3809 Key codes are replaced, thus when the user presses the <Del>
3810 key you get the code for the <Del> key, not the raw character
3811 sequence. Examples: >
3812 getchar() == "\<Del>"
3813 getchar() == "\<S-Left>"
3814< This example redefines "f" to ignore case: >
3815 :nmap f :call FindChar()<CR>
3816 :function FindChar()
3817 : let c = nr2char(getchar())
3818 : while col('.') < col('$') - 1
3819 : normal l
3820 : if getline('.')[col('.') - 1] ==? c
3821 : break
3822 : endif
3823 : endwhile
3824 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01003825<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003826 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01003827 |<CursorHold>|. Often you will want to ignore this and get
3828 another character: >
3829 :function GetKey()
3830 : let c = getchar()
3831 : while c == "\<CursorHold>"
3832 : let c = getchar()
3833 : endwhile
3834 : return c
3835 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00003836
3837getcharmod() *getcharmod()*
3838 The result is a Number which is the state of the modifiers for
3839 the last obtained character with getchar() or in another way.
3840 These values are added together:
3841 2 shift
3842 4 control
3843 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01003844 16 meta (when it's different from ALT)
3845 32 mouse double click
3846 64 mouse triple click
3847 96 mouse quadruple click (== 32 + 64)
3848 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003849 Only the modifiers that have not been included in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003850 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003851 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003852
Bram Moolenaardbd24b52015-08-11 14:26:19 +02003853getcharsearch() *getcharsearch()*
3854 Return the current character search information as a {dict}
3855 with the following entries:
3856
3857 char character previously used for a character
3858 search (|t|, |f|, |T|, or |F|); empty string
3859 if no character search has been performed
3860 forward direction of character search; 1 for forward,
3861 0 for backward
3862 until type of character search; 1 for a |t| or |T|
3863 character search, 0 for an |f| or |F|
3864 character search
3865
3866 This can be useful to always have |;| and |,| search
3867 forward/backward regardless of the direction of the previous
3868 character search: >
3869 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
3870 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
3871< Also see |setcharsearch()|.
3872
Bram Moolenaar071d4272004-06-13 20:20:40 +00003873getcmdline() *getcmdline()*
3874 Return the current command-line. Only works when the command
3875 line is being edited, thus requires use of |c_CTRL-\_e| or
3876 |c_CTRL-R_=|.
3877 Example: >
3878 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003879< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003880
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003881getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003882 Return the position of the cursor in the command line as a
3883 byte count. The first column is 1.
3884 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003885 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3886 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003887 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3888
3889getcmdtype() *getcmdtype()*
3890 Return the current command-line type. Possible return values
3891 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00003892 : normal Ex command
3893 > debug mode command |debug-mode|
3894 / forward search command
3895 ? backward search command
3896 @ |input()| command
3897 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02003898 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003899 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02003900 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
3901 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00003902 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003903
Bram Moolenaarfb539272014-08-22 19:21:47 +02003904getcmdwintype() *getcmdwintype()*
3905 Return the current |command-line-window| type. Possible return
3906 values are the same as |getcmdtype()|. Returns an empty string
3907 when not in the command-line window.
3908
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003909 *getcurpos()*
3910getcurpos() Get the position of the cursor. This is like getpos('.'), but
3911 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01003912 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003913 The "curswant" number is the preferred column when moving the
3914 cursor vertically.
3915 This can be used to save and restore the cursor position: >
3916 let save_cursor = getcurpos()
3917 MoveTheCursorAround
3918 call setpos('.', save_cursor)
Bram Moolenaarfb539272014-08-22 19:21:47 +02003919<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003920 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01003921getcwd([{winnr} [, {tabnr}]])
3922 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00003923 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01003924 Without arguments, for the current window.
3925
3926 With {winnr} return the local current directory of this window
3927 in the current tab page.
3928 With {winnr} and {tabnr} return the local current directory of
3929 the window in the specified tab page.
3930 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003931
3932getfsize({fname}) *getfsize()*
3933 The result is a Number, which is the size in bytes of the
3934 given file {fname}.
3935 If {fname} is a directory, 0 is returned.
3936 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00003937 If the size of {fname} is too big to fit in a Number then -2
3938 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003939
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003940getfontname([{name}]) *getfontname()*
3941 Without an argument returns the name of the normal font being
3942 used. Like what is used for the Normal highlight group
3943 |hl-Normal|.
3944 With an argument a check is done whether {name} is a valid
3945 font name. If not then an empty string is returned.
3946 Otherwise the actual font name is returned, or {name} if the
3947 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00003948 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003949 gvimrc file. Use the |GUIEnter| autocommand to use this
3950 function just after the GUI has started.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003951 Note that the GTK 2 GUI accepts any font name, thus checking
3952 for a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00003953
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003954getfperm({fname}) *getfperm()*
3955 The result is a String, which is the read, write, and execute
3956 permissions of the given file {fname}.
3957 If {fname} does not exist or its directory cannot be read, an
3958 empty string is returned.
3959 The result is of the form "rwxrwxrwx", where each group of
3960 "rwx" flags represent, in turn, the permissions of the owner
3961 of the file, the group the file belongs to, and other users.
3962 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02003963 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003964 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02003965 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003966< This will hopefully (from a security point of view) display
3967 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003968
Bram Moolenaar80492532016-03-08 17:08:53 +01003969 For setting permissins use |setfperm()|.
3970
Bram Moolenaar071d4272004-06-13 20:20:40 +00003971getftime({fname}) *getftime()*
3972 The result is a Number, which is the last modification time of
3973 the given file {fname}. The value is measured as seconds
3974 since 1st Jan 1970, and may be passed to strftime(). See also
3975 |localtime()| and |strftime()|.
3976 If the file {fname} can't be found -1 is returned.
3977
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003978getftype({fname}) *getftype()*
3979 The result is a String, which is a description of the kind of
3980 file of the given file {fname}.
3981 If {fname} does not exist an empty string is returned.
3982 Here is a table over different kinds of files and their
3983 results:
3984 Normal file "file"
3985 Directory "dir"
3986 Symbolic link "link"
3987 Block device "bdev"
3988 Character device "cdev"
3989 Socket "socket"
3990 FIFO "fifo"
3991 All other "other"
3992 Example: >
3993 getftype("/home")
3994< Note that a type such as "link" will only be returned on
3995 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01003996 "file" are returned. On MS-Windows a symbolic link to a
3997 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003998
Bram Moolenaar071d4272004-06-13 20:20:40 +00003999 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004000getline({lnum} [, {end}])
4001 Without {end} the result is a String, which is line {lnum}
4002 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004003 getline(1)
4004< When {lnum} is a String that doesn't start with a
4005 digit, line() is called to translate the String into a Number.
4006 To get the line under the cursor: >
4007 getline(".")
4008< When {lnum} is smaller than 1 or bigger than the number of
4009 lines in the buffer, an empty string is returned.
4010
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004011 When {end} is given the result is a |List| where each item is
4012 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004013 including line {end}.
4014 {end} is used in the same way as {lnum}.
4015 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004016 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004017 Example: >
4018 :let start = line('.')
4019 :let end = search("^$") - 1
4020 :let lines = getline(start, end)
4021
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004022< To get lines from another buffer see |getbufline()|
4023
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004024getloclist({nr}) *getloclist()*
4025 Returns a list with all the entries in the location list for
4026 window {nr}. When {nr} is zero the current window is used.
4027 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00004028 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004029 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004030
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004031getmatches() *getmatches()*
4032 Returns a |List| with all matches previously defined by
4033 |matchadd()| and the |:match| commands. |getmatches()| is
4034 useful in combination with |setmatches()|, as |setmatches()|
4035 can restore a list of matches saved by |getmatches()|.
4036 Example: >
4037 :echo getmatches()
4038< [{'group': 'MyGroup1', 'pattern': 'TODO',
4039 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4040 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4041 :let m = getmatches()
4042 :call clearmatches()
4043 :echo getmatches()
4044< [] >
4045 :call setmatches(m)
4046 :echo getmatches()
4047< [{'group': 'MyGroup1', 'pattern': 'TODO',
4048 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4049 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4050 :unlet m
4051<
Bram Moolenaar822ff862014-06-12 21:46:14 +02004052 *getpid()*
4053getpid() Return a Number which is the process ID of the Vim process.
4054 On Unix and MS-Windows this is a unique number, until Vim
4055 exits. On MS-DOS it's always zero.
4056
4057 *getpos()*
4058getpos({expr}) Get the position for {expr}. For possible values of {expr}
4059 see |line()|. For getting the cursor position see
4060 |getcurpos()|.
4061 The result is a |List| with four numbers:
4062 [bufnum, lnum, col, off]
4063 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4064 is the buffer number of the mark.
4065 "lnum" and "col" are the position in the buffer. The first
4066 column is 1.
4067 The "off" number is zero, unless 'virtualedit' is used. Then
4068 it is the offset in screen columns from the start of the
4069 character. E.g., a position within a <Tab> or after the last
4070 character.
4071 Note that for '< and '> Visual mode matters: when it is "V"
4072 (visual line mode) the column of '< is zero and the column of
4073 '> is a large number.
4074 This can be used to save and restore the position of a mark: >
4075 let save_a_mark = getpos("'a")
4076 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01004077 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02004078< Also see |getcurpos()| and |setpos()|.
4079
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004080
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004081getqflist() *getqflist()*
4082 Returns a list with all the current quickfix errors. Each
4083 list item is a dictionary with these entries:
4084 bufnr number of buffer that has the file name, use
4085 bufname() to get the name
4086 lnum line number in the buffer (first line is 1)
4087 col column number (first column is 1)
Bram Moolenaar582fd852005-03-28 20:58:01 +00004088 vcol non-zero: "col" is visual column
4089 zero: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004090 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004091 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004092 text description of the error
4093 type type of the error, 'E', '1', etc.
4094 valid non-zero: recognized error message
4095
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004096 When there is no error list or it's empty an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00004097 returned. Quickfix list entries with non-existing buffer
4098 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00004099
Bram Moolenaar68b76a62005-03-25 21:53:48 +00004100 Useful application: Find pattern matches in multiple files and
4101 do something with them: >
4102 :vimgrep /theword/jg *.c
4103 :for d in getqflist()
4104 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
4105 :endfor
4106
4107
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004108getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004109 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004110 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004111 :let cliptext = getreg('*')
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004112< When {regname} was not set the result is a empty string.
4113
4114 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004115 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00004116 getreg('=', 1) returns the expression itself, so that it can
4117 be restored with |setreg()|. For other registers the extra
4118 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004119
4120 If {list} is present and non-zero, the result type is changed
4121 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02004122 about zero bytes possibly present inside register: without
4123 third argument both NLs and zero bytes are represented as NLs
4124 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004125 When the register was not set an empty list is returned.
4126
Bram Moolenaar071d4272004-06-13 20:20:40 +00004127 If {regname} is not specified, |v:register| is used.
4128
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004129
Bram Moolenaar071d4272004-06-13 20:20:40 +00004130getregtype([{regname}]) *getregtype()*
4131 The result is a String, which is type of register {regname}.
4132 The value will be one of:
4133 "v" for |characterwise| text
4134 "V" for |linewise| text
4135 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01004136 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00004137 <CTRL-V> is one character with value 0x16.
4138 If {regname} is not specified, |v:register| is used.
4139
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004140gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004141 Get the value of a tab-local variable {varname} in tab page
4142 {tabnr}. |t:var|
4143 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02004144 When {varname} is empty a dictionary with all tab-local
4145 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004146 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004147 When the tab or variable doesn't exist {def} or an empty
4148 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02004149
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004150gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004151 Get the value of window-local variable {varname} in window
4152 {winnr} in tab page {tabnr}.
4153 When {varname} starts with "&" get the value of a window-local
4154 option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004155 When {varname} is empty a dictionary with all window-local
4156 variables is returned.
4157 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004158 Tabs are numbered starting with one. For the current tabpage
4159 use |getwinvar()|.
4160 When {winnr} is zero the current window is used.
4161 This also works for a global option, buffer-local option and
4162 window-local option, but it doesn't work for a global variable
4163 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004164 When the tab, window or variable doesn't exist {def} or an
4165 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004166 Examples: >
4167 :let list_is_on = gettabwinvar(1, 2, '&list')
4168 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004169<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004170 *getwinposx()*
4171getwinposx() The result is a Number, which is the X coordinate in pixels of
4172 the left hand side of the GUI Vim window. The result will be
4173 -1 if the information is not available.
4174
4175 *getwinposy()*
4176getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar446cb832008-06-24 21:56:24 +00004177 the top of the GUI Vim window. The result will be -1 if the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004178 information is not available.
4179
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004180getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00004181 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004182 Examples: >
4183 :let list_is_on = getwinvar(2, '&list')
4184 :echo "myvar = " . getwinvar(1, 'myvar')
4185<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004186glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004187 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004188 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004189
4190 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004191 the 'suffixes' and 'wildignore' options apply: Names matching
4192 one of the patterns in 'wildignore' will be skipped and
4193 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01004194 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004195
4196 When {list} is present and it is non-zero the result is a List
4197 with all matching files. The advantage of using a List is,
4198 you also get filenames containing newlines correctly.
4199 Otherwise the result is a String and when there are several
4200 matches, they are separated by <NL> characters.
4201
4202 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004203
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02004204 A name for a non-existing file is not included. A symbolic
4205 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004206 However, when the {alllinks} argument is present and it is
4207 non-zero then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004208
4209 For most systems backticks can be used to get files names from
4210 any external command. Example: >
4211 :let tagfiles = glob("`find . -name tags -print`")
4212 :let &tags = substitute(tagfiles, "\n", ",", "g")
4213< The result of the program inside the backticks should be one
Bram Moolenaar446cb832008-06-24 21:56:24 +00004214 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004215
4216 See |expand()| for expanding special Vim variables. See
4217 |system()| for getting the raw output of an external command.
4218
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01004219glob2regpat({expr}) *glob2regpat()*
4220 Convert a file pattern, as used by glob(), into a search
4221 pattern. The result can be used to match with a string that
4222 is a file name. E.g. >
4223 if filename =~ glob2regpat('Make*.mak')
4224< This is equivalent to: >
4225 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01004226< When {expr} is an empty string the result is "^$", match an
4227 empty string.
4228
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004229 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004230globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00004231 Perform glob() on all directories in {path} and concatenate
4232 the results. Example: >
4233 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004234<
4235 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00004236 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004237 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004238 To add a comma inside a directory name escape it with a
4239 backslash. Note that on MS-Windows a directory may have a
4240 trailing backslash, remove it if you put a comma after it.
4241 If the expansion fails for one of the directories, there is no
4242 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004243
4244 Unless the optional {nosuf} argument is given and is non-zero,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00004245 the 'suffixes' and 'wildignore' options apply: Names matching
4246 one of the patterns in 'wildignore' will be skipped and
4247 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004248
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02004249 When {list} is present and it is non-zero the result is a List
4250 with all matching files. The advantage of using a List is, you
4251 also get filenames containing newlines correctly. Otherwise
4252 the result is a String and when there are several matches,
4253 they are separated by <NL> characters. Example: >
4254 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
4255<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004256 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01004257
Bram Moolenaar02743632005-07-25 20:42:36 +00004258 The "**" item can be used to search in a directory tree.
4259 For example, to find all "README.txt" files in the directories
4260 in 'runtimepath' and below: >
4261 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00004262< Upwards search and limiting the depth of "**" is not
4263 supported, thus using 'path' will not always work properly.
4264
Bram Moolenaar071d4272004-06-13 20:20:40 +00004265 *has()*
4266has({feature}) The result is a Number, which is 1 if the feature {feature} is
4267 supported, zero otherwise. The {feature} argument is a
4268 string. See |feature-list| below.
4269 Also see |exists()|.
4270
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004271
4272has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004273 The result is a Number, which is 1 if |Dictionary| {dict} has
4274 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004275
Bram Moolenaarc9703302016-01-17 21:49:33 +01004276haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
4277 The result is a Number, which is 1 when the window has set a
4278 local path via |:lcd|, and 0 otherwise.
4279
4280 Without arguments use the current window.
4281 With {winnr} use this window in the current tab page.
4282 With {winnr} and {tabnr} use the window in the specified tab
4283 page.
4284 Return 0 if the arguments are invalid.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004285
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004286hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004287 The result is a Number, which is 1 if there is a mapping that
4288 contains {what} in somewhere in the rhs (what it is mapped to)
4289 and this mapping exists in one of the modes indicated by
4290 {mode}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004291 When {abbr} is there and it is non-zero use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00004292 instead of mappings. Don't forget to specify Insert and/or
4293 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004294 Both the global mappings and the mappings local to the current
4295 buffer are checked for a match.
4296 If no matching mapping is found 0 is returned.
4297 The following characters are recognized in {mode}:
4298 n Normal mode
4299 v Visual mode
4300 o Operator-pending mode
4301 i Insert mode
4302 l Language-Argument ("r", "f", "t", etc.)
4303 c Command-line mode
4304 When {mode} is omitted, "nvo" is used.
4305
4306 This function is useful to check if a mapping already exists
Bram Moolenaar446cb832008-06-24 21:56:24 +00004307 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004308 :if !hasmapto('\ABCdoit')
4309 : map <Leader>d \ABCdoit
4310 :endif
4311< This installs the mapping to "\ABCdoit" only if there isn't
4312 already a mapping to "\ABCdoit".
4313
4314histadd({history}, {item}) *histadd()*
4315 Add the String {item} to the history {history} which can be
4316 one of: *hist-names*
4317 "cmd" or ":" command line history
4318 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00004319 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00004320 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02004321 "debug" or ">" debug command history
4322 The {history} string does not need to be the whole name, one
4323 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004324 If {item} does already exist in the history, it will be
4325 shifted to become the newest entry.
4326 The result is a Number: 1 if the operation was successful,
4327 otherwise 0 is returned.
4328
4329 Example: >
4330 :call histadd("input", strftime("%Y %b %d"))
4331 :let date=input("Enter date: ")
4332< This function is not available in the |sandbox|.
4333
4334histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004335 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004336 for the possible values of {history}.
4337
Bram Moolenaarc236c162008-07-13 17:41:49 +00004338 If the parameter {item} evaluates to a String, it is used as a
4339 regular expression. All entries matching that expression will
4340 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004341 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004342 If {item} evaluates to a Number, it will be interpreted as
4343 an index, see |:history-indexing|. The respective entry will
4344 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004345
4346 The result is a Number: 1 for a successful operation,
4347 otherwise 0 is returned.
4348
4349 Examples:
4350 Clear expression register history: >
4351 :call histdel("expr")
4352<
4353 Remove all entries starting with "*" from the search history: >
4354 :call histdel("/", '^\*')
4355<
4356 The following three are equivalent: >
4357 :call histdel("search", histnr("search"))
4358 :call histdel("search", -1)
4359 :call histdel("search", '^'.histget("search", -1).'$')
4360<
4361 To delete the last search pattern and use the last-but-one for
4362 the "n" command and 'hlsearch': >
4363 :call histdel("search", -1)
4364 :let @/ = histget("search", -1)
4365
4366histget({history} [, {index}]) *histget()*
4367 The result is a String, the entry with Number {index} from
4368 {history}. See |hist-names| for the possible values of
4369 {history}, and |:history-indexing| for {index}. If there is
4370 no such entry, an empty String is returned. When {index} is
4371 omitted, the most recent item from the history is used.
4372
4373 Examples:
4374 Redo the second last search from history. >
4375 :execute '/' . histget("search", -2)
4376
4377< Define an Ex command ":H {num}" that supports re-execution of
4378 the {num}th entry from the output of |:history|. >
4379 :command -nargs=1 H execute histget("cmd", 0+<args>)
4380<
4381histnr({history}) *histnr()*
4382 The result is the Number of the current entry in {history}.
4383 See |hist-names| for the possible values of {history}.
4384 If an error occurred, -1 is returned.
4385
4386 Example: >
4387 :let inp_index = histnr("expr")
4388<
4389hlexists({name}) *hlexists()*
4390 The result is a Number, which is non-zero if a highlight group
4391 called {name} exists. This is when the group has been
4392 defined in some way. Not necessarily when highlighting has
4393 been defined for it, it may also have been used for a syntax
4394 item.
4395 *highlight_exists()*
4396 Obsolete name: highlight_exists().
4397
4398 *hlID()*
4399hlID({name}) The result is a Number, which is the ID of the highlight group
4400 with name {name}. When the highlight group doesn't exist,
4401 zero is returned.
4402 This can be used to retrieve information about the highlight
Bram Moolenaar446cb832008-06-24 21:56:24 +00004403 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004404 "Comment" group: >
4405 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
4406< *highlightID()*
4407 Obsolete name: highlightID().
4408
4409hostname() *hostname()*
4410 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00004411 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00004412 256 characters long are truncated.
4413
4414iconv({expr}, {from}, {to}) *iconv()*
4415 The result is a String, which is the text {expr} converted
4416 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004417 When the conversion completely fails an empty string is
4418 returned. When some characters could not be converted they
4419 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004420 The encoding names are whatever the iconv() library function
4421 can accept, see ":!man 3 iconv".
4422 Most conversions require Vim to be compiled with the |+iconv|
4423 feature. Otherwise only UTF-8 to latin1 conversion and back
4424 can be done.
4425 This can be used to display messages with special characters,
4426 no matter what 'encoding' is set to. Write the message in
4427 UTF-8 and use: >
4428 echo iconv(utf8_str, "utf-8", &enc)
4429< Note that Vim uses UTF-8 for all Unicode encodings, conversion
4430 from/to UCS-2 is automatically changed to use UTF-8. You
4431 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004432 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004433
4434 *indent()*
4435indent({lnum}) The result is a Number, which is indent of line {lnum} in the
4436 current buffer. The indent is counted in spaces, the value
4437 of 'tabstop' is relevant. {lnum} is used just like in
4438 |getline()|.
4439 When {lnum} is invalid -1 is returned.
4440
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004441
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004442index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004443 Return the lowest index in |List| {list} where the item has a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004444 value equal to {expr}. There is no automatic conversion, so
4445 the String "4" is different from the Number 4. And the number
4446 4 is different from the Float 4.0. The value of 'ignorecase'
4447 is not used here, case always matters.
Bram Moolenaar748bf032005-02-02 23:04:36 +00004448 If {start} is given then start looking at the item with index
4449 {start} (may be negative for an item relative to the end).
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004450 When {ic} is given and it is non-zero, ignore case. Otherwise
4451 case must match.
4452 -1 is returned when {expr} is not found in {list}.
4453 Example: >
4454 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004455 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004456
4457
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004458input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004459 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004460 the command-line. The {prompt} argument is either a prompt
4461 string, or a blank string (for no prompt). A '\n' can be used
4462 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004463 The highlighting set with |:echohl| is used for the prompt.
4464 The input is entered just like a command-line, with the same
Bram Moolenaar446cb832008-06-24 21:56:24 +00004465 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004466 for lines typed for input().
4467 Example: >
4468 :if input("Coffee or beer? ") == "beer"
4469 : echo "Cheers!"
4470 :endif
4471<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004472 If the optional {text} argument is present and not empty, this
4473 is used for the default reply, as if the user typed this.
4474 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004475 :let color = input("Color? ", "white")
4476
4477< The optional {completion} argument specifies the type of
4478 completion supported for the input. Without it completion is
Bram Moolenaar446cb832008-06-24 21:56:24 +00004479 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004480 that can be supplied to a user-defined command using the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004481 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004482 more information. Example: >
4483 let fname = input("File: ", "", "file")
4484<
4485 NOTE: This function must not be used in a startup file, for
4486 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004487 Note: When input() is called from within a mapping it will
4488 consume remaining characters from that mapping, because a
4489 mapping is handled like the characters were typed.
4490 Use |inputsave()| before input() and |inputrestore()|
4491 after input() to avoid that. Another solution is to avoid
4492 that further characters follow in the mapping, e.g., by using
4493 |:execute| or |:normal|.
4494
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004495 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004496 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
4497 :function GetFoo()
4498 : call inputsave()
4499 : let g:Foo = input("enter search pattern: ")
4500 : call inputrestore()
4501 :endfunction
4502
4503inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004504 Like |input()|, but when the GUI is running and text dialogs
4505 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004506 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02004507 :let n = inputdialog("value for shiftwidth", shiftwidth())
4508 :if n != ""
4509 : let &sw = n
4510 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00004511< When the dialog is cancelled {cancelreturn} is returned. When
4512 omitted an empty string is returned.
4513 Hitting <Enter> works like pressing the OK button. Hitting
4514 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004515 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004516
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004517inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004518 {textlist} must be a |List| of strings. This |List| is
4519 displayed, one string per line. The user will be prompted to
4520 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004521 The user can also select an item by clicking on it with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00004522 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004523 above the first item a negative number is returned. When
4524 clicking on the prompt one more than the length of {textlist}
4525 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004526 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +00004527 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004528 the start of the string. And put a prompt in the first item.
4529 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00004530 let color = inputlist(['Select color:', '1. red',
4531 \ '2. green', '3. blue'])
4532
Bram Moolenaar071d4272004-06-13 20:20:40 +00004533inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004534 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004535 Should be called the same number of times inputsave() is
4536 called. Calling it more often is harmless though.
4537 Returns 1 when there is nothing to restore, 0 otherwise.
4538
4539inputsave() *inputsave()*
4540 Preserve typeahead (also from mappings) and clear it, so that
4541 a following prompt gets input from the user. Should be
4542 followed by a matching inputrestore() after the prompt. Can
4543 be used several times, in which case there must be just as
4544 many inputrestore() calls.
4545 Returns 1 when out of memory, 0 otherwise.
4546
4547inputsecret({prompt} [, {text}]) *inputsecret()*
4548 This function acts much like the |input()| function with but
4549 two exceptions:
4550 a) the user's response will be displayed as a sequence of
4551 asterisks ("*") thereby keeping the entry secret, and
4552 b) the user's response will not be recorded on the input
4553 |history| stack.
4554 The result is a String, which is whatever the user actually
4555 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004556 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004557
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004558insert({list}, {item} [, {idx}]) *insert()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004559 Insert {item} at the start of |List| {list}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004560 If {idx} is specified insert {item} before the item with index
Bram Moolenaar446cb832008-06-24 21:56:24 +00004561 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004562 like omitting {idx}. A negative {idx} is also possible, see
4563 |list-index|. -1 inserts just before the last item.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004564 Returns the resulting |List|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004565 :let mylist = insert([2, 3, 5], 1)
4566 :call insert(mylist, 4, -1)
4567 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004568< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004569 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004570 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004571
Bram Moolenaard6e256c2011-12-14 15:32:50 +01004572invert({expr}) *invert()*
4573 Bitwise invert. The argument is converted to a number. A
4574 List, Dict or Float argument causes an error. Example: >
4575 :let bits = invert(bits)
4576
Bram Moolenaar071d4272004-06-13 20:20:40 +00004577isdirectory({directory}) *isdirectory()*
4578 The result is a Number, which is non-zero when a directory
4579 with the name {directory} exists. If {directory} doesn't
4580 exist, or isn't a directory, the result is FALSE. {directory}
4581 is any expression, which is used as a String.
4582
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004583islocked({expr}) *islocked()* *E786*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004584 The result is a Number, which is non-zero when {expr} is the
4585 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004586 {expr} must be the name of a variable, |List| item or
4587 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004588 :let alist = [0, ['a', 'b'], 2, 3]
4589 :lockvar 1 alist
4590 :echo islocked('alist') " 1
4591 :echo islocked('alist[1]') " 0
4592
4593< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004594 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00004595
Bram Moolenaarf3913272016-02-25 00:00:01 +01004596isnan({expr}) *isnan()*
4597 Return non-zero if {expr} is a float with value NaN. >
4598 echo isnan(0.0 / 0.0)
4599< 1 ~
4600
4601 {only available when compiled with the |+float| feature}
4602
Bram Moolenaar677ee682005-01-27 14:41:15 +00004603items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004604 Return a |List| with all the key-value pairs of {dict}. Each
4605 |List| item is a list with two items: the key of a {dict}
4606 entry and the value of this entry. The |List| is in arbitrary
4607 order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00004608
Bram Moolenaar38a55632016-02-15 22:07:32 +01004609job_getchannel({job}) *job_getchannel()*
4610 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01004611 To check if the job has no channel: >
4612 if string(job_getchannel()) == 'channel fail'
4613<
Bram Moolenaar38a55632016-02-15 22:07:32 +01004614 {only available when compiled with the |+job| feature}
4615
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004616job_info({job}) *job_info()*
4617 Returns a Dictionary with information about {job}:
4618 "status" what |job_status()| returns
4619 "channel" what |job_getchannel()| returns
4620 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01004621 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004622 "stoponexit" |job-stoponexit|
4623
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004624job_setoptions({job}, {options}) *job_setoptions()*
4625 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01004626 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01004627 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004628
Bram Moolenaar38a55632016-02-15 22:07:32 +01004629job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01004630 Start a job and return a Job object. Unlike |system()| and
4631 |:!cmd| this does not wait for the job to finish.
4632
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004633 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01004634 Unix it is split up in white-separated parts to be passed to
4635 execvp(). Arguments in double quotes can contain white space.
4636
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004637 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01004638 and further items are the arguments. All items are converted
4639 to String. This works best on Unix.
4640
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004641 On MS-Windows, job_start() makes a GUI application hidden. If
4642 want to show it, Use |:!start| instead.
4643
Bram Moolenaar835dc632016-02-07 14:27:38 +01004644 The command is executed directly, not through a shell, the
4645 'shell' option is not used. To use the shell: >
4646 let job = job_start(["/bin/sh", "-c", "echo hello"])
4647< Or: >
4648 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004649< Note that this will start two processes, the shell and the
4650 command it executes. If you don't want this use the "exec"
4651 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004652
4653 On Unix $PATH is used to search for the executable only when
4654 the command does not contain a slash.
4655
4656 The job will use the same terminal as Vim. If it reads from
4657 stdin the job and Vim will be fighting over input, that
4658 doesn't work. Redirect stdin and stdout to avoid problems: >
4659 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
4660<
4661 The returned Job object can be used to get the status with
4662 |job_status()| and stop the job with |job_stop()|.
4663
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004664 {options} must be a Dictionary. It can contain many optional
4665 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004666
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004667 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004668
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004669job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01004670 Returns a String with the status of {job}:
4671 "run" job is running
4672 "fail" job failed to start
4673 "dead" job died or was stopped after running
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004674
Bram Moolenaar03413f42016-04-12 21:07:15 +02004675 If an exit callback was set with the "exit_cb" option and the
Bram Moolenaar02e83b42016-02-21 20:10:26 +01004676 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004677
Bram Moolenaar8950a562016-03-12 15:22:55 +01004678 For more information see |job_info()|.
4679
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004680 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004681
4682job_stop({job} [, {how}]) *job_stop()*
4683 Stop the {job}. This can also be used to signal the job.
4684
Bram Moolenaar923d9262016-02-25 20:56:01 +01004685 When {how} is omitted or is "term" the job will be terminated.
4686 For Unix SIGTERM is sent. On MS-Windows the job will be
4687 terminated forcedly (there is no "gentle" way).
4688 This goes to the process group, thus children may also be
4689 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004690
Bram Moolenaar923d9262016-02-25 20:56:01 +01004691 Effect for Unix:
4692 "term" SIGTERM (default)
4693 "hup" SIGHUP
4694 "quit" SIGQUIT
4695 "int" SIGINT
4696 "kill" SIGKILL (strongest way to stop)
4697 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01004698
Bram Moolenaar923d9262016-02-25 20:56:01 +01004699 Effect for MS-Windows:
4700 "term" terminate process forcedly (default)
4701 "hup" CTRL_BREAK
4702 "quit" CTRL_BREAK
4703 "int" CTRL_C
4704 "kill" terminate process forcedly
4705 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004706
4707 On Unix the signal is sent to the process group. This means
4708 that when the job is "sh -c command" it affects both the shell
4709 and the command.
4710
Bram Moolenaar835dc632016-02-07 14:27:38 +01004711 The result is a Number: 1 if the operation could be executed,
4712 0 if "how" is not supported on the system.
4713 Note that even when the operation was executed, whether the
4714 job was actually stopped needs to be checked with
4715 job_status().
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004716 The status of the job isn't checked, the operation will even
4717 be done when Vim thinks the job isn't running.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004718
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004719 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01004720
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004721join({list} [, {sep}]) *join()*
4722 Join the items in {list} together into one String.
4723 When {sep} is specified it is put in between the items. If
4724 {sep} is omitted a single space is used.
4725 Note that {sep} is not added at the end. You might want to
4726 add it there too: >
4727 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004728< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004729 converted into a string like with |string()|.
4730 The opposite function is |split()|.
4731
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004732js_decode({string}) *js_decode()*
4733 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004734 - Object key names do not have to be in quotes.
4735 - Empty items in an array (between two commas) are allowed and
4736 result in v:none items.
4737
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004738js_encode({expr}) *js_encode()*
4739 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004740 - Object key names are not in quotes.
4741 - v:none items in an array result in an empty item between
4742 commas.
4743 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004744 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004745 Will be encoded as:
4746 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004747 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004748 [1,null,{"one":1},null] ~
4749 This encoding is valid for JavaScript. It is more efficient
4750 than JSON, especially when using an array with optional items.
4751
4752
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004753json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01004754 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004755 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01004756 JSON and Vim values.
4757 The decoding is permissive:
4758 - A trailing comma in an array and object is ignored.
Bram Moolenaar705ada12016-01-24 17:56:50 +01004759 - More floating point numbers are recognized, e.g. "1." for
4760 "1.0".
Bram Moolenaar009d84a2016-01-28 14:12:00 +01004761 The result must be a valid Vim type:
4762 - An empty object member name is not allowed.
4763 - Duplicate object member names are not allowed.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004764
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01004765json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01004766 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004767 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01004768 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004769 Vim values are converted as follows:
4770 Number decimal number
4771 Float floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01004772 Float nan "NaN"
4773 Float inf "Infinity"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004774 String in double quotes (possibly null)
Bram Moolenaar705ada12016-01-24 17:56:50 +01004775 Funcref not possible, error
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004776 List as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02004777 used recursively: []
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004778 Dict as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02004779 used recursively: {}
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004780 v:false "false"
4781 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01004782 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004783 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01004784 Note that NaN and Infinity are passed on as values. This is
4785 missing in the JSON standard, but several implementations do
4786 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01004787
Bram Moolenaard8b02732005-01-14 21:48:43 +00004788keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004789 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaard8b02732005-01-14 21:48:43 +00004790 arbitrary order.
4791
Bram Moolenaar13065c42005-01-08 16:08:21 +00004792 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004793len({expr}) The result is a Number, which is the length of the argument.
4794 When {expr} is a String or a Number the length in bytes is
4795 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004796 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004797 returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004798 When {expr} is a |Dictionary| the number of entries in the
4799 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004800 Otherwise an error is given.
4801
Bram Moolenaar071d4272004-06-13 20:20:40 +00004802 *libcall()* *E364* *E368*
4803libcall({libname}, {funcname}, {argument})
4804 Call function {funcname} in the run-time library {libname}
4805 with single argument {argument}.
4806 This is useful to call functions in a library that you
4807 especially made to be used with Vim. Since only one argument
4808 is possible, calling standard library functions is rather
4809 limited.
4810 The result is the String returned by the function. If the
4811 function returns NULL, this will appear as an empty string ""
4812 to Vim.
4813 If the function returns a number, use libcallnr()!
4814 If {argument} is a number, it is passed to the function as an
4815 int; if {argument} is a string, it is passed as a
4816 null-terminated string.
4817 This function will fail in |restricted-mode|.
4818
4819 libcall() allows you to write your own 'plug-in' extensions to
4820 Vim without having to recompile the program. It is NOT a
4821 means to call system functions! If you try to do so Vim will
4822 very probably crash.
4823
4824 For Win32, the functions you write must be placed in a DLL
4825 and use the normal C calling convention (NOT Pascal which is
4826 used in Windows System DLLs). The function must take exactly
4827 one parameter, either a character pointer or a long integer,
4828 and must return a character pointer or NULL. The character
4829 pointer returned must point to memory that will remain valid
4830 after the function has returned (e.g. in static data in the
4831 DLL). If it points to allocated memory, that memory will
4832 leak away. Using a static buffer in the function should work,
4833 it's then freed when the DLL is unloaded.
4834
4835 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00004836 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00004837 because Vim thinks it's a pointer.
4838 For Win32 systems, {libname} should be the filename of the DLL
4839 without the ".DLL" suffix. A full path is only required if
4840 the DLL is not in the usual places.
4841 For Unix: When compiling your own plugins, remember that the
4842 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004843 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004844 feature is present}
4845 Examples: >
4846 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004847<
4848 *libcallnr()*
4849libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004850 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004851 int instead of a string.
4852 {only in Win32 on some Unix versions, when the |+libcall|
4853 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00004854 Examples: >
4855 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004856 :call libcallnr("libc.so", "printf", "Hello World!\n")
4857 :call libcallnr("libc.so", "sleep", 10)
4858<
4859 *line()*
4860line({expr}) The result is a Number, which is the line number of the file
4861 position given with {expr}. The accepted positions are:
4862 . the cursor position
4863 $ the last line in the current buffer
4864 'x position of mark x (if the mark is not set, 0 is
4865 returned)
Bram Moolenaarc7453f52006-02-10 23:20:28 +00004866 w0 first line visible in current window
4867 w$ last line visible in current window
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00004868 v In Visual mode: the start of the Visual area (the
4869 cursor is the end). When not in Visual mode
4870 returns the cursor position. Differs from |'<| in
4871 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004872 Note that a mark in another file can be used. The line number
4873 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00004874 To get the column number use |col()|. To get both use
4875 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004876 Examples: >
4877 line(".") line number of the cursor
4878 line("'t") line number of mark t
4879 line("'" . marker) line number of mark marker
4880< *last-position-jump*
4881 This autocommand jumps to the last known position in a file
4882 just after opening it, if the '" mark is set: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004883 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00004884
Bram Moolenaar071d4272004-06-13 20:20:40 +00004885line2byte({lnum}) *line2byte()*
4886 Return the byte count from the start of the buffer for line
4887 {lnum}. This includes the end-of-line character, depending on
4888 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004889 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004890 This can also be used to get the byte count for the line just
4891 below the last line: >
4892 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01004893< This is the buffer size plus one. If 'fileencoding' is empty
4894 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004895 When {lnum} is invalid, or the |+byte_offset| feature has been
4896 disabled at compile time, -1 is returned.
4897 Also see |byte2line()|, |go| and |:goto|.
4898
4899lispindent({lnum}) *lispindent()*
4900 Get the amount of indent for line {lnum} according the lisp
4901 indenting rules, as with 'lisp'.
4902 The indent is counted in spaces, the value of 'tabstop' is
4903 relevant. {lnum} is used just like in |getline()|.
4904 When {lnum} is invalid or Vim was not compiled the
4905 |+lispindent| feature, -1 is returned.
4906
4907localtime() *localtime()*
4908 Return the current time, measured as seconds since 1st Jan
4909 1970. See also |strftime()| and |getftime()|.
4910
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004911
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004912log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004913 Return the natural logarithm (base e) of {expr} as a |Float|.
4914 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004915 (0, inf].
4916 Examples: >
4917 :echo log(10)
4918< 2.302585 >
4919 :echo log(exp(5))
4920< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02004921 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004922
4923
Bram Moolenaar446cb832008-06-24 21:56:24 +00004924log10({expr}) *log10()*
4925 Return the logarithm of Float {expr} to base 10 as a |Float|.
4926 {expr} must evaluate to a |Float| or a |Number|.
4927 Examples: >
4928 :echo log10(1000)
4929< 3.0 >
4930 :echo log10(0.01)
4931< -2.0
4932 {only available when compiled with the |+float| feature}
4933
Bram Moolenaard38b0552012-04-25 19:07:41 +02004934luaeval({expr}[, {expr}]) *luaeval()*
4935 Evaluate Lua expression {expr} and return its result converted
4936 to Vim data structures. Second {expr} may hold additional
4937 argument accessible as _A inside first {expr}.
4938 Strings are returned as they are.
4939 Boolean objects are converted to numbers.
4940 Numbers are converted to |Float| values if vim was compiled
4941 with |+float| and to numbers otherwise.
4942 Dictionaries and lists obtained by vim.eval() are returned
4943 as-is.
4944 Other objects are returned as zero without any errors.
4945 See |lua-luaeval| for more details.
4946 {only available when compiled with the |+lua| feature}
4947
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004948map({expr}, {string}) *map()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004949 {expr} must be a |List| or a |Dictionary|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004950 Replace each item in {expr} with the result of evaluating
4951 {string}.
4952 Inside {string} |v:val| has the value of the current item.
Bram Moolenaar627b1d32009-11-17 11:20:35 +00004953 For a |Dictionary| |v:key| has the key of the current item
4954 and for a |List| |v:key| has the index of the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004955 Example: >
4956 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004957< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004958
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004959 Note that {string} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004960 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00004961 |literal-string| to avoid having to double backslashes. You
4962 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004963
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004964 The operation is done in-place. If you want a |List| or
4965 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02004966 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004967
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004968< Returns {expr}, the |List| or |Dictionary| that was filtered.
Bram Moolenaar280f1262006-01-30 00:14:18 +00004969 When an error is encountered while evaluating {string} no
4970 further items in {expr} are processed.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004971
4972
Bram Moolenaarbd743252010-10-20 21:23:33 +02004973maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
4974 When {dict} is omitted or zero: Return the rhs of mapping
4975 {name} in mode {mode}. The returned String has special
4976 characters translated like in the output of the ":map" command
4977 listing.
4978
4979 When there is no mapping for {name}, an empty String is
4980 returned.
4981
4982 The {name} can have special key names, like in the ":map"
4983 command.
4984
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004985 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004986 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02004987 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004988 "o" Operator-pending
4989 "i" Insert
4990 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02004991 "s" Select
4992 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00004993 "l" langmap |language-mapping|
4994 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00004995 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004996
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00004997 When {abbr} is there and it is non-zero use abbreviations
4998 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02004999
5000 When {dict} is there and it is non-zero return a dictionary
5001 containing all the information of the mapping with the
5002 following items:
5003 "lhs" The {lhs} of the mapping.
5004 "rhs" The {rhs} of the mapping as typed.
5005 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02005006 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02005007 "expr" 1 for an expression mapping (|:map-<expr>|).
5008 "buffer" 1 for a buffer local mapping (|:map-local|).
5009 "mode" Modes for which the mapping is defined. In
5010 addition to the modes mentioned above, these
5011 characters will be used:
5012 " " Normal, Visual and Operator-pending
5013 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01005014 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02005015 "sid" The script local ID, used for <sid> mappings
5016 (|<SID>|).
Bram Moolenaardfb18412013-12-11 18:53:29 +01005017 "nowait" Do not wait for other, longer mappings.
5018 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02005019
Bram Moolenaar071d4272004-06-13 20:20:40 +00005020 The mappings local to the current buffer are checked first,
5021 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00005022 This function can be used to map a key even when it's already
5023 mapped, and have it do the original mapping too. Sketch: >
5024 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
5025
Bram Moolenaar071d4272004-06-13 20:20:40 +00005026
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005027mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005028 Check if there is a mapping that matches with {name} in mode
5029 {mode}. See |maparg()| for {mode} and special names in
5030 {name}.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005031 When {abbr} is there and it is non-zero use abbreviations
5032 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005033 A match happens with a mapping that starts with {name} and
5034 with a mapping which is equal to the start of {name}.
5035
Bram Moolenaar446cb832008-06-24 21:56:24 +00005036 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00005037 mapcheck("a") yes yes yes
5038 mapcheck("abc") yes yes yes
5039 mapcheck("ax") yes no no
5040 mapcheck("b") no no no
5041
5042 The difference with maparg() is that mapcheck() finds a
5043 mapping that matches with {name}, while maparg() only finds a
5044 mapping for {name} exactly.
5045 When there is no mapping that starts with {name}, an empty
5046 String is returned. If there is one, the rhs of that mapping
5047 is returned. If there are several mappings that start with
5048 {name}, the rhs of one of them is returned.
5049 The mappings local to the current buffer are checked first,
5050 then the global mappings.
5051 This function can be used to check if a mapping can be added
5052 without being ambiguous. Example: >
5053 :if mapcheck("_vv") == ""
5054 : map _vv :set guifont=7x13<CR>
5055 :endif
5056< This avoids adding the "_vv" mapping when there already is a
5057 mapping for "_v" or for "_vvv".
5058
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005059match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005060 When {expr} is a |List| then this returns the index of the
5061 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005062 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005063 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005064 Number, which gives the index (byte offset) in {expr} where
5065 {pat} matches.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005066 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005067 If there is no match -1 is returned.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02005068 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005069 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005070 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005071 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005072< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00005073 *strpbrk()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005074 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00005075 :let sepidx = match(line, '[.,;: \t]')
5076< *strcasestr()*
5077 Vim doesn't have a strcasestr() function. But you can add
5078 "\c" to the pattern to ignore case: >
5079 :let idx = match(haystack, '\cneedle')
5080<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005081 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005082 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005083 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005084 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005085 :echo match("testing", "ing", 2)
5086< result is again "4". >
5087 :echo match("testing", "ing", 4)
5088< result is again "4". >
5089 :echo match("testing", "t", 2)
5090< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005091 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00005092 {start} bytes later, thus "^" will match at {start}. Except
5093 when {count} is given, then it's like matches before the
5094 {start} byte are ignored (this is a bit complicated to keep it
5095 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005096 For a String, if {start} < 0, it will be set to 0. For a list
5097 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005098 If {start} is out of range ({start} > strlen({expr}) for a
5099 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005100
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005101 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00005102 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005103 character further. Thus this example results in 1: >
5104 echo match("testing", "..", 0, 2)
5105< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00005106 Note that when {count} is added the way {start} works changes,
5107 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00005108
Bram Moolenaar071d4272004-06-13 20:20:40 +00005109 See |pattern| for the patterns that are accepted.
5110 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar446cb832008-06-24 21:56:24 +00005111 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00005112 done like 'magic' is set and 'cpoptions' is empty.
5113
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005114 *matchadd()* *E798* *E799* *E801*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005115matchadd({group}, {pattern}[, {priority}[, {id}[, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005116 Defines a pattern to be highlighted in the current window (a
5117 "match"). It will be highlighted with {group}. Returns an
5118 identification number (ID), which can be used to delete the
5119 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01005120 Matching is case sensitive and magic, unless case sensitivity
5121 or magicness are explicitly overridden in {pattern}. The
5122 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02005123 The "Conceal" value is special, it causes the match to be
5124 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005125
5126 The optional {priority} argument assigns a priority to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00005127 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005128 highlighting overrule that of a match with a lower priority.
5129 A priority is specified as an integer (negative numbers are no
5130 exception). If the {priority} argument is not specified, the
5131 default priority is 10. The priority of 'hlsearch' is zero,
5132 hence all matches with a priority greater than zero will
5133 overrule it. Syntax highlighting (see 'syntax') is a separate
5134 mechanism, and regardless of the chosen priority a match will
5135 always overrule syntax highlighting.
5136
5137 The optional {id} argument allows the request for a specific
5138 match ID. If a specified ID is already taken, an error
5139 message will appear and the match will not be added. An ID
5140 is specified as a positive integer (zero excluded). IDs 1, 2
5141 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02005142 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005143 |matchadd()| automatically chooses a free ID.
5144
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005145 The optional {dict} argument allows for further custom
5146 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02005147 conceal character that will be shown for |hl-Conceal|
5148 highlighted matches. The dict can have the following members:
5149
5150 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005151 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02005152 matches, see |:syn-cchar|)
5153
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005154 The number of matches is not limited, as it is the case with
5155 the |:match| commands.
5156
5157 Example: >
5158 :highlight MyGroup ctermbg=green guibg=green
5159 :let m = matchadd("MyGroup", "TODO")
5160< Deletion of the pattern: >
5161 :call matchdelete(m)
5162
5163< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar446cb832008-06-24 21:56:24 +00005164 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005165 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005166
Bram Moolenaar6561d522015-07-21 15:48:27 +02005167matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()*
Bram Moolenaarb3414592014-06-17 17:48:32 +02005168 Same as |matchadd()|, but requires a list of positions {pos}
5169 instead of a pattern. This command is faster than |matchadd()|
5170 because it does not require to handle regular expressions and
5171 sets buffer line boundaries to redraw screen. It is supposed
5172 to be used when fast match additions and deletions are
5173 required, for example to highlight matching parentheses.
5174
5175 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005176 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02005177 line has number 1.
5178 - A list with one number, e.g., [23]. The whole line with this
5179 number will be highlighted.
5180 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005181 the line number, the second one is the column number (first
5182 column is 1, the value must correspond to the byte index as
5183 |col()| would return). The character at this position will
5184 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005185 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02005186 the third number gives the length of the highlight in bytes.
Bram Moolenaarb3414592014-06-17 17:48:32 +02005187
5188 The maximum number of positions is 8.
5189
5190 Example: >
5191 :highlight MyGroup ctermbg=green guibg=green
5192 :let m = matchaddpos("MyGroup", [[23, 24], 34])
5193< Deletion of the pattern: >
5194 :call matchdelete(m)
5195
5196< Matches added by |matchaddpos()| are returned by
5197 |getmatches()| with an entry "pos1", "pos2", etc., with the
5198 value a list like the {pos} item.
5199 These matches cannot be set via |setmatches()|, however they
5200 can still be deleted by |clearmatches()|.
5201
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005202matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005203 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005204 |:2match| or |:3match| command.
5205 Return a |List| with two elements:
5206 The name of the highlight group used
5207 The pattern used.
5208 When {nr} is not 1, 2 or 3 returns an empty |List|.
5209 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005210 This is useful to save and restore a |:match|.
5211 Highlighting matches using the |:match| commands are limited
5212 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005213
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005214matchdelete({id}) *matchdelete()* *E802* *E803*
5215 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00005216 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005217 otherwise -1. See example for |matchadd()|. All matches can
5218 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005219
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005220matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005221 Same as |match()|, but return the index of first character
5222 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005223 :echo matchend("testing", "ing")
5224< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00005225 *strspn()* *strcspn()*
5226 Vim doesn't have a strspn() or strcspn() function, but you can
5227 do it with matchend(): >
5228 :let span = matchend(line, '[a-zA-Z]')
5229 :let span = matchend(line, '[^a-zA-Z]')
5230< Except that -1 is returned when there are no matches.
5231
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005232 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005233 :echo matchend("testing", "ing", 2)
5234< results in "7". >
5235 :echo matchend("testing", "ing", 5)
5236< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005237 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005238
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005239matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005240 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005241 list is the matched string, same as what matchstr() would
5242 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00005243 in |:substitute|. When an optional submatch didn't match an
5244 empty string is used. Example: >
5245 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
5246< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005247 When there is no match an empty list is returned.
5248
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00005249matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005250 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005251 :echo matchstr("testing", "ing")
5252< results in "ing".
5253 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005254 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005255 :echo matchstr("testing", "ing", 2)
5256< results in "ing". >
5257 :echo matchstr("testing", "ing", 5)
5258< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005259 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005260 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005261
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02005262matchstrpos({expr}, {pat}[, {start}[, {count}]]) *matchstrpos()*
5263 Same as |matchstr()|, but return the matched string, the start
5264 position and the end position of the match. Example: >
5265 :echo matchstrpos("testing", "ing")
5266< results in ["ing", 4, 7].
5267 When there is no match ["", -1, -1] is returned.
5268 The {start}, if given, has the same meaning as for |match()|. >
5269 :echo matchstrpos("testing", "ing", 2)
5270< results in ["ing", 4, 7]. >
5271 :echo matchstrpos("testing", "ing", 5)
5272< result is ["", -1, -1].
5273 When {expr} is a |List| then the matching item, the index
5274 of first item where {pat} matches, the start position and the
5275 end position of the match are returned. >
5276 :echo matchstrpos([1, '__x'], '\a')
5277< result is ["x", 1, 2, 3].
5278 The type isn't changed, it's not necessarily a String.
5279
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005280 *max()*
5281max({list}) Return the maximum value of all items in {list}.
5282 If {list} is not a list or one of the items in {list} cannot
5283 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005284 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005285
5286 *min()*
Bram Moolenaar79166c42007-05-10 18:29:51 +00005287min({list}) Return the minimum value of all items in {list}.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005288 If {list} is not a list or one of the items in {list} cannot
5289 be used as a Number this results in an error.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005290 An empty |List| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005291
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005292 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005293mkdir({name} [, {path} [, {prot}]])
5294 Create directory {name}.
5295 If {path} is "p" then intermediate directories are created as
5296 necessary. Otherwise it must be "".
5297 If {prot} is given it is used to set the protection bits of
5298 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar446cb832008-06-24 21:56:24 +00005299 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00005300 for others. This is only used for the last part of {name}.
5301 Thus if you create /tmp/foo/bar then /tmp/foo will be created
5302 with 0755.
5303 Example: >
5304 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
5305< This function is not available in the |sandbox|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005306 Not available on all systems. To check use: >
5307 :if exists("*mkdir")
5308<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005309 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005310mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00005311 If [expr] is supplied and it evaluates to a non-zero Number or
5312 a non-empty String (|non-zero-arg|), then the full mode is
5313 returned, otherwise only the first letter is returned. Note
5314 that " " and "0" are also non-empty strings.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005315
Bram Moolenaar071d4272004-06-13 20:20:40 +00005316 n Normal
Bram Moolenaar446cb832008-06-24 21:56:24 +00005317 no Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +00005318 v Visual by character
5319 V Visual by line
5320 CTRL-V Visual blockwise
5321 s Select by character
5322 S Select by line
5323 CTRL-S Select blockwise
5324 i Insert
Bram Moolenaar446cb832008-06-24 21:56:24 +00005325 R Replace |R|
5326 Rv Virtual Replace |gR|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005327 c Command-line
Bram Moolenaar446cb832008-06-24 21:56:24 +00005328 cv Vim Ex mode |gQ|
5329 ce Normal Ex mode |Q|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005330 r Hit-enter prompt
Bram Moolenaar446cb832008-06-24 21:56:24 +00005331 rm The -- more -- prompt
5332 r? A |:confirm| query of some sort
5333 ! Shell or external command is executing
5334 This is useful in the 'statusline' option or when used
5335 with |remote_expr()| In most other places it always returns
5336 "c" or "n".
5337 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005338
Bram Moolenaar7e506b62010-01-19 15:55:06 +01005339mzeval({expr}) *mzeval()*
5340 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02005341 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01005342 Numbers and strings are returned as they are.
5343 Pairs (including lists and improper lists) and vectors are
5344 returned as Vim |Lists|.
5345 Hash tables are represented as Vim |Dictionary| type with keys
5346 converted to strings.
5347 All other types are converted to string with display function.
5348 Examples: >
5349 :mz (define l (list 1 2 3))
5350 :mz (define h (make-hash)) (hash-set! h "list" l)
5351 :echo mzeval("l")
5352 :echo mzeval("h")
5353<
5354 {only available when compiled with the |+mzscheme| feature}
5355
Bram Moolenaar071d4272004-06-13 20:20:40 +00005356nextnonblank({lnum}) *nextnonblank()*
5357 Return the line number of the first line at or below {lnum}
5358 that is not blank. Example: >
5359 if getline(nextnonblank(1)) =~ "Java"
5360< When {lnum} is invalid or there is no non-blank line at or
5361 below it, zero is returned.
5362 See also |prevnonblank()|.
5363
Bram Moolenaard35d7842013-01-23 17:17:10 +01005364nr2char({expr}[, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005365 Return a string with a single character, which has the number
5366 value {expr}. Examples: >
5367 nr2char(64) returns "@"
5368 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01005369< When {utf8} is omitted or zero, the current 'encoding' is used.
5370 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005371 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01005372< With {utf8} set to 1, always return utf-8 characters.
5373 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00005374 nr2char(10), because NULs are represented with newline
5375 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00005376 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005377
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005378or({expr}, {expr}) *or()*
5379 Bitwise OR on the two arguments. The arguments are converted
5380 to a number. A List, Dict or Float argument causes an error.
5381 Example: >
5382 :let bits = or(bits, 0x80)
5383
5384
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005385pathshorten({expr}) *pathshorten()*
5386 Shorten directory names in the path {expr} and return the
5387 result. The tail, the file name, is kept as-is. The other
5388 components in the path are reduced to single letters. Leading
5389 '~' and '.' characters are kept. Example: >
5390 :echo pathshorten('~/.vim/autoload/myfile.vim')
5391< ~/.v/a/myfile.vim ~
5392 It doesn't matter if the path exists or not.
5393
Bram Moolenaare9b892e2016-01-17 21:15:58 +01005394perleval({expr}) *perleval()*
5395 Evaluate Perl expression {expr} in scalar context and return
5396 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005397 converted, it is returned as a string Perl representation.
5398 Note: If you want an array or hash, {expr} must return a
5399 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01005400 Example: >
5401 :echo perleval('[1 .. 4]')
5402< [1, 2, 3, 4]
5403 {only available when compiled with the |+perl| feature}
5404
Bram Moolenaar446cb832008-06-24 21:56:24 +00005405pow({x}, {y}) *pow()*
5406 Return the power of {x} to the exponent {y} as a |Float|.
5407 {x} and {y} must evaluate to a |Float| or a |Number|.
5408 Examples: >
5409 :echo pow(3, 3)
5410< 27.0 >
5411 :echo pow(2, 16)
5412< 65536.0 >
5413 :echo pow(32, 0.20)
5414< 2.0
5415 {only available when compiled with the |+float| feature}
5416
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005417prevnonblank({lnum}) *prevnonblank()*
5418 Return the line number of the first line at or above {lnum}
5419 that is not blank. Example: >
5420 let ind = indent(prevnonblank(v:lnum - 1))
5421< When {lnum} is invalid or there is no non-blank line at or
5422 above it, zero is returned.
5423 Also see |nextnonblank()|.
5424
5425
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005426printf({fmt}, {expr1} ...) *printf()*
5427 Return a String with {fmt}, where "%" items are replaced by
5428 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005429 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005430< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005431 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005432
5433 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005434 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01005435 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00005436 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00005437 %.9s string truncated to 9 bytes
5438 %c single byte
5439 %d decimal number
5440 %5d decimal number padded with spaces to 5 characters
5441 %x hex number
5442 %04x hex number padded with zeros to at least 4 characters
5443 %X hex number using upper case letters
5444 %o octal number
5445 %f floating point number in the form 123.456
5446 %e floating point number in the form 1.234e3
5447 %E floating point number in the form 1.234E3
5448 %g floating point number, as %f or %e depending on value
5449 %G floating point number, as %f or %E depending on value
5450 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005451
5452 Conversion specifications start with '%' and end with the
5453 conversion type. All other characters are copied unchanged to
5454 the result.
5455
5456 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005457 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005458
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005459 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005460
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005461 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005462 Zero or more of the following flags:
5463
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005464 # The value should be converted to an "alternate
5465 form". For c, d, and s conversions, this option
5466 has no effect. For o conversions, the precision
5467 of the number is increased to force the first
5468 character of the output string to a zero (except
5469 if a zero value is printed with an explicit
5470 precision of zero).
5471 For x and X conversions, a non-zero result has
5472 the string "0x" (or "0X" for X conversions)
5473 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005474
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005475 0 (zero) Zero padding. For all conversions the converted
5476 value is padded on the left with zeros rather
5477 than blanks. If a precision is given with a
5478 numeric conversion (d, o, x, and X), the 0 flag
5479 is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005480
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005481 - A negative field width flag; the converted value
5482 is to be left adjusted on the field boundary.
5483 The converted value is padded on the right with
5484 blanks, rather than on the left with blanks or
5485 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005486
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005487 ' ' (space) A blank should be left before a positive
5488 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005489
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005490 + A sign must always be placed before a number
Bram Moolenaar446cb832008-06-24 21:56:24 +00005491 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005492 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005493
5494 field-width
5495 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00005496 field width. If the converted value has fewer bytes
5497 than the field width, it will be padded with spaces on
5498 the left (or right, if the left-adjustment flag has
5499 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005500
5501 .precision
5502 An optional precision, in the form of a period '.'
5503 followed by an optional digit string. If the digit
5504 string is omitted, the precision is taken as zero.
5505 This gives the minimum number of digits to appear for
5506 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00005507 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005508 For floating point it is the number of digits after
5509 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005510
5511 type
5512 A character that specifies the type of conversion to
5513 be applied, see below.
5514
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005515 A field width or precision, or both, may be indicated by an
5516 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar446cb832008-06-24 21:56:24 +00005517 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005518 negative field width is treated as a left adjustment flag
5519 followed by a positive field width; a negative precision is
5520 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005521 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005522< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005523 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005524
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005525 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005526
Bram Moolenaar446cb832008-06-24 21:56:24 +00005527 *printf-d* *printf-o* *printf-x* *printf-X*
5528 doxX The Number argument is converted to signed decimal
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005529 (d), unsigned octal (o), or unsigned hexadecimal (x
5530 and X) notation. The letters "abcdef" are used for
5531 x conversions; the letters "ABCDEF" are used for X
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005532 conversions.
5533 The precision, if any, gives the minimum number of
5534 digits that must appear; if the converted value
5535 requires fewer digits, it is padded on the left with
5536 zeros.
5537 In no case does a non-existent or small field width
5538 cause truncation of a numeric field; if the result of
5539 a conversion is wider than the field width, the field
5540 is expanded to contain the conversion result.
5541
Bram Moolenaar446cb832008-06-24 21:56:24 +00005542 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005543 c The Number argument is converted to a byte, and the
5544 resulting character is written.
5545
Bram Moolenaar446cb832008-06-24 21:56:24 +00005546 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005547 s The text of the String argument is used. If a
5548 precision is specified, no more bytes than the number
5549 specified are used.
Bram Moolenaar0122c402015-02-03 19:13:34 +01005550 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01005551 S The text of the String argument is used. If a
5552 precision is specified, no more display cells than the
5553 number specified are used. Without the |+multi_byte|
5554 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005555
Bram Moolenaar446cb832008-06-24 21:56:24 +00005556 *printf-f* *E807*
5557 f The Float argument is converted into a string of the
5558 form 123.456. The precision specifies the number of
5559 digits after the decimal point. When the precision is
5560 zero the decimal point is omitted. When the precision
5561 is not specified 6 is used. A really big number
5562 (out of range or dividing by zero) results in "inf".
5563 "0.0 / 0.0" results in "nan".
5564 Example: >
5565 echo printf("%.2f", 12.115)
5566< 12.12
5567 Note that roundoff depends on the system libraries.
5568 Use |round()| when in doubt.
5569
5570 *printf-e* *printf-E*
5571 e E The Float argument is converted into a string of the
5572 form 1.234e+03 or 1.234E+03 when using 'E'. The
5573 precision specifies the number of digits after the
5574 decimal point, like with 'f'.
5575
5576 *printf-g* *printf-G*
5577 g G The Float argument is converted like with 'f' if the
5578 value is between 0.001 (inclusive) and 10000000.0
5579 (exclusive). Otherwise 'e' is used for 'g' and 'E'
5580 for 'G'. When no precision is specified superfluous
5581 zeroes and '+' signs are removed, except for the zero
5582 immediately after the decimal point. Thus 10000000.0
5583 results in 1.0e7.
5584
5585 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005586 % A '%' is written. No argument is converted. The
5587 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005588
Bram Moolenaarc236c162008-07-13 17:41:49 +00005589 When a Number argument is expected a String argument is also
5590 accepted and automatically converted.
5591 When a Float or String argument is expected a Number argument
5592 is also accepted and automatically converted.
5593 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005594
Bram Moolenaar83bab712005-08-01 21:58:57 +00005595 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005596 The number of {exprN} arguments must exactly match the number
5597 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00005598 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00005599
5600
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005601pumvisible() *pumvisible()*
5602 Returns non-zero when the popup menu is visible, zero
5603 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005604 This can be used to avoid some things that would remove the
5605 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005606
Bram Moolenaar30b65812012-07-12 22:01:11 +02005607py3eval({expr}) *py3eval()*
5608 Evaluate Python expression {expr} and return its result
5609 converted to Vim data structures.
5610 Numbers and strings are returned as they are (strings are
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01005611 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02005612 'encoding').
5613 Lists are represented as Vim |List| type.
5614 Dictionaries are represented as Vim |Dictionary| type with
5615 keys converted to strings.
5616 {only available when compiled with the |+python3| feature}
5617
5618 *E858* *E859*
5619pyeval({expr}) *pyeval()*
5620 Evaluate Python expression {expr} and return its result
5621 converted to Vim data structures.
5622 Numbers and strings are returned as they are (strings are
5623 copied though).
5624 Lists are represented as Vim |List| type.
Bram Moolenaard09acef2012-09-21 14:54:30 +02005625 Dictionaries are represented as Vim |Dictionary| type,
5626 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02005627 {only available when compiled with the |+python| feature}
5628
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00005629 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00005630range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005631 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00005632 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
5633 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
5634 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
5635 {max}] (increasing {expr} with {stride} each time, not
5636 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00005637 When the maximum is one before the start the result is an
5638 empty list. When the maximum is more than one before the
5639 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00005640 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005641 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00005642 range(2, 4) " [2, 3, 4]
5643 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005644 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00005645 range(0) " []
5646 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00005647<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005648 *readfile()*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005649readfile({fname} [, {binary} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005650 Read file {fname} and return a |List|, each line of the file
5651 as an item. Lines broken at NL characters. Macintosh files
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005652 separated with CR will result in a single long line (unless a
5653 NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02005654 All NUL characters are replaced with a NL character.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02005655 When {binary} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005656 - When the last line ends in a NL an extra empty list item is
5657 added.
5658 - No CR characters are removed.
5659 Otherwise:
5660 - CR characters that appear before a NL are removed.
5661 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02005662 - When 'encoding' is Unicode any UTF-8 byte order mark is
5663 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005664 When {max} is given this specifies the maximum number of lines
5665 to be read. Useful if you only want to check the first ten
5666 lines of a file: >
5667 :for line in readfile(fname, '', 10)
5668 : if line =~ 'Date' | echo line | endif
5669 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00005670< When {max} is negative -{max} lines from the end of the file
5671 are returned, or as many as there are.
5672 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005673 Note that without {max} the whole file is read into memory.
5674 Also note that there is no recognition of encoding. Read a
5675 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00005676 When the file can't be opened an error message is given and
5677 the result is an empty list.
5678 Also see |writefile()|.
5679
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005680reltime([{start} [, {end}]]) *reltime()*
5681 Return an item that represents a time value. The format of
5682 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02005683 |reltimestr()| to convert it to a string or |reltimefloat()|
5684 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005685 Without an argument it returns the current time.
5686 With one argument is returns the time passed since the time
5687 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005688 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005689 and {end}.
5690 The {start} and {end} arguments must be values returned by
5691 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02005692 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005693
Bram Moolenaar03413f42016-04-12 21:07:15 +02005694reltimefloat({time}) *reltimefloat()*
5695 Return a Float that represents the time value of {time}.
5696 Example: >
5697 let start = reltime()
5698 call MyFunction()
5699 let seconds = reltimefloat(reltime(start))
5700< See the note of reltimestr() about overhead.
5701 Also see |profiling|.
5702 {only available when compiled with the |+reltime| feature}
5703
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005704reltimestr({time}) *reltimestr()*
5705 Return a String that represents the time value of {time}.
5706 This is the number of seconds, a dot and the number of
5707 microseconds. Example: >
5708 let start = reltime()
5709 call MyFunction()
5710 echo reltimestr(reltime(start))
5711< Note that overhead for the commands will be added to the time.
5712 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005713 Leading spaces are used to make the string align nicely. You
5714 can use split() to remove it. >
5715 echo split(reltimestr(reltime(start)))[0]
5716< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005717 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00005718
Bram Moolenaar071d4272004-06-13 20:20:40 +00005719 *remote_expr()* *E449*
5720remote_expr({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005721 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005722 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005723 The result must be a String or a |List|. A |List| is turned
5724 into a String by joining the items with a line break in
5725 between (not at the end), like with join(expr, "\n").
Bram Moolenaar071d4272004-06-13 20:20:40 +00005726 If {idvar} is present, it is taken as the name of a
5727 variable and a {serverid} for later use with
5728 remote_read() is stored there.
5729 See also |clientserver| |RemoteReply|.
5730 This function is not available in the |sandbox|.
5731 {only available when compiled with the |+clientserver| feature}
5732 Note: Any errors will cause a local error message to be issued
5733 and the result will be the empty string.
5734 Examples: >
5735 :echo remote_expr("gvim", "2+2")
5736 :echo remote_expr("gvim1", "b:current_syntax")
5737<
5738
5739remote_foreground({server}) *remote_foreground()*
5740 Move the Vim server with the name {server} to the foreground.
5741 This works like: >
5742 remote_expr({server}, "foreground()")
5743< Except that on Win32 systems the client does the work, to work
5744 around the problem that the OS doesn't always allow the server
5745 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00005746 Note: This does not restore the window if it was minimized,
5747 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005748 This function is not available in the |sandbox|.
5749 {only in the Win32, Athena, Motif and GTK GUI versions and the
5750 Win32 console version}
5751
5752
5753remote_peek({serverid} [, {retvar}]) *remote_peek()*
5754 Returns a positive number if there are available strings
5755 from {serverid}. Copies any reply string into the variable
Bram Moolenaar446cb832008-06-24 21:56:24 +00005756 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005757 name of a variable.
5758 Returns zero if none are available.
5759 Returns -1 if something is wrong.
5760 See also |clientserver|.
5761 This function is not available in the |sandbox|.
5762 {only available when compiled with the |+clientserver| feature}
5763 Examples: >
5764 :let repl = ""
5765 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
5766
5767remote_read({serverid}) *remote_read()*
5768 Return the oldest available reply from {serverid} and consume
5769 it. It blocks until a reply is available.
5770 See also |clientserver|.
5771 This function is not available in the |sandbox|.
5772 {only available when compiled with the |+clientserver| feature}
5773 Example: >
5774 :echo remote_read(id)
5775<
5776 *remote_send()* *E241*
5777remote_send({server}, {string} [, {idvar}])
Bram Moolenaar446cb832008-06-24 21:56:24 +00005778 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00005779 keys and the function returns immediately. At the Vim server
5780 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00005781 If {idvar} is present, it is taken as the name of a variable
5782 and a {serverid} for later use with remote_read() is stored
5783 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005784 See also |clientserver| |RemoteReply|.
5785 This function is not available in the |sandbox|.
5786 {only available when compiled with the |+clientserver| feature}
5787 Note: Any errors will be reported in the server and may mess
5788 up the display.
5789 Examples: >
5790 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
5791 \ remote_read(serverid)
5792
5793 :autocmd NONE RemoteReply *
5794 \ echo remote_read(expand("<amatch>"))
5795 :echo remote_send("gvim", ":sleep 10 | echo ".
5796 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005797<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005798remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005799 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005800 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005801 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005802 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005803 item as {end} a list with one item is returned. When {end}
5804 points to an item before {idx} this is an error.
5805 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005806 Example: >
5807 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005808 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00005809remove({dict}, {key})
5810 Remove the entry from {dict} with key {key}. Example: >
5811 :echo "removed " . remove(dict, "one")
5812< If there is no {key} in {dict} this is an error.
5813
5814 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005815
Bram Moolenaar071d4272004-06-13 20:20:40 +00005816rename({from}, {to}) *rename()*
5817 Rename the file by the name {from} to the name {to}. This
5818 should also work to move files across file systems. The
5819 result is a Number, which is 0 if the file was renamed
5820 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00005821 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005822 This function is not available in the |sandbox|.
5823
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005824repeat({expr}, {count}) *repeat()*
5825 Repeat {expr} {count} times and return the concatenated
5826 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005827 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005828< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005829 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar446cb832008-06-24 21:56:24 +00005830 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005831 :let longlist = repeat(['a', 'b'], 3)
5832< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00005833
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005834
Bram Moolenaar071d4272004-06-13 20:20:40 +00005835resolve({filename}) *resolve()* *E655*
5836 On MS-Windows, when {filename} is a shortcut (a .lnk file),
5837 returns the path the shortcut points to in a simplified form.
5838 On Unix, repeat resolving symbolic links in all path
5839 components of {filename} and return the simplified result.
5840 To cope with link cycles, resolving of symbolic links is
5841 stopped after 100 iterations.
5842 On other systems, return the simplified {filename}.
5843 The simplification step is done as by |simplify()|.
5844 resolve() keeps a leading path component specifying the
5845 current directory (provided the result is still a relative
5846 path name) and also keeps a trailing path separator.
5847
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005848 *reverse()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00005849reverse({list}) Reverse the order of items in {list} in-place. Returns
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005850 {list}.
5851 If you want a list to remain unmodified make a copy first: >
5852 :let revlist = reverse(copy(mylist))
5853
Bram Moolenaar446cb832008-06-24 21:56:24 +00005854round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00005855 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00005856 as a |Float|. If {expr} lies halfway between two integral
5857 values, then use the larger one (away from zero).
5858 {expr} must evaluate to a |Float| or a |Number|.
5859 Examples: >
5860 echo round(0.456)
5861< 0.0 >
5862 echo round(4.5)
5863< 5.0 >
5864 echo round(-4.5)
5865< -5.0
5866 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005867
Bram Moolenaar9a773482013-06-11 18:40:13 +02005868screenattr(row, col) *screenattr()*
5869 Like screenchar(), but return the attribute. This is a rather
5870 arbitrary number that can only be used to compare to the
5871 attribute at other positions.
5872
5873screenchar(row, col) *screenchar()*
5874 The result is a Number, which is the character at position
5875 [row, col] on the screen. This works for every possible
5876 screen position, also status lines, window separators and the
5877 command line. The top left position is row one, column one
5878 The character excludes composing characters. For double-byte
5879 encodings it may only be the first byte.
5880 This is mainly to be used for testing.
5881 Returns -1 when row or col is out of range.
5882
Bram Moolenaar34feacb2012-12-05 19:01:43 +01005883screencol() *screencol()*
5884 The result is a Number, which is the current screen column of
5885 the cursor. The leftmost column has number 1.
5886 This function is mainly used for testing.
5887
5888 Note: Always returns the current screen column, thus if used
5889 in a command (e.g. ":echo screencol()") it will return the
5890 column inside the command line, which is 1 when the command is
5891 executed. To get the cursor position in the file use one of
5892 the following mappings: >
5893 nnoremap <expr> GG ":echom ".screencol()."\n"
5894 nnoremap <silent> GG :echom screencol()<CR>
5895<
5896screenrow() *screenrow()*
5897 The result is a Number, which is the current screen row of the
5898 cursor. The top line has number one.
5899 This function is mainly used for testing.
5900
5901 Note: Same restrictions as with |screencol()|.
5902
Bram Moolenaar76929292008-01-06 19:07:36 +00005903search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005904 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00005905 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00005906
Bram Moolenaar2df58b42012-11-28 18:21:11 +01005907 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005908 If there is no match a 0 is returned and the cursor doesn't
5909 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01005910
Bram Moolenaar071d4272004-06-13 20:20:40 +00005911 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005912 'b' search Backward instead of forward
5913 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005914 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005915 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005916 'p' return number of matching sub-Pattern (see below)
5917 's' Set the ' mark at the previous location of the cursor
5918 'w' Wrap around the end of the file
5919 'W' don't Wrap around the end of the file
5920 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00005921 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
5922
Bram Moolenaar02743632005-07-25 20:42:36 +00005923 If the 's' flag is supplied, the ' mark is set, only if the
5924 cursor is moved. The 's' flag cannot be combined with the 'n'
5925 flag.
5926
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005927 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005928
Bram Moolenaar85084ef2016-01-17 22:26:33 +01005929 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01005930 column zero and then matches before the cursor are skipped.
5931 When the 'c' flag is present in 'cpo' the next search starts
5932 after the match. Without the 'c' flag the next search starts
5933 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005934
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005935 When the {stopline} argument is given then the search stops
5936 after searching this line. This is useful to restrict the
5937 search to a range of lines. Examples: >
5938 let match = search('(', 'b', line("w0"))
5939 let end = search('END', '', line("w$"))
5940< When {stopline} is used and it is not zero this also implies
5941 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00005942 A zero value is equal to not giving the argument.
5943
5944 When the {timeout} argument is given the search stops when
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02005945 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00005946 {timeout} is 500 the search stops after half a second.
5947 The value must not be negative. A zero value is like not
5948 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005949 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005950
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005951 *search()-sub-match*
5952 With the 'p' flag the returned value is one more than the
5953 first sub-match in \(\). One if none of them matched but the
5954 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005955 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005956
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005957 The cursor will be positioned at the match, unless the 'n'
5958 flag is used.
5959
Bram Moolenaar071d4272004-06-13 20:20:40 +00005960 Example (goes over all files in the argument list): >
5961 :let n = 1
5962 :while n <= argc() " loop over all files in arglist
5963 : exe "argument " . n
5964 : " start at the last char in the file and wrap for the
5965 : " first search to find match at start of file
5966 : normal G$
5967 : let flags = "w"
5968 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00005969 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00005970 : let flags = "W"
5971 : endwhile
5972 : update " write the file if modified
5973 : let n = n + 1
5974 :endwhile
5975<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00005976 Example for using some flags: >
5977 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
5978< This will search for the keywords "if", "else", and "endif"
5979 under or after the cursor. Because of the 'p' flag, it
5980 returns 1, 2, or 3 depending on which keyword is found, or 0
5981 if the search fails. With the cursor on the first word of the
5982 line:
5983 if (foo == 0) | let foo = foo + 1 | endif ~
5984 the function returns 1. Without the 'c' flag, the function
5985 finds the "endif" and returns 3. The same thing happens
5986 without the 'e' flag if the cursor is on the "f" of "if".
5987 The 'n' flag tells the function not to move the cursor.
5988
Bram Moolenaar92d640f2005-09-05 22:11:52 +00005989
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005990searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
5991 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00005992
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005993 With a non-zero {global} argument it works like |gD|, find
5994 first match in the file. Otherwise it works like |gd|, find
5995 first match in the function.
5996
5997 With a non-zero {thisblock} argument matches in a {} block
5998 that ends before the cursor position are ignored. Avoids
5999 finding variable declarations only valid in another scope.
6000
Bram Moolenaar92d640f2005-09-05 22:11:52 +00006001 Moves the cursor to the found match.
6002 Returns zero for success, non-zero for failure.
6003 Example: >
6004 if searchdecl('myvar') == 0
6005 echo getline('.')
6006 endif
6007<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006008 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006009searchpair({start}, {middle}, {end} [, {flags} [, {skip}
6010 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00006011 Search for the match of a nested start-end pair. This can be
6012 used to find the "endif" that matches an "if", while other
6013 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006014 The search starts at the cursor. The default is to search
6015 forward, include 'b' in {flags} to search backward.
6016 If a match is found, the cursor is positioned at it and the
6017 line number is returned. If no match is found 0 or -1 is
6018 returned and the cursor doesn't move. No error message is
6019 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006020
6021 {start}, {middle} and {end} are patterns, see |pattern|. They
6022 must not contain \( \) pairs. Use of \%( \) is allowed. When
6023 {middle} is not empty, it is found when searching from either
6024 direction, but only when not in a nested start-end pair. A
6025 typical use is: >
6026 searchpair('\<if\>', '\<else\>', '\<endif\>')
6027< By leaving {middle} empty the "else" is skipped.
6028
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006029 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
6030 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006031 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006032 outer pair. Implies the 'W' flag.
6033 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00006034 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006035 Note: it's nearly always a good idea to use the 'W' flag, to
6036 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006037
6038 When a match for {start}, {middle} or {end} is found, the
6039 {skip} expression is evaluated with the cursor positioned on
6040 the start of the match. It should return non-zero if this
6041 match is to be skipped. E.g., because it is inside a comment
6042 or a string.
6043 When {skip} is omitted or empty, every match is accepted.
6044 When evaluating {skip} causes an error the search is aborted
6045 and -1 returned.
6046
Bram Moolenaar76929292008-01-06 19:07:36 +00006047 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006048
Bram Moolenaar071d4272004-06-13 20:20:40 +00006049 The value of 'ignorecase' is used. 'magic' is ignored, the
6050 patterns are used like it's on.
6051
6052 The search starts exactly at the cursor. A match with
6053 {start}, {middle} or {end} at the next character, in the
6054 direction of searching, is the first one found. Example: >
6055 if 1
6056 if 2
6057 endif 2
6058 endif 1
6059< When starting at the "if 2", with the cursor on the "i", and
6060 searching forwards, the "endif 2" is found. When starting on
6061 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar446cb832008-06-24 21:56:24 +00006062 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006063 then this is considered to be a nested if/endif from "if 2" to
6064 "endif 2".
6065 When searching backwards and {end} is more than one character,
6066 it may be useful to put "\zs" at the end of the pattern, so
6067 that when the cursor is inside a match with the end it finds
6068 the matching start.
6069
6070 Example, to find the "endif" command in a Vim script: >
6071
6072 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
6073 \ 'getline(".") =~ "^\\s*\""')
6074
6075< The cursor must be at or after the "if" for which a match is
6076 to be found. Note that single-quote strings are used to avoid
6077 having to double the backslashes. The skip expression only
6078 catches comments at the start of a line, not after a command.
6079 Also, a word "en" or "if" halfway a line is considered a
6080 match.
6081 Another example, to search for the matching "{" of a "}": >
6082
6083 :echo searchpair('{', '', '}', 'bW')
6084
6085< This works when the cursor is at or before the "}" for which a
6086 match is to be found. To reject matches that syntax
6087 highlighting recognized as strings: >
6088
6089 :echo searchpair('{', '', '}', 'bW',
6090 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
6091<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006092 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00006093searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
6094 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006095 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006096 column position of the match. The first element of the |List|
6097 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006098 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006099 returns [0, 0]. >
6100
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006101 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
6102<
6103 See |match-parens| for a bigger and more useful example.
6104
Bram Moolenaar76929292008-01-06 19:07:36 +00006105searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006106 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006107 column position of the match. The first element of the |List|
6108 is the line number and the second element is the byte index of
6109 the column position of the match. If no match is found,
6110 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006111 Example: >
6112 :let [lnum, col] = searchpos('mypattern', 'n')
6113
6114< When the 'p' flag is given then there is an extra item with
6115 the sub-pattern match number |search()-sub-match|. Example: >
6116 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
6117< In this example "submatch" is 2 when a lowercase letter is
6118 found |/\l|, 3 when an uppercase letter is found |/\u|.
6119
Bram Moolenaar81edd172016-04-14 13:51:37 +02006120server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006121 Send a reply string to {clientid}. The most recent {clientid}
6122 that sent a string can be retrieved with expand("<client>").
6123 {only available when compiled with the |+clientserver| feature}
6124 Note:
6125 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006126 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006127 before calling any commands that waits for input.
6128 See also |clientserver|.
6129 Example: >
6130 :echo server2client(expand("<client>"), "HELLO")
6131<
6132serverlist() *serverlist()*
6133 Return a list of available server names, one per line.
6134 When there are no servers or the information is not available
6135 an empty string is returned. See also |clientserver|.
6136 {only available when compiled with the |+clientserver| feature}
6137 Example: >
6138 :echo serverlist()
6139<
6140setbufvar({expr}, {varname}, {val}) *setbufvar()*
6141 Set option or local variable {varname} in buffer {expr} to
6142 {val}.
6143 This also works for a global or local window option, but it
6144 doesn't work for a global or local window variable.
6145 For a local window option the global value is unchanged.
6146 For the use of {expr}, see |bufname()| above.
6147 Note that the variable name without "b:" must be used.
6148 Examples: >
6149 :call setbufvar(1, "&mod", 1)
6150 :call setbufvar("todo", "myvar", "foobar")
6151< This function is not available in the |sandbox|.
6152
Bram Moolenaar12969c02015-09-08 23:36:10 +02006153setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02006154 Set the current character search information to {dict},
6155 which contains one or more of the following entries:
6156
6157 char character which will be used for a subsequent
6158 |,| or |;| command; an empty string clears the
6159 character search
6160 forward direction of character search; 1 for forward,
6161 0 for backward
6162 until type of character search; 1 for a |t| or |T|
6163 character search, 0 for an |f| or |F|
6164 character search
6165
6166 This can be useful to save/restore a user's character search
6167 from a script: >
6168 :let prevsearch = getcharsearch()
6169 :" Perform a command which clobbers user's search
6170 :call setcharsearch(prevsearch)
6171< Also see |getcharsearch()|.
6172
Bram Moolenaar071d4272004-06-13 20:20:40 +00006173setcmdpos({pos}) *setcmdpos()*
6174 Set the cursor position in the command line to byte position
Bram Moolenaar446cb832008-06-24 21:56:24 +00006175 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006176 Use |getcmdpos()| to obtain the current position.
6177 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00006178 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
6179 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
6180 set after the command line is set to the expression. For
6181 |c_CTRL-R_=| it is set after evaluating the expression but
6182 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006183 When the number is too big the cursor is put at the end of the
6184 line. A number smaller than one has undefined results.
6185 Returns 0 when successful, 1 when not editing the command
6186 line.
6187
Bram Moolenaar80492532016-03-08 17:08:53 +01006188setfperm({fname}, {mode}) *setfperm()* *chmod*
6189 Set the file permissions for {fname} to {mode}.
6190 {mode} must be a string with 9 characters. It is of the form
6191 "rwxrwxrwx", where each group of "rwx" flags represent, in
6192 turn, the permissions of the owner of the file, the group the
6193 file belongs to, and other users. A '-' character means the
6194 permission is off, any other character means on. Multi-byte
6195 characters are not supported.
6196
6197 For example "rw-r-----" means read-write for the user,
6198 readable by the group, not accessible by others. "xx-x-----"
6199 would do the same thing.
6200
6201 Returns non-zero for success, zero for failure.
6202
6203 To read permissions see |getfperm()|.
6204
6205
Bram Moolenaar446cb832008-06-24 21:56:24 +00006206setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01006207 Set line {lnum} of the current buffer to {text}. To insert
6208 lines use |append()|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006209 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006210 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006211 added as a new line.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006212 If this succeeds, 0 is returned. If this fails (most likely
6213 because {lnum} is invalid) 1 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006214 :call setline(5, strftime("%c"))
Bram Moolenaar446cb832008-06-24 21:56:24 +00006215< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006216 will be set to the items in the list. Example: >
6217 :call setline(5, ['aaa', 'bbb', 'ccc'])
6218< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02006219 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006220 : call setline(n, l)
6221 :endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00006222< Note: The '[ and '] marks are not set.
6223
Bram Moolenaar17c7c012006-01-26 22:25:15 +00006224setloclist({nr}, {list} [, {action}]) *setloclist()*
6225 Create or replace or add to the location list for window {nr}.
6226 When {nr} is zero the current window is used. For a location
Bram Moolenaar280f1262006-01-30 00:14:18 +00006227 list window, the displayed location list is modified. For an
6228 invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006229 Otherwise, same as |setqflist()|.
6230 Also see |location-list|.
6231
6232setmatches({list}) *setmatches()*
6233 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00006234 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006235 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006236
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006237 *setpos()*
6238setpos({expr}, {list})
6239 Set the position for {expr}. Possible values:
6240 . the cursor
6241 'x mark x
6242
Bram Moolenaar493c1782014-05-28 14:34:46 +02006243 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006244 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02006245 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006246
Bram Moolenaar446cb832008-06-24 21:56:24 +00006247 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006248 current buffer. Setting the cursor is only possible for
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006249 the current buffer. To set a mark in another buffer you can
6250 use the |bufnr()| function to turn a file name into a buffer
6251 number.
Bram Moolenaardb552d602006-03-23 22:59:57 +00006252 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006253
6254 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006255 column is 1. Use a zero "lnum" to delete a mark. If "col" is
6256 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006257
6258 The "off" number is only used when 'virtualedit' is set. Then
6259 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006260 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006261 character.
6262
Bram Moolenaar493c1782014-05-28 14:34:46 +02006263 The "curswant" number is only used when setting the cursor
6264 position. It sets the preferred column for when moving the
6265 cursor vertically. When the "curswant" number is missing the
6266 preferred column is not set. When it is present and setting a
6267 mark position it is not used.
6268
Bram Moolenaardfb18412013-12-11 18:53:29 +01006269 Note that for '< and '> changing the line number may result in
6270 the marks to be effectively be swapped, so that '< is always
6271 before '>.
6272
Bram Moolenaar08250432008-02-13 11:42:46 +00006273 Returns 0 when the position could be set, -1 otherwise.
6274 An error message is given if {expr} is invalid.
6275
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02006276 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006277
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006278 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02006279 vertically; if you set the cursor position with this, |j| and
6280 |k| motions will jump to previous columns! Use |cursor()| to
6281 also set the preferred column. Also see the "curswant" key in
6282 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006283
Bram Moolenaar65c923a2006-03-03 22:56:30 +00006284
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006285setqflist({list} [, {action}]) *setqflist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00006286 Create or replace or add to the quickfix list using the items
6287 in {list}. Each item in {list} is a dictionary.
6288 Non-dictionary items in {list} are ignored. Each dictionary
6289 item can contain the following entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006290
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006291 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00006292 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006293 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00006294 present or it is invalid.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006295 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006296 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00006297 col column number
6298 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006299 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00006300 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006301 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00006302 type single-character error type, 'E', 'W', etc.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006303
Bram Moolenaar582fd852005-03-28 20:58:01 +00006304 The "col", "vcol", "nr", "type" and "text" entries are
6305 optional. Either "lnum" or "pattern" entry can be used to
6306 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006307 If the "filename" and "bufnr" entries are not present or
6308 neither the "lnum" or "pattern" entries are present, then the
6309 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006310 If both "pattern" and "lnum" are present then "pattern" will
6311 be used.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02006312 If you supply an empty {list}, the quickfix list will be
6313 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00006314 Note that the list is not exactly the same as what
6315 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006316
Bram Moolenaar35c54e52005-05-20 21:25:31 +00006317 If {action} is set to 'a', then the items from {list} are
6318 added to the existing quickfix list. If there is no existing
6319 list, then a new list is created. If {action} is set to 'r',
6320 then the items from the current quickfix list are replaced
6321 with the items from {list}. If {action} is not present or is
6322 set to ' ', then a new list is created.
6323
Bram Moolenaar68b76a62005-03-25 21:53:48 +00006324 Returns zero for success, -1 for failure.
6325
6326 This function can be used to create a quickfix list
6327 independent of the 'errorformat' setting. Use a command like
6328 ":cc 1" to jump to the first position.
6329
6330
Bram Moolenaar071d4272004-06-13 20:20:40 +00006331 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01006332setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00006333 Set the register {regname} to {value}.
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006334 {value} may be any value returned by |getreg()|, including
6335 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006336 If {options} contains "a" or {regname} is upper case,
6337 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02006338 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006339 "c" or "v" |characterwise| mode
6340 "l" or "V" |linewise| mode
6341 "b" or "<CTRL-V>" |blockwise-visual| mode
6342 If a number immediately follows "b" or "<CTRL-V>" then this is
6343 used as the width of the selection - if it is not specified
6344 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006345 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006346
6347 If {options} contains no register settings, then the default
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006348 is to use character mode unless {value} ends in a <NL> for
6349 string {value} and linewise mode for list {value}. Blockwise
6350 mode is never selected automatically.
6351 Returns zero for success, non-zero for failure.
6352
6353 *E883*
Bram Moolenaar34401cc2014-08-29 15:12:19 +02006354 Note: you may not use |List| containing more than one item to
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006355 set search and expression registers. Lists containing no
6356 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006357
6358 Examples: >
6359 :call setreg(v:register, @*)
6360 :call setreg('*', @%, 'ac')
6361 :call setreg('a', "1\n2\n3", 'b5')
6362
6363< This example shows using the functions to save and restore a
Bram Moolenaar5a50c222014-04-02 22:17:10 +02006364 register (note: you may not reliably restore register value
6365 without using the third argument to |getreg()| as without it
6366 newlines are represented as newlines AND Nul bytes are
6367 represented as newlines as well, see |NL-used-for-Nul|). >
6368 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006369 :let var_amode = getregtype('a')
6370 ....
6371 :call setreg('a', var_a, var_amode)
6372
6373< You can also change the type of a register by appending
6374 nothing: >
6375 :call setreg('a', '', 'al')
6376
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006377settabvar({tabnr}, {varname}, {val}) *settabvar()*
6378 Set tab-local variable {varname} to {val} in tab page {tabnr}.
6379 |t:var|
6380 Note that the variable name without "t:" must be used.
6381 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006382 This function is not available in the |sandbox|.
6383
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006384settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
6385 Set option or local variable {varname} in window {winnr} to
6386 {val}.
6387 Tabs are numbered starting with one. For the current tabpage
6388 use |setwinvar()|.
6389 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006390 This also works for a global or local buffer option, but it
6391 doesn't work for a global or local buffer variable.
6392 For a local buffer option the global value is unchanged.
6393 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006394 Examples: >
6395 :call settabwinvar(1, 1, "&list", 0)
6396 :call settabwinvar(3, 2, "myvar", "foobar")
6397< This function is not available in the |sandbox|.
6398
6399setwinvar({nr}, {varname}, {val}) *setwinvar()*
6400 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006401 Examples: >
6402 :call setwinvar(1, "&list", 0)
6403 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006404
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01006405sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01006406 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01006407 checksum of {string}.
6408 {only available when compiled with the |+cryptv| feature}
6409
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006410shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006411 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006412 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006413 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006414 quotes within {string}.
6415 For other systems, it will enclose {string} in single quotes
6416 and replace all "'" with "'\''".
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006417 When the {special} argument is present and it's a non-zero
6418 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006419 items such as "!", "%", "#" and "<cword>" will be preceded by
6420 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006421 command.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00006422 The "!" character will be escaped (again with a |non-zero-arg|
6423 {special}) when 'shell' contains "csh" in the tail. That is
6424 because for csh and tcsh "!" is used for history replacement
6425 even when inside single quotes.
6426 The <NL> character is also escaped. With a |non-zero-arg|
6427 {special} and 'shell' containing "csh" in the tail it's
6428 escaped a second time.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006429 Example of use with a |:!| command: >
6430 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
6431< This results in a directory listing for the file under the
6432 cursor. Example of use with |system()|: >
6433 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01006434< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00006435
6436
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006437shiftwidth() *shiftwidth()*
6438 Returns the effective value of 'shiftwidth'. This is the
6439 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006440 'tabstop' value. This function was introduced with patch
6441 7.3.694 in 2012, everybody should have it by now.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006442
6443
Bram Moolenaar071d4272004-06-13 20:20:40 +00006444simplify({filename}) *simplify()*
6445 Simplify the file name as much as possible without changing
6446 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
6447 Unix) are not resolved. If the first path component in
6448 {filename} designates the current directory, this will be
6449 valid for the result as well. A trailing path separator is
6450 not removed either.
6451 Example: >
6452 simplify("./dir/.././/file/") == "./file/"
6453< Note: The combination "dir/.." is only removed if "dir" is
6454 a searchable directory or does not exist. On Unix, it is also
6455 removed when "dir" is a symbolic link within the same
6456 directory. In order to resolve all the involved symbolic
6457 links before simplifying the path name, use |resolve()|.
6458
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006459
Bram Moolenaar446cb832008-06-24 21:56:24 +00006460sin({expr}) *sin()*
6461 Return the sine of {expr}, measured in radians, as a |Float|.
6462 {expr} must evaluate to a |Float| or a |Number|.
6463 Examples: >
6464 :echo sin(100)
6465< -0.506366 >
6466 :echo sin(-4.01)
6467< 0.763301
6468 {only available when compiled with the |+float| feature}
6469
6470
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006471sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006472 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006473 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006474 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006475 Examples: >
6476 :echo sinh(0.5)
6477< 0.521095 >
6478 :echo sinh(-0.9)
6479< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02006480 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006481
6482
Bram Moolenaar5f894962011-06-19 02:55:37 +02006483sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01006484 Sort the items in {list} in-place. Returns {list}.
6485
6486 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006487 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02006488
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006489< When {func} is omitted, is empty or zero, then sort() uses the
6490 string representation of each item to sort on. Numbers sort
6491 after Strings, |Lists| after Numbers. For sorting text in the
6492 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01006493
Bram Moolenaar34401cc2014-08-29 15:12:19 +02006494 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02006495 ignored.
6496
6497 When {func} is given and it is 'n' then all items will be
6498 sorted numerical (Implementation detail: This uses the
6499 strtod() function to parse numbers, Strings, Lists, Dicts and
6500 Funcrefs will be considered as being 0).
6501
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01006502 When {func} is given and it is 'N' then all items will be
6503 sorted numerical. This is like 'n' but a string containing
6504 digits will be used as the number they represent.
6505
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01006506 When {func} is given and it is 'f' then all items will be
6507 sorted numerical. All values must be a Number or a Float.
6508
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006509 When {func} is a |Funcref| or a function name, this function
6510 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006511 items as argument and must return zero if they are equal, 1 or
6512 bigger if the first one sorts after the second one, -1 or
6513 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01006514
6515 {dict} is for functions with the "dict" attribute. It will be
6516 used to set the local variable "self". |Dictionary-function|
6517
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02006518 The sort is stable, items which compare equal (as number or as
6519 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02006520 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02006521 same order as they were originally.
6522
Bram Moolenaar327aa022014-03-25 18:24:23 +01006523 Also see |uniq()|.
6524
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006525 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006526 func MyCompare(i1, i2)
6527 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
6528 endfunc
6529 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006530< A shorter compare version for this specific simple case, which
6531 ignores overflow: >
6532 func MyCompare(i1, i2)
6533 return a:i1 - a:i2
6534 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006535<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00006536 *soundfold()*
6537soundfold({word})
6538 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00006539 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00006540 soundfolding. 'spell' must be set. When no sound folding is
6541 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00006542 This can be used for making spelling suggestions. Note that
6543 the method can be quite slow.
6544
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006545 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00006546spellbadword([{sentence}])
6547 Without argument: The result is the badly spelled word under
6548 or after the cursor. The cursor is moved to the start of the
6549 bad word. When no bad word is found in the cursor line the
6550 result is an empty string and the cursor doesn't move.
6551
6552 With argument: The result is the first word in {sentence} that
6553 is badly spelled. If there are no spelling mistakes the
6554 result is an empty string.
6555
6556 The return value is a list with two items:
6557 - The badly spelled word or an empty string.
6558 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006559 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00006560 "rare" rare word
6561 "local" word only valid in another region
6562 "caps" word should start with Capital
6563 Example: >
6564 echo spellbadword("the quik brown fox")
6565< ['quik', 'bad'] ~
6566
6567 The spelling information for the current window is used. The
6568 'spell' option must be set and the value of 'spelllang' is
6569 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006570
6571 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006572spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006573 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006574 When {max} is given up to this number of suggestions are
6575 returned. Otherwise up to 25 suggestions are returned.
6576
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006577 When the {capital} argument is given and it's non-zero only
6578 suggestions with a leading capital will be given. Use this
6579 after a match with 'spellcapcheck'.
6580
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006581 {word} can be a badly spelled word followed by other text.
6582 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00006583 suggestions also include the following text, thus you can
6584 replace a line.
6585
6586 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00006587 returned. {word} itself is not included in the suggestions,
6588 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006589
6590 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00006591 'spell' option must be set and the values of 'spelllang' and
6592 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00006593
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006594
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006595split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006596 Make a |List| out of {expr}. When {pattern} is omitted or
6597 empty each white-separated sequence of characters becomes an
6598 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006599 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01006600 removing the matched characters. 'ignorecase' is not used
6601 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006602 When the first or last item is empty it is omitted, unless the
6603 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00006604 Other empty items are kept when {pattern} matches at least one
6605 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006606 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006607 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006608< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006609 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02006610< If you want to keep the separator you can also use '\zs' at
6611 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00006612 :echo split('abc:def:ghi', ':\zs')
6613< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00006614 Splitting a table where the first element can be empty: >
6615 :let items = split(line, ':', 1)
6616< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006617
6618
Bram Moolenaar446cb832008-06-24 21:56:24 +00006619sqrt({expr}) *sqrt()*
6620 Return the non-negative square root of Float {expr} as a
6621 |Float|.
6622 {expr} must evaluate to a |Float| or a |Number|. When {expr}
6623 is negative the result is NaN (Not a Number).
6624 Examples: >
6625 :echo sqrt(100)
6626< 10.0 >
6627 :echo sqrt(-4.01)
6628< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00006629 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006630 {only available when compiled with the |+float| feature}
6631
6632
Bram Moolenaar81edd172016-04-14 13:51:37 +02006633str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006634 Convert String {expr} to a Float. This mostly works the same
6635 as when using a floating point number in an expression, see
6636 |floating-point-format|. But it's a bit more permissive.
6637 E.g., "1e40" is accepted, while in an expression you need to
6638 write "1.0e40".
6639 Text after the number is silently ignored.
6640 The decimal point is always '.', no matter what the locale is
6641 set to. A comma ends the number: "12,345.67" is converted to
6642 12.0. You can strip out thousands separators with
6643 |substitute()|: >
6644 let f = str2float(substitute(text, ',', '', 'g'))
6645< {only available when compiled with the |+float| feature}
6646
6647
Bram Moolenaar81edd172016-04-14 13:51:37 +02006648str2nr({expr} [, {base}]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006649 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01006650 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006651 When {base} is omitted base 10 is used. This also means that
6652 a leading zero doesn't cause octal conversion to be used, as
6653 with the default String to Number conversion.
6654 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01006655 different base the result will be zero. Similarly, when
6656 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
6657 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006658 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006659
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006660
Bram Moolenaar979243b2015-06-26 19:35:49 +02006661strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02006662 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02006663 in String {expr}.
6664 When {skipcc} is omitted or zero, composing characters are
6665 counted separately.
6666 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02006667 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02006668
6669 {skipcc} is only available after 7.4.755. For backward
6670 compatibility, you can define a wrapper function: >
6671 if has("patch-7.4.755")
6672 function s:strchars(str, skipcc)
6673 return strchars(a:str, a:skipcc)
6674 endfunction
6675 else
6676 function s:strchars(str, skipcc)
6677 if a:skipcc
6678 return strlen(substitute(a:str, ".", "x", "g"))
6679 else
6680 return strchars(a:str)
6681 endif
6682 endfunction
6683 endif
6684<
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006685strcharpart({src}, {start}[, {len}]) *strcharpart()*
6686 Like |strpart()| but using character index and length instead
6687 of byte index and length.
6688 When a character index is used where a character does not
6689 exist it is assumed to be one byte. For example: >
6690 strcharpart('abc', -1, 2)
6691< results in 'a'.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02006692
Bram Moolenaardc536092010-07-18 15:45:49 +02006693strdisplaywidth({expr}[, {col}]) *strdisplaywidth()*
6694 The result is a Number, which is the number of display cells
Bram Moolenaar979243b2015-06-26 19:35:49 +02006695 String {expr} occupies on the screen when it starts at {col}.
Bram Moolenaardc536092010-07-18 15:45:49 +02006696 When {col} is omitted zero is used. Otherwise it is the
6697 screen column where to start. This matters for Tab
6698 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02006699 The option settings of the current window are used. This
6700 matters for anything that's displayed differently, such as
6701 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006702 When {expr} contains characters with East Asian Width Class
6703 Ambiguous, this function's return value depends on 'ambiwidth'.
6704 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006705
Bram Moolenaar071d4272004-06-13 20:20:40 +00006706strftime({format} [, {time}]) *strftime()*
6707 The result is a String, which is a formatted date and time, as
6708 specified by the {format} string. The given {time} is used,
6709 or the current time if no time is given. The accepted
6710 {format} depends on your system, thus this is not portable!
6711 See the manual page of the C function strftime() for the
6712 format. The maximum length of the result is 80 characters.
6713 See also |localtime()| and |getftime()|.
6714 The language can be changed with the |:language| command.
6715 Examples: >
6716 :echo strftime("%c") Sun Apr 27 11:49:23 1997
6717 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
6718 :echo strftime("%y%m%d %T") 970427 11:53:55
6719 :echo strftime("%H:%M") 11:55
6720 :echo strftime("%c", getftime("file.c"))
6721 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006722< Not available on all systems. To check use: >
6723 :if exists("*strftime")
6724
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006725strgetchar({str}, {index}) *strgetchar()*
6726 Get character {index} from {str}. This uses a character
6727 index, not a byte index. Composing characters are considered
6728 separate characters here.
6729 Also see |strcharpart()| and |strchars()|.
6730
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006731stridx({haystack}, {needle} [, {start}]) *stridx()*
6732 The result is a Number, which gives the byte index in
6733 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006734 If {start} is specified, the search starts at index {start}.
6735 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01006736 :let colon1 = stridx(line, ":")
6737 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00006738< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006739 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006740 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00006741 See also |strridx()|.
6742 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006743 :echo stridx("An Example", "Example") 3
6744 :echo stridx("Starting point", "Start") 0
6745 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006746< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006747 stridx() works similar to the C function strstr(). When used
6748 with a single character it works similar to strchr().
6749
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006750 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006751string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar446cb832008-06-24 21:56:24 +00006752 Float, String or a composition of them, then the result can be
6753 parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006754 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01006755 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006756 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00006757 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00006758 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006759 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00006760 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01006761
6762 When a List or Dictionary has a recursive reference it is
6763 replaced by "[...]" or "{...}". Using eval() on the result
6764 will then fail.
6765
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006766 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006767
Bram Moolenaar071d4272004-06-13 20:20:40 +00006768 *strlen()*
6769strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00006770 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006771 If the argument is a Number it is first converted to a String.
6772 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02006773 If you want to count the number of multi-byte characters use
6774 |strchars()|.
6775 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006776
6777strpart({src}, {start}[, {len}]) *strpart()*
6778 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00006779 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006780 To count characters instead of bytes use |strcharpart()|.
6781
6782 When bytes are selected which do not exist, this doesn't
6783 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006784 If {len} is missing, the copy continues from {start} till the
6785 end of the {src}. >
6786 strpart("abcdefg", 3, 2) == "de"
6787 strpart("abcdefg", -2, 4) == "ab"
6788 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00006789 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006790
Bram Moolenaar071d4272004-06-13 20:20:40 +00006791< Note: To get the first character, {start} must be 0. For
6792 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00006793 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006794<
Bram Moolenaar677ee682005-01-27 14:41:15 +00006795strridx({haystack}, {needle} [, {start}]) *strridx()*
6796 The result is a Number, which gives the byte index in
6797 {haystack} of the last occurrence of the String {needle}.
6798 When {start} is specified, matches beyond this index are
6799 ignored. This can be used to find a match before a previous
6800 match: >
6801 :let lastcomma = strridx(line, ",")
6802 :let comma2 = strridx(line, ",", lastcomma - 1)
6803< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00006804 For pattern searches use |match()|.
6805 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00006806 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006807 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006808 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006809< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00006810 When used with a single character it works similar to the C
6811 function strrchr().
6812
Bram Moolenaar071d4272004-06-13 20:20:40 +00006813strtrans({expr}) *strtrans()*
6814 The result is a String, which is {expr} with all unprintable
6815 characters translated into printable characters |'isprint'|.
6816 Like they are shown in a window. Example: >
6817 echo strtrans(@a)
6818< This displays a newline in register a as "^@" instead of
6819 starting a new line.
6820
Bram Moolenaar72597a52010-07-18 15:31:08 +02006821strwidth({expr}) *strwidth()*
6822 The result is a Number, which is the number of display cells
6823 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02006824 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006825 When {expr} contains characters with East Asian Width Class
6826 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02006827 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02006828
Bram Moolenaar41571762014-04-02 19:00:58 +02006829submatch({nr}[, {list}]) *submatch()*
Bram Moolenaar251e1912011-06-19 05:09:16 +02006830 Only for an expression in a |:substitute| command or
6831 substitute() function.
6832 Returns the {nr}'th submatch of the matched text. When {nr}
6833 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02006834 Note that a NL in the string can stand for a line break of a
6835 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006836 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02006837
6838 If {list} is present and non-zero then submatch() returns
6839 a list of strings, similar to |getline()| with two arguments.
6840 NL characters in the text represent NUL characters in the
6841 text.
6842 Only returns more than one item for |:substitute|, inside
6843 |substitute()| this list will always contain one or zero
6844 items, since there are no real line breaks.
6845
Bram Moolenaar071d4272004-06-13 20:20:40 +00006846 Example: >
6847 :s/\d\+/\=submatch(0) + 1/
6848< This finds the first number in the line and adds one to it.
6849 A line break is included as a newline character.
6850
6851substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
6852 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02006853 the first match of {pat} is replaced with {sub}.
6854 When {flags} is "g", all matches of {pat} in {expr} are
6855 replaced. Otherwise {flags} should be "".
6856
6857 This works like the ":substitute" command (without any flags).
6858 But the matching with {pat} is always done like the 'magic'
6859 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01006860 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
6861 if you want to ignore or match case and ignore 'ignorecase'.
6862 'smartcase' is not used. See |string-match| for how {pat} is
6863 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006864
6865 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006866 Note that some codes in {sub} have a special meaning
Bram Moolenaar446cb832008-06-24 21:56:24 +00006867 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006868 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006869
Bram Moolenaar071d4272004-06-13 20:20:40 +00006870 When {pat} does not match in {expr}, {expr} is returned
6871 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02006872
Bram Moolenaar071d4272004-06-13 20:20:40 +00006873 Example: >
6874 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
6875< This removes the last component of the 'path' option. >
6876 :echo substitute("testing", ".*", "\\U\\0", "")
6877< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02006878
6879 When {sub} starts with "\=", the remainder is interpreted as
6880 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006881 :echo substitute(s, '%\(\x\x\)',
6882 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00006883
Bram Moolenaar47136d72004-10-12 20:02:24 +00006884synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006885 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00006886 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006887 The syntax ID can be used with |synIDattr()| and
6888 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006889
Bram Moolenaar47136d72004-10-12 20:02:24 +00006890 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006891 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02006892 Note that when the position is after the last character,
6893 that's where the cursor can be in Insert mode, synID() returns
6894 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00006895
Bram Moolenaar071d4272004-06-13 20:20:40 +00006896 When {trans} is non-zero, transparent items are reduced to the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006897 item that they reveal. This is useful when wanting to know
Bram Moolenaar071d4272004-06-13 20:20:40 +00006898 the effective color. When {trans} is zero, the transparent
6899 item is returned. This is useful when wanting to know which
6900 syntax item is effective (e.g. inside parens).
6901 Warning: This function can be very slow. Best speed is
6902 obtained by going through the file in forward direction.
6903
6904 Example (echoes the name of the syntax item under the cursor): >
6905 :echo synIDattr(synID(line("."), col("."), 1), "name")
6906<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02006907
Bram Moolenaar071d4272004-06-13 20:20:40 +00006908synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
6909 The result is a String, which is the {what} attribute of
6910 syntax ID {synID}. This can be used to obtain information
6911 about a syntax item.
6912 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006913 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00006914 used, the attributes for the currently active highlighting are
6915 used (GUI, cterm or term).
6916 Use synIDtrans() to follow linked highlight groups.
6917 {what} result
6918 "name" the name of the syntax item
6919 "fg" foreground color (GUI: color name used to set
6920 the color, cterm: color number as a string,
6921 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006922 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01006923 "font" font name (only available in the GUI)
6924 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006925 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006926 "fg#" like "fg", but for the GUI and the GUI is
6927 running the name in "#RRGGBB" form
6928 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00006929 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006930 "bold" "1" if bold
6931 "italic" "1" if italic
6932 "reverse" "1" if reverse
6933 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01006934 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00006935 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00006936 "undercurl" "1" if undercurled
Bram Moolenaar071d4272004-06-13 20:20:40 +00006937
6938 Example (echoes the color of the syntax item under the
6939 cursor): >
6940 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
6941<
6942synIDtrans({synID}) *synIDtrans()*
6943 The result is a Number, which is the translated syntax ID of
6944 {synID}. This is the syntax group ID of what is being used to
6945 highlight the character. Highlight links given with
6946 ":highlight link" are followed.
6947
Bram Moolenaar483c5d82010-10-20 18:45:33 +02006948synconcealed({lnum}, {col}) *synconcealed()*
6949 The result is a List. The first item in the list is 0 if the
6950 character at the position {lnum} and {col} is not part of a
6951 concealable region, 1 if it is. The second item in the list is
6952 a string. If the first item is 1, the second item contains the
6953 text which will be displayed in place of the concealed text,
6954 depending on the current setting of 'conceallevel'. The third
6955 and final item in the list is a unique number representing the
6956 specific syntax region matched. This allows detection of the
6957 beginning of a new concealable region if there are two
6958 consecutive regions with the same replacement character.
6959 For an example use see $VIMRUNTIME/syntax/2html.vim .
6960
6961
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006962synstack({lnum}, {col}) *synstack()*
6963 Return a |List|, which is the stack of syntax items at the
6964 position {lnum} and {col} in the current window. Each item in
6965 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006966 The first item in the List is the outer region, following are
6967 items contained in that one. The last one is what |synID()|
6968 returns, unless not the whole item is highlighted or it is a
6969 transparent item.
6970 This function is useful for debugging a syntax file.
6971 Example that shows the syntax stack under the cursor: >
6972 for id in synstack(line("."), col("."))
6973 echo synIDattr(id, "name")
6974 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02006975< When the position specified with {lnum} and {col} is invalid
6976 nothing is returned. The position just after the last
6977 character in a line and the first column in an empty line are
6978 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00006979
Bram Moolenaarc0197e22004-09-13 20:26:32 +00006980system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02006981 Get the output of the shell command {expr} as a string. See
6982 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02006983
6984 When {input} is given and is a string this string is written
6985 to a file and passed as stdin to the command. The string is
6986 written as-is, you need to take care of using the correct line
6987 separators yourself.
6988 If {input} is given and is a |List| it is written to the file
6989 in a way |writefile()| does with {binary} set to "b" (i.e.
6990 with a newline between each list item with newlines inside
6991 list items converted to NULs).
6992 Pipes are not used.
6993
Bram Moolenaar52a72462014-08-29 15:53:52 +02006994 When prepended by |:silent| the shell will not be set to
6995 cooked mode. This is meant to be used for commands that do
6996 not need the user to type. It avoids stray characters showing
6997 up on the screen which require |CTRL-L| to remove. >
6998 :silent let f = system('ls *.vim')
6999<
Bram Moolenaar26df0922014-02-23 23:39:13 +01007000 Note: Use |shellescape()| or |::S| with |expand()| or
7001 |fnamemodify()| to escape special characters in a command
7002 argument. Newlines in {expr} may cause the command to fail.
7003 The characters in 'shellquote' and 'shellxquote' may also
7004 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007005 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007006
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007007 The result is a String. Example: >
7008 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01007009 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00007010
7011< To make the result more system-independent, the shell output
7012 is filtered to replace <CR> with <NL> for Macintosh, and
7013 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02007014 To avoid the string being truncated at a NUL, all NUL
7015 characters are replaced with SOH (0x01).
7016
Bram Moolenaar071d4272004-06-13 20:20:40 +00007017 The command executed is constructed using several options:
7018 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
7019 ({tmp} is an automatically generated file name).
7020 For Unix and OS/2 braces are put around {expr} to allow for
7021 concatenated commands.
7022
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007023 The command will be executed in "cooked" mode, so that a
7024 CTRL-C will interrupt the command (on Unix at least).
7025
Bram Moolenaar071d4272004-06-13 20:20:40 +00007026 The resulting error code can be found in |v:shell_error|.
7027 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00007028
7029 Note that any wrong value in the options mentioned above may
7030 make the function fail. It has also been reported to fail
7031 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007032 Unlike ":!cmd" there is no automatic check for changed files.
7033 Use |:checktime| to force a check.
7034
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007035
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007036systemlist({expr} [, {input}]) *systemlist()*
7037 Same as |system()|, but returns a |List| with lines (parts of
7038 output separated by NL) with NULs transformed into NLs. Output
7039 is the same as |readfile()| will output with {binary} argument
7040 set to "b".
7041
Bram Moolenaar975b5272016-03-15 23:10:59 +01007042 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02007043
7044
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007045tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007046 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007047 buffer associated with each window in the current tab page.
7048 {arg} specifies the number of tab page to be used. When
7049 omitted the current tab page is used.
7050 When {arg} is invalid the number zero is returned.
7051 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007052 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007053 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007054 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007055 endfor
7056< Note that a buffer may appear in more than one window.
7057
7058
7059tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00007060 The result is a Number, which is the number of the current
7061 tab page. The first tab page has number 1.
7062 When the optional argument is "$", the number of the last tab
7063 page is returned (the tab page count).
7064 The number can be used with the |:tab| command.
7065
7066
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007067tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02007068 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007069 {tabarg} specifies the number of tab page to be used.
7070 {arg} is used like with |winnr()|:
7071 - When omitted the current window number is returned. This is
7072 the window which will be used when going to this tab page.
7073 - When "$" the number of windows is returned.
7074 - When "#" the previous window nr is returned.
7075 Useful examples: >
7076 tabpagewinnr(1) " current window of tab page 1
7077 tabpagewinnr(4, '$') " number of windows in tab page 4
7078< When {tabarg} is invalid zero is returned.
7079
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00007080 *tagfiles()*
7081tagfiles() Returns a |List| with the file names used to search for tags
7082 for the current buffer. This is the 'tags' option expanded.
7083
7084
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007085taglist({expr}) *taglist()*
7086 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaard8c00872005-07-22 21:52:15 +00007087 Each list item is a dictionary with at least the following
7088 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00007089 name Name of the tag.
7090 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007091 defined. It is either relative to the
7092 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007093 cmd Ex command used to locate the tag in
7094 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007095 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007096 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007097 kind values. Only available when
7098 using a tags file generated by
7099 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00007100 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007101 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007102 More entries may be present, depending on the content of the
7103 tags file: access, implementation, inherits and signature.
7104 Refer to the ctags documentation for information about these
7105 fields. For C code the fields "struct", "class" and "enum"
7106 may appear, they give the name of the entity the tag is
7107 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007108
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00007109 The ex-command 'cmd' can be either an ex search pattern, a
7110 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007111
7112 If there are no matching tags, then an empty list is returned.
7113
7114 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01007115 used in {expr}. This also make the function work faster.
7116 Refer to |tag-regexp| for more information about the tag
7117 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00007118
7119 Refer to |'tags'| for information about how the tags file is
7120 located by Vim. Refer to |tags-file-format| for the format of
7121 the tags file generated by the different ctags tools.
7122
Bram Moolenaar071d4272004-06-13 20:20:40 +00007123tempname() *tempname()* *temp-file-name*
7124 The result is a String, which is the name of a file that
Bram Moolenaar446cb832008-06-24 21:56:24 +00007125 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar071d4272004-06-13 20:20:40 +00007126 is different for at least 26 consecutive calls. Example: >
7127 :let tmpfile = tempname()
7128 :exe "redir > " . tmpfile
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007129< For Unix, the file will be in a private directory |tempfile|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007130 For MS-Windows forward slashes are used when the 'shellslash'
7131 option is set or when 'shellcmdflag' starts with '-'.
7132
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007133
7134tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007135 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007136 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007137 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007138 Examples: >
7139 :echo tan(10)
7140< 0.648361 >
7141 :echo tan(-4.01)
7142< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02007143 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007144
7145
7146tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007147 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007148 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007149 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007150 Examples: >
7151 :echo tanh(0.5)
7152< 0.462117 >
7153 :echo tanh(-1)
7154< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02007155 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007156
7157
Bram Moolenaar975b5272016-03-15 23:10:59 +01007158 *timer_start()*
7159timer_start({time}, {callback} [, {options}])
7160 Create a timer and return the timer ID.
7161
7162 {time} is the waiting time in milliseconds. This is the
7163 minimum time before invoking the callback. When the system is
7164 busy or Vim is not waiting for input the time will be longer.
7165
7166 {callback} is the function to call. It can be the name of a
7167 function or a Funcref. It is called with one argument, which
7168 is the timer ID. The callback is only invoked when Vim is
7169 waiting for input.
7170
7171 {options} is a dictionary. Supported entries:
7172 "repeat" Number of times to repeat calling the
Bram Moolenaar81edd172016-04-14 13:51:37 +02007173 callback. -1 means forever.
Bram Moolenaar975b5272016-03-15 23:10:59 +01007174
7175 Example: >
7176 func MyHandler(timer)
7177 echo 'Handler called'
7178 endfunc
7179 let timer = timer_start(500, 'MyHandler',
7180 \ {'repeat': 3})
7181< This will invoke MyHandler() three times at 500 msec
7182 intervals.
7183 {only available when compiled with the |+timers| feature}
7184
Bram Moolenaar03602ec2016-03-20 20:57:45 +01007185timer_stop({timer}) *timer_stop()*
7186 Stop a timer. {timer} is an ID returned by timer_start().
7187 The timer callback will no longer be invoked.
7188
Bram Moolenaar071d4272004-06-13 20:20:40 +00007189tolower({expr}) *tolower()*
7190 The result is a copy of the String given, with all uppercase
7191 characters turned into lowercase (just like applying |gu| to
7192 the string).
7193
7194toupper({expr}) *toupper()*
7195 The result is a copy of the String given, with all lowercase
7196 characters turned into uppercase (just like applying |gU| to
7197 the string).
7198
Bram Moolenaar8299df92004-07-10 09:47:34 +00007199tr({src}, {fromstr}, {tostr}) *tr()*
7200 The result is a copy of the {src} string with all characters
7201 which appear in {fromstr} replaced by the character in that
7202 position in the {tostr} string. Thus the first character in
7203 {fromstr} is translated into the first character in {tostr}
7204 and so on. Exactly like the unix "tr" command.
7205 This code also deals with multibyte characters properly.
7206
7207 Examples: >
7208 echo tr("hello there", "ht", "HT")
7209< returns "Hello THere" >
7210 echo tr("<blob>", "<>", "{}")
7211< returns "{blob}"
7212
Bram Moolenaar446cb832008-06-24 21:56:24 +00007213trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007214 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00007215 equal to {expr} as a |Float| (truncate towards zero).
7216 {expr} must evaluate to a |Float| or a |Number|.
7217 Examples: >
7218 echo trunc(1.456)
7219< 1.0 >
7220 echo trunc(-5.456)
7221< -5.0 >
7222 echo trunc(4.0)
7223< 4.0
7224 {only available when compiled with the |+float| feature}
7225
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007226 *type()*
7227type({expr}) The result is a Number, depending on the type of {expr}:
Bram Moolenaar748bf032005-02-02 23:04:36 +00007228 Number: 0
7229 String: 1
7230 Funcref: 2
7231 List: 3
7232 Dictionary: 4
Bram Moolenaar446cb832008-06-24 21:56:24 +00007233 Float: 5
Bram Moolenaar705ada12016-01-24 17:56:50 +01007234 Boolean: 6 (v:false and v:true)
7235 None 7 (v:null and v:none)
Bram Moolenaar835dc632016-02-07 14:27:38 +01007236 Job 8
Bram Moolenaar38a55632016-02-15 22:07:32 +01007237 Channel 9
Bram Moolenaar748bf032005-02-02 23:04:36 +00007238 To avoid the magic numbers it should be used this way: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007239 :if type(myvar) == type(0)
7240 :if type(myvar) == type("")
7241 :if type(myvar) == type(function("tr"))
7242 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00007243 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00007244 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +01007245 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +01007246 :if type(myvar) == type(v:none)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007247
Bram Moolenaara17d4c12010-05-30 18:30:36 +02007248undofile({name}) *undofile()*
7249 Return the name of the undo file that would be used for a file
7250 with name {name} when writing. This uses the 'undodir'
7251 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02007252 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02007253 {name} is always expanded to the full path, since that is what
7254 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02007255 If {name} is empty undofile() returns an empty string, since a
7256 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02007257 Useful in combination with |:wundo| and |:rundo|.
7258 When compiled without the +persistent_undo option this always
7259 returns an empty string.
7260
Bram Moolenaara800b422010-06-27 01:15:55 +02007261undotree() *undotree()*
7262 Return the current state of the undo tree in a dictionary with
7263 the following items:
7264 "seq_last" The highest undo sequence number used.
7265 "seq_cur" The sequence number of the current position in
7266 the undo tree. This differs from "seq_last"
7267 when some changes were undone.
7268 "time_cur" Time last used for |:earlier| and related
7269 commands. Use |strftime()| to convert to
7270 something readable.
7271 "save_last" Number of the last file write. Zero when no
7272 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02007273 "save_cur" Number of the current position in the undo
7274 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02007275 "synced" Non-zero when the last undo block was synced.
7276 This happens when waiting from input from the
7277 user. See |undo-blocks|.
7278 "entries" A list of dictionaries with information about
7279 undo blocks.
7280
7281 The first item in the "entries" list is the oldest undo item.
7282 Each List item is a Dictionary with these items:
7283 "seq" Undo sequence number. Same as what appears in
7284 |:undolist|.
7285 "time" Timestamp when the change happened. Use
7286 |strftime()| to convert to something readable.
7287 "newhead" Only appears in the item that is the last one
7288 that was added. This marks the last change
7289 and where further changes will be added.
7290 "curhead" Only appears in the item that is the last one
7291 that was undone. This marks the current
7292 position in the undo tree, the block that will
7293 be used by a redo command. When nothing was
7294 undone after the last change this item will
7295 not appear anywhere.
7296 "save" Only appears on the last block before a file
7297 write. The number is the write count. The
7298 first write has number 1, the last one the
7299 "save_last" mentioned above.
7300 "alt" Alternate entry. This is again a List of undo
7301 blocks. Each item may again have an "alt"
7302 item.
7303
Bram Moolenaar327aa022014-03-25 18:24:23 +01007304uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
7305 Remove second and succeeding copies of repeated adjacent
7306 {list} items in-place. Returns {list}. If you want a list
7307 to remain unmodified make a copy first: >
7308 :let newlist = uniq(copy(mylist))
7309< The default compare function uses the string representation of
7310 each item. For the use of {func} and {dict} see |sort()|.
7311
Bram Moolenaar677ee682005-01-27 14:41:15 +00007312values({dict}) *values()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007313 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007314 in arbitrary order.
Bram Moolenaar677ee682005-01-27 14:41:15 +00007315
7316
Bram Moolenaar071d4272004-06-13 20:20:40 +00007317virtcol({expr}) *virtcol()*
7318 The result is a Number, which is the screen column of the file
7319 position given with {expr}. That is, the last screen position
7320 occupied by the character at that position, when the screen
7321 would be of unlimited width. When there is a <Tab> at the
7322 position, the returned Number will be the column at the end of
7323 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007324 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00007325 For the byte position use |col()|.
7326 For the use of {expr} see |col()|.
7327 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00007328 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007329 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02007330 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007331 When Virtual editing is active in the current mode, a position
7332 beyond the end of the line can be returned. |'virtualedit'|
7333 The accepted positions are:
7334 . the cursor position
7335 $ the end of the cursor line (the result is the
7336 number of displayed characters in the cursor line
7337 plus one)
7338 'x position of mark x (if the mark is not set, 0 is
7339 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01007340 v In Visual mode: the start of the Visual area (the
7341 cursor is the end). When not in Visual mode
7342 returns the cursor position. Differs from |'<| in
7343 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007344 Note that only marks in the current file can be used.
7345 Examples: >
7346 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
7347 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00007348 virtcol("'t") with text " there", with 't at 'h', returns 6
7349< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007350 A more advanced example that echoes the maximum length of
7351 all lines: >
7352 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
7353
Bram Moolenaar071d4272004-06-13 20:20:40 +00007354
7355visualmode([expr]) *visualmode()*
7356 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007357 used in the current buffer. Initially it returns an empty
7358 string, but once Visual mode has been used, it returns "v",
7359 "V", or "<CTRL-V>" (a single CTRL-V character) for
7360 character-wise, line-wise, or block-wise Visual mode
7361 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007362 Example: >
7363 :exe "normal " . visualmode()
7364< This enters the same Visual mode as before. It is also useful
7365 in scripts if you wish to act differently depending on the
7366 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007367 If Visual mode is active, use |mode()| to get the Visual mode
7368 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007369 *non-zero-arg*
7370 If [expr] is supplied and it evaluates to a non-zero Number or
7371 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaar446cb832008-06-24 21:56:24 +00007372 the old value is returned. Note that " " and "0" are also
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007373 non-empty strings, thus cause the mode to be cleared. A List,
7374 Dictionary or Float is not a Number or String, thus does not
7375 cause the mode to be cleared.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007376
Bram Moolenaar8738fc12013-02-20 17:59:11 +01007377wildmenumode() *wildmenumode()*
7378 Returns non-zero when the wildmenu is active and zero
7379 otherwise. See 'wildmenu' and 'wildmode'.
7380 This can be used in mappings to handle the 'wildcharm' option
7381 gracefully. (Makes only sense with |mapmode-c| mappings).
7382
7383 For example to make <c-j> work like <down> in wildmode, use: >
7384 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
7385<
7386 (Note, this needs the 'wildcharm' option set appropriately).
7387
7388
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01007389win_findbuf({bufnr}) *win_findbuf()*
7390 Returns a list with window IDs for windows that contain buffer
7391 {bufnr}. When there is none the list is empty.
7392
Bram Moolenaar86edef62016-03-13 18:07:30 +01007393win_getid([{win} [, {tab}]]) *win_getid()*
7394 Get the window ID for the specified window.
7395 When {win} is missing use the current window.
7396 With {win} this is the window number. The top window has
7397 number 1.
7398 Without {tab} use the current tab, otherwise the tab with
7399 number {tab}. The first tab has number one.
7400 Return zero if the window cannot be found.
7401
7402win_gotoid({expr}) *win_gotoid()*
7403 Go to window with ID {expr}. This may also change the current
7404 tabpage.
7405 Return 1 if successful, 0 if the window cannot be found.
7406
Bram Moolenaar03413f42016-04-12 21:07:15 +02007407win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +01007408 Return a list with the tab number and window number of window
7409 with ID {expr}: [tabnr, winnr].
7410 Return [0, 0] if the window cannot be found.
7411
7412win_id2win({expr}) *win_id2win()*
7413 Return the window number of window with ID {expr}.
7414 Return 0 if the window cannot be found in the current tabpage.
7415
Bram Moolenaar071d4272004-06-13 20:20:40 +00007416 *winbufnr()*
7417winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007418 associated with window {nr}. When {nr} is zero, the number of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007419 the buffer in the current window is returned. When window
7420 {nr} doesn't exist, -1 is returned.
7421 Example: >
7422 :echo "The file in the current window is " . bufname(winbufnr(0))
7423<
7424 *wincol()*
7425wincol() The result is a Number, which is the virtual column of the
7426 cursor in the window. This is counting screen cells from the
7427 left side of the window. The leftmost column is one.
7428
7429winheight({nr}) *winheight()*
7430 The result is a Number, which is the height of window {nr}.
7431 When {nr} is zero, the height of the current window is
7432 returned. When window {nr} doesn't exist, -1 is returned.
7433 An existing window always has a height of zero or more.
7434 Examples: >
7435 :echo "The current window has " . winheight(0) . " lines."
7436<
7437 *winline()*
7438winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar446cb832008-06-24 21:56:24 +00007439 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00007440 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00007441 If the cursor was moved the view on the file will be updated
7442 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007443
7444 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007445winnr([{arg}]) The result is a Number, which is the number of the current
7446 window. The top window has number 1.
7447 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007448 last window is returned (the window count). >
7449 let window_count = winnr('$')
7450< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007451 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007452 If there is no previous window or it is in another tab page 0
7453 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007454 The number can be used with |CTRL-W_w| and ":wincmd w"
7455 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007456 Also see |tabpagewinnr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007457
7458 *winrestcmd()*
7459winrestcmd() Returns a sequence of |:resize| commands that should restore
7460 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007461 are opened or closed and the current window and tab page is
7462 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007463 Example: >
7464 :let cmd = winrestcmd()
7465 :call MessWithWindowSizes()
7466 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007467<
7468 *winrestview()*
7469winrestview({dict})
7470 Uses the |Dictionary| returned by |winsaveview()| to restore
7471 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +02007472 Note: The {dict} does not have to contain all values, that are
7473 returned by |winsaveview()|. If values are missing, those
7474 settings won't be restored. So you can use: >
7475 :call winrestview({'curswant': 4})
7476<
7477 This will only set the curswant value (the column the cursor
7478 wants to move on vertical movements) of the cursor to column 5
7479 (yes, that is 5), while all other settings will remain the
7480 same. This is useful, if you set the cursor position manually.
7481
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007482 If you have changed the values the result is unpredictable.
7483 If the window size changed the result won't be the same.
7484
7485 *winsaveview()*
7486winsaveview() Returns a |Dictionary| that contains information to restore
7487 the view of the current window. Use |winrestview()| to
7488 restore the view.
7489 This is useful if you have a mapping that jumps around in the
7490 buffer and you want to go back to the original view.
7491 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +00007492 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +02007493 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007494 The return value includes:
7495 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +02007496 col cursor column (Note: the first column
7497 zero, as opposed to what getpos()
7498 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007499 coladd cursor column offset for 'virtualedit'
7500 curswant column for vertical movement
7501 topline first line in the window
7502 topfill filler lines, only in diff mode
7503 leftcol first column displayed
7504 skipcol columns skipped
7505 Note that no option values are saved.
7506
Bram Moolenaar071d4272004-06-13 20:20:40 +00007507
7508winwidth({nr}) *winwidth()*
7509 The result is a Number, which is the width of window {nr}.
7510 When {nr} is zero, the width of the current window is
7511 returned. When window {nr} doesn't exist, -1 is returned.
7512 An existing window always has a width of zero or more.
7513 Examples: >
7514 :echo "The current window has " . winwidth(0) . " columns."
7515 :if winwidth(0) <= 50
7516 : exe "normal 50\<C-W>|"
7517 :endif
7518<
Bram Moolenaared767a22016-01-03 22:49:16 +01007519wordcount() *wordcount()*
7520 The result is a dictionary of byte/chars/word statistics for
7521 the current buffer. This is the same info as provided by
7522 |g_CTRL-G|
7523 The return value includes:
7524 bytes Number of bytes in the buffer
7525 chars Number of chars in the buffer
7526 words Number of words in the buffer
7527 cursor_bytes Number of bytes before cursor position
7528 (not in Visual mode)
7529 cursor_chars Number of chars before cursor position
7530 (not in Visual mode)
7531 cursor_words Number of words before cursor position
7532 (not in Visual mode)
7533 visual_bytes Number of bytes visually selected
7534 (only in Visual mode)
7535 visual_chars Number of chars visually selected
7536 (only in Visual mode)
7537 visual_words Number of chars visually selected
7538 (only in Visual mode)
7539
7540
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007541 *writefile()*
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007542writefile({list}, {fname} [, {flags}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007543 Write |List| {list} to file {fname}. Each list item is
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007544 separated with a NL. Each list item must be a String or
7545 Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007546 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007547 not be a NL after the last list item. An empty item at the
7548 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +01007549
7550 When {flags} contains "a" then append mode is used, lines are
7551 append to the file: >
7552 :call writefile(["foo"], "event.log", "a")
7553 :call writefile(["bar"], "event.log", "a")
7554>
7555< All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007556 Inserting CR characters needs to be done before passing {list}
7557 to writefile().
7558 An existing file is overwritten, if possible.
7559 When the write fails -1 is returned, otherwise 0. There is an
7560 error message if the file can't be created or when writing
7561 fails.
7562 Also see |readfile()|.
7563 To copy a file byte for byte: >
7564 :let fl = readfile("foo", "b")
7565 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007566
7567
7568xor({expr}, {expr}) *xor()*
7569 Bitwise XOR on the two arguments. The arguments are converted
7570 to a number. A List, Dict or Float argument causes an error.
7571 Example: >
7572 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +01007573<
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007574
Bram Moolenaar071d4272004-06-13 20:20:40 +00007575
7576 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02007577There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +000075781. Features that are only supported when they have been enabled when Vim
7579 was compiled |+feature-list|. Example: >
7580 :if has("cindent")
75812. Features that are only supported when certain conditions have been met.
7582 Example: >
7583 :if has("gui_running")
7584< *has-patch*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020075853. Included patches. The "patch123" feature means that patch 123 has been
7586 included. Note that this form does not check the version of Vim, you need
7587 to inspect |v:version| for that.
7588 Example (checking version 6.2.148 or later): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007589 :if v:version > 602 || v:version == 602 && has("patch148")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007590< Note that it's possible for patch 147 to be omitted even though 148 is
7591 included.
7592
75934. Beyond a certain version or at a certain version and including a specific
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007594 patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or
7595 later, or it is version 7.4 and patch 237 was included.
7596 Note that this only works for patch 7.4.237 and later, before that you
7597 need to use the example above that checks v:version. Example: >
7598 :if has("patch-7.4.248")
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02007599< Note that it's possible for patch 147 to be omitted even though 148 is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007600 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007601
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02007602acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007603all_builtin_terms Compiled with all builtin terminals enabled.
7604amiga Amiga version of Vim.
7605arabic Compiled with Arabic support |Arabic|.
7606arp Compiled with ARP support (Amiga).
Bram Moolenaara9b1e742005-12-19 22:14:58 +00007607autocmd Compiled with autocommand support. |autocommand|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007608balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +00007609balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007610beos BeOS version of Vim.
7611browse Compiled with |:browse| support, and browse() will
7612 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +02007613browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007614builtin_terms Compiled with some builtin terminals.
7615byte_offset Compiled with support for 'o' in 'statusline'
7616cindent Compiled with 'cindent' support.
7617clientserver Compiled with remote invocation support |clientserver|.
7618clipboard Compiled with 'clipboard' support.
7619cmdline_compl Compiled with |cmdline-completion| support.
7620cmdline_hist Compiled with |cmdline-history| support.
7621cmdline_info Compiled with 'showcmd' and 'ruler' support.
7622comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007623compatible Compiled to be very Vi compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007624cryptv Compiled with encryption support |encryption|.
7625cscope Compiled with |cscope| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007626debug Compiled with "DEBUG" defined.
7627dialog_con Compiled with console dialog support.
7628dialog_gui Compiled with GUI dialog support.
7629diff Compiled with |vimdiff| and 'diff' support.
7630digraphs Compiled with support for digraphs.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02007631directx Compiled with support for Direct-X and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007632dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007633dos16 16 bits DOS version of Vim.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007634dos32 32 bits DOS (DJGPP) version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007635ebcdic Compiled on a machine with ebcdic character set.
7636emacs_tags Compiled with support for Emacs tags.
7637eval Compiled with expression evaluation support. Always
7638 true, of course!
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01007639ex_extra |+ex_extra|, always true now
Bram Moolenaar071d4272004-06-13 20:20:40 +00007640extra_search Compiled with support for |'incsearch'| and
7641 |'hlsearch'|
7642farsi Compiled with Farsi support |farsi|.
7643file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007644filterpipe When 'shelltemp' is off pipes are used for shell
7645 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00007646find_in_path Compiled with support for include file searches
7647 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007648float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007649fname_case Case in file names matters (for Amiga, MS-DOS, and
7650 Windows this is not present).
7651folding Compiled with |folding| support.
7652footer Compiled with GUI footer support. |gui-footer|
7653fork Compiled to use fork()/exec() instead of system().
7654gettext Compiled with message translation |multi-lang|
7655gui Compiled with GUI enabled.
7656gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007657gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007658gui_gtk Compiled with GTK+ GUI (any version).
7659gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +01007660gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007661gui_mac Compiled with Macintosh GUI.
7662gui_motif Compiled with Motif GUI.
7663gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007664gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007665gui_win32 Compiled with MS Windows Win32 GUI.
7666gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007667hangul_input Compiled with Hangul input support. |hangul|
7668iconv Can use iconv() for conversion.
7669insert_expand Compiled with support for CTRL-X expansion commands in
7670 Insert mode.
7671jumplist Compiled with |jumplist| support.
7672keymap Compiled with 'keymap' support.
7673langmap Compiled with 'langmap' support.
7674libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +02007675linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
7676 'breakindent' support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007677lispindent Compiled with support for lisp indenting.
7678listcmds Compiled with commands for the buffer list |:files|
7679 and the argument list |arglist|.
7680localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +02007681lua Compiled with Lua interface |Lua|.
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01007682mac Any Macintosh version of Vim.
Bram Moolenaarf8df7ad2016-02-16 14:07:40 +01007683macunix Compiled for OS X, with darwin
7684osx Compiled for OS X, with or without darwin
Bram Moolenaar071d4272004-06-13 20:20:40 +00007685menu Compiled with support for |:menu|.
7686mksession Compiled with support for |:mksession|.
7687modify_fname Compiled with file name modifiers. |filename-modifiers|
7688mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007689mouse_dec Compiled with support for Dec terminal mouse.
7690mouse_gpm Compiled with support for gpm (Linux console mouse)
7691mouse_netterm Compiled with support for netterm mouse.
7692mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007693mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +02007694mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01007695mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007696mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007697mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +00007698multi_byte Compiled with support for 'encoding'
7699multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007700multi_byte_ime Compiled with support for IME input method.
7701multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00007702mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +02007703netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007704netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007705ole Compiled with OLE automation support for Win32.
7706os2 OS/2 version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007707path_extra Compiled with up/downwards search in 'path' and 'tags'
7708perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02007709persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007710postscript Compiled with PostScript file printing.
7711printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +00007712profile Compiled with |:profile| support.
Bram Moolenaar446beb42011-05-10 17:18:44 +02007713python Compiled with Python 2.x interface. |has-python|
7714python3 Compiled with Python 3.x interface. |has-python|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007715qnx QNX version of Vim.
7716quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +00007717reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007718rightleft Compiled with 'rightleft' support.
7719ruby Compiled with Ruby interface |ruby|.
7720scrollbind Compiled with 'scrollbind' support.
7721showcmd Compiled with 'showcmd' support.
7722signs Compiled with |:sign| support.
7723smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007724spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +00007725startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007726statusline Compiled with support for 'statusline', 'rulerformat'
7727 and special formats of 'titlestring' and 'iconstring'.
7728sun_workshop Compiled with support for Sun |workshop|.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007729syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007730syntax_items There are active syntax highlighting items for the
7731 current buffer.
7732system Compiled to use system() instead of fork()/exec().
7733tag_binary Compiled with binary searching in tags files
7734 |tag-binary-search|.
7735tag_old_static Compiled with support for old static tags
7736 |tag-old-static|.
7737tag_any_white Compiled with support for any white characters in tags
7738 files |tag-any-white|.
7739tcl Compiled with Tcl interface.
7740terminfo Compiled with terminfo instead of termcap.
7741termresponse Compiled with support for |t_RV| and |v:termresponse|.
7742textobjects Compiled with support for |text-objects|.
7743tgetent Compiled with tgetent support, able to use a termcap
7744 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +01007745timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007746title Compiled with window title support |'title'|.
7747toolbar Compiled with support for |gui-toolbar|.
7748unix Unix version of Vim.
7749user_commands User-defined commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007750vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007751vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01007752 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007753viminfo Compiled with viminfo support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007754virtualedit Compiled with 'virtualedit' option.
7755visual Compiled with Visual mode.
7756visualextra Compiled with extra Visual mode commands.
7757 |blockwise-operators|.
7758vms VMS version of Vim.
7759vreplace Compiled with |gR| and |gr| commands.
7760wildignore Compiled with 'wildignore' option.
7761wildmenu Compiled with 'wildmenu' option.
Bram Moolenaard58e9292011-02-09 17:07:58 +01007762win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
7763 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007764win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007765win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007766win95 Win32 version for MS-Windows 95/98/ME.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +01007767winaltkeys Compiled with 'winaltkeys' option.
7768windows Compiled with support for more than one window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007769writebackup Compiled with 'writebackup' default on.
7770xfontset Compiled with X fontset support |xfontset|.
7771xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02007772xpm Compiled with pixmap support.
7773xpm_w32 Compiled with pixmap support for Win32. (Only for
7774 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007775xsmp Compiled with X session management support.
7776xsmp_interact Compiled with interactive X session management support.
7777xterm_clipboard Compiled with support for xterm clipboard.
7778xterm_save Compiled with support for saving and restoring the
7779 xterm screen.
7780x11 Compiled with X11 support.
7781
7782 *string-match*
7783Matching a pattern in a String
7784
7785A regexp pattern as explained at |pattern| is normally used to find a match in
7786the buffer lines. When a pattern is used to find a match in a String, almost
7787everything works in the same way. The difference is that a String is handled
7788like it is one line. When it contains a "\n" character, this is not seen as a
7789line break for the pattern. It can be matched with a "\n" in the pattern, or
7790with ".". Example: >
7791 :let a = "aaaa\nxxxx"
7792 :echo matchstr(a, "..\n..")
7793 aa
7794 xx
7795 :echo matchstr(a, "a.x")
7796 a
7797 x
7798
7799Don't forget that "^" will only match at the first character of the String and
7800"$" at the last character of the string. They don't match after or before a
7801"\n".
7802
7803==============================================================================
78045. Defining functions *user-functions*
7805
7806New functions can be defined. These can be called just like builtin
7807functions. The function executes a sequence of Ex commands. Normal mode
7808commands can be executed with the |:normal| command.
7809
7810The function name must start with an uppercase letter, to avoid confusion with
7811builtin functions. To prevent from using the same name in different scripts
7812avoid obvious, short names. A good habit is to start the function name with
7813the name of the script, e.g., "HTMLcolor()".
7814
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007815It's also possible to use curly braces, see |curly-braces-names|. And the
7816|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007817
7818 *local-function*
7819A function local to a script must start with "s:". A local script function
7820can only be called from within the script and from functions, user commands
7821and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007822function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +00007823instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007824There are only script-local functions, no buffer-local or window-local
7825functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007826
7827 *:fu* *:function* *E128* *E129* *E123*
7828:fu[nction] List all functions and their arguments.
7829
7830:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007831 {name} can also be a |Dictionary| entry that is a
7832 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007833 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007834
7835:fu[nction] /{pattern} List functions with a name matching {pattern}.
7836 Example that lists all functions ending with "File": >
7837 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00007838<
7839 *:function-verbose*
7840When 'verbose' is non-zero, listing a function will also display where it was
7841last defined. Example: >
7842
7843 :verbose function SetFileTypeSH
7844 function SetFileTypeSH(name)
7845 Last set from /usr/share/vim/vim-7.0/filetype.vim
7846<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007847See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00007848
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007849 *E124* *E125* *E853* *E884*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007850:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007851 Define a new function by the name {name}. The name
7852 must be made of alphanumeric characters and '_', and
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007853 must start with a capital or "s:" (see above). Note
7854 that using "b:" or "g:" is not allowed. (since patch
7855 7.4.260 E884 is given if the function name has a colon
7856 in the name, e.g. for "foo:bar()". Before that patch
7857 no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007858
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007859 {name} can also be a |Dictionary| entry that is a
7860 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007861 :function dict.init(arg)
Bram Moolenaar446cb832008-06-24 21:56:24 +00007862< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007863 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar446cb832008-06-24 21:56:24 +00007864 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007865 result is a |Funcref| to a numbered function. The
7866 function can only be used with a |Funcref| and will be
7867 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007868 *E127* *E122*
7869 When a function by this name already exists and [!] is
7870 not used an error message is given. When [!] is used,
7871 an existing function is silently replaced. Unless it
7872 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007873
7874 For the {arguments} see |function-argument|.
7875
Bram Moolenaar8d043172014-01-23 14:24:41 +01007876 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007877 When the [range] argument is added, the function is
7878 expected to take care of a range itself. The range is
7879 passed as "a:firstline" and "a:lastline". If [range]
7880 is excluded, ":{range}call" will call the function for
7881 each line in the range, with the cursor on the start
7882 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007883 The cursor is still moved to the first line of the
7884 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +01007885 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007886 When the [abort] argument is added, the function will
7887 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +01007888 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007889 When the [dict] argument is added, the function must
Bram Moolenaar446cb832008-06-24 21:56:24 +00007890 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007891 local variable "self" will then be set to the
7892 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007893
Bram Moolenaar446cb832008-06-24 21:56:24 +00007894 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00007895 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00007896 will not be changed by the function. This also
7897 implies that the effect of |:nohlsearch| is undone
7898 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00007899
Bram Moolenaar071d4272004-06-13 20:20:40 +00007900 *:endf* *:endfunction* *E126* *E193*
7901:endf[unction] The end of a function definition. Must be on a line
7902 by its own, without other commands.
7903
7904 *:delf* *:delfunction* *E130* *E131*
7905:delf[unction] {name} Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007906 {name} can also be a |Dictionary| entry that is a
7907 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007908 :delfunc dict.init
Bram Moolenaar446cb832008-06-24 21:56:24 +00007909< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007910 function is deleted if there are no more references to
7911 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007912 *:retu* *:return* *E133*
7913:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
7914 evaluated and returned as the result of the function.
7915 If "[expr]" is not given, the number 0 is returned.
7916 When a function ends without an explicit ":return",
7917 the number 0 is returned.
7918 Note that there is no check for unreachable lines,
7919 thus there is no warning if commands follow ":return".
7920
7921 If the ":return" is used after a |:try| but before the
7922 matching |:finally| (if present), the commands
7923 following the ":finally" up to the matching |:endtry|
7924 are executed first. This process applies to all
7925 nested ":try"s inside the function. The function
7926 returns at the outermost ":endtry".
7927
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007928 *function-argument* *a:var*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007929An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007930be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007931 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007932Up to 20 arguments can be given, separated by commas. After the named
7933arguments an argument "..." can be specified, which means that more arguments
7934may optionally be following. In the function the extra arguments can be used
7935as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007936can be 0). "a:000" is set to a |List| that contains these arguments. Note
7937that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00007938 *E742*
7939The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007940However, if a |List| or |Dictionary| is used, you can change their contents.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007941Thus you can pass a |List| to a function and have the function add an item to
7942it. If you want to make sure the function cannot change a |List| or
7943|Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007944
Bram Moolenaar8f999f12005-01-25 22:12:55 +00007945When not using "...", the number of arguments in a function call must be equal
7946to the number of named arguments. When using "...", the number of arguments
7947may be larger.
7948
7949It is also possible to define a function without any arguments. You must
7950still supply the () then. The body of the function follows in the next lines,
7951until the matching |:endfunction|. It is allowed to define another function
7952inside a function body.
7953
7954 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007955Inside a function variables can be used. These are local variables, which
7956will disappear when the function returns. Global variables need to be
7957accessed with "g:".
7958
7959Example: >
7960 :function Table(title, ...)
7961 : echohl Title
7962 : echo a:title
7963 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +00007964 : echo a:0 . " items:"
7965 : for s in a:000
7966 : echon ' ' . s
7967 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00007968 :endfunction
7969
7970This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00007971 call Table("Table", "line1", "line2")
7972 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007973
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007974To return more than one value, return a |List|: >
7975 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007976 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007977 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007978 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007979 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00007980 :endfunction
7981
7982This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007983 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007984 :if success == "ok"
7985 : echo div
7986 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007987<
Bram Moolenaar39f05632006-03-19 22:15:26 +00007988 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007989:[range]cal[l] {name}([arguments])
7990 Call a function. The name of the function and its arguments
7991 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007992 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007993 Without a range and for functions that accept a range, the
7994 function is called once. When a range is given the cursor is
7995 positioned at the start of the first line before executing the
7996 function.
7997 When a range is given and the function doesn't handle it
7998 itself, the function is executed for each line in the range,
7999 with the cursor in the first column of that line. The cursor
8000 is left at the last line (possibly moved by the last function
Bram Moolenaar446cb832008-06-24 21:56:24 +00008001 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00008002 this works:
8003 *function-range-example* >
8004 :function Mynumber(arg)
8005 : echo line(".") . " " . a:arg
8006 :endfunction
8007 :1,5call Mynumber(getline("."))
8008<
8009 The "a:firstline" and "a:lastline" are defined anyway, they
8010 can be used to do something different at the start or end of
8011 the range.
8012
8013 Example of a function that handles the range itself: >
8014
8015 :function Cont() range
8016 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
8017 :endfunction
8018 :4,8call Cont()
8019<
8020 This function inserts the continuation character "\" in front
8021 of all the lines in the range, except the first one.
8022
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008023 When the function returns a composite value it can be further
8024 dereferenced, but the range will not be used then. Example: >
8025 :4,8call GetDict().method()
8026< Here GetDict() gets the range but method() does not.
8027
Bram Moolenaar071d4272004-06-13 20:20:40 +00008028 *E132*
8029The recursiveness of user functions is restricted with the |'maxfuncdepth'|
8030option.
8031
Bram Moolenaar7c626922005-02-07 22:01:03 +00008032
8033AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00008034 *autoload-functions*
8035When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00008036only when they are used. There are two methods: with an autocommand and with
8037the "autoload" directory in 'runtimepath'.
8038
8039
8040Using an autocommand ~
8041
Bram Moolenaar05159a02005-02-26 23:04:13 +00008042This is introduced in the user manual, section |41.14|.
8043
Bram Moolenaar7c626922005-02-07 22:01:03 +00008044The autocommand is useful if you have a plugin that is a long Vim script file.
8045You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008046That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +00008047again, setting a variable to skip the |:finish| command.
8048
8049Use the FuncUndefined autocommand event with a pattern that matches the
8050function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008051
8052 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
8053
8054The file "~/vim/bufnetfuncs.vim" should then define functions that start with
8055"BufNet". Also see |FuncUndefined|.
8056
Bram Moolenaar7c626922005-02-07 22:01:03 +00008057
8058Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008059 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00008060This is introduced in the user manual, section |41.15|.
8061
Bram Moolenaar7c626922005-02-07 22:01:03 +00008062Using a script in the "autoload" directory is simpler, but requires using
8063exactly the right file name. A function that can be autoloaded has a name
8064like this: >
8065
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008066 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00008067
8068When such a function is called, and it is not defined yet, Vim will search the
8069"autoload" directories in 'runtimepath' for a script file called
8070"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
8071then define the function like this: >
8072
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008073 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00008074 echo "Done!"
8075 endfunction
8076
Bram Moolenaar60a795a2005-09-16 21:55:43 +00008077The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00008078exactly, and the defined function must have the name exactly as it will be
8079called.
8080
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008081It is possible to use subdirectories. Every # in the function name works like
8082a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00008083
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008084 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00008085
8086Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
8087
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008088This also works when reading a variable that has not been set yet: >
8089
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008090 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008091
Bram Moolenaara5792f52005-11-23 21:25:05 +00008092However, when the autoload script was already loaded it won't be loaded again
8093for an unknown variable.
8094
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008095When assigning a value to such a variable nothing special happens. This can
8096be used to pass settings to the autoload script before it's loaded: >
8097
Bram Moolenaara7fc0102005-05-18 22:17:12 +00008098 :let foo#bar#toggle = 1
8099 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008100
Bram Moolenaar4399ef42005-02-12 14:29:27 +00008101Note that when you make a mistake and call a function that is supposed to be
8102defined in an autoload script, but the script doesn't actually define the
8103function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008104And you will get an error message every time.
8105
8106Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008107other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008108Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00008109
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008110Hint: If you distribute a bunch of scripts you can pack them together with the
8111|vimball| utility. Also read the user manual |distribute-script|.
8112
Bram Moolenaar071d4272004-06-13 20:20:40 +00008113==============================================================================
81146. Curly braces names *curly-braces-names*
8115
Bram Moolenaar84f72352012-03-11 15:57:40 +01008116In most places where you can use a variable, you can use a "curly braces name"
8117variable. This is a regular variable name with one or more expressions
8118wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008119 my_{adjective}_variable
8120
8121When Vim encounters this, it evaluates the expression inside the braces, puts
8122that in place of the expression, and re-interprets the whole as a variable
8123name. So in the above example, if the variable "adjective" was set to
8124"noisy", then the reference would be to "my_noisy_variable", whereas if
8125"adjective" was set to "quiet", then it would be to "my_quiet_variable".
8126
8127One application for this is to create a set of variables governed by an option
Bram Moolenaar446cb832008-06-24 21:56:24 +00008128value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008129 echo my_{&background}_message
8130
8131would output the contents of "my_dark_message" or "my_light_message" depending
8132on the current value of 'background'.
8133
8134You can use multiple brace pairs: >
8135 echo my_{adverb}_{adjective}_message
8136..or even nest them: >
8137 echo my_{ad{end_of_word}}_message
8138where "end_of_word" is either "verb" or "jective".
8139
8140However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008141variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008142 :let foo='a + b'
8143 :echo c{foo}d
8144.. since the result of expansion is "ca + bd", which is not a variable name.
8145
8146 *curly-braces-function-names*
8147You can call and define functions by an evaluated name in a similar way.
8148Example: >
8149 :let func_end='whizz'
8150 :call my_func_{func_end}(parameter)
8151
8152This would call the function "my_func_whizz(parameter)".
8153
Bram Moolenaar84f72352012-03-11 15:57:40 +01008154This does NOT work: >
8155 :let i = 3
8156 :let @{i} = '' " error
8157 :echo @{i} " error
8158
Bram Moolenaar071d4272004-06-13 20:20:40 +00008159==============================================================================
81607. Commands *expression-commands*
8161
8162:let {var-name} = {expr1} *:let* *E18*
8163 Set internal variable {var-name} to the result of the
8164 expression {expr1}. The variable will get the type
8165 from the {expr}. If {var-name} didn't exist yet, it
8166 is created.
8167
Bram Moolenaar13065c42005-01-08 16:08:21 +00008168:let {var-name}[{idx}] = {expr1} *E689*
8169 Set a list item to the result of the expression
8170 {expr1}. {var-name} must refer to a list and {idx}
8171 must be a valid index in that list. For nested list
8172 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008173 This cannot be used to add an item to a |List|.
8174 This cannot be used to set a byte in a String. You
8175 can do that like this: >
8176 :let var = var[0:2] . 'X' . var[4:]
8177<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008178 *E711* *E719*
8179:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008180 Set a sequence of items in a |List| to the result of
8181 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008182 correct number of items.
8183 {idx1} can be omitted, zero is used instead.
8184 {idx2} can be omitted, meaning the end of the list.
8185 When the selected range of items is partly past the
8186 end of the list, items will be added.
8187
Bram Moolenaar748bf032005-02-02 23:04:36 +00008188 *:let+=* *:let-=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008189:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
8190:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
8191:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
8192 These fail if {var} was not set yet and when the type
8193 of {var} and {expr1} don't fit the operator.
8194
8195
Bram Moolenaar071d4272004-06-13 20:20:40 +00008196:let ${env-name} = {expr1} *:let-environment* *:let-$*
8197 Set environment variable {env-name} to the result of
8198 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008199:let ${env-name} .= {expr1}
8200 Append {expr1} to the environment variable {env-name}.
8201 If the environment variable didn't exist yet this
8202 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00008203
8204:let @{reg-name} = {expr1} *:let-register* *:let-@*
8205 Write the result of the expression {expr1} in register
8206 {reg-name}. {reg-name} must be a single letter, and
8207 must be the name of a writable register (see
8208 |registers|). "@@" can be used for the unnamed
8209 register, "@/" for the search pattern.
8210 If the result of {expr1} ends in a <CR> or <NL>, the
8211 register will be linewise, otherwise it will be set to
8212 characterwise.
8213 This can be used to clear the last search pattern: >
8214 :let @/ = ""
8215< This is different from searching for an empty string,
8216 that would match everywhere.
8217
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008218:let @{reg-name} .= {expr1}
Bram Moolenaar446cb832008-06-24 21:56:24 +00008219 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008220 register was empty it's like setting it to {expr1}.
8221
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008222:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008223 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008224 expression {expr1}. A String or Number value is
8225 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008226 For an option local to a window or buffer the effect
8227 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00008228 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008229 Example: >
8230 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00008231
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008232:let &{option-name} .= {expr1}
8233 For a string option: Append {expr1} to the value.
8234 Does not insert a comma like |:set+=|.
8235
8236:let &{option-name} += {expr1}
8237:let &{option-name} -= {expr1}
8238 For a number or boolean option: Add or subtract
8239 {expr1}.
8240
Bram Moolenaar071d4272004-06-13 20:20:40 +00008241:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008242:let &l:{option-name} .= {expr1}
8243:let &l:{option-name} += {expr1}
8244:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008245 Like above, but only set the local value of an option
8246 (if there is one). Works like |:setlocal|.
8247
8248:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008249:let &g:{option-name} .= {expr1}
8250:let &g:{option-name} += {expr1}
8251:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008252 Like above, but only set the global value of an option
8253 (if there is one). Works like |:setglobal|.
8254
Bram Moolenaar13065c42005-01-08 16:08:21 +00008255:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008256 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008257 the list is assigned to {name1}, the second item to
8258 {name2}, etc.
8259 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008260 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008261 Each name can be one of the items of the ":let"
8262 command as mentioned above.
8263 Example: >
8264 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008265< Detail: {expr1} is evaluated first, then the
8266 assignments are done in sequence. This matters if
8267 {name2} depends on {name1}. Example: >
8268 :let x = [0, 1]
8269 :let i = 0
8270 :let [i, x[i]] = [1, 2]
8271 :echo x
8272< The result is [0, 2].
8273
8274:let [{name1}, {name2}, ...] .= {expr1}
8275:let [{name1}, {name2}, ...] += {expr1}
8276:let [{name1}, {name2}, ...] -= {expr1}
8277 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008278 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008279
8280:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008281 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008282 items than there are names. A list of the remaining
8283 items is assigned to {lastname}. If there are no
8284 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00008285 Example: >
8286 :let [a, b; rest] = ["aval", "bval", 3, 4]
8287<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008288:let [{name}, ..., ; {lastname}] .= {expr1}
8289:let [{name}, ..., ; {lastname}] += {expr1}
8290:let [{name}, ..., ; {lastname}] -= {expr1}
8291 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008292 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02008293
8294 *E121*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008295:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00008296 variable names may be given. Special names recognized
8297 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00008298 g: global variables
8299 b: local buffer variables
8300 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00008301 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00008302 s: script-local variables
8303 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00008304 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008305
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008306:let List the values of all variables. The type of the
8307 variable is indicated before the value:
8308 <nothing> String
8309 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008310 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00008311
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008312
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008313:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008314 Remove the internal variable {name}. Several variable
8315 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008316 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008317 With [!] no error message is given for non-existing
8318 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008319 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00008320 :unlet list[3] " remove fourth item
8321 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008322< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00008323 :unlet dict['two']
8324 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00008325< This is especially useful to clean up used global
8326 variables and script-local variables (these are not
8327 deleted when the script ends). Function-local
8328 variables are automatically deleted when the function
8329 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008330
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008331:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
8332 Lock the internal variable {name}. Locking means that
8333 it can no longer be changed (until it is unlocked).
8334 A locked variable can be deleted: >
8335 :lockvar v
8336 :let v = 'asdf' " fails!
8337 :unlet v
8338< *E741*
8339 If you try to change a locked variable you get an
Bram Moolenaar8a94d872015-01-25 13:02:57 +01008340 error message: "E741: Value is locked: {name}"
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008341
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008342 [depth] is relevant when locking a |List| or
8343 |Dictionary|. It specifies how deep the locking goes:
8344 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008345 cannot add or remove items, but can
8346 still change their values.
8347 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008348 the items. If an item is a |List| or
8349 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008350 items, but can still change the
8351 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008352 3 Like 2 but for the |List| /
8353 |Dictionary| in the |List| /
8354 |Dictionary|, one level deeper.
8355 The default [depth] is 2, thus when {name} is a |List|
8356 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008357 *E743*
8358 For unlimited depth use [!] and omit [depth].
8359 However, there is a maximum depth of 100 to catch
8360 loops.
8361
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008362 Note that when two variables refer to the same |List|
8363 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00008364 locked when used through the other variable.
8365 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00008366 :let l = [0, 1, 2, 3]
8367 :let cl = l
8368 :lockvar l
8369 :let cl[1] = 99 " won't work!
8370< You may want to make a copy of a list to avoid this.
8371 See |deepcopy()|.
8372
8373
8374:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
8375 Unlock the internal variable {name}. Does the
8376 opposite of |:lockvar|.
8377
8378
Bram Moolenaar071d4272004-06-13 20:20:40 +00008379:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
8380:en[dif] Execute the commands until the next matching ":else"
8381 or ":endif" if {expr1} evaluates to non-zero.
8382
8383 From Vim version 4.5 until 5.0, every Ex command in
8384 between the ":if" and ":endif" is ignored. These two
8385 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +01008386 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00008387 that any ":else" or ":elseif" was ignored, the "else"
8388 part was not executed either.
8389
8390 You can use this to remain compatible with older
8391 versions: >
8392 :if version >= 500
8393 : version-5-specific-commands
8394 :endif
8395< The commands still need to be parsed to find the
8396 "endif". Sometimes an older Vim has a problem with a
8397 new command. For example, ":silent" is recognized as
8398 a ":substitute" command. In that case ":execute" can
8399 avoid problems: >
8400 :if version >= 600
8401 : execute "silent 1,$delete"
8402 :endif
8403<
8404 NOTE: The ":append" and ":insert" commands don't work
8405 properly in between ":if" and ":endif".
8406
8407 *:else* *:el* *E581* *E583*
8408:el[se] Execute the commands until the next matching ":else"
8409 or ":endif" if they previously were not being
8410 executed.
8411
8412 *:elseif* *:elsei* *E582* *E584*
8413:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
8414 is no extra ":endif".
8415
8416:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008417 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008418:endw[hile] Repeat the commands between ":while" and ":endwhile",
8419 as long as {expr1} evaluates to non-zero.
8420 When an error is detected from a command inside the
8421 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00008422 Example: >
8423 :let lnum = 1
8424 :while lnum <= line("$")
8425 :call FixLine(lnum)
8426 :let lnum = lnum + 1
8427 :endwhile
8428<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008429 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00008430 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008431
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008432:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00008433:endfo[r] *:endfo* *:endfor*
8434 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008435 each item in {list}. Variable {var} is set to the
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008436 value of each item.
8437 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00008438 loop, execution continues after the "endfor".
Bram Moolenaar572cb562005-08-05 21:35:02 +00008439 Changing {list} inside the loop affects what items are
8440 used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008441 :for item in copy(mylist)
8442< When not making a copy, Vim stores a reference to the
8443 next item in the list, before executing the commands
Bram Moolenaar446cb832008-06-24 21:56:24 +00008444 with the current item. Thus the current item can be
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008445 removed without effect. Removing any later item means
8446 it will not be found. Thus the following example
8447 works (an inefficient way to make a list empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008448 for item in mylist
8449 call remove(mylist, 0)
8450 endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00008451< Note that reordering the list (e.g., with sort() or
8452 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +00008453
Bram Moolenaar12805862005-01-05 22:16:17 +00008454:for [{var1}, {var2}, ...] in {listlist}
8455:endfo[r]
8456 Like ":for" above, but each item in {listlist} must be
8457 a list, of which each item is assigned to {var1},
8458 {var2}, etc. Example: >
8459 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
8460 :echo getline(lnum)[col]
8461 :endfor
8462<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008463 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00008464:con[tinue] When used inside a ":while" or ":for" loop, jumps back
8465 to the start of the loop.
8466 If it is used after a |:try| inside the loop but
8467 before the matching |:finally| (if present), the
8468 commands following the ":finally" up to the matching
8469 |:endtry| are executed first. This process applies to
8470 all nested ":try"s inside the loop. The outermost
8471 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008472
8473 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00008474:brea[k] When used inside a ":while" or ":for" loop, skips to
8475 the command after the matching ":endwhile" or
8476 ":endfor".
8477 If it is used after a |:try| inside the loop but
8478 before the matching |:finally| (if present), the
8479 commands following the ":finally" up to the matching
8480 |:endtry| are executed first. This process applies to
8481 all nested ":try"s inside the loop. The outermost
8482 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008483
8484:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
8485:endt[ry] Change the error handling for the commands between
8486 ":try" and ":endtry" including everything being
8487 executed across ":source" commands, function calls,
8488 or autocommand invocations.
8489
8490 When an error or interrupt is detected and there is
8491 a |:finally| command following, execution continues
8492 after the ":finally". Otherwise, or when the
8493 ":endtry" is reached thereafter, the next
8494 (dynamically) surrounding ":try" is checked for
8495 a corresponding ":finally" etc. Then the script
8496 processing is terminated. (Whether a function
8497 definition has an "abort" argument does not matter.)
8498 Example: >
8499 :try | edit too much | finally | echo "cleanup" | endtry
8500 :echo "impossible" " not reached, script terminated above
8501<
8502 Moreover, an error or interrupt (dynamically) inside
8503 ":try" and ":endtry" is converted to an exception. It
8504 can be caught as if it were thrown by a |:throw|
8505 command (see |:catch|). In this case, the script
8506 processing is not terminated.
8507
8508 The value "Vim:Interrupt" is used for an interrupt
8509 exception. An error in a Vim command is converted
8510 to a value of the form "Vim({command}):{errmsg}",
8511 other errors are converted to a value of the form
8512 "Vim:{errmsg}". {command} is the full command name,
8513 and {errmsg} is the message that is displayed if the
8514 error exception is not caught, always beginning with
8515 the error number.
8516 Examples: >
8517 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
8518 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
8519<
8520 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008521:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008522 |:finally|, or |:endtry| that belongs to the same
8523 |:try| as the ":catch" are executed when an exception
8524 matching {pattern} is being thrown and has not yet
8525 been caught by a previous ":catch". Otherwise, these
8526 commands are skipped.
8527 When {pattern} is omitted all errors are caught.
8528 Examples: >
8529 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
8530 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
8531 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
8532 :catch /^Vim(write):/ " catch all errors in :write
8533 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
8534 :catch /my-exception/ " catch user exception
8535 :catch /.*/ " catch everything
8536 :catch " same as /.*/
8537<
8538 Another character can be used instead of / around the
8539 {pattern}, so long as it does not have a special
8540 meaning (e.g., '|' or '"') and doesn't occur inside
8541 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02008542 Information about the exception is available in
8543 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008544 NOTE: It is not reliable to ":catch" the TEXT of
8545 an error message because it may vary in different
8546 locales.
8547
8548 *:fina* *:finally* *E606* *E607*
8549:fina[lly] The following commands until the matching |:endtry|
8550 are executed whenever the part between the matching
8551 |:try| and the ":finally" is left: either by falling
8552 through to the ":finally" or by a |:continue|,
8553 |:break|, |:finish|, or |:return|, or by an error or
8554 interrupt or exception (see |:throw|).
8555
8556 *:th* *:throw* *E608*
8557:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
8558 If the ":throw" is used after a |:try| but before the
8559 first corresponding |:catch|, commands are skipped
8560 until the first ":catch" matching {expr1} is reached.
8561 If there is no such ":catch" or if the ":throw" is
8562 used after a ":catch" but before the |:finally|, the
8563 commands following the ":finally" (if present) up to
8564 the matching |:endtry| are executed. If the ":throw"
8565 is after the ":finally", commands up to the ":endtry"
8566 are skipped. At the ":endtry", this process applies
8567 again for the next dynamically surrounding ":try"
8568 (which may be found in a calling function or sourcing
8569 script), until a matching ":catch" has been found.
8570 If the exception is not caught, the command processing
8571 is terminated.
8572 Example: >
8573 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01008574< Note that "catch" may need to be on a separate line
8575 for when an error causes the parsing to skip the whole
8576 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008577
8578 *:ec* *:echo*
8579:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
8580 first {expr1} starts on a new line.
8581 Also see |:comment|.
8582 Use "\n" to start a new line. Use "\r" to move the
8583 cursor to the first column.
8584 Uses the highlighting set by the |:echohl| command.
8585 Cannot be followed by a comment.
8586 Example: >
8587 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008588< *:echo-redraw*
8589 A later redraw may make the message disappear again.
8590 And since Vim mostly postpones redrawing until it's
8591 finished with a sequence of commands this happens
8592 quite often. To avoid that a command from before the
8593 ":echo" causes a redraw afterwards (redraws are often
8594 postponed until you type something), force a redraw
8595 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008596 :new | redraw | echo "there is a new window"
8597<
8598 *:echon*
8599:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
8600 |:comment|.
8601 Uses the highlighting set by the |:echohl| command.
8602 Cannot be followed by a comment.
8603 Example: >
8604 :echon "the value of 'shell' is " &shell
8605<
8606 Note the difference between using ":echo", which is a
8607 Vim command, and ":!echo", which is an external shell
8608 command: >
8609 :!echo % --> filename
8610< The arguments of ":!" are expanded, see |:_%|. >
8611 :!echo "%" --> filename or "filename"
8612< Like the previous example. Whether you see the double
8613 quotes or not depends on your 'shell'. >
8614 :echo % --> nothing
8615< The '%' is an illegal character in an expression. >
8616 :echo "%" --> %
8617< This just echoes the '%' character. >
8618 :echo expand("%") --> filename
8619< This calls the expand() function to expand the '%'.
8620
8621 *:echoh* *:echohl*
8622:echoh[l] {name} Use the highlight group {name} for the following
8623 |:echo|, |:echon| and |:echomsg| commands. Also used
8624 for the |input()| prompt. Example: >
8625 :echohl WarningMsg | echo "Don't panic!" | echohl None
8626< Don't forget to set the group back to "None",
8627 otherwise all following echo's will be highlighted.
8628
8629 *:echom* *:echomsg*
8630:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
8631 message in the |message-history|.
8632 Spaces are placed between the arguments as with the
8633 |:echo| command. But unprintable characters are
8634 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008635 The parsing works slightly different from |:echo|,
8636 more like |:execute|. All the expressions are first
8637 evaluated and concatenated before echoing anything.
8638 The expressions must evaluate to a Number or String, a
8639 Dictionary or List causes an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008640 Uses the highlighting set by the |:echohl| command.
8641 Example: >
8642 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008643< See |:echo-redraw| to avoid the message disappearing
8644 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008645 *:echoe* *:echoerr*
8646:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
8647 message in the |message-history|. When used in a
8648 script or function the line number will be added.
8649 Spaces are placed between the arguments as with the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008650 :echo command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008651 the message is raised as an error exception instead
8652 (see |try-echoerr|).
8653 Example: >
8654 :echoerr "This script just failed!"
8655< If you just want a highlighted message use |:echohl|.
8656 And to get a beep: >
8657 :exe "normal \<Esc>"
8658<
8659 *:exe* *:execute*
8660:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008661 of {expr1} as an Ex command.
8662 Multiple arguments are concatenated, with a space in
8663 between. To avoid the extra space use the "."
8664 operator to concatenate strings into one argument.
8665 {expr1} is used as the processed command, command line
8666 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008667 Cannot be followed by a comment.
8668 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02008669 :execute "buffer" nextbuf
8670 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008671<
8672 ":execute" can be used to append a command to commands
8673 that don't accept a '|'. Example: >
8674 :execute '!ls' | echo "theend"
8675
8676< ":execute" is also a nice way to avoid having to type
8677 control characters in a Vim script for a ":normal"
8678 command: >
8679 :execute "normal ixxx\<Esc>"
8680< This has an <Esc> character, see |expr-string|.
8681
Bram Moolenaar446cb832008-06-24 21:56:24 +00008682 Be careful to correctly escape special characters in
8683 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008684 for Vim commands, |shellescape()| for |:!| commands.
8685 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00008686 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +01008687 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00008688<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008689 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01008690 starting or ending "if", "while" and "for" does not
8691 always work, because when commands are skipped the
8692 ":execute" is not evaluated and Vim loses track of
8693 where blocks start and end. Also "break" and
8694 "continue" should not be inside ":execute".
8695 This example does not work, because the ":execute" is
8696 not evaluated and Vim does not see the "while", and
8697 gives an error for finding an ":endwhile": >
8698 :if 0
8699 : execute 'while i > 5'
8700 : echo "test"
8701 : endwhile
8702 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00008703<
8704 It is allowed to have a "while" or "if" command
8705 completely in the executed string: >
8706 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
8707<
8708
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008709 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008710 ":execute", ":echo" and ":echon" cannot be followed by
8711 a comment directly, because they see the '"' as the
8712 start of a string. But, you can use '|' followed by a
8713 comment. Example: >
8714 :echo "foo" | "this is a comment
8715
8716==============================================================================
87178. Exception handling *exception-handling*
8718
8719The Vim script language comprises an exception handling feature. This section
8720explains how it can be used in a Vim script.
8721
8722Exceptions may be raised by Vim on an error or on interrupt, see
8723|catch-errors| and |catch-interrupt|. You can also explicitly throw an
8724exception by using the ":throw" command, see |throw-catch|.
8725
8726
8727TRY CONDITIONALS *try-conditionals*
8728
8729Exceptions can be caught or can cause cleanup code to be executed. You can
8730use a try conditional to specify catch clauses (that catch exceptions) and/or
8731a finally clause (to be executed for cleanup).
8732 A try conditional begins with a |:try| command and ends at the matching
8733|:endtry| command. In between, you can use a |:catch| command to start
8734a catch clause, or a |:finally| command to start a finally clause. There may
8735be none or multiple catch clauses, but there is at most one finally clause,
8736which must not be followed by any catch clauses. The lines before the catch
8737clauses and the finally clause is called a try block. >
8738
8739 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00008740 : ...
8741 : ... TRY BLOCK
8742 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008743 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00008744 : ...
8745 : ... CATCH CLAUSE
8746 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008747 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00008748 : ...
8749 : ... CATCH CLAUSE
8750 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008751 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00008752 : ...
8753 : ... FINALLY CLAUSE
8754 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00008755 :endtry
8756
8757The try conditional allows to watch code for exceptions and to take the
8758appropriate actions. Exceptions from the try block may be caught. Exceptions
8759from the try block and also the catch clauses may cause cleanup actions.
8760 When no exception is thrown during execution of the try block, the control
8761is transferred to the finally clause, if present. After its execution, the
8762script continues with the line following the ":endtry".
8763 When an exception occurs during execution of the try block, the remaining
8764lines in the try block are skipped. The exception is matched against the
8765patterns specified as arguments to the ":catch" commands. The catch clause
8766after the first matching ":catch" is taken, other catch clauses are not
8767executed. The catch clause ends when the next ":catch", ":finally", or
8768":endtry" command is reached - whatever is first. Then, the finally clause
8769(if present) is executed. When the ":endtry" is reached, the script execution
8770continues in the following line as usual.
8771 When an exception that does not match any of the patterns specified by the
8772":catch" commands is thrown in the try block, the exception is not caught by
8773that try conditional and none of the catch clauses is executed. Only the
8774finally clause, if present, is taken. The exception pends during execution of
8775the finally clause. It is resumed at the ":endtry", so that commands after
8776the ":endtry" are not executed and the exception might be caught elsewhere,
8777see |try-nesting|.
8778 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008779remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00008780not matched against the patterns in any of the ":catch" commands of the same
8781try conditional and none of its catch clauses is taken. If there is, however,
8782a finally clause, it is executed, and the exception pends during its
8783execution. The commands following the ":endtry" are not executed. The new
8784exception might, however, be caught elsewhere, see |try-nesting|.
8785 When during execution of the finally clause (if present) an exception is
Bram Moolenaar446cb832008-06-24 21:56:24 +00008786thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00008787clause has been taken because of an exception from the try block or one of the
8788catch clauses, the original (pending) exception is discarded. The commands
8789following the ":endtry" are not executed, and the exception from the finally
8790clause is propagated and can be caught elsewhere, see |try-nesting|.
8791
8792The finally clause is also executed, when a ":break" or ":continue" for
8793a ":while" loop enclosing the complete try conditional is executed from the
8794try block or a catch clause. Or when a ":return" or ":finish" is executed
8795from the try block or a catch clause of a try conditional in a function or
8796sourced script, respectively. The ":break", ":continue", ":return", or
8797":finish" pends during execution of the finally clause and is resumed when the
8798":endtry" is reached. It is, however, discarded when an exception is thrown
8799from the finally clause.
8800 When a ":break" or ":continue" for a ":while" loop enclosing the complete
8801try conditional or when a ":return" or ":finish" is encountered in the finally
8802clause, the rest of the finally clause is skipped, and the ":break",
8803":continue", ":return" or ":finish" is executed as usual. If the finally
8804clause has been taken because of an exception or an earlier ":break",
8805":continue", ":return", or ":finish" from the try block or a catch clause,
8806this pending exception or command is discarded.
8807
8808For examples see |throw-catch| and |try-finally|.
8809
8810
8811NESTING OF TRY CONDITIONALS *try-nesting*
8812
8813Try conditionals can be nested arbitrarily. That is, a complete try
8814conditional can be put into the try block, a catch clause, or the finally
8815clause of another try conditional. If the inner try conditional does not
8816catch an exception thrown in its try block or throws a new exception from one
8817of its catch clauses or its finally clause, the outer try conditional is
8818checked according to the rules above. If the inner try conditional is in the
8819try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar446cb832008-06-24 21:56:24 +00008820otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00008821nesting, whether the inner try conditional is directly contained in the outer
8822one, or whether the outer one sources a script or calls a function containing
8823the inner try conditional.
8824
8825When none of the active try conditionals catches an exception, just their
8826finally clauses are executed. Thereafter, the script processing terminates.
8827An error message is displayed in case of an uncaught exception explicitly
8828thrown by a ":throw" command. For uncaught error and interrupt exceptions
8829implicitly raised by Vim, the error message(s) or interrupt message are shown
8830as usual.
8831
8832For examples see |throw-catch|.
8833
8834
8835EXAMINING EXCEPTION HANDLING CODE *except-examine*
8836
8837Exception handling code can get tricky. If you are in doubt what happens, set
8838'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
8839script file. Then you see when an exception is thrown, discarded, caught, or
8840finished. When using a verbosity level of at least 14, things pending in
8841a finally clause are also shown. This information is also given in debug mode
8842(see |debug-scripts|).
8843
8844
8845THROWING AND CATCHING EXCEPTIONS *throw-catch*
8846
8847You can throw any number or string as an exception. Use the |:throw| command
8848and pass the value to be thrown as argument: >
8849 :throw 4711
8850 :throw "string"
8851< *throw-expression*
8852You can also specify an expression argument. The expression is then evaluated
8853first, and the result is thrown: >
8854 :throw 4705 + strlen("string")
8855 :throw strpart("strings", 0, 6)
8856
8857An exception might be thrown during evaluation of the argument of the ":throw"
8858command. Unless it is caught there, the expression evaluation is abandoned.
8859The ":throw" command then does not throw a new exception.
8860 Example: >
8861
8862 :function! Foo(arg)
8863 : try
8864 : throw a:arg
8865 : catch /foo/
8866 : endtry
8867 : return 1
8868 :endfunction
8869 :
8870 :function! Bar()
8871 : echo "in Bar"
8872 : return 4710
8873 :endfunction
8874 :
8875 :throw Foo("arrgh") + Bar()
8876
8877This throws "arrgh", and "in Bar" is not displayed since Bar() is not
8878executed. >
8879 :throw Foo("foo") + Bar()
8880however displays "in Bar" and throws 4711.
8881
8882Any other command that takes an expression as argument might also be
Bram Moolenaar446cb832008-06-24 21:56:24 +00008883abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008884exception is then propagated to the caller of the command.
8885 Example: >
8886
8887 :if Foo("arrgh")
8888 : echo "then"
8889 :else
8890 : echo "else"
8891 :endif
8892
8893Here neither of "then" or "else" is displayed.
8894
8895 *catch-order*
8896Exceptions can be caught by a try conditional with one or more |:catch|
8897commands, see |try-conditionals|. The values to be caught by each ":catch"
8898command can be specified as a pattern argument. The subsequent catch clause
8899gets executed when a matching exception is caught.
8900 Example: >
8901
8902 :function! Foo(value)
8903 : try
8904 : throw a:value
8905 : catch /^\d\+$/
8906 : echo "Number thrown"
8907 : catch /.*/
8908 : echo "String thrown"
8909 : endtry
8910 :endfunction
8911 :
8912 :call Foo(0x1267)
8913 :call Foo('string')
8914
8915The first call to Foo() displays "Number thrown", the second "String thrown".
8916An exception is matched against the ":catch" commands in the order they are
8917specified. Only the first match counts. So you should place the more
8918specific ":catch" first. The following order does not make sense: >
8919
8920 : catch /.*/
8921 : echo "String thrown"
8922 : catch /^\d\+$/
8923 : echo "Number thrown"
8924
8925The first ":catch" here matches always, so that the second catch clause is
8926never taken.
8927
8928 *throw-variables*
8929If you catch an exception by a general pattern, you may access the exact value
8930in the variable |v:exception|: >
8931
8932 : catch /^\d\+$/
8933 : echo "Number thrown. Value is" v:exception
8934
8935You may also be interested where an exception was thrown. This is stored in
8936|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
8937exception most recently caught as long it is not finished.
8938 Example: >
8939
8940 :function! Caught()
8941 : if v:exception != ""
8942 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
8943 : else
8944 : echo 'Nothing caught'
8945 : endif
8946 :endfunction
8947 :
8948 :function! Foo()
8949 : try
8950 : try
8951 : try
8952 : throw 4711
8953 : finally
8954 : call Caught()
8955 : endtry
8956 : catch /.*/
8957 : call Caught()
8958 : throw "oops"
8959 : endtry
8960 : catch /.*/
8961 : call Caught()
8962 : finally
8963 : call Caught()
8964 : endtry
8965 :endfunction
8966 :
8967 :call Foo()
8968
8969This displays >
8970
8971 Nothing caught
8972 Caught "4711" in function Foo, line 4
8973 Caught "oops" in function Foo, line 10
8974 Nothing caught
8975
8976A practical example: The following command ":LineNumber" displays the line
8977number in the script or function where it has been used: >
8978
8979 :function! LineNumber()
8980 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
8981 :endfunction
8982 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
8983<
8984 *try-nested*
8985An exception that is not caught by a try conditional can be caught by
8986a surrounding try conditional: >
8987
8988 :try
8989 : try
8990 : throw "foo"
8991 : catch /foobar/
8992 : echo "foobar"
8993 : finally
8994 : echo "inner finally"
8995 : endtry
8996 :catch /foo/
8997 : echo "foo"
8998 :endtry
8999
9000The inner try conditional does not catch the exception, just its finally
9001clause is executed. The exception is then caught by the outer try
9002conditional. The example displays "inner finally" and then "foo".
9003
9004 *throw-from-catch*
9005You can catch an exception and throw a new one to be caught elsewhere from the
9006catch clause: >
9007
9008 :function! Foo()
9009 : throw "foo"
9010 :endfunction
9011 :
9012 :function! Bar()
9013 : try
9014 : call Foo()
9015 : catch /foo/
9016 : echo "Caught foo, throw bar"
9017 : throw "bar"
9018 : endtry
9019 :endfunction
9020 :
9021 :try
9022 : call Bar()
9023 :catch /.*/
9024 : echo "Caught" v:exception
9025 :endtry
9026
9027This displays "Caught foo, throw bar" and then "Caught bar".
9028
9029 *rethrow*
9030There is no real rethrow in the Vim script language, but you may throw
9031"v:exception" instead: >
9032
9033 :function! Bar()
9034 : try
9035 : call Foo()
9036 : catch /.*/
9037 : echo "Rethrow" v:exception
9038 : throw v:exception
9039 : endtry
9040 :endfunction
9041< *try-echoerr*
9042Note that this method cannot be used to "rethrow" Vim error or interrupt
9043exceptions, because it is not possible to fake Vim internal exceptions.
9044Trying so causes an error exception. You should throw your own exception
9045denoting the situation. If you want to cause a Vim error exception containing
9046the original error exception value, you can use the |:echoerr| command: >
9047
9048 :try
9049 : try
9050 : asdf
9051 : catch /.*/
9052 : echoerr v:exception
9053 : endtry
9054 :catch /.*/
9055 : echo v:exception
9056 :endtry
9057
9058This code displays
9059
Bram Moolenaar446cb832008-06-24 21:56:24 +00009060 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009061
9062
9063CLEANUP CODE *try-finally*
9064
9065Scripts often change global settings and restore them at their end. If the
9066user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar446cb832008-06-24 21:56:24 +00009067an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00009068a script when an error occurs or you explicitly throw an exception without
9069catching it. You can solve these problems by using a try conditional with
9070a finally clause for restoring the settings. Its execution is guaranteed on
9071normal control flow, on error, on an explicit ":throw", and on interrupt.
9072(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar446cb832008-06-24 21:56:24 +00009073to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00009074clause has been executed.)
9075Example: >
9076
9077 :try
9078 : let s:saved_ts = &ts
9079 : set ts=17
9080 :
9081 : " Do the hard work here.
9082 :
9083 :finally
9084 : let &ts = s:saved_ts
9085 : unlet s:saved_ts
9086 :endtry
9087
9088This method should be used locally whenever a function or part of a script
9089changes global settings which need to be restored on failure or normal exit of
9090that function or script part.
9091
9092 *break-finally*
9093Cleanup code works also when the try block or a catch clause is left by
9094a ":continue", ":break", ":return", or ":finish".
9095 Example: >
9096
9097 :let first = 1
9098 :while 1
9099 : try
9100 : if first
9101 : echo "first"
9102 : let first = 0
9103 : continue
9104 : else
9105 : throw "second"
9106 : endif
9107 : catch /.*/
9108 : echo v:exception
9109 : break
9110 : finally
9111 : echo "cleanup"
9112 : endtry
9113 : echo "still in while"
9114 :endwhile
9115 :echo "end"
9116
9117This displays "first", "cleanup", "second", "cleanup", and "end". >
9118
9119 :function! Foo()
9120 : try
9121 : return 4711
9122 : finally
9123 : echo "cleanup\n"
9124 : endtry
9125 : echo "Foo still active"
9126 :endfunction
9127 :
9128 :echo Foo() "returned by Foo"
9129
9130This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar446cb832008-06-24 21:56:24 +00009131extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009132return value.)
9133
9134 *except-from-finally*
9135Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
9136a finally clause is possible, but not recommended since it abandons the
9137cleanup actions for the try conditional. But, of course, interrupt and error
9138exceptions might get raised from a finally clause.
9139 Example where an error in the finally clause stops an interrupt from
9140working correctly: >
9141
9142 :try
9143 : try
9144 : echo "Press CTRL-C for interrupt"
9145 : while 1
9146 : endwhile
9147 : finally
9148 : unlet novar
9149 : endtry
9150 :catch /novar/
9151 :endtry
9152 :echo "Script still running"
9153 :sleep 1
9154
9155If you need to put commands that could fail into a finally clause, you should
9156think about catching or ignoring the errors in these commands, see
9157|catch-errors| and |ignore-errors|.
9158
9159
9160CATCHING ERRORS *catch-errors*
9161
9162If you want to catch specific errors, you just have to put the code to be
9163watched in a try block and add a catch clause for the error message. The
9164presence of the try conditional causes all errors to be converted to an
9165exception. No message is displayed and |v:errmsg| is not set then. To find
9166the right pattern for the ":catch" command, you have to know how the format of
9167the error exception is.
9168 Error exceptions have the following format: >
9169
9170 Vim({cmdname}):{errmsg}
9171or >
9172 Vim:{errmsg}
9173
9174{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar446cb832008-06-24 21:56:24 +00009175the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00009176when the error occurs outside try conditionals. It always begins with
9177a capital "E", followed by a two or three-digit error number, a colon, and
9178a space.
9179
9180Examples:
9181
9182The command >
9183 :unlet novar
9184normally produces the error message >
9185 E108: No such variable: "novar"
9186which is converted inside try conditionals to an exception >
9187 Vim(unlet):E108: No such variable: "novar"
9188
9189The command >
9190 :dwim
9191normally produces the error message >
9192 E492: Not an editor command: dwim
9193which is converted inside try conditionals to an exception >
9194 Vim:E492: Not an editor command: dwim
9195
9196You can catch all ":unlet" errors by a >
9197 :catch /^Vim(unlet):/
9198or all errors for misspelled command names by a >
9199 :catch /^Vim:E492:/
9200
9201Some error messages may be produced by different commands: >
9202 :function nofunc
9203and >
9204 :delfunction nofunc
9205both produce the error message >
9206 E128: Function name must start with a capital: nofunc
9207which is converted inside try conditionals to an exception >
9208 Vim(function):E128: Function name must start with a capital: nofunc
9209or >
9210 Vim(delfunction):E128: Function name must start with a capital: nofunc
9211respectively. You can catch the error by its number independently on the
9212command that caused it if you use the following pattern: >
9213 :catch /^Vim(\a\+):E128:/
9214
9215Some commands like >
9216 :let x = novar
9217produce multiple error messages, here: >
9218 E121: Undefined variable: novar
9219 E15: Invalid expression: novar
9220Only the first is used for the exception value, since it is the most specific
9221one (see |except-several-errors|). So you can catch it by >
9222 :catch /^Vim(\a\+):E121:/
9223
9224You can catch all errors related to the name "nofunc" by >
9225 :catch /\<nofunc\>/
9226
9227You can catch all Vim errors in the ":write" and ":read" commands by >
9228 :catch /^Vim(\(write\|read\)):E\d\+:/
9229
9230You can catch all Vim errors by the pattern >
9231 :catch /^Vim\((\a\+)\)\=:E\d\+:/
9232<
9233 *catch-text*
9234NOTE: You should never catch the error message text itself: >
9235 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01009236only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +00009237a different language by the |:language| command. It is however helpful to
9238cite the message text in a comment: >
9239 :catch /^Vim(\a\+):E108:/ " No such variable
9240
9241
9242IGNORING ERRORS *ignore-errors*
9243
9244You can ignore errors in a specific Vim command by catching them locally: >
9245
9246 :try
9247 : write
9248 :catch
9249 :endtry
9250
9251But you are strongly recommended NOT to use this simple form, since it could
9252catch more than you want. With the ":write" command, some autocommands could
9253be executed and cause errors not related to writing, for instance: >
9254
9255 :au BufWritePre * unlet novar
9256
9257There could even be such errors you are not responsible for as a script
9258writer: a user of your script might have defined such autocommands. You would
9259then hide the error from the user.
9260 It is much better to use >
9261
9262 :try
9263 : write
9264 :catch /^Vim(write):/
9265 :endtry
9266
9267which only catches real write errors. So catch only what you'd like to ignore
9268intentionally.
9269
9270For a single command that does not cause execution of autocommands, you could
9271even suppress the conversion of errors to exceptions by the ":silent!"
9272command: >
9273 :silent! nunmap k
9274This works also when a try conditional is active.
9275
9276
9277CATCHING INTERRUPTS *catch-interrupt*
9278
9279When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar446cb832008-06-24 21:56:24 +00009280the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00009281script is not terminated, then.
9282 Example: >
9283
9284 :function! TASK1()
9285 : sleep 10
9286 :endfunction
9287
9288 :function! TASK2()
9289 : sleep 20
9290 :endfunction
9291
9292 :while 1
9293 : let command = input("Type a command: ")
9294 : try
9295 : if command == ""
9296 : continue
9297 : elseif command == "END"
9298 : break
9299 : elseif command == "TASK1"
9300 : call TASK1()
9301 : elseif command == "TASK2"
9302 : call TASK2()
9303 : else
9304 : echo "\nIllegal command:" command
9305 : continue
9306 : endif
9307 : catch /^Vim:Interrupt$/
9308 : echo "\nCommand interrupted"
9309 : " Caught the interrupt. Continue with next prompt.
9310 : endtry
9311 :endwhile
9312
9313You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar446cb832008-06-24 21:56:24 +00009314a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009315
9316For testing what happens when CTRL-C would be pressed on a specific line in
9317your script, use the debug mode and execute the |>quit| or |>interrupt|
9318command on that line. See |debug-scripts|.
9319
9320
9321CATCHING ALL *catch-all*
9322
9323The commands >
9324
9325 :catch /.*/
9326 :catch //
9327 :catch
9328
9329catch everything, error exceptions, interrupt exceptions and exceptions
9330explicitly thrown by the |:throw| command. This is useful at the top level of
9331a script in order to catch unexpected things.
9332 Example: >
9333
9334 :try
9335 :
9336 : " do the hard work here
9337 :
9338 :catch /MyException/
9339 :
9340 : " handle known problem
9341 :
9342 :catch /^Vim:Interrupt$/
9343 : echo "Script interrupted"
9344 :catch /.*/
9345 : echo "Internal error (" . v:exception . ")"
9346 : echo " - occurred at " . v:throwpoint
9347 :endtry
9348 :" end of script
9349
9350Note: Catching all might catch more things than you want. Thus, you are
9351strongly encouraged to catch only for problems that you can really handle by
9352specifying a pattern argument to the ":catch".
9353 Example: Catching all could make it nearly impossible to interrupt a script
9354by pressing CTRL-C: >
9355
9356 :while 1
9357 : try
9358 : sleep 1
9359 : catch
9360 : endtry
9361 :endwhile
9362
9363
9364EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
9365
9366Exceptions may be used during execution of autocommands. Example: >
9367
9368 :autocmd User x try
9369 :autocmd User x throw "Oops!"
9370 :autocmd User x catch
9371 :autocmd User x echo v:exception
9372 :autocmd User x endtry
9373 :autocmd User x throw "Arrgh!"
9374 :autocmd User x echo "Should not be displayed"
9375 :
9376 :try
9377 : doautocmd User x
9378 :catch
9379 : echo v:exception
9380 :endtry
9381
9382This displays "Oops!" and "Arrgh!".
9383
9384 *except-autocmd-Pre*
9385For some commands, autocommands get executed before the main action of the
9386command takes place. If an exception is thrown and not caught in the sequence
9387of autocommands, the sequence and the command that caused its execution are
9388abandoned and the exception is propagated to the caller of the command.
9389 Example: >
9390
9391 :autocmd BufWritePre * throw "FAIL"
9392 :autocmd BufWritePre * echo "Should not be displayed"
9393 :
9394 :try
9395 : write
9396 :catch
9397 : echo "Caught:" v:exception "from" v:throwpoint
9398 :endtry
9399
9400Here, the ":write" command does not write the file currently being edited (as
9401you can see by checking 'modified'), since the exception from the BufWritePre
9402autocommand abandons the ":write". The exception is then caught and the
9403script displays: >
9404
9405 Caught: FAIL from BufWrite Auto commands for "*"
9406<
9407 *except-autocmd-Post*
9408For some commands, autocommands get executed after the main action of the
9409command has taken place. If this main action fails and the command is inside
9410an active try conditional, the autocommands are skipped and an error exception
9411is thrown that can be caught by the caller of the command.
9412 Example: >
9413
9414 :autocmd BufWritePost * echo "File successfully written!"
9415 :
9416 :try
9417 : write /i/m/p/o/s/s/i/b/l/e
9418 :catch
9419 : echo v:exception
9420 :endtry
9421
9422This just displays: >
9423
9424 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
9425
9426If you really need to execute the autocommands even when the main action
9427fails, trigger the event from the catch clause.
9428 Example: >
9429
9430 :autocmd BufWritePre * set noreadonly
9431 :autocmd BufWritePost * set readonly
9432 :
9433 :try
9434 : write /i/m/p/o/s/s/i/b/l/e
9435 :catch
9436 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
9437 :endtry
9438<
9439You can also use ":silent!": >
9440
9441 :let x = "ok"
9442 :let v:errmsg = ""
9443 :autocmd BufWritePost * if v:errmsg != ""
9444 :autocmd BufWritePost * let x = "after fail"
9445 :autocmd BufWritePost * endif
9446 :try
9447 : silent! write /i/m/p/o/s/s/i/b/l/e
9448 :catch
9449 :endtry
9450 :echo x
9451
9452This displays "after fail".
9453
9454If the main action of the command does not fail, exceptions from the
9455autocommands will be catchable by the caller of the command: >
9456
9457 :autocmd BufWritePost * throw ":-("
9458 :autocmd BufWritePost * echo "Should not be displayed"
9459 :
9460 :try
9461 : write
9462 :catch
9463 : echo v:exception
9464 :endtry
9465<
9466 *except-autocmd-Cmd*
9467For some commands, the normal action can be replaced by a sequence of
9468autocommands. Exceptions from that sequence will be catchable by the caller
9469of the command.
9470 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar446cb832008-06-24 21:56:24 +00009471had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00009472some way. >
9473
9474 :if !exists("cnt")
9475 : let cnt = 0
9476 :
9477 : autocmd BufWriteCmd * if &modified
9478 : autocmd BufWriteCmd * let cnt = cnt + 1
9479 : autocmd BufWriteCmd * if cnt % 3 == 2
9480 : autocmd BufWriteCmd * throw "BufWriteCmdError"
9481 : autocmd BufWriteCmd * endif
9482 : autocmd BufWriteCmd * write | set nomodified
9483 : autocmd BufWriteCmd * if cnt % 3 == 0
9484 : autocmd BufWriteCmd * throw "BufWriteCmdError"
9485 : autocmd BufWriteCmd * endif
9486 : autocmd BufWriteCmd * echo "File successfully written!"
9487 : autocmd BufWriteCmd * endif
9488 :endif
9489 :
9490 :try
9491 : write
9492 :catch /^BufWriteCmdError$/
9493 : if &modified
9494 : echo "Error on writing (file contents not changed)"
9495 : else
9496 : echo "Error after writing"
9497 : endif
9498 :catch /^Vim(write):/
9499 : echo "Error on writing"
9500 :endtry
9501
9502When this script is sourced several times after making changes, it displays
9503first >
9504 File successfully written!
9505then >
9506 Error on writing (file contents not changed)
9507then >
9508 Error after writing
9509etc.
9510
9511 *except-autocmd-ill*
9512You cannot spread a try conditional over autocommands for different events.
9513The following code is ill-formed: >
9514
9515 :autocmd BufWritePre * try
9516 :
9517 :autocmd BufWritePost * catch
9518 :autocmd BufWritePost * echo v:exception
9519 :autocmd BufWritePost * endtry
9520 :
9521 :write
9522
9523
9524EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
9525
9526Some programming languages allow to use hierarchies of exception classes or to
9527pass additional information with the object of an exception class. You can do
9528similar things in Vim.
9529 In order to throw an exception from a hierarchy, just throw the complete
9530class name with the components separated by a colon, for instance throw the
9531string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
9532 When you want to pass additional information with your exception class, add
9533it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
9534for an error when writing "myfile".
9535 With the appropriate patterns in the ":catch" command, you can catch for
9536base classes or derived classes of your hierarchy. Additional information in
9537parentheses can be cut out from |v:exception| with the ":substitute" command.
9538 Example: >
9539
9540 :function! CheckRange(a, func)
9541 : if a:a < 0
9542 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
9543 : endif
9544 :endfunction
9545 :
9546 :function! Add(a, b)
9547 : call CheckRange(a:a, "Add")
9548 : call CheckRange(a:b, "Add")
9549 : let c = a:a + a:b
9550 : if c < 0
9551 : throw "EXCEPT:MATHERR:OVERFLOW"
9552 : endif
9553 : return c
9554 :endfunction
9555 :
9556 :function! Div(a, b)
9557 : call CheckRange(a:a, "Div")
9558 : call CheckRange(a:b, "Div")
9559 : if (a:b == 0)
9560 : throw "EXCEPT:MATHERR:ZERODIV"
9561 : endif
9562 : return a:a / a:b
9563 :endfunction
9564 :
9565 :function! Write(file)
9566 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00009567 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009568 : catch /^Vim(write):/
9569 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
9570 : endtry
9571 :endfunction
9572 :
9573 :try
9574 :
9575 : " something with arithmetics and I/O
9576 :
9577 :catch /^EXCEPT:MATHERR:RANGE/
9578 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
9579 : echo "Range error in" function
9580 :
9581 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
9582 : echo "Math error"
9583 :
9584 :catch /^EXCEPT:IO/
9585 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
9586 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
9587 : if file !~ '^/'
9588 : let file = dir . "/" . file
9589 : endif
9590 : echo 'I/O error for "' . file . '"'
9591 :
9592 :catch /^EXCEPT/
9593 : echo "Unspecified error"
9594 :
9595 :endtry
9596
9597The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
9598a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
9599exceptions with the "Vim" prefix; they are reserved for Vim.
9600 Vim error exceptions are parameterized with the name of the command that
9601failed, if known. See |catch-errors|.
9602
9603
9604PECULIARITIES
9605 *except-compat*
9606The exception handling concept requires that the command sequence causing the
9607exception is aborted immediately and control is transferred to finally clauses
9608and/or a catch clause.
9609
9610In the Vim script language there are cases where scripts and functions
9611continue after an error: in functions without the "abort" flag or in a command
9612after ":silent!", control flow goes to the following line, and outside
9613functions, control flow goes to the line following the outermost ":endwhile"
9614or ":endif". On the other hand, errors should be catchable as exceptions
9615(thus, requiring the immediate abortion).
9616
9617This problem has been solved by converting errors to exceptions and using
9618immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar446cb832008-06-24 21:56:24 +00009619conditional is active. This is no restriction since an (error) exception can
9620be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00009621termination without catching the error, just use a try conditional without
9622catch clause. (You can cause cleanup code being executed before termination
9623by specifying a finally clause.)
9624
9625When no try conditional is active, the usual abortion and continuation
9626behavior is used instead of immediate abortion. This ensures compatibility of
9627scripts written for Vim 6.1 and earlier.
9628
9629However, when sourcing an existing script that does not use exception handling
9630commands (or when calling one of its functions) from inside an active try
9631conditional of a new script, you might change the control flow of the existing
9632script on error. You get the immediate abortion on error and can catch the
9633error in the new script. If however the sourced script suppresses error
9634messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar446cb832008-06-24 21:56:24 +00009635|v:errmsg| if appropriate), its execution path is not changed. The error is
9636not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00009637where this happens is for scripts that don't care about errors and produce
9638error messages. You probably won't want to use such code from your new
9639scripts.
9640
9641 *except-syntax-err*
9642Syntax errors in the exception handling commands are never caught by any of
9643the ":catch" commands of the try conditional they belong to. Its finally
9644clauses, however, is executed.
9645 Example: >
9646
9647 :try
9648 : try
9649 : throw 4711
9650 : catch /\(/
9651 : echo "in catch with syntax error"
9652 : catch
9653 : echo "inner catch-all"
9654 : finally
9655 : echo "inner finally"
9656 : endtry
9657 :catch
9658 : echo 'outer catch-all caught "' . v:exception . '"'
9659 : finally
9660 : echo "outer finally"
9661 :endtry
9662
9663This displays: >
9664 inner finally
9665 outer catch-all caught "Vim(catch):E54: Unmatched \("
9666 outer finally
9667The original exception is discarded and an error exception is raised, instead.
9668
9669 *except-single-line*
9670The ":try", ":catch", ":finally", and ":endtry" commands can be put on
9671a single line, but then syntax errors may make it difficult to recognize the
9672"catch" line, thus you better avoid this.
9673 Example: >
9674 :try | unlet! foo # | catch | endtry
9675raises an error exception for the trailing characters after the ":unlet!"
9676argument, but does not see the ":catch" and ":endtry" commands, so that the
9677error exception is discarded and the "E488: Trailing characters" message gets
9678displayed.
9679
9680 *except-several-errors*
9681When several errors appear in a single command, the first error message is
9682usually the most specific one and therefor converted to the error exception.
9683 Example: >
9684 echo novar
9685causes >
9686 E121: Undefined variable: novar
9687 E15: Invalid expression: novar
9688The value of the error exception inside try conditionals is: >
9689 Vim(echo):E121: Undefined variable: novar
9690< *except-syntax-error*
9691But when a syntax error is detected after a normal error in the same command,
9692the syntax error is used for the exception being thrown.
9693 Example: >
9694 unlet novar #
9695causes >
9696 E108: No such variable: "novar"
9697 E488: Trailing characters
9698The value of the error exception inside try conditionals is: >
9699 Vim(unlet):E488: Trailing characters
9700This is done because the syntax error might change the execution path in a way
9701not intended by the user. Example: >
9702 try
9703 try | unlet novar # | catch | echo v:exception | endtry
9704 catch /.*/
9705 echo "outer catch:" v:exception
9706 endtry
9707This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
9708a "E600: Missing :endtry" error message is given, see |except-single-line|.
9709
9710==============================================================================
97119. Examples *eval-examples*
9712
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009713Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009714>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009715 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009716 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009717 : let n = a:nr
9718 : let r = ""
9719 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009720 : let r = '01'[n % 2] . r
9721 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00009722 : endwhile
9723 : return r
9724 :endfunc
9725
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009726 :" The function String2Bin() converts each character in a string to a
9727 :" binary string, separated with dashes.
9728 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009729 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009730 : for ix in range(strlen(a:str))
9731 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
9732 : endfor
9733 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00009734 :endfunc
9735
9736Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009737 :echo Nr2Bin(32)
9738result: "100000" >
9739 :echo String2Bin("32")
9740result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009741
9742
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009743Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009744
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009745This example sorts lines with a specific compare function. >
9746
9747 :func SortBuffer()
9748 : let lines = getline(1, '$')
9749 : call sort(lines, function("Strcmp"))
9750 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009751 :endfunction
9752
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009753As a one-liner: >
9754 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00009755
Bram Moolenaar071d4272004-06-13 20:20:40 +00009756
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009757scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00009758 *sscanf*
9759There is no sscanf() function in Vim. If you need to extract parts from a
9760line, you can use matchstr() and substitute() to do it. This example shows
9761how to get the file name, line number and column number out of a line like
9762"foobar.txt, 123, 45". >
9763 :" Set up the match bit
9764 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
9765 :"get the part matching the whole expression
9766 :let l = matchstr(line, mx)
9767 :"get each item out of the match
9768 :let file = substitute(l, mx, '\1', '')
9769 :let lnum = substitute(l, mx, '\2', '')
9770 :let col = substitute(l, mx, '\3', '')
9771
9772The input is in the variable "line", the results in the variables "file",
9773"lnum" and "col". (idea from Michael Geddes)
9774
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009775
9776getting the scriptnames in a Dictionary ~
9777 *scriptnames-dictionary*
9778The |:scriptnames| command can be used to get a list of all script files that
9779have been sourced. There is no equivalent function or variable for this
9780(because it's rarely needed). In case you need to manipulate the list this
9781code can be used: >
9782 " Get the output of ":scriptnames" in the scriptnames_output variable.
9783 let scriptnames_output = ''
9784 redir => scriptnames_output
9785 silent scriptnames
9786 redir END
9787
Bram Moolenaar446cb832008-06-24 21:56:24 +00009788 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009789 " "scripts" dictionary.
9790 let scripts = {}
9791 for line in split(scriptnames_output, "\n")
9792 " Only do non-blank lines.
9793 if line =~ '\S'
9794 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009795 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009796 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00009797 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009798 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00009799 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009800 endif
9801 endfor
9802 unlet scriptnames_output
9803
Bram Moolenaar071d4272004-06-13 20:20:40 +00009804==============================================================================
980510. No +eval feature *no-eval-feature*
9806
9807When the |+eval| feature was disabled at compile time, none of the expression
9808evaluation commands are available. To prevent this from causing Vim scripts
9809to generate all kinds of errors, the ":if" and ":endif" commands are still
9810recognized, though the argument of the ":if" and everything between the ":if"
9811and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
9812only if the commands are at the start of the line. The ":else" command is not
9813recognized.
9814
9815Example of how to avoid executing commands when the |+eval| feature is
9816missing: >
9817
9818 :if 1
9819 : echo "Expression evaluation is compiled in"
9820 :else
9821 : echo "You will _never_ see this message"
9822 :endif
9823
9824==============================================================================
982511. The sandbox *eval-sandbox* *sandbox* *E48*
9826
Bram Moolenaar368373e2010-07-19 20:46:22 +02009827The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
9828'foldtext' options may be evaluated in a sandbox. This means that you are
9829protected from these expressions having nasty side effects. This gives some
9830safety for when these options are set from a modeline. It is also used when
9831the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009832The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009833
9834These items are not allowed in the sandbox:
9835 - changing the buffer text
9836 - defining or changing mapping, autocommands, functions, user commands
9837 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009838 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009839 - executing a shell command
9840 - reading or writing a file
9841 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00009842 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009843This is not guaranteed 100% secure, but it should block most attacks.
9844
9845 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00009846:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00009847 option that may have been set from a modeline, e.g.
9848 'foldexpr'.
9849
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009850 *sandbox-option*
9851A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00009852have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009853restrictive, thus this only happens when the option was set from an insecure
9854location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00009855- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009856- while executing in the sandbox
9857- value coming from a modeline
9858
9859Note that when in the sandbox and saving an option value and restoring it, the
9860option will still be marked as it was set in the sandbox.
9861
9862==============================================================================
986312. Textlock *textlock*
9864
9865In a few situations it is not allowed to change the text in the buffer, jump
9866to another window and some other things that might confuse or break what Vim
9867is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar446cb832008-06-24 21:56:24 +00009868actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00009869happen any moment the mouse cursor is resting at some position.
9870
9871This is not allowed when the textlock is active:
9872 - changing the buffer text
9873 - jumping to another buffer or window
9874 - editing another file
9875 - closing a window or quitting Vim
9876 - etc.
9877
Bram Moolenaar071d4272004-06-13 20:20:40 +00009878
9879 vim:tw=78:ts=8:ft=help:norl: