blob: 3e5c6ee44b1ec3da219c4b95bda5ba94503ae52c [file] [log] [blame]
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01001*eval.txt* For Vim version 8.2. Last change: 2021 Mar 10
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
Bram Moolenaar446cb832008-06-24 21:56:24 +00004 VIM REFERENCE MANUAL by Bram Moolenaar
Bram Moolenaar071d4272004-06-13 20:20:40 +00005
6
7Expression evaluation *expression* *expr* *E15* *eval*
8
9Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|.
10
11Note: Expression evaluation can be disabled at compile time. If this has been
Bram Moolenaar58b85342016-08-14 19:54:54 +020012done, 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 Moolenaar8a7d6542020-01-26 15:56:19 +010015This file is about the backwards compatible Vim script. For Vim9 script,
16which executes much faster, supports type checking and much more, see
17|vim9.txt|.
18
Bram Moolenaar13065c42005-01-08 16:08:21 +0000191. Variables |variables|
20 1.1 Variable types
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000021 1.2 Function references |Funcref|
Bram Moolenaar7c626922005-02-07 22:01:03 +000022 1.3 Lists |Lists|
Bram Moolenaard8b02732005-01-14 21:48:43 +000023 1.4 Dictionaries |Dictionaries|
Bram Moolenaard8968242019-01-15 22:51:57 +010024 1.5 Blobs |Blobs|
25 1.6 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000262. Expression syntax |expression-syntax|
273. Internal variable |internal-variables|
284. Builtin Functions |functions|
295. Defining functions |user-functions|
306. Curly braces names |curly-braces-names|
317. Commands |expression-commands|
328. Exception handling |exception-handling|
339. Examples |eval-examples|
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02003410. Vim script version |vimscript-version|
3511. No +eval feature |no-eval-feature|
3612. The sandbox |eval-sandbox|
3713. Textlock |textlock|
Bram Moolenaared997ad2019-07-21 16:42:00 +020038
39Testing support is documented in |testing.txt|.
40Profiling is documented at |profiling|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000041
Bram Moolenaar071d4272004-06-13 20:20:40 +000042==============================================================================
431. Variables *variables*
44
Bram Moolenaar13065c42005-01-08 16:08:21 +0000451.1 Variable types ~
Bram Moolenaarbf821bc2019-01-23 21:15:02 +010046 *E712* *E896* *E897* *E899*
Bram Moolenaar06fe74a2019-08-31 16:20:32 +020047There are ten types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000048
Bram Moolenaar664f3cf2019-12-07 16:03:51 +010049 *Number* *Integer*
50Number A 32 or 64 bit signed number. |expr-number|
Bram Moolenaarf9706e92020-02-22 14:27:04 +010051 The number of bits is available in |v:numbersize|.
Bram Moolenaar6f02b002021-01-10 20:22:54 +010052 Examples: -123 0x10 0177 0o177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000053
Bram Moolenaar446cb832008-06-24 21:56:24 +000054Float A floating point number. |floating-point-format| *Float*
55 {only when compiled with the |+float| feature}
56 Examples: 123.456 1.15e-6 -1.1e3
57
Bram Moolenaar06481422016-04-30 15:13:38 +020058 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000059String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000060 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000061
Bram Moolenaard8968242019-01-15 22:51:57 +010062List An ordered sequence of items, see |List| for details.
Bram Moolenaard8b02732005-01-14 21:48:43 +000063 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000064
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000065Dictionary An associative, unordered array: Each entry has a key and a
66 value. |Dictionary|
Bram Moolenaard5abb4c2019-07-13 22:46:10 +020067 Examples:
68 {'blue': "#0000ff", 'red': "#ff0000"}
Bram Moolenaar4c6d9042019-07-16 22:04:02 +020069 #{blue: "#0000ff", red: "#ff0000"}
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000070
Bram Moolenaar835dc632016-02-07 14:27:38 +010071Funcref A reference to a function |Funcref|.
72 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020073 It can be bound to a dictionary and arguments, it then works
74 like a Partial.
75 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010076
Bram Moolenaar02e83b42016-02-21 20:10:26 +010077Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010078
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020079Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010080
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020081Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010082
Bram Moolenaard8968242019-01-15 22:51:57 +010083Blob Binary Large Object. Stores any sequence of bytes. See |Blob|
84 for details
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010085 Example: 0zFF00ED015DAF
86 0z is an empty Blob.
87
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000088The Number and String types are converted automatically, depending on how they
89are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000090
91Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020092the Number. Examples:
93 Number 123 --> String "123" ~
94 Number 0 --> String "0" ~
95 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020096 *octal*
Bram Moolenaard43906d2020-07-20 21:31:32 +020097Conversion from a String to a Number only happens in legacy Vim script, not in
98Vim9 script. It is done by converting the first digits to a number.
99Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10"
Bram Moolenaar6f02b002021-01-10 20:22:54 +0100100numbers are recognized
101NOTE: when using |scriptversion-4| octal with a leading "0" is not recognized.
102The 0o notation requires patch 8.2.0886.
103If the String doesn't start with digits, the result is zero.
Bram Moolenaarfa735342016-01-03 22:14:44 +0100104Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200105 String "456" --> Number 456 ~
106 String "6bar" --> Number 6 ~
107 String "foo" --> Number 0 ~
108 String "0xf1" --> Number 241 ~
109 String "0100" --> Number 64 ~
Bram Moolenaarc17e66c2020-06-02 21:38:22 +0200110 String "0o100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +0100111 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200112 String "-8" --> Number -8 ~
113 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000114
115To force conversion from String to Number, add zero to it: >
116 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000117< 64 ~
118
119To avoid a leading zero to cause octal conversion, or for using a different
120base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000121
Bram Moolenaard09091d2019-01-17 16:07:22 +0100122 *TRUE* *FALSE* *Boolean*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000123For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100124You can also use |v:false| and |v:true|. In Vim9 script |false| and |true|.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200125When TRUE is returned from a function it is the Number one, FALSE is the
126number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000127
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200128Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000129 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200130 :" NOT executed
131"foo" is converted to 0, which means FALSE. If the string starts with a
132non-zero number it means TRUE: >
133 :if "8foo"
134 :" executed
135To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200136 :if !empty("foo")
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200137
138< *falsy* *truthy*
139An expression can be used as a condition, ignoring the type and only using
140whether the value is "sort of true" or "sort of false". Falsy is:
141 the number zero
142 empty string, blob, list or dictionary
143Other values are truthy. Examples:
144 0 falsy
145 1 truthy
146 -1 truthy
147 0.0 falsy
148 0.1 truthy
149 '' falsy
150 'x' truthy
151 [] falsy
152 [0] truthy
153 {} falsy
154 #{x: 1} truthy
155 0z falsy
156 0z00 truthy
157
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200158 *non-zero-arg*
159Function arguments often behave slightly different from |TRUE|: If the
160argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200161non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100162Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
163A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200164
Bram Moolenaar38a55632016-02-15 22:07:32 +0100165 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +0100166 *E974* *E975* *E976*
Bram Moolenaard09091d2019-01-17 16:07:22 +0100167|List|, |Dictionary|, |Funcref|, |Job|, |Channel| and |Blob| types are not
168automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000169
Bram Moolenaar446cb832008-06-24 21:56:24 +0000170 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200171When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000172there is no automatic conversion of Float. You can use str2float() for String
173to Float, printf() for Float to String and float2nr() for Float to Number.
174
Bram Moolenaar38a55632016-02-15 22:07:32 +0100175 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100176When expecting a Float a Number can also be used, but nothing else.
177
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100178 *no-type-checking*
179You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000180
Bram Moolenaar13065c42005-01-08 16:08:21 +0000181
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001821.2 Function references ~
Bram Moolenaare46a4402020-06-30 20:38:27 +0200183 *Funcref* *E695* *E718*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200184A Funcref variable is obtained with the |function()| function, the |funcref()|
185function or created with the lambda expression |expr-lambda|. It can be used
186in an expression in the place of a function name, before the parenthesis
187around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000188
189 :let Fn = function("MyFunc")
190 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000191< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000192A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200193can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000194cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000195
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000196A special case is defining a function and directly assigning its Funcref to a
197Dictionary entry. Example: >
198 :function dict.init() dict
199 : let self.val = 0
200 :endfunction
201
202The key of the Dictionary can start with a lower case letter. The actual
203function name is not used here. Also see |numbered-function|.
204
205A Funcref can also be used with the |:call| command: >
206 :call Fn()
207 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000208
209The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000210 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000211
212You can use |call()| to invoke a Funcref and use a list variable for the
213arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000214 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200215<
216 *Partial*
217A Funcref optionally binds a Dictionary and/or arguments. This is also called
218a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200219function() or funcref(). When calling the function the Dictionary and/or
220arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200221
222 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100223 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200224
225This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100226 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200227
228This is very useful when passing a function around, e.g. in the arguments of
229|ch_open()|.
230
231Note that binding a function to a Dictionary also happens when the function is
232a member of the Dictionary: >
233
234 let myDict.myFunction = MyFunction
235 call myDict.myFunction()
236
237Here MyFunction() will get myDict passed as "self". This happens when the
238"myFunction" member is accessed. When making assigning "myFunction" to
239otherDict and calling it, it will be bound to otherDict: >
240
241 let otherDict.myFunction = myDict.myFunction
242 call otherDict.myFunction()
243
244Now "self" will be "otherDict". But when the dictionary was bound explicitly
245this won't happen: >
246
247 let myDict.myFunction = function(MyFunction, myDict)
248 let otherDict.myFunction = myDict.myFunction
249 call otherDict.myFunction()
250
Bram Moolenaard823fa92016-08-12 16:29:27 +0200251Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000252
253
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002541.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200255 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000256A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200257can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000258position in the sequence.
259
Bram Moolenaar13065c42005-01-08 16:08:21 +0000260
261List creation ~
262 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000263A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000264Examples: >
265 :let mylist = [1, two, 3, "four"]
266 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000267
Bram Moolenaar58b85342016-08-14 19:54:54 +0200268An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000269List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000270 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000271
272An extra comma after the last item is ignored.
273
Bram Moolenaar13065c42005-01-08 16:08:21 +0000274
275List index ~
276 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000277An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000278after the List. Indexes are zero-based, thus the first item has index zero. >
279 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000280 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000281
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000282When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000283 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000284<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000285A negative index is counted from the end. Index -1 refers to the last item in
286the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000287 :let last = mylist[-1] " get the last item: "four"
288
Bram Moolenaar13065c42005-01-08 16:08:21 +0000289To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000290is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000291 :echo get(mylist, idx)
292 :echo get(mylist, idx, "NONE")
293
294
295List concatenation ~
Bram Moolenaar34453202021-01-31 13:08:38 +0100296 *list-concatenation*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000297Two lists can be concatenated with the "+" operator: >
298 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000299 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000300
Bram Moolenaar34453202021-01-31 13:08:38 +0100301To prepend or append an item, turn the item into a list by putting [] around
302it. To change a list in-place, refer to |list-modification| below.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000303
304
305Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200306 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000307A part of the List can be obtained by specifying the first and last index,
308separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000309 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000310
311Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000312similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000313 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
314 :let shortlist = mylist[2:2] " List with one item: [3]
315 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000316
Bram Moolenaar6601b622021-01-13 21:47:15 +0100317Notice that the last index is inclusive. If you prefer using an exclusive
318index use the |slice()| method.
319
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000320If the first index is beyond the last item of the List or the second item is
321before the first item, the result is an empty list. There is no error
322message.
323
324If the second index is equal to or greater than the length of the list the
325length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000326 :let mylist = [0, 1, 2, 3]
327 :echo mylist[2:8] " result: [2, 3]
328
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000329NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200330using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000331mylist[s : e].
332
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000333
Bram Moolenaar13065c42005-01-08 16:08:21 +0000334List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000335 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000336When variable "aa" is a list and you assign it to another variable "bb", both
337variables refer to the same list. Thus changing the list "aa" will also
338change "bb": >
339 :let aa = [1, 2, 3]
340 :let bb = aa
341 :call add(aa, 4)
342 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000343< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000344
345Making a copy of a list is done with the |copy()| function. Using [:] also
346works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000347a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000348 :let aa = [[1, 'a'], 2, 3]
349 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000350 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000351 :let aa[0][1] = 'aaa'
352 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000353< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000354 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000355< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000356
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000357To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000358copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000359
360The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000361List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000362the same value. >
363 :let alist = [1, 2, 3]
364 :let blist = [1, 2, 3]
365 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000366< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000367 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000368< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000369
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000370Note about comparing lists: Two lists are considered equal if they have the
371same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000372exception: When comparing a number with a string they are considered
373different. There is no automatic type conversion, as with using "==" on
374variables. Example: >
375 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000376< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000377 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000378< 0
379
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000380Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000381can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000382
383 :let a = 5
384 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000385 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000386< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000387 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000388< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000389
Bram Moolenaar13065c42005-01-08 16:08:21 +0000390
391List unpack ~
392
393To unpack the items in a list to individual variables, put the variables in
394square brackets, like list items: >
395 :let [var1, var2] = mylist
396
397When the number of variables does not match the number of items in the list
398this produces an error. To handle any extra items from the list append ";"
399and a variable name: >
400 :let [var1, var2; rest] = mylist
401
402This works like: >
403 :let var1 = mylist[0]
404 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000405 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000406
407Except that there is no error if there are only two items. "rest" will be an
408empty list then.
409
410
411List modification ~
412 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000413To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000414 :let list[4] = "four"
415 :let listlist[0][3] = item
416
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000417To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000418modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000419 :let list[3:5] = [3, 4, 5]
420
Bram Moolenaar13065c42005-01-08 16:08:21 +0000421Adding and removing items from a list is done with functions. Here are a few
422examples: >
423 :call insert(list, 'a') " prepend item 'a'
424 :call insert(list, 'a', 3) " insert item 'a' before list[3]
425 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000426 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000427 :call extend(list, [1, 2]) " extend the list with two more items
428 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000429 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000430 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000431 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000432 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000433
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000434Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000435 :call sort(list) " sort a list alphabetically
436 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100437 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000438
Bram Moolenaar13065c42005-01-08 16:08:21 +0000439
440For loop ~
441
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000442The |:for| loop executes commands for each item in a list. A variable is set
443to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000444 :for item in mylist
445 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000446 :endfor
447
448This works like: >
449 :let index = 0
450 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000451 : let item = mylist[index]
452 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000453 : let index = index + 1
454 :endwhile
455
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000456If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000457function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000458
Bram Moolenaar58b85342016-08-14 19:54:54 +0200459Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000460requires the argument to be a list of lists. >
461 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
462 : call Doit(lnum, col)
463 :endfor
464
465This works like a |:let| command is done for each list item. Again, the types
466must remain the same to avoid an error.
467
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000468It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000469 :for [i, j; rest] in listlist
470 : call Doit(i, j)
471 : if !empty(rest)
472 : echo "remainder: " . string(rest)
473 : endif
474 :endfor
475
476
477List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000478 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000479Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000480 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000481 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000482 :let l = len(list) " number of items in list
483 :let big = max(list) " maximum value in list
484 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000485 :let xs = count(list, 'x') " count nr of times 'x' appears in list
486 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000487 :let lines = getline(1, 10) " get ten text lines from buffer
488 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000489 :let list = split("a b c") " create list from items in a string
490 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000491 :let s = string(list) " String representation of list
492 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000493
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000494Don't forget that a combination of features can make things simple. For
495example, to add up all the numbers in a list: >
496 :exe 'let sum = ' . join(nrlist, '+')
497
Bram Moolenaar13065c42005-01-08 16:08:21 +0000498
Bram Moolenaard8b02732005-01-14 21:48:43 +00004991.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100500 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000501A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000502entry can be located with the key. The entries are stored without a specific
503ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000504
505
506Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000507 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000508A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000509braces. Each entry has a key and a value, separated by a colon. Each key can
510only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000511 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
512 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000513< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000514A key is always a String. You can use a Number, it will be converted to a
515String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200516entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaard5abb4c2019-07-13 22:46:10 +0200517Number will be converted to the String '4'. The empty string can also be used
518as a key.
Bram Moolenaar56c860c2019-08-17 20:09:31 +0200519 *literal-Dict* *#{}*
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200520To avoid having to put quotes around every key the #{} form can be used. This
Bram Moolenaard5abb4c2019-07-13 22:46:10 +0200521does require the key to consist only of ASCII letters, digits, '-' and '_'.
522Example: >
Bram Moolenaar10455d42019-11-21 15:36:18 +0100523 :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3}
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200524Note that 333 here is the string "333". Empty keys are not possible with #{}.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000525
Bram Moolenaar58b85342016-08-14 19:54:54 +0200526A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000527nested Dictionary: >
528 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
529
530An extra comma after the last entry is ignored.
531
532
533Accessing entries ~
534
535The normal way to access an entry is by putting the key in square brackets: >
536 :let val = mydict["one"]
537 :let mydict["four"] = 4
538
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000539You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000540
541For keys that consist entirely of letters, digits and underscore the following
542form can be used |expr-entry|: >
543 :let val = mydict.one
544 :let mydict.four = 4
545
546Since an entry can be any type, also a List and a Dictionary, the indexing and
547key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000548 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000549
550
551Dictionary to List conversion ~
552
Bram Moolenaar58b85342016-08-14 19:54:54 +0200553You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000554turn the Dictionary into a List and pass it to |:for|.
555
556Most often you want to loop over the keys, using the |keys()| function: >
557 :for key in keys(mydict)
558 : echo key . ': ' . mydict[key]
559 :endfor
560
561The List of keys is unsorted. You may want to sort them first: >
562 :for key in sort(keys(mydict))
563
564To loop over the values use the |values()| function: >
565 :for v in values(mydict)
566 : echo "value: " . v
567 :endfor
568
569If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100570a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000571 :for [key, value] in items(mydict)
572 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000573 :endfor
574
575
576Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000577 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000578Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
579Dictionary. Otherwise, assignment results in referring to the same
580Dictionary: >
581 :let onedict = {'a': 1, 'b': 2}
582 :let adict = onedict
583 :let adict['a'] = 11
584 :echo onedict['a']
585 11
586
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000587Two Dictionaries compare equal if all the key-value pairs compare equal. For
588more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000589
590
591Dictionary modification ~
592 *dict-modification*
593To change an already existing entry of a Dictionary, or to add a new entry,
594use |:let| this way: >
595 :let dict[4] = "four"
596 :let dict['one'] = item
597
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000598Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
599Three ways to remove the entry with key "aaa" from dict: >
600 :let i = remove(dict, 'aaa')
601 :unlet dict.aaa
602 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000603
604Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000605 :call extend(adict, bdict)
606This extends adict with all entries from bdict. Duplicate keys cause entries
607in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000608Note that the order of entries in a Dictionary is irrelevant, thus don't
609expect ":echo adict" to show the items from bdict after the older entries in
610adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000611
612Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000613 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000614This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200615This can also be used to remove all entries: >
616 call filter(dict, 0)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000617
618
619Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100620 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000621When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200622special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000623 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000624 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000625 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000626 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
627 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000628
629This is like a method in object oriented programming. The entry in the
630Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
631the function was invoked from.
632
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000633It is also possible to add a function without the "dict" attribute as a
634Funcref to a Dictionary, but the "self" variable is not available then.
635
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000636 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000637To avoid the extra name for the function it can be defined and directly
638assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000639 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200640 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000641 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000642 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000643 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000644
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000645The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200646that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000647|Funcref|. It will automatically be deleted when there is no |Funcref|
648remaining that refers to it.
649
650It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000651
Bram Moolenaar1affd722010-08-04 17:49:30 +0200652If you get an error for a numbered function, you can find out what it is with
653a trick. Assuming the function is 42, the command is: >
654 :function {42}
655
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000656
657Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000658 *E715*
659Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000660 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
661 :if empty(dict) " TRUE if dict is empty
662 :let l = len(dict) " number of items in dict
663 :let big = max(dict) " maximum value in dict
664 :let small = min(dict) " minimum value in dict
665 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
666 :let s = string(dict) " String representation of dict
667 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000668
669
Bram Moolenaard8968242019-01-15 22:51:57 +01006701.5 Blobs ~
671 *blob* *Blob* *Blobs* *E978*
Bram Moolenaaraff74912019-03-30 18:11:49 +0100672A Blob is a binary object. It can be used to read an image from a file and
673send it over a channel, for example.
674
675A Blob mostly behaves like a |List| of numbers, where each number has the
676value of an 8-bit byte, from 0 to 255.
Bram Moolenaard8968242019-01-15 22:51:57 +0100677
678
679Blob creation ~
680
681A Blob can be created with a |blob-literal|: >
682 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100683Dots can be inserted between bytes (pair of hex characters) for readability,
684they don't change the value: >
685 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100686
687A blob can be read from a file with |readfile()| passing the {type} argument
688set to "B", for example: >
689 :let b = readfile('image.png', 'B')
690
691A blob can be read from a channel with the |ch_readblob()| function.
692
693
694Blob index ~
695 *blob-index* *E979*
696A byte in the Blob can be accessed by putting the index in square brackets
697after the Blob. Indexes are zero-based, thus the first byte has index zero. >
698 :let myblob = 0z00112233
699 :let byte = myblob[0] " get the first byte: 0x00
700 :let byte = myblob[2] " get the third byte: 0x22
701
702A negative index is counted from the end. Index -1 refers to the last byte in
703the Blob, -2 to the last but one byte, etc. >
704 :let last = myblob[-1] " get the last byte: 0x33
705
706To avoid an error for an invalid index use the |get()| function. When an item
707is not available it returns -1 or the default value you specify: >
708 :echo get(myblob, idx)
709 :echo get(myblob, idx, 999)
710
711
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100712Blob iteration ~
713
714The |:for| loop executes commands for each byte of a Blob. The loop variable is
715set to each byte in the Blob. Example: >
716 :for byte in 0z112233
717 : call Doit(byte)
718 :endfor
719This calls Doit() with 0x11, 0x22 and 0x33.
720
721
Bram Moolenaard8968242019-01-15 22:51:57 +0100722Blob concatenation ~
723
724Two blobs can be concatenated with the "+" operator: >
725 :let longblob = myblob + 0z4455
726 :let myblob += 0z6677
727
728To change a blob in-place see |blob-modification| below.
729
730
731Part of a blob ~
732
733A part of the Blob can be obtained by specifying the first and last index,
734separated by a colon in square brackets: >
735 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100736 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100737 :let shortblob = myblob[2:-1] " get 0z2233
738
739Omitting the first index is similar to zero. Omitting the last index is
740similar to -1. >
741 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
742 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
743 :let otherblob = myblob[:] " make a copy of the Blob
744
Bram Moolenaard09091d2019-01-17 16:07:22 +0100745If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100746before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100747message.
748
749If the second index is equal to or greater than the length of the list the
750length minus one is used: >
751 :echo myblob[2:8] " result: 0z2233
752
753
754Blob modification ~
755 *blob-modification*
756To change a specific byte of a blob use |:let| this way: >
757 :let blob[4] = 0x44
758
759When the index is just one beyond the end of the Blob, it is appended. Any
760higher index is an error.
761
762To change a sequence of bytes the [:] notation can be used: >
763 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100764The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100765provided. *E972*
766
767To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100768modified. The value must have the same number of bytes in the range: >
769 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100770
771You can also use the functions |add()|, |remove()| and |insert()|.
772
773
774Blob identity ~
775
776Blobs can be compared for equality: >
777 if blob == 0z001122
778And for equal identity: >
779 if blob is otherblob
780< *blob-identity* *E977*
781When variable "aa" is a Blob and you assign it to another variable "bb", both
782variables refer to the same Blob. Then the "is" operator returns true.
783
784When making a copy using [:] or |copy()| the values are the same, but the
785identity is different: >
786 :let blob = 0z112233
787 :let blob2 = blob
788 :echo blob == blob2
789< 1 >
790 :echo blob is blob2
791< 1 >
792 :let blob3 = blob[:]
793 :echo blob == blob3
794< 1 >
795 :echo blob is blob3
796< 0
797
Bram Moolenaard09091d2019-01-17 16:07:22 +0100798Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100799works, as explained above.
800
801
8021.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000803 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000804If you need to know the type of a variable or expression, use the |type()|
805function.
806
807When the '!' flag is included in the 'viminfo' option, global variables that
808start with an uppercase letter, and don't contain a lowercase letter, are
809stored in the viminfo file |viminfo-file|.
810
811When the 'sessionoptions' option contains "global", global variables that
812start with an uppercase letter and contain at least one lowercase letter are
813stored in the session file |session-file|.
814
815variable name can be stored where ~
816my_var_6 not
817My_Var_6 session file
818MY_VAR_6 viminfo file
819
820
821It's possible to form a variable name with curly braces, see
822|curly-braces-names|.
823
824==============================================================================
8252. Expression syntax *expression-syntax*
826
827Expression syntax summary, from least to most significant:
828
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200829|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200830 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000831
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200832|expr2| expr3
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200833 expr3 || expr3 ... logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000834
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200835|expr3| expr4
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200836 expr4 && expr4 ... logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000837
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200838|expr4| expr5
839 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000840 expr5 != expr5 not equal
841 expr5 > expr5 greater than
842 expr5 >= expr5 greater than or equal
843 expr5 < expr5 smaller than
844 expr5 <= expr5 smaller than or equal
845 expr5 =~ expr5 regexp matches
846 expr5 !~ expr5 regexp doesn't match
847
848 expr5 ==? expr5 equal, ignoring case
849 expr5 ==# expr5 equal, match case
850 etc. As above, append ? for ignoring case, # for
851 matching case
852
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100853 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
854 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
855 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000856
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200857|expr5| expr6
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200858 expr6 + expr6 ... number addition, list or blob concatenation
859 expr6 - expr6 ... number subtraction
860 expr6 . expr6 ... string concatenation
861 expr6 .. expr6 ... string concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000862
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200863|expr6| expr7
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200864 expr7 * expr7 ... number multiplication
865 expr7 / expr7 ... number division
866 expr7 % expr7 ... number modulo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000867
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200868|expr7| expr8
869 ! expr7 logical NOT
Bram Moolenaar071d4272004-06-13 20:20:40 +0000870 - expr7 unary minus
871 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000872
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200873|expr8| expr9
874 expr8[expr1] byte of a String or item of a |List|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000875 expr8[expr1 : expr1] substring of a String or sublist of a |List|
876 expr8.name entry in a |Dictionary|
877 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar25e42232019-08-04 15:04:10 +0200878 expr8->name(expr1, ...) |method| call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000879
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200880|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000881 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000882 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000883 [expr1, ...] |List|
884 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar25e42232019-08-04 15:04:10 +0200885 #{key: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000886 &option option value
887 (expr1) nested expression
888 variable internal variable
889 va{ria}ble internal variable with curly braces
890 $VAR environment variable
891 @r contents of register 'r'
892 function(expr1, ...) function call
893 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar069c1e72016-07-15 21:25:08 +0200894 {args -> expr1} lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000895
896
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200897"..." indicates that the operations in this level can be concatenated.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000898Example: >
899 &nu || &list && &shell == "csh"
900
901All expressions within one level are parsed from left to right.
902
903
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200904expr1 *expr1* *trinary* *falsy-operator* *??* *E109*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000905-----
906
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200907The trinary operator: expr2 ? expr1 : expr1
908The falsy operator: expr2 ?? expr1
909
910Trinary operator ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000911
912The expression before the '?' is evaluated to a number. If it evaluates to
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200913|TRUE|, the result is the value of the expression between the '?' and ':',
Bram Moolenaar071d4272004-06-13 20:20:40 +0000914otherwise the result is the value of the expression after the ':'.
915Example: >
916 :echo lnum == 1 ? "top" : lnum
917
918Since the first expression is an "expr2", it cannot contain another ?:. The
919other two expressions can, thus allow for recursive use of ?:.
920Example: >
921 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
922
923To keep this readable, using |line-continuation| is suggested: >
924 :echo lnum == 1
925 :\ ? "top"
926 :\ : lnum == 1000
927 :\ ? "last"
928 :\ : lnum
929
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000930You should always put a space before the ':', otherwise it can be mistaken for
931use in a variable such as "a:1".
932
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200933Falsy operator ~
934
935This is also known as the "null coalescing operator", but that's too
936complicated, thus we just call it the falsy operator.
937
938The expression before the '??' is evaluated. If it evaluates to
939|truthy|, this is used as the result. Otherwise the expression after the '??'
940is evaluated and used as the result. This is most useful to have a default
941value for an expression that may result in zero or empty: >
942 echo theList ?? 'list is empty'
943 echo GetName() ?? 'unknown'
944
945These are similar, but not equal: >
946 expr2 ?? expr1
947 expr2 ? expr2 : expr1
948In the second line "expr2" is evaluated twice.
949
Bram Moolenaar071d4272004-06-13 20:20:40 +0000950
951expr2 and expr3 *expr2* *expr3*
952---------------
953
Bram Moolenaar04186092016-08-29 21:55:35 +0200954expr3 || expr3 .. logical OR *expr-barbar*
955expr4 && expr4 .. logical AND *expr-&&*
956
Bram Moolenaar071d4272004-06-13 20:20:40 +0000957The "||" and "&&" operators take one argument on each side. The arguments
958are (converted to) Numbers. The result is:
959
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200960 input output ~
961n1 n2 n1 || n2 n1 && n2 ~
962|FALSE| |FALSE| |FALSE| |FALSE|
963|FALSE| |TRUE| |TRUE| |FALSE|
964|TRUE| |FALSE| |TRUE| |FALSE|
965|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000966
967The operators can be concatenated, for example: >
968
969 &nu || &list && &shell == "csh"
970
971Note that "&&" takes precedence over "||", so this has the meaning of: >
972
973 &nu || (&list && &shell == "csh")
974
975Once the result is known, the expression "short-circuits", that is, further
976arguments are not evaluated. This is like what happens in C. For example: >
977
978 let a = 1
979 echo a || b
980
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200981This is valid even if there is no variable called "b" because "a" is |TRUE|,
982so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000983
984 echo exists("b") && b == "yes"
985
986This is valid whether "b" has been defined or not. The second clause will
987only be evaluated if "b" has been defined.
988
989
990expr4 *expr4*
991-----
992
993expr5 {cmp} expr5
994
995Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
996if it evaluates to true.
997
Bram Moolenaar446cb832008-06-24 21:56:24 +0000998 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000999 *expr-<* *expr-<=* *expr-=~* *expr-!~*
1000 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
1001 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
1002 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
1003 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001004 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
1005 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001006 use 'ignorecase' match case ignore case ~
1007equal == ==# ==?
1008not equal != !=# !=?
1009greater than > ># >?
1010greater than or equal >= >=# >=?
1011smaller than < <# <?
1012smaller than or equal <= <=# <=?
1013regexp matches =~ =~# =~?
1014regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +02001015same instance is is# is?
1016different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +00001017
1018Examples:
1019"abc" ==# "Abc" evaluates to 0
1020"abc" ==? "Abc" evaluates to 1
1021"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
1022
Bram Moolenaar13065c42005-01-08 16:08:21 +00001023 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +01001024A |List| can only be compared with a |List| and only "equal", "not equal",
1025"is" and "isnot" can be used. This compares the values of the list,
1026recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001027
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001028 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001029A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +01001030equal", "is" and "isnot" can be used. This compares the key/values of the
1031|Dictionary| recursively. Ignoring case means case is ignored when comparing
1032item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001033
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001034 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001035A |Funcref| can only be compared with a |Funcref| and only "equal", "not
1036equal", "is" and "isnot" can be used. Case is never ignored. Whether
1037arguments or a Dictionary are bound (with a partial) matters. The
1038Dictionaries must also be equal (or the same, in case of "is") and the
1039arguments must be equal (or the same).
1040
1041To compare Funcrefs to see if they refer to the same function, ignoring bound
1042Dictionary and arguments, use |get()| to get the function name: >
1043 if get(Part1, 'name') == get(Part2, 'name')
1044 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001045
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001046Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
1047the expressions are referring to the same |List|, |Dictionary| or |Blob|
1048instance. A copy of a |List| is different from the original |List|. When
1049using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
1050using "equal", using "isnot" equivalent to using "not equal". Except that
1051a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001052 echo 4 == '4'
1053 1
1054 echo 4 is '4'
1055 0
1056 echo 0 is []
1057 0
1058"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001059
Bram Moolenaar071d4272004-06-13 20:20:40 +00001060When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar58b85342016-08-14 19:54:54 +02001061and the comparison is done on Numbers. This means that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001062 echo 0 == 'x'
1063 1
1064because 'x' converted to a Number is zero. However: >
1065 echo [0] == ['x']
1066 0
1067Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001068
1069When comparing two Strings, this is done with strcmp() or stricmp(). This
1070results in the mathematical difference (comparing byte values), not
1071necessarily the alphabetical difference in the local language.
1072
Bram Moolenaar446cb832008-06-24 21:56:24 +00001073When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001074'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001075
1076When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001077'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1078
1079'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001080
1081The "=~" and "!~" operators match the lefthand argument with the righthand
1082argument, which is used as a pattern. See |pattern| for what a pattern is.
1083This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1084matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1085portable. To avoid backslashes in the regexp pattern to be doubled, use a
1086single-quote string, see |literal-string|.
1087Since a string is considered to be a single line, a multi-line pattern
1088(containing \n, backslash-n) will not match. However, a literal NL character
1089can be matched like an ordinary character. Examples:
1090 "foo\nbar" =~ "\n" evaluates to 1
1091 "foo\nbar" =~ "\\n" evaluates to 0
1092
1093
1094expr5 and expr6 *expr5* *expr6*
1095---------------
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001096expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+*
1097expr6 - expr6 Number subtraction *expr--*
1098expr6 . expr6 String concatenation *expr-.*
1099expr6 .. expr6 String concatenation *expr-..*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001100
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001101For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001102result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001103
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001104For String concatenation ".." is preferred, since "." is ambiguous, it is also
1105used for |Dict| member access and floating point numbers.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001106When |vimscript-version| is 2 or higher, using "." is not allowed.
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001107
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001108expr7 * expr7 Number multiplication *expr-star*
1109expr7 / expr7 Number division *expr-/*
1110expr7 % expr7 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001111
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02001112For all, except "." and "..", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001113For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001114
1115Note the difference between "+" and ".":
1116 "123" + "456" = 579
1117 "123" . "456" = "123456"
1118
Bram Moolenaar446cb832008-06-24 21:56:24 +00001119Since '.' has the same precedence as '+' and '-', you need to read: >
1120 1 . 90 + 90.0
1121As: >
1122 (1 . 90) + 90.0
1123That works, since the String "190" is automatically converted to the Number
1124190, which can be added to the Float 90.0. However: >
1125 1 . 90 * 90.0
1126Should be read as: >
1127 1 . (90 * 90.0)
1128Since '.' has lower precedence than '*'. This does NOT work, since this
1129attempts to concatenate a Float and a String.
1130
1131When dividing a Number by zero the result depends on the value:
1132 0 / 0 = -0x80000000 (like NaN for Float)
1133 >0 / 0 = 0x7fffffff (like positive infinity)
1134 <0 / 0 = -0x7fffffff (like negative infinity)
1135 (before Vim 7.2 it was always 0x7fffffff)
1136
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001137When 64-bit Number support is enabled:
1138 0 / 0 = -0x8000000000000000 (like NaN for Float)
1139 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1140 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1141
Bram Moolenaar071d4272004-06-13 20:20:40 +00001142When the righthand side of '%' is zero, the result is 0.
1143
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001144None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001145
Bram Moolenaar446cb832008-06-24 21:56:24 +00001146. and % do not work for Float. *E804*
1147
Bram Moolenaar071d4272004-06-13 20:20:40 +00001148
1149expr7 *expr7*
1150-----
1151! expr7 logical NOT *expr-!*
1152- expr7 unary minus *expr-unary--*
1153+ expr7 unary plus *expr-unary-+*
1154
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001155For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001156For '-' the sign of the number is changed.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001157For '+' the number is unchanged. Note: "++" has no effect.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001158
1159A String will be converted to a Number first.
1160
Bram Moolenaar58b85342016-08-14 19:54:54 +02001161These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001162 !-1 == 0
1163 !!8 == 1
1164 --9 == 9
1165
1166
1167expr8 *expr8*
1168-----
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001169This expression is either |expr9| or a sequence of the alternatives below,
1170in any order. E.g., these are all possible:
Bram Moolenaar25e42232019-08-04 15:04:10 +02001171 expr8[expr1].name
1172 expr8.name[expr1]
1173 expr8(expr1, ...)[expr1].name
1174 expr8->(expr1, ...)[expr1]
Bram Moolenaarac92e252019-08-03 21:58:38 +02001175Evaluation is always from left to right.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001176
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001177expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +02001178 *E909* *subscript*
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001179In legacy Vim script:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001180If expr8 is a Number or String this results in a String that contains the
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001181expr1'th single byte from expr8. expr8 is used as a String (a number is
1182automatically converted to a String), expr1 as a Number. This doesn't
Bram Moolenaar207f0092020-08-30 17:20:20 +02001183recognize multibyte encodings, see `byteidx()` for an alternative, or use
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001184`split()` to turn the string into a list of characters. Example, to get the
1185byte under the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001186 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001187
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001188In Vim9 script:
1189If expr8 is a String this results in a String that contains the expr1'th
1190single character from expr8. To use byte indexes use |strpart()|.
1191
1192Index zero gives the first byte or character. Careful: text column numbers
1193start with one!
1194
Bram Moolenaar071d4272004-06-13 20:20:40 +00001195If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001196String. A negative index always results in an empty string (reason: backward
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001197compatibility). Use [-1:] to get the last byte or character.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001198In Vim9 script a negative index is used like with a list: count from the end.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001199
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001200If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001201for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001202error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001203 :let item = mylist[-1] " get last item
1204
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001205Generally, if a |List| index is equal to or higher than the length of the
1206|List|, or more negative than the length of the |List|, this results in an
1207error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001208
Bram Moolenaard8b02732005-01-14 21:48:43 +00001209
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001210expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001211
Bram Moolenaar207f0092020-08-30 17:20:20 +02001212If expr8 is a String this results in the substring with the bytes or
1213characters from expr1a to and including expr1b. expr8 is used as a String,
1214expr1a and expr1b are used as a Number.
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001215
1216In legacy Vim script the indexes are byte indexes. This doesn't recognize
Bram Moolenaar207f0092020-08-30 17:20:20 +02001217multibyte encodings, see |byteidx()| for computing the indexes. If expr8 is
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001218a Number it is first converted to a String.
1219
1220In Vim9 script the indexes are character indexes. To use byte indexes use
1221|strpart()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001222
Bram Moolenaar6601b622021-01-13 21:47:15 +01001223The item at index expr1b is included, it is inclusive. For an exclusive index
1224use the |slice()| function.
1225
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001226If expr1a is omitted zero is used. If expr1b is omitted the length of the
1227string minus one is used.
1228
1229A negative number can be used to measure from the end of the string. -1 is
1230the last character, -2 the last but one, etc.
1231
1232If an index goes out of range for the string characters are omitted. If
1233expr1b is smaller than expr1a the result is an empty string.
1234
1235Examples: >
1236 :let c = name[-1:] " last byte of a string
Bram Moolenaar207f0092020-08-30 17:20:20 +02001237 :let c = name[0:-1] " the whole string
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001238 :let c = name[-2:-2] " last but one byte of a string
1239 :let s = line(".")[4:] " from the fifth byte to the end
1240 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001241<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001242 *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001243If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001244the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001245just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001246 :let l = mylist[:3] " first four items
1247 :let l = mylist[4:4] " List with one item
1248 :let l = mylist[:] " shallow copy of a List
1249
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001250If expr8 is a |Blob| this results in a new |Blob| with the bytes in the
1251indexes expr1a and expr1b, inclusive. Examples: >
1252 :let b = 0zDEADBEEF
1253 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001254 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001255
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001256Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
1257error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001258
Bram Moolenaarda440d22016-01-16 21:27:23 +01001259Watch out for confusion between a namespace and a variable followed by a colon
1260for a sublist: >
1261 mylist[n:] " uses variable n
1262 mylist[s:] " uses namespace s:, error!
1263
Bram Moolenaard8b02732005-01-14 21:48:43 +00001264
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001265expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +00001266
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001267If expr8 is a |Dictionary| and it is followed by a dot, then the following
1268name will be used as a key in the |Dictionary|. This is just like:
1269expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001270
1271The name must consist of alphanumeric characters, just like a variable name,
1272but it may start with a number. Curly braces cannot be used.
1273
1274There must not be white space before or after the dot.
1275
1276Examples: >
1277 :let dict = {"one": 1, 2: "two"}
Bram Moolenaar68e65602019-05-26 21:33:31 +02001278 :echo dict.one " shows "1"
1279 :echo dict.2 " shows "two"
1280 :echo dict .2 " error because of space before the dot
Bram Moolenaard8b02732005-01-14 21:48:43 +00001281
1282Note that the dot is also used for String concatenation. To avoid confusion
1283always put spaces around the dot for String concatenation.
1284
1285
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001286expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001287
1288When expr8 is a |Funcref| type variable, invoke the function it refers to.
1289
1290
Bram Moolenaar22a0c0c2019-08-09 23:25:08 +02001291expr8->name([args]) method call *method* *->*
1292expr8->{lambda}([args])
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001293 *E276*
Bram Moolenaar25e42232019-08-04 15:04:10 +02001294For methods that are also available as global functions this is the same as: >
Bram Moolenaarac92e252019-08-03 21:58:38 +02001295 name(expr8 [, args])
1296There can also be methods specifically for the type of "expr8".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001297
Bram Moolenaar51841322019-08-08 21:10:01 +02001298This allows for chaining, passing the value that one method returns to the
1299next method: >
Bram Moolenaar25e42232019-08-04 15:04:10 +02001300 mylist->filter(filterexpr)->map(mapexpr)->sort()->join()
1301<
Bram Moolenaar22a0c0c2019-08-09 23:25:08 +02001302Example of using a lambda: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02001303 GetPercentage()->{x -> x * 100}()->printf('%d%%')
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001304<
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02001305When using -> the |expr7| operators will be applied first, thus: >
1306 -1.234->string()
1307Is equivalent to: >
1308 (-1.234)->string()
1309And NOT: >
1310 -(1.234->string())
1311<
Bram Moolenaar51841322019-08-08 21:10:01 +02001312 *E274*
1313"->name(" must not contain white space. There can be white space before the
1314"->" and after the "(", thus you can split the lines like this: >
1315 mylist
1316 \ ->filter(filterexpr)
1317 \ ->map(mapexpr)
1318 \ ->sort()
1319 \ ->join()
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001320
1321When using the lambda form there must be no white space between the } and the
1322(.
1323
Bram Moolenaar25e42232019-08-04 15:04:10 +02001324
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001325 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001326number
1327------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001328number number constant *expr-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001329
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001330 *0x* *hex-number* *0o* *octal-number* *binary-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001331Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02001332and Octal (starting with 0, 0o or 0O).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001333
Bram Moolenaar446cb832008-06-24 21:56:24 +00001334 *floating-point-format*
1335Floating point numbers can be written in two forms:
1336
1337 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001338 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001339
1340{N} and {M} are numbers. Both {N} and {M} must be present and can only
1341contain digits.
1342[-+] means there is an optional plus or minus sign.
1343{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001344Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001345locale is.
1346{only when compiled with the |+float| feature}
1347
1348Examples:
1349 123.456
1350 +0.0001
1351 55.0
1352 -0.123
1353 1.234e03
1354 1.0E-6
1355 -3.1416e+88
1356
1357These are INVALID:
1358 3. empty {M}
1359 1e40 missing .{M}
1360
1361Rationale:
1362Before floating point was introduced, the text "123.456" was interpreted as
1363the two numbers "123" and "456", both converted to a string and concatenated,
1364resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001365could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001366incompatibility was accepted in favor of being able to use the normal notation
1367for floating point numbers.
1368
Bram Moolenaard47d5222018-12-09 20:43:55 +01001369 *float-pi* *float-e*
1370A few useful values to copy&paste: >
1371 :let pi = 3.14159265359
1372 :let e = 2.71828182846
1373Or, if you don't want to write them in as floating-point literals, you can
1374also use functions, like the following: >
1375 :let pi = acos(-1.0)
1376 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001377<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001378 *floating-point-precision*
1379The precision and range of floating points numbers depends on what "double"
1380means in the library Vim was compiled with. There is no way to change this at
1381runtime.
1382
1383The default for displaying a |Float| is to use 6 decimal places, like using
1384printf("%g", f). You can select something else when using the |printf()|
1385function. Example: >
1386 :echo printf('%.15e', atan(1))
1387< 7.853981633974483e-01
1388
1389
Bram Moolenaar071d4272004-06-13 20:20:40 +00001390
Bram Moolenaar979243b2015-06-26 19:35:49 +02001391string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001392------
1393"string" string constant *expr-quote*
1394
1395Note that double quotes are used.
1396
1397A string constant accepts these special characters:
1398\... three-digit octal number (e.g., "\316")
1399\.. two-digit octal number (must be followed by non-digit)
1400\. one-digit octal number (must be followed by non-digit)
1401\x.. byte specified with two hex numbers (e.g., "\x1f")
1402\x. byte specified with one hex number (must be followed by non-hex char)
1403\X.. same as \x..
1404\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001405\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001406 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001407\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001408\b backspace <BS>
1409\e escape <Esc>
1410\f formfeed <FF>
1411\n newline <NL>
1412\r return <CR>
1413\t tab <Tab>
1414\\ backslash
1415\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001416\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001417 in mappings, the 0x80 byte is escaped.
1418 To use the double quote character it must be escaped: "<M-\">".
1419 Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as
1420 mentioned above.
Bram Moolenaarfccd93f2020-05-31 22:06:51 +02001421\<*xxx> Like \<xxx> but prepends a modifier instead of including it in the
1422 character. E.g. "\<C-w>" is one character 0x17 while "\<*C-w>" is four
Bram Moolenaarebe9d342020-05-30 21:52:54 +02001423 bytes: 3 for the CTRL modifier and then character "W".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001425Note that "\xff" is stored as the byte 255, which may be invalid in some
1426encodings. Use "\u00ff" to store character 255 according to the current value
1427of 'encoding'.
1428
Bram Moolenaar071d4272004-06-13 20:20:40 +00001429Note that "\000" and "\x00" force the end of the string.
1430
1431
Bram Moolenaard8968242019-01-15 22:51:57 +01001432blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001433------------
1434
1435Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1436The sequence must be an even number of hex characters. Example: >
1437 :let b = 0zFF00ED015DAF
1438
1439
Bram Moolenaar071d4272004-06-13 20:20:40 +00001440literal-string *literal-string* *E115*
1441---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001442'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001443
1444Note that single quotes are used.
1445
Bram Moolenaar58b85342016-08-14 19:54:54 +02001446This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001447meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001448
1449Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001450to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001451 if a =~ "\\s*"
1452 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001453
1454
1455option *expr-option* *E112* *E113*
1456------
1457&option option value, local value if possible
1458&g:option global option value
1459&l:option local option value
1460
1461Examples: >
1462 echo "tabstop is " . &tabstop
1463 if &insertmode
1464
1465Any option name can be used here. See |options|. When using the local value
1466and there is no buffer-local or window-local value, the global value is used
1467anyway.
1468
1469
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001470register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001471--------
1472@r contents of register 'r'
1473
1474The result is the contents of the named register, as a single string.
1475Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001476register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001477registers.
1478
1479When using the '=' register you get the expression itself, not what it
1480evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001481
1482
1483nesting *expr-nesting* *E110*
1484-------
1485(expr1) nested expression
1486
1487
1488environment variable *expr-env*
1489--------------------
1490$VAR environment variable
1491
1492The String value of any environment variable. When it is not defined, the
1493result is an empty string.
Bram Moolenaar691ddee2019-05-09 14:52:41 +02001494
1495The functions `getenv()` and `setenv()` can also be used and work for
1496environment variables with non-alphanumeric names.
1497The function `environ()` can be used to get a Dict with all environment
1498variables.
1499
1500
Bram Moolenaar071d4272004-06-13 20:20:40 +00001501 *expr-env-expand*
1502Note that there is a difference between using $VAR directly and using
1503expand("$VAR"). Using it directly will only expand environment variables that
1504are known inside the current Vim session. Using expand() will first try using
1505the environment variables known inside the current Vim session. If that
1506fails, a shell will be used to expand the variable. This can be slow, but it
1507does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001508 :echo $shell
1509 :echo expand("$shell")
1510The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511variable (if your shell supports it).
1512
1513
1514internal variable *expr-variable*
1515-----------------
1516variable internal variable
1517See below |internal-variables|.
1518
1519
Bram Moolenaar05159a02005-02-26 23:04:13 +00001520function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001521-------------
1522function(expr1, ...) function call
1523See below |functions|.
1524
1525
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001526lambda expression *expr-lambda* *lambda*
1527-----------------
1528{args -> expr1} lambda expression
1529
1530A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001531evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001532the following ways:
1533
15341. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1535 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020015362. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001537 :let F = {arg1, arg2 -> arg1 - arg2}
1538 :echo F(5, 2)
1539< 3
1540
1541The arguments are optional. Example: >
1542 :let F = {-> 'error function'}
1543 :echo F()
1544< error function
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001545 *closure*
1546Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001547often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001548while they already exist in the function scope. They remain valid even after
1549the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001550 :function Foo(arg)
1551 : let i = 3
1552 : return {x -> x + i - a:arg}
1553 :endfunction
1554 :let Bar = Foo(4)
1555 :echo Bar(6)
1556< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001557
Bram Moolenaar388a5d42020-05-26 21:20:45 +02001558Note that the variables must exist in the outer scope before the lambda is
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001559defined for this to work. See also |:func-closure|.
1560
1561Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001562 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001563
1564Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1565 :echo map([1, 2, 3], {idx, val -> val + 1})
1566< [2, 3, 4] >
1567 :echo sort([3,7,2,1,4], {a, b -> a - b})
1568< [1, 2, 3, 4, 7]
1569
1570The lambda expression is also useful for Channel, Job and timer: >
1571 :let timer = timer_start(500,
1572 \ {-> execute("echo 'Handler called'", "")},
1573 \ {'repeat': 3})
1574< Handler called
1575 Handler called
1576 Handler called
1577
1578Note how execute() is used to execute an Ex command. That's ugly though.
1579
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001580
1581Lambda expressions have internal names like '<lambda>42'. If you get an error
1582for a lambda expression, you can find what it is with the following command: >
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001583 :function <lambda>42
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001584See also: |numbered-function|
1585
Bram Moolenaar071d4272004-06-13 20:20:40 +00001586==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020015873. Internal variable *internal-variables* *E461*
1588
Bram Moolenaar071d4272004-06-13 20:20:40 +00001589An internal variable name can be made up of letters, digits and '_'. But it
1590cannot start with a digit. It's also possible to use curly braces, see
1591|curly-braces-names|.
1592
1593An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001594An internal variable is explicitly destroyed with the ":unlet" command
1595|:unlet|.
1596Using a name that is not an internal variable or refers to a variable that has
1597been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001598
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001599 *variable-scope*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001600There are several name spaces for variables. Which one is to be used is
1601specified by what is prepended:
1602
1603 (nothing) In a function: local to a function; otherwise: global
1604|buffer-variable| b: Local to the current buffer.
1605|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001606|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001607|global-variable| g: Global.
1608|local-variable| l: Local to a function.
1609|script-variable| s: Local to a |:source|'ed Vim script.
1610|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001611|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001612
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001613The scope name by itself can be used as a |Dictionary|. For example, to
1614delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001615 :for k in keys(s:)
1616 : unlet s:[k]
1617 :endfor
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001618
1619Note: in Vim9 script this is different, see |vim9-scopes|.
1620
Bram Moolenaar531da592013-05-06 05:58:55 +02001621 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001622A variable name that is preceded with "b:" is local to the current buffer.
1623Thus you can have several "b:foo" variables, one for each buffer.
1624This kind of variable is deleted when the buffer is wiped out or deleted with
1625|:bdelete|.
1626
1627One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001628 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001629b:changedtick The total number of changes to the current buffer. It is
1630 incremented for each change. An undo command is also a change
Bram Moolenaarc024b462019-06-08 18:07:21 +02001631 in this case. Resetting 'modified' when writing the buffer is
1632 also counted.
1633 This can be used to perform an action only when the buffer has
1634 changed. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001635 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001636 : let my_changedtick = b:changedtick
1637 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001638 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001639< You cannot change or delete the b:changedtick variable.
1640
Bram Moolenaar531da592013-05-06 05:58:55 +02001641 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001642A variable name that is preceded with "w:" is local to the current window. It
1643is deleted when the window is closed.
1644
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001645 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001646A variable name that is preceded with "t:" is local to the current tab page,
1647It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001648without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001649
Bram Moolenaar531da592013-05-06 05:58:55 +02001650 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001651Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar58b85342016-08-14 19:54:54 +02001652access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001653place if you like.
1654
Bram Moolenaar531da592013-05-06 05:58:55 +02001655 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001656Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001657But you can also prepend "l:" if you like. However, without prepending "l:"
1658you may run into reserved variable names. For example "count". By itself it
1659refers to "v:count". Using "l:count" you can have a local variable with the
1660same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001661
1662 *script-variable* *s:var*
1663In a Vim script variables starting with "s:" can be used. They cannot be
1664accessed from outside of the scripts, thus are local to the script.
1665
1666They can be used in:
1667- commands executed while the script is sourced
1668- functions defined in the script
1669- autocommands defined in the script
1670- functions and autocommands defined in functions and autocommands which were
1671 defined in the script (recursively)
1672- user defined commands defined in the script
1673Thus not in:
1674- other scripts sourced from this one
1675- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001676- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001677- etc.
1678
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001679Script variables can be used to avoid conflicts with global variable names.
1680Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001681
1682 let s:counter = 0
1683 function MyCounter()
1684 let s:counter = s:counter + 1
1685 echo s:counter
1686 endfunction
1687 command Tick call MyCounter()
1688
1689You can now invoke "Tick" from any script, and the "s:counter" variable in
1690that script will not be changed, only the "s:counter" in the script where
1691"Tick" was defined is used.
1692
1693Another example that does the same: >
1694
1695 let s:counter = 0
1696 command Tick let s:counter = s:counter + 1 | echo s:counter
1697
1698When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001699script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001700defined.
1701
1702The script variables are also available when a function is defined inside a
1703function that is defined in a script. Example: >
1704
1705 let s:counter = 0
1706 function StartCounting(incr)
1707 if a:incr
1708 function MyCounter()
1709 let s:counter = s:counter + 1
1710 endfunction
1711 else
1712 function MyCounter()
1713 let s:counter = s:counter - 1
1714 endfunction
1715 endif
1716 endfunction
1717
1718This defines the MyCounter() function either for counting up or counting down
1719when calling StartCounting(). It doesn't matter from where StartCounting() is
1720called, the s:counter variable will be accessible in MyCounter().
1721
1722When the same script is sourced again it will use the same script variables.
1723They will remain valid as long as Vim is running. This can be used to
1724maintain a counter: >
1725
1726 if !exists("s:counter")
1727 let s:counter = 1
1728 echo "script executed for the first time"
1729 else
1730 let s:counter = s:counter + 1
1731 echo "script executed " . s:counter . " times now"
1732 endif
1733
1734Note that this means that filetype plugins don't get a different set of script
1735variables for each buffer. Use local buffer variables instead |b:var|.
1736
1737
Bram Moolenaard47d5222018-12-09 20:43:55 +01001738PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
1739 *E963*
1740Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001741
Bram Moolenaar69bf6342019-10-29 04:16:57 +01001742 *v:argv* *argv-variable*
1743v:argv The command line arguments Vim was invoked with. This is a
1744 list of strings. The first item is the Vim command.
1745
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001746 *v:beval_col* *beval_col-variable*
1747v:beval_col The number of the column, over which the mouse pointer is.
1748 This is the byte index in the |v:beval_lnum| line.
1749 Only valid while evaluating the 'balloonexpr' option.
1750
1751 *v:beval_bufnr* *beval_bufnr-variable*
1752v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1753 valid while evaluating the 'balloonexpr' option.
1754
1755 *v:beval_lnum* *beval_lnum-variable*
1756v:beval_lnum The number of the line, over which the mouse pointer is. Only
1757 valid while evaluating the 'balloonexpr' option.
1758
1759 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001760v:beval_text The text under or after the mouse pointer. Usually a word as
1761 it is useful for debugging a C program. 'iskeyword' applies,
1762 but a dot and "->" before the position is included. When on a
1763 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001764 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001765 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001766 Only valid while evaluating the 'balloonexpr' option.
1767
1768 *v:beval_winnr* *beval_winnr-variable*
1769v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001770 valid while evaluating the 'balloonexpr' option. The first
1771 window has number zero (unlike most other places where a
1772 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001773
Bram Moolenaar511972d2016-06-04 18:09:59 +02001774 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001775v:beval_winid The |window-ID| of the window, over which the mouse pointer
1776 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001777
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001778 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001779v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001780 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001781 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001782
Bram Moolenaar071d4272004-06-13 20:20:40 +00001783 *v:charconvert_from* *charconvert_from-variable*
1784v:charconvert_from
1785 The name of the character encoding of a file to be converted.
1786 Only valid while evaluating the 'charconvert' option.
1787
1788 *v:charconvert_to* *charconvert_to-variable*
1789v:charconvert_to
1790 The name of the character encoding of a file after conversion.
1791 Only valid while evaluating the 'charconvert' option.
1792
1793 *v:cmdarg* *cmdarg-variable*
1794v:cmdarg This variable is used for two purposes:
1795 1. The extra arguments given to a file read/write command.
1796 Currently these are "++enc=" and "++ff=". This variable is
1797 set before an autocommand event for a file read/write
1798 command is triggered. There is a leading space to make it
1799 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001800 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001801 included here, because it will be executed anyway.
1802 2. When printing a PostScript file with ":hardcopy" this is
1803 the argument for the ":hardcopy" command. This can be used
1804 in 'printexpr'.
1805
1806 *v:cmdbang* *cmdbang-variable*
1807v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1808 was used the value is 1, otherwise it is 0. Note that this
1809 can only be used in autocommands. For user commands |<bang>|
1810 can be used.
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02001811 *v:collate* *collate-variable*
1812v:collate The current locale setting for collation order of the runtime
1813 environment. This allows Vim scripts to be aware of the
1814 current locale encoding. Technical: it's the value of
1815 LC_COLLATE. When not using a locale the value is "C".
1816 This variable can not be set directly, use the |:language|
1817 command.
1818 See |multi-lang|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001819
Bram Moolenaar42a45122015-07-10 17:56:23 +02001820 *v:completed_item* *completed_item-variable*
1821v:completed_item
1822 |Dictionary| containing the |complete-items| for the most
1823 recently completed word after |CompleteDone|. The
1824 |Dictionary| is empty if the completion failed.
1825
Bram Moolenaar071d4272004-06-13 20:20:40 +00001826 *v:count* *count-variable*
1827v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001828 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001829 :map _x :<C-U>echo "the count is " . v:count<CR>
1830< Note: The <C-U> is required to remove the line range that you
1831 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001832 When there are two counts, as in "3d2w", they are multiplied,
1833 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001834 Also used for evaluating the 'formatexpr' option.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001835 "count" also works, for backwards compatibility, unless
1836 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001837
1838 *v:count1* *count1-variable*
1839v:count1 Just like "v:count", but defaults to one when no count is
1840 used.
1841
1842 *v:ctype* *ctype-variable*
1843v:ctype The current locale setting for characters of the runtime
1844 environment. This allows Vim scripts to be aware of the
1845 current locale encoding. Technical: it's the value of
1846 LC_CTYPE. When not using a locale the value is "C".
1847 This variable can not be set directly, use the |:language|
1848 command.
1849 See |multi-lang|.
1850
1851 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001852v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001853 one. When multiple signals are caught the number increases.
1854 Can be used in an autocommand to check if Vim didn't
1855 terminate normally. {only works on Unix}
1856 Example: >
1857 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001858< Note: if another deadly signal is caught when v:dying is one,
1859 VimLeave autocommands will not be executed.
1860
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001861 *v:exiting* *exiting-variable*
1862v:exiting Vim exit code. Normally zero, non-zero when something went
1863 wrong. The value is v:null before invoking the |VimLeavePre|
1864 and |VimLeave| autocmds. See |:q|, |:x| and |:cquit|.
1865 Example: >
1866 :au VimLeave * echo "Exit value is " .. v:exiting
1867<
Bram Moolenaar37f4cbd2019-08-23 20:58:45 +02001868 *v:echospace* *echospace-variable*
1869v:echospace Number of screen cells that can be used for an `:echo` message
1870 in the last screen line before causing the |hit-enter-prompt|.
1871 Depends on 'showcmd', 'ruler' and 'columns'. You need to
1872 check 'cmdheight' for whether there are full-width lines
1873 available above the last line.
1874
Bram Moolenaar071d4272004-06-13 20:20:40 +00001875 *v:errmsg* *errmsg-variable*
1876v:errmsg Last given error message. It's allowed to set this variable.
1877 Example: >
1878 :let v:errmsg = ""
1879 :silent! next
1880 :if v:errmsg != ""
1881 : ... handle error
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001882< "errmsg" also works, for backwards compatibility, unless
1883 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001884
Bram Moolenaar65a54642018-04-28 16:56:53 +02001885 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001886v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001887 This is a list of strings.
1888 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02001889 The return value indicates this: a one is returned if an item
1890 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01001891 To remove old results make it empty: >
1892 :let v:errors = []
1893< If v:errors is set to anything but a list it is made an empty
1894 list by the assert function.
1895
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001896 *v:event* *event-variable*
1897v:event Dictionary containing information about the current
Bram Moolenaar560979e2020-02-04 22:53:05 +01001898 |autocommand|. See the specific event for what it puts in
1899 this dictionary.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02001900 The dictionary is emptied when the |autocommand| finishes,
1901 please refer to |dict-identity| for how to get an independent
1902 copy of it. Use |deepcopy()| if you want to keep the
1903 information after the event triggers. Example: >
1904 au TextYankPost * let g:foo = deepcopy(v:event)
1905<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001906 *v:exception* *exception-variable*
1907v:exception The value of the exception most recently caught and not
1908 finished. See also |v:throwpoint| and |throw-variables|.
1909 Example: >
1910 :try
1911 : throw "oops"
1912 :catch /.*/
Bram Moolenaar54775062019-07-31 21:07:14 +02001913 : echo "caught " .. v:exception
Bram Moolenaar071d4272004-06-13 20:20:40 +00001914 :endtry
1915< Output: "caught oops".
1916
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001917 *v:false* *false-variable*
1918v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001919 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001920 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001921 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001922< v:false ~
1923 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001924 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001925
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001926 *v:fcs_reason* *fcs_reason-variable*
1927v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1928 Can be used in an autocommand to decide what to do and/or what
1929 to set v:fcs_choice to. Possible values:
1930 deleted file no longer exists
1931 conflict file contents, mode or timestamp was
1932 changed and buffer is modified
1933 changed file contents has changed
1934 mode mode of file changed
1935 time only file timestamp changed
1936
1937 *v:fcs_choice* *fcs_choice-variable*
1938v:fcs_choice What should happen after a |FileChangedShell| event was
1939 triggered. Can be used in an autocommand to tell Vim what to
1940 do with the affected buffer:
1941 reload Reload the buffer (does not work if
1942 the file was deleted).
1943 ask Ask the user what to do, as if there
1944 was no autocommand. Except that when
1945 only the timestamp changed nothing
1946 will happen.
1947 <empty> Nothing, the autocommand should do
1948 everything that needs to be done.
1949 The default is empty. If another (invalid) value is used then
1950 Vim behaves like it is empty, there is no warning message.
1951
Bram Moolenaar071d4272004-06-13 20:20:40 +00001952 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001953v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001954 option used for ~
1955 'charconvert' file to be converted
1956 'diffexpr' original file
1957 'patchexpr' original file
1958 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001959 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001960
1961 *v:fname_out* *fname_out-variable*
1962v:fname_out The name of the output file. Only valid while
1963 evaluating:
1964 option used for ~
1965 'charconvert' resulting converted file (*)
1966 'diffexpr' output of diff
1967 'patchexpr' resulting patched file
1968 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02001969 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001970 for a read command (e.g., ":e file") it will be a temporary
1971 file and different from v:fname_in.
1972
1973 *v:fname_new* *fname_new-variable*
1974v:fname_new The name of the new version of the file. Only valid while
1975 evaluating 'diffexpr'.
1976
1977 *v:fname_diff* *fname_diff-variable*
1978v:fname_diff The name of the diff (patch) file. Only valid while
1979 evaluating 'patchexpr'.
1980
1981 *v:folddashes* *folddashes-variable*
1982v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1983 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001984 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001985
1986 *v:foldlevel* *foldlevel-variable*
1987v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001988 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001989
1990 *v:foldend* *foldend-variable*
1991v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001992 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001993
1994 *v:foldstart* *foldstart-variable*
1995v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001996 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001997
Bram Moolenaar817a8802013-11-09 01:44:43 +01001998 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001999v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01002000 Setting it makes sense only if 'hlsearch' is enabled which
2001 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01002002 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01002003 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02002004< Note that the value is restored when returning from a
2005 function. |function-search-undo|.
2006
Bram Moolenaar843ee412004-06-30 16:16:41 +00002007 *v:insertmode* *insertmode-variable*
2008v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
2009 events. Values:
2010 i Insert mode
2011 r Replace mode
2012 v Virtual Replace mode
2013
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002014 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002015v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002016 evaluating the expression used with |map()| and |filter()|.
2017 Read-only.
2018
Bram Moolenaar071d4272004-06-13 20:20:40 +00002019 *v:lang* *lang-variable*
2020v:lang The current locale setting for messages of the runtime
2021 environment. This allows Vim scripts to be aware of the
2022 current language. Technical: it's the value of LC_MESSAGES.
2023 The value is system dependent.
2024 This variable can not be set directly, use the |:language|
2025 command.
2026 It can be different from |v:ctype| when messages are desired
2027 in a different language than what is used for character
2028 encoding. See |multi-lang|.
2029
2030 *v:lc_time* *lc_time-variable*
2031v:lc_time The current locale setting for time messages of the runtime
2032 environment. This allows Vim scripts to be aware of the
2033 current language. Technical: it's the value of LC_TIME.
2034 This variable can not be set directly, use the |:language|
2035 command. See |multi-lang|.
2036
2037 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02002038v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
2039 'indentexpr' expressions, tab page number for 'guitablabel'
2040 and 'guitabtooltip'. Only valid while one of these
2041 expressions is being evaluated. Read-only when in the
2042 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002043
Bram Moolenaar219b8702006-11-01 14:32:36 +00002044 *v:mouse_win* *mouse_win-variable*
2045v:mouse_win Window number for a mouse click obtained with |getchar()|.
2046 First window has number 1, like with |winnr()|. The value is
2047 zero when there was no mouse button click.
2048
Bram Moolenaar511972d2016-06-04 18:09:59 +02002049 *v:mouse_winid* *mouse_winid-variable*
2050v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
2051 The value is zero when there was no mouse button click.
2052
Bram Moolenaar219b8702006-11-01 14:32:36 +00002053 *v:mouse_lnum* *mouse_lnum-variable*
2054v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
2055 This is the text line number, not the screen line number. The
2056 value is zero when there was no mouse button click.
2057
2058 *v:mouse_col* *mouse_col-variable*
2059v:mouse_col Column number for a mouse click obtained with |getchar()|.
2060 This is the screen column number, like with |virtcol()|. The
2061 value is zero when there was no mouse button click.
2062
Bram Moolenaard09091d2019-01-17 16:07:22 +01002063 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002064v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002065 |json_encode()|.
Bram Moolenaar2547aa92020-07-26 17:00:44 +02002066 This can also be used as a function argument to use the
2067 default value, see |none-function_argument|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01002068 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002069 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002070 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002071< v:none ~
2072 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002073 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002074
2075 *v:null* *null-variable*
2076v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002077 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01002078 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002079 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002080 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002081< v:null ~
2082 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002083 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002084
Bram Moolenaar57d5a012021-01-21 21:42:31 +01002085 *v:numbermax* *numbermax-variable*
2086v:numbermax Maximum value of a number.
2087
Bram Moolenaare0e39172021-01-25 21:14:57 +01002088 *v:numbermin* *numbermin-variable*
Bram Moolenaar57d5a012021-01-21 21:42:31 +01002089v:numbermin Minimum value of a number (negative)
2090
Bram Moolenaarf9706e92020-02-22 14:27:04 +01002091 *v:numbersize* *numbersize-variable*
2092v:numbersize Number of bits in a Number. This is normally 64, but on some
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01002093 systems it may be 32.
Bram Moolenaarf9706e92020-02-22 14:27:04 +01002094
Bram Moolenaard812df62008-11-09 12:46:09 +00002095 *v:oldfiles* *oldfiles-variable*
2096v:oldfiles List of file names that is loaded from the |viminfo| file on
2097 startup. These are the files that Vim remembers marks for.
2098 The length of the List is limited by the ' argument of the
2099 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01002100 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00002101 Also see |:oldfiles| and |c_#<|.
2102 The List can be modified, but this has no effect on what is
2103 stored in the |viminfo| file later. If you use values other
2104 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02002105 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00002106
Bram Moolenaar53744302015-07-17 17:38:22 +02002107 *v:option_new*
2108v:option_new New value of the option. Valid while executing an |OptionSet|
2109 autocommand.
2110 *v:option_old*
2111v:option_old Old value of the option. Valid while executing an |OptionSet|
Bram Moolenaard7c96872019-06-15 17:12:48 +02002112 autocommand. Depending on the command used for setting and the
2113 kind of option this is either the local old value or the
2114 global old value.
2115 *v:option_oldlocal*
2116v:option_oldlocal
2117 Old local value of the option. Valid while executing an
2118 |OptionSet| autocommand.
2119 *v:option_oldglobal*
2120v:option_oldglobal
2121 Old global value of the option. Valid while executing an
2122 |OptionSet| autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02002123 *v:option_type*
2124v:option_type Scope of the set command. Valid while executing an
2125 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaard7c96872019-06-15 17:12:48 +02002126 *v:option_command*
2127v:option_command
2128 Command used to set the option. Valid while executing an
2129 |OptionSet| autocommand.
2130 value option was set via ~
2131 "setlocal" |:setlocal| or ":let l:xxx"
2132 "setglobal" |:setglobal| or ":let g:xxx"
2133 "set" |:set| or |:let|
2134 "modeline" |modeline|
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002135 *v:operator* *operator-variable*
2136v:operator The last operator given in Normal mode. This is a single
2137 character except for commands starting with <g> or <z>,
2138 in which case it is two characters. Best used alongside
2139 |v:prevcount| and |v:register|. Useful if you want to cancel
2140 Operator-pending mode and then use the operator, e.g.: >
2141 :omap O <Esc>:call MyMotion(v:operator)<CR>
2142< The value remains set until another operator is entered, thus
2143 don't expect it to be empty.
2144 v:operator is not set for |:delete|, |:yank| or other Ex
2145 commands.
2146 Read-only.
2147
Bram Moolenaar071d4272004-06-13 20:20:40 +00002148 *v:prevcount* *prevcount-variable*
2149v:prevcount The count given for the last but one Normal mode command.
2150 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002151 you want to cancel Visual or Operator-pending mode and then
2152 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002153 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
2154< Read-only.
2155
Bram Moolenaar05159a02005-02-26 23:04:13 +00002156 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002157v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00002158 See |profiling|.
2159
Bram Moolenaar071d4272004-06-13 20:20:40 +00002160 *v:progname* *progname-variable*
2161v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02002162 invoked. Allows you to do special initialisations for |view|,
2163 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002164 Read-only.
2165
Bram Moolenaara1706c92014-04-01 19:55:49 +02002166 *v:progpath* *progpath-variable*
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002167v:progpath Contains the command with which Vim was invoked, in a form
2168 that when passed to the shell will run the same Vim executable
2169 as the current one (if $PATH remains unchanged).
2170 Useful if you want to message a Vim server using a
Bram Moolenaara1706c92014-04-01 19:55:49 +02002171 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02002172 To get the full path use: >
2173 echo exepath(v:progpath)
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002174< If the command has a relative path it will be expanded to the
2175 full path, so that it still works after `:cd`. Thus starting
2176 "./vim" results in "/home/user/path/to/vim/src/vim".
2177 On Linux and other systems it will always be the full path.
2178 On Mac it may just be "vim" and using exepath() as mentioned
2179 above should be used to get the full path.
Bram Moolenaar08cab962017-03-04 14:37:18 +01002180 On MS-Windows the executable may be called "vim.exe", but the
2181 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02002182 Read-only.
2183
Bram Moolenaar071d4272004-06-13 20:20:40 +00002184 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01002185v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02002186 command (regardless of whether that command actually used a
2187 register). Or for the currently executing normal mode mapping
2188 (use this in custom commands that take a register).
2189 If none is supplied it is the default register '"', unless
2190 'clipboard' contains "unnamed" or "unnamedplus", then it is
2191 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01002192 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002193
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002194 *v:scrollstart* *scrollstart-variable*
2195v:scrollstart String describing the script or function that caused the
2196 screen to scroll up. It's only set when it is empty, thus the
2197 first reason is remembered. It is set to "Unknown" for a
2198 typed command.
2199 This can be used to find out why your script causes the
2200 hit-enter prompt.
2201
Bram Moolenaar071d4272004-06-13 20:20:40 +00002202 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002203v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002204 Read-only.
2205
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002206
Bram Moolenaar446cb832008-06-24 21:56:24 +00002207v:searchforward *v:searchforward* *searchforward-variable*
2208 Search direction: 1 after a forward search, 0 after a
2209 backward search. It is reset to forward when directly setting
2210 the last search pattern, see |quote/|.
2211 Note that the value is restored when returning from a
2212 function. |function-search-undo|.
2213 Read-write.
2214
Bram Moolenaar071d4272004-06-13 20:20:40 +00002215 *v:shell_error* *shell_error-variable*
2216v:shell_error Result of the last shell command. When non-zero, the last
2217 shell command had an error. When zero, there was no problem.
2218 This only works when the shell returns the error code to Vim.
2219 The value -1 is often used when the command could not be
2220 executed. Read-only.
2221 Example: >
2222 :!mv foo bar
2223 :if v:shell_error
2224 : echo 'could not rename "foo" to "bar"!'
2225 :endif
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002226< "shell_error" also works, for backwards compatibility, unless
2227 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002228
2229 *v:statusmsg* *statusmsg-variable*
2230v:statusmsg Last given status message. It's allowed to set this variable.
2231
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002232 *v:swapname* *swapname-variable*
2233v:swapname Only valid when executing |SwapExists| autocommands: Name of
2234 the swap file found. Read-only.
2235
2236 *v:swapchoice* *swapchoice-variable*
2237v:swapchoice |SwapExists| autocommands can set this to the selected choice
2238 for handling an existing swap file:
2239 'o' Open read-only
2240 'e' Edit anyway
2241 'r' Recover
2242 'd' Delete swapfile
2243 'q' Quit
2244 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002245 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002246 results in the user being asked, as would happen when there is
2247 no SwapExists autocommand. The default is empty.
2248
Bram Moolenaarb3480382005-12-11 21:33:32 +00002249 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002250v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002251 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002252 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002253 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002254 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002255
Bram Moolenaard823fa92016-08-12 16:29:27 +02002256 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002257v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002258 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002259v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002260 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002261v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002262 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002263v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002264 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002265v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002266 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002267v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002268 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002269v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002270 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002271v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002272 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002273v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002274 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002275v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002276 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002277v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002278
Bram Moolenaar071d4272004-06-13 20:20:40 +00002279 *v:termresponse* *termresponse-variable*
2280v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002281 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaarb4230122019-05-30 18:40:53 +02002282 that starts with ESC [ or CSI, then '>' or '?' and ends in a
2283 'c', with only digits and ';' in between.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002284 When this option is set, the TermResponse autocommand event is
2285 fired, so that you can react to the response from the
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +02002286 terminal. You can use |terminalprops()| to see what Vim
2287 figured out about the terminal.
Bram Moolenaarb4230122019-05-30 18:40:53 +02002288 The response from a new xterm is: "<Esc>[> Pp ; Pv ; Pc c". Pp
Bram Moolenaar071d4272004-06-13 20:20:40 +00002289 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2290 patch level (since this was introduced in patch 95, it's
2291 always 95 or bigger). Pc is always zero.
2292 {only when compiled with |+termresponse| feature}
2293
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002294 *v:termblinkresp*
2295v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2296 termcap entry. This is used to find out whether the terminal
2297 cursor is blinking. This is used by |term_getcursor()|.
2298
2299 *v:termstyleresp*
2300v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2301 termcap entry. This is used to find out what the shape of the
2302 cursor is. This is used by |term_getcursor()|.
2303
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002304 *v:termrbgresp*
2305v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002306 termcap entry. This is used to find out what the terminal
2307 background color is, see 'background'.
2308
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002309 *v:termrfgresp*
2310v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2311 termcap entry. This is used to find out what the terminal
2312 foreground color is.
2313
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002314 *v:termu7resp*
2315v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2316 termcap entry. This is used to find out what the terminal
2317 does with ambiguous width characters, see 'ambiwidth'.
2318
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002319 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002320v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002321 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002322 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002323
Bram Moolenaar071d4272004-06-13 20:20:40 +00002324 *v:this_session* *this_session-variable*
2325v:this_session Full filename of the last loaded or saved session file. See
2326 |:mksession|. It is allowed to set this variable. When no
2327 session file has been saved, this variable is empty.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002328 "this_session" also works, for backwards compatibility, unless
2329 |scriptversion| is 3 or higher
Bram Moolenaar071d4272004-06-13 20:20:40 +00002330
2331 *v:throwpoint* *throwpoint-variable*
2332v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002333 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002334 also |v:exception| and |throw-variables|.
2335 Example: >
2336 :try
2337 : throw "oops"
2338 :catch /.*/
2339 : echo "Exception from" v:throwpoint
2340 :endtry
2341< Output: "Exception from test.vim, line 2"
2342
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002343 *v:true* *true-variable*
2344v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002345 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002346 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002347 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002348< v:true ~
2349 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002350 value. Read-only.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002351 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002352v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002353 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002354 |filter()|. Read-only.
2355
Bram Moolenaar071d4272004-06-13 20:20:40 +00002356 *v:version* *version-variable*
2357v:version Version number of Vim: Major version number times 100 plus
Bram Moolenaar9b283522019-06-17 22:19:33 +02002358 minor version number. Version 5.0 is 500. Version 5.1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002359 is 501. Read-only. "version" also works, for backwards
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002360 compatibility, unless |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002361 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002362 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002363< Note that patch numbers are specific to the version, thus both
2364 version 5.0 and 5.1 may have a patch 123, but these are
2365 completely different.
2366
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002367 *v:versionlong* *versionlong-variable*
Bram Moolenaar9b283522019-06-17 22:19:33 +02002368v:versionlong Like v:version, but also including the patchlevel in the last
2369 four digits. Version 8.1 with patch 123 has value 8010123.
2370 This can be used like this: >
2371 if v:versionlong >= 8010123
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002372< However, if there are gaps in the list of patches included
2373 this will not work well. This can happen if a recent patch
2374 was included into an older version, e.g. for a security fix.
2375 Use the has() function to make sure the patch is actually
2376 included.
2377
Bram Moolenaar14735512016-03-26 21:00:08 +01002378 *v:vim_did_enter* *vim_did_enter-variable*
2379v:vim_did_enter Zero until most of startup is done. It is set to one just
2380 before |VimEnter| autocommands are triggered.
2381
Bram Moolenaar071d4272004-06-13 20:20:40 +00002382 *v:warningmsg* *warningmsg-variable*
2383v:warningmsg Last given warning message. It's allowed to set this variable.
2384
Bram Moolenaar727c8762010-10-20 19:17:48 +02002385 *v:windowid* *windowid-variable*
2386v:windowid When any X11 based GUI is running or when running in a
2387 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002388 set to the window ID.
2389 When an MS-Windows GUI is running this will be set to the
2390 window handle.
2391 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002392 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2393 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002394
Bram Moolenaar071d4272004-06-13 20:20:40 +00002395==============================================================================
23964. Builtin Functions *functions*
2397
2398See |function-list| for a list grouped by what the function is used for.
2399
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002400(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002401
2402USAGE RESULT DESCRIPTION ~
2403
Bram Moolenaar81edd172016-04-14 13:51:37 +02002404abs({expr}) Float or Number absolute value of {expr}
2405acos({expr}) Float arc cosine of {expr}
Bram Moolenaard8968242019-01-15 22:51:57 +01002406add({object}, {item}) List/Blob append {item} to {object}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002407and({expr}, {expr}) Number bitwise AND
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002408append({lnum}, {text}) Number append {text} below line {lnum}
2409appendbufline({expr}, {lnum}, {text})
2410 Number append {text} below line {lnum}
2411 in buffer {expr}
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002412argc([{winid}]) Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002413argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002414arglistid([{winnr} [, {tabnr}]]) Number argument list id
Bram Moolenaare6e39892018-10-25 12:32:11 +02002415argv({nr} [, {winid}]) String {nr} entry of the argument list
2416argv([-1, {winid}]) List the argument list
Bram Moolenaarfb517ba2020-06-03 19:55:35 +02002417asin({expr}) Float arc sine of {expr}
Bram Moolenaar65a54642018-04-28 16:56:53 +02002418assert_beeps({cmd}) Number assert {cmd} causes a beep
Bram Moolenaar42205552017-03-18 19:42:22 +01002419assert_equal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002420 Number assert {exp} is equal to {act}
Bram Moolenaarfb517ba2020-06-03 19:55:35 +02002421assert_equalfile({fname-one}, {fname-two} [, {msg}])
2422 Number assert file contents are equal
Bram Moolenaar42205552017-03-18 19:42:22 +01002423assert_exception({error} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002424 Number assert {error} is in v:exception
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002425assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002426 Number assert {cmd} fails
Bram Moolenaar42205552017-03-18 19:42:22 +01002427assert_false({actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002428 Number assert {actual} is false
Bram Moolenaar61c04492016-07-23 15:35:35 +02002429assert_inrange({lower}, {upper}, {actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002430 Number assert {actual} is inside the range
Bram Moolenaar42205552017-03-18 19:42:22 +01002431assert_match({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002432 Number assert {pat} matches {text}
Bram Moolenaar42205552017-03-18 19:42:22 +01002433assert_notequal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002434 Number assert {exp} is not equal {act}
Bram Moolenaar42205552017-03-18 19:42:22 +01002435assert_notmatch({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002436 Number assert {pat} not matches {text}
2437assert_report({msg}) Number report a test failure
2438assert_true({actual} [, {msg}]) Number assert {actual} is true
Bram Moolenaar81edd172016-04-14 13:51:37 +02002439atan({expr}) Float arc tangent of {expr}
Bram Moolenaar04186092016-08-29 21:55:35 +02002440atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02002441balloon_gettext() String current text in the balloon
Bram Moolenaar74240d32017-12-10 15:26:15 +01002442balloon_show({expr}) none show {expr} inside the balloon
Bram Moolenaar246fe032017-11-19 19:56:27 +01002443balloon_split({msg}) List split {msg} as used for a balloon
Bram Moolenaar81edd172016-04-14 13:51:37 +02002444browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002445 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02002446browsedir({title}, {initdir}) String put up a directory requester
Bram Moolenaar15e248e2019-06-30 20:21:37 +02002447bufadd({name}) Number add a buffer to the buffer list
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002448bufexists({expr}) Number |TRUE| if buffer {expr} exists
2449buflisted({expr}) Number |TRUE| if buffer {expr} is listed
Bram Moolenaar15e248e2019-06-30 20:21:37 +02002450bufload({expr}) Number load buffer {expr} if not loaded yet
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002451bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded
Bram Moolenaara8eee212019-08-24 22:14:58 +02002452bufname([{expr}]) String Name of the buffer {expr}
2453bufnr([{expr} [, {create}]]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002454bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002455bufwinnr({expr}) Number window number of buffer {expr}
2456byte2line({byte}) Number line number at byte count {byte}
2457byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2458byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2459call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002460 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002461ceil({expr}) Float round {expr} up
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002462ch_canread({handle}) Number check if there is something to read
Bram Moolenaar81edd172016-04-14 13:51:37 +02002463ch_close({handle}) none close {handle}
Bram Moolenaar0874a832016-09-01 15:11:51 +02002464ch_close_in({handle}) none close in part of {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002465ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002466 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002467ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002468 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002469ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2470ch_getjob({channel}) Job get the Job of {channel}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002471ch_info({handle}) String info about channel {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002472ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2473ch_logfile({fname} [, {mode}]) none start logging channel activity
2474ch_open({address} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002475 Channel open a channel to {address}
2476ch_read({handle} [, {options}]) String read from {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002477ch_readblob({handle} [, {options}])
2478 Blob read Blob from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002479ch_readraw({handle} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002480 String read raw from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002481ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002482 any send {expr} over JSON {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002483ch_sendraw({handle}, {expr} [, {options}])
2484 any send {expr} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002485ch_setoptions({handle}, {options})
2486 none set options for {handle}
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002487ch_status({handle} [, {options}])
2488 String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002489changenr() Number current change number
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002490char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaar4e4473c2020-08-28 22:24:57 +02002491charclass({string}) Number character class of {string}
Bram Moolenaar6f02b002021-01-10 20:22:54 +01002492charcol({expr}) Number column number of cursor or mark
Bram Moolenaar17793ef2020-12-28 12:56:58 +01002493charidx({string}, {idx} [, {countcc}])
2494 Number char index of byte {idx} in {string}
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02002495chdir({dir}) String change current working directory
Bram Moolenaar81edd172016-04-14 13:51:37 +02002496cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaaraff74912019-03-30 18:11:49 +01002497clearmatches([{win}]) none clear all matches
Bram Moolenaar6f02b002021-01-10 20:22:54 +01002498col({expr}) Number column byte index of cursor or mark
Bram Moolenaar81edd172016-04-14 13:51:37 +02002499complete({startcol}, {matches}) none set Insert mode completion
2500complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002501complete_check() Number check for key typed during completion
Bram Moolenaarfd133322019-03-29 12:20:27 +01002502complete_info([{what}]) Dict get current completion information
Bram Moolenaar81edd172016-04-14 13:51:37 +02002503confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002504 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002505copy({expr}) any make a shallow copy of {expr}
2506cos({expr}) Float cosine of {expr}
2507cosh({expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002508count({comp}, {expr} [, {ic} [, {start}]])
2509 Number count how many {expr} are in {comp}
Bram Moolenaardc1f1642016-08-16 18:33:43 +02002510cscope_connection([{num}, {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002511 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02002512cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002513 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002514cursor({list}) Number move cursor to position in {list}
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02002515debugbreak({pid}) Number interrupt process being debugged
Bram Moolenaar81edd172016-04-14 13:51:37 +02002516deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2517delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002518deletebufline({expr}, {first} [, {last}])
Bram Moolenaard79a2622018-06-07 18:17:46 +02002519 Number delete lines from buffer {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002520did_filetype() Number |TRUE| if FileType autocmd event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002521diff_filler({lnum}) Number diff filler lines about {lnum}
2522diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar4132eb52020-02-14 16:53:00 +01002523echoraw({expr}) none output {expr} as-is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002524empty({expr}) Number |TRUE| if {expr} is empty
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002525environ() Dict return environment variables
Bram Moolenaar81edd172016-04-14 13:51:37 +02002526escape({string}, {chars}) String escape {chars} in {string} with '\'
2527eval({string}) any evaluate {string} into its value
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002528eventhandler() Number |TRUE| if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02002529executable({expr}) Number 1 if executable {expr} exists
Bram Moolenaar79815f12016-07-09 17:07:29 +02002530execute({command}) String execute {command} and get the output
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002531exepath({expr}) String full path of the command {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002532exists({expr}) Number |TRUE| if {expr} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002533exp({expr}) Float exponential of {expr}
2534expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002535 any expand special keywords in {expr}
Bram Moolenaar80dad482019-06-09 17:22:31 +02002536expandcmd({expr}) String expand {expr} like with `:edit`
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002537extend({expr1}, {expr2} [, {expr3}])
2538 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaarb0e6b512021-01-12 20:23:40 +01002539extendnew({expr1}, {expr2} [, {expr3}])
2540 List/Dict like |extend()| but creates a new
2541 List or Dictionary
Bram Moolenaar81edd172016-04-14 13:51:37 +02002542feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002543filereadable({file}) Number |TRUE| if {file} is a readable file
2544filewritable({file}) Number |TRUE| if {file} is a writable file
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002545filter({expr1}, {expr2}) List/Dict remove items from {expr1} where
2546 {expr2} is 0
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002547finddir({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002548 String find directory {name} in {path}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002549findfile({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002550 String find file {name} in {path}
Bram Moolenaar077a1e62020-06-08 20:50:43 +02002551flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
Bram Moolenaar3b690062021-02-01 20:14:51 +01002552flattennew({list} [, {maxdepth}])
2553 List flatten a copy of {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002554float2nr({expr}) Number convert Float {expr} to a Number
2555floor({expr}) Float round {expr} down
2556fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2557fnameescape({fname}) String escape special characters in {fname}
2558fnamemodify({fname}, {mods}) String modify file name
2559foldclosed({lnum}) Number first line of fold at {lnum} if closed
2560foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2561foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002562foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02002563foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002564foreground() Number bring the Vim window to the foreground
Bram Moolenaar038e09e2021-02-06 12:38:51 +01002565fullcommand({name}) String get full command from {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002566funcref({name} [, {arglist}] [, {dict}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002567 Funcref reference to function {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002568function({name} [, {arglist}] [, {dict}])
2569 Funcref named reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002570garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02002571get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2572get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02002573get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002574getbufinfo([{expr}]) List information about buffers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002575getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00002576 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002577getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002578 any variable {varname} in buffer {expr}
Bram Moolenaar4c313b12019-08-24 22:58:31 +02002579getchangelist([{expr}]) List list of change list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002580getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002581getcharmod() Number modifiers for the last typed character
Bram Moolenaar6f02b002021-01-10 20:22:54 +01002582getcharpos({expr}) List position of cursor, mark, etc.
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02002583getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002584getcmdline() String return the current command-line
2585getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02002586getcmdtype() String return current command-line type
2587getcmdwintype() String return current command-line window type
Bram Moolenaare9d58a62016-08-13 15:07:41 +02002588getcompletion({pat}, {type} [, {filtered}])
2589 List list of cmdline completion matches
Bram Moolenaar99ca9c42020-09-22 21:55:41 +02002590getcurpos([{winnr}]) List position of the cursor
Bram Moolenaar6f02b002021-01-10 20:22:54 +01002591getcursorcharpos([{winnr}]) List character position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002592getcwd([{winnr} [, {tabnr}]]) String get the current working directory
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002593getenv({name}) String return environment variable
Bram Moolenaar81edd172016-04-14 13:51:37 +02002594getfontname([{name}]) String name of font being used
2595getfperm({fname}) String file permissions of file {fname}
2596getfsize({fname}) Number size in bytes of file {fname}
2597getftime({fname}) Number last modification time of file
2598getftype({fname}) String description of type of file {fname}
Bram Moolenaara3a12462019-09-07 15:08:38 +02002599getimstatus() Number |TRUE| if the IME status is active
Bram Moolenaar4f505882018-02-10 21:06:32 +01002600getjumplist([{winnr} [, {tabnr}]])
2601 List list of jump list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002602getline({lnum}) String line {lnum} of current buffer
2603getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaare46a4402020-06-30 20:38:27 +02002604getloclist({nr}) List list of location list items
2605getloclist({nr}, {what}) Dict get specific location list properties
Bram Moolenaarcfb4b472020-05-31 15:41:57 +02002606getmarklist([{expr}]) List list of global/local marks
Bram Moolenaaraff74912019-03-30 18:11:49 +01002607getmatches([{win}]) List list of current matches
Bram Moolenaardb3a2052019-11-16 18:22:41 +01002608getmousepos() Dict last known mouse position
Bram Moolenaar18081e32008-02-20 19:11:07 +00002609getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002610getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaare46a4402020-06-30 20:38:27 +02002611getqflist() List list of quickfix items
2612getqflist({what}) Dict get specific quickfix list properties
Bram Moolenaar81edd172016-04-14 13:51:37 +02002613getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarbb861e22020-06-07 18:16:36 +02002614 String or List contents of a register
2615getreginfo([{regname}]) Dict information about a register
2616getregtype([{regname}]) String type of a register
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002617gettabinfo([{expr}]) List list of tab pages
Bram Moolenaar81edd172016-04-14 13:51:37 +02002618gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002619 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002620gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002621 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002622gettagstack([{nr}]) Dict get the tag stack of window {nr}
Bram Moolenaar0b39c3f2020-08-30 15:52:10 +02002623gettext({text}) String lookup translation of {text}
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02002624getwininfo([{winid}]) List list of info about each window
Bram Moolenaar98ef2332018-03-18 14:44:37 +01002625getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01002626getwinposx() Number X coord in pixels of the Vim window
2627getwinposy() Number Y coord in pixels of the Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002628getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002629 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002630glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002631 any expand file wildcards in {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002632glob2regpat({expr}) String convert a glob pat into a search pat
Bram Moolenaar81edd172016-04-14 13:51:37 +02002633globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002634 String do glob({expr}) for all dirs in {path}
Bram Moolenaar79296512020-03-22 16:17:14 +01002635has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002636has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002637haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002638 Number |TRUE| if the window executed |:lcd|
Bram Moolenaar00aa0692019-04-27 20:37:57 +02002639 or |:tcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002640hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002641 Number |TRUE| if mapping to {what} exists
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01002642histadd({history}, {item}) Number add an item to a history
2643histdel({history} [, {item}]) Number remove an item from a history
Bram Moolenaar81edd172016-04-14 13:51:37 +02002644histget({history} [, {index}]) String get the item {index} from a history
2645histnr({history}) Number highest index of a history
Bram Moolenaar81edd172016-04-14 13:51:37 +02002646hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002647hlexists({name}) Number |TRUE| if highlight group {name} exists
Bram Moolenaar071d4272004-06-13 20:20:40 +00002648hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002649iconv({expr}, {from}, {to}) String convert encoding of {expr}
2650indent({lnum}) Number indent of line {lnum}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002651index({object}, {expr} [, {start} [, {ic}]])
2652 Number index in {object} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002653input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002654 String get input from the user
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02002655inputdialog({prompt} [, {text} [, {completion}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002656 String like input() but in a GUI dialog
Bram Moolenaar81edd172016-04-14 13:51:37 +02002657inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002658inputrestore() Number restore typeahead
2659inputsave() Number save and clear typeahead
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002660inputsecret({prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002661insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
Bram Moolenaar67a2deb2019-11-25 00:05:32 +01002662interrupt() none interrupt script execution
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002663invert({expr}) Number bitwise invert
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002664isdirectory({directory}) Number |TRUE| if {directory} is a directory
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02002665isinf({expr}) Number determine if {expr} is infinity value
2666 (positive or negative)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002667islocked({expr}) Number |TRUE| if {expr} is locked
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002668isnan({expr}) Number |TRUE| if {expr} is NaN
Bram Moolenaar81edd172016-04-14 13:51:37 +02002669items({dict}) List key-value pairs in {dict}
2670job_getchannel({job}) Channel get the channel handle for {job}
Bram Moolenaare1fc5152018-04-21 19:49:08 +02002671job_info([{job}]) Dict get information about {job}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002672job_setoptions({job}, {options}) none set options for {job}
2673job_start({command} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002674 Job start a job
Bram Moolenaar81edd172016-04-14 13:51:37 +02002675job_status({job}) String get the status of {job}
2676job_stop({job} [, {how}]) Number stop {job}
2677join({list} [, {sep}]) String join {list} items into one String
2678js_decode({string}) any decode JS style JSON
2679js_encode({expr}) String encode JS style JSON
2680json_decode({string}) any decode JSON
2681json_encode({expr}) String encode JSON
2682keys({dict}) List keys in {dict}
2683len({expr}) Number the length of {expr}
2684libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002685libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02002686line({expr} [, {winid}]) Number line nr of cursor, last line or mark
Bram Moolenaar81edd172016-04-14 13:51:37 +02002687line2byte({lnum}) Number byte count of line {lnum}
2688lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar9d401282019-04-06 13:18:12 +02002689list2str({list} [, {utf8}]) String turn numbers in {list} into a String
Bram Moolenaara3347722019-05-11 21:14:24 +02002690listener_add({callback} [, {buf}])
2691 Number add a callback to listen to changes
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02002692listener_flush([{buf}]) none invoke listener callbacks
Bram Moolenaara3347722019-05-11 21:14:24 +02002693listener_remove({id}) none remove a listener callback
Bram Moolenaar071d4272004-06-13 20:20:40 +00002694localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002695log({expr}) Float natural logarithm (base e) of {expr}
2696log10({expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002697luaeval({expr} [, {expr}]) any evaluate |Lua| expression
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002698map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002699maparg({name} [, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002700 String or Dict
2701 rhs of mapping {name} in mode {mode}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002702mapcheck({name} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002703 String check for mappings matching {name}
Bram Moolenaarea696852020-11-09 18:31:39 +01002704mapnew({expr1}, {expr2}) List/Dict like |map()| but creates a new List
2705 or Dictionary
2706mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002707match({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002708 Number position where {pat} matches in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002709matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002710 Number highlight {pattern} with {group}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002711matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002712 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002713matcharg({nr}) List arguments of |:match|
Bram Moolenaaraff74912019-03-30 18:11:49 +01002714matchdelete({id} [, {win}]) Number delete match identified by {id}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002715matchend({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002716 Number position where {pat} ends in {expr}
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02002717matchfuzzy({list}, {str} [, {dict}])
2718 List fuzzy match {str} in {list}
2719matchfuzzypos({list}, {str} [, {dict}])
2720 List fuzzy match {str} in {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002721matchlist({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002722 List match and submatches of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002723matchstr({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002724 String {count}'th match of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002725matchstrpos({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002726 List {count}'th match of {pat} in {expr}
Bram Moolenaar690afe12017-01-28 18:34:47 +01002727max({expr}) Number maximum value of items in {expr}
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +01002728menu_info({name} [, {mode}]) Dict get menu item information
Bram Moolenaar690afe12017-01-28 18:34:47 +01002729min({expr}) Number minimum value of items in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002730mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002731 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002732mode([expr]) String current editing mode
2733mzeval({expr}) any evaluate |MzScheme| expression
2734nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002735nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002736or({expr}, {expr}) Number bitwise OR
Bram Moolenaar6a33ef02020-09-25 22:42:48 +02002737pathshorten({expr} [, {len}]) String shorten directory names in a path
Bram Moolenaar81edd172016-04-14 13:51:37 +02002738perleval({expr}) any evaluate |Perl| expression
Bram Moolenaar931a2772019-07-04 16:54:54 +02002739popup_atcursor({what}, {options}) Number create popup window near the cursor
Bram Moolenaar589edb32019-09-20 14:38:13 +02002740popup_beval({what}, {options}) Number create popup window for 'ballooneval'
Bram Moolenaar931a2772019-07-04 16:54:54 +02002741popup_clear() none close all popup windows
2742popup_close({id} [, {result}]) none close popup window {id}
2743popup_create({what}, {options}) Number create a popup window
2744popup_dialog({what}, {options}) Number create a popup window used as a dialog
2745popup_filter_menu({id}, {key}) Number filter for a menu popup window
2746popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
Bram Moolenaare49fbff2019-08-21 22:50:07 +02002747popup_findinfo() Number get window ID of info popup window
2748popup_findpreview() Number get window ID of preview popup window
Bram Moolenaar931a2772019-07-04 16:54:54 +02002749popup_getoptions({id}) Dict get options of popup window {id}
2750popup_getpos({id}) Dict get position of popup window {id}
2751popup_hide({id}) none hide popup menu {id}
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002752popup_list() List get a list of window IDs of all popups
Bram Moolenaaref6b9792020-05-13 16:34:15 +02002753popup_locate({row}, {col}) Number get window ID of popup at position
Bram Moolenaar931a2772019-07-04 16:54:54 +02002754popup_menu({what}, {options}) Number create a popup window used as a menu
2755popup_move({id}, {options}) none set position of popup window {id}
2756popup_notification({what}, {options})
2757 Number create a notification popup window
Bram Moolenaar931a2772019-07-04 16:54:54 +02002758popup_setoptions({id}, {options})
2759 none set options for popup window {id}
2760popup_settext({id}, {text}) none set the text of popup window {id}
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002761popup_show({id}) none unhide popup window {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002762pow({x}, {y}) Float {x} to the power of {y}
2763prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2764printf({fmt}, {expr1}...) String format text
Bram Moolenaar077cc7a2020-09-04 16:35:35 +02002765prompt_getprompt({buf}) String get prompt text
Bram Moolenaarf2732452018-06-03 14:47:35 +02002766prompt_setcallback({buf}, {expr}) none set prompt callback function
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02002767prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
2768prompt_setprompt({buf}, {text}) none set prompt text
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002769prop_add({lnum}, {col}, {props}) none add a text property
Bram Moolenaare3d31b02018-12-24 23:07:04 +01002770prop_clear({lnum} [, {lnum-end} [, {props}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002771 none remove all text properties
2772prop_find({props} [, {direction}])
2773 Dict search for a text property
Bram Moolenaar7ceefb32020-05-01 16:07:38 +02002774prop_list({lnum} [, {props}]) List text properties in {lnum}
Bram Moolenaarc8c88492018-12-27 23:59:26 +01002775prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002776 Number remove a text property
2777prop_type_add({name}, {props}) none define a new property type
2778prop_type_change({name}, {props})
2779 none change an existing property type
2780prop_type_delete({name} [, {props}])
2781 none delete a property type
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01002782prop_type_get({name} [, {props}])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002783 Dict get property type values
2784prop_type_list([{props}]) List get list of property types
Bram Moolenaare9bd5722019-08-17 19:36:06 +02002785pum_getpos() Dict position and size of pum if visible
Bram Moolenaar446cb832008-06-24 21:56:24 +00002786pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002787py3eval({expr}) any evaluate |python3| expression
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002788pyeval({expr}) any evaluate |Python| expression
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01002789pyxeval({expr}) any evaluate |python_x| expression
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +01002790rand([{expr}]) Number get pseudo-random number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002791range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002792 List items from {expr} to {max}
Bram Moolenaarc423ad72021-01-13 20:38:03 +01002793readblob({fname}) Blob read a |Blob| from {fname}
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02002794readdir({dir} [, {expr} [, {dict}]])
2795 List file names in {dir} selected by {expr}
2796readdirex({dir} [, {expr} [, {dict}]])
2797 List file info in {dir} selected by {expr}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002798readfile({fname} [, {type} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002799 List get list of lines from file {fname}
Bram Moolenaar85629982020-06-01 18:39:20 +02002800reduce({object}, {func} [, {initial}])
2801 any reduce {object} using {func}
Bram Moolenaarf2732452018-06-03 14:47:35 +02002802reg_executing() String get the executing register name
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02002803reg_recording() String get the recording register name
Bram Moolenaar81edd172016-04-14 13:51:37 +02002804reltime([{start} [, {end}]]) List get time value
2805reltimefloat({time}) Float turn the time value into a Float
2806reltimestr({time}) String turn time value into a String
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002807remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002808 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002809remote_foreground({server}) Number bring Vim server to the foreground
2810remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002811 Number check for reply string
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002812remote_read({serverid} [, {timeout}])
2813 String read reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002814remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002815 String send key sequence
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01002816remote_startserver({name}) none become server {name}
Bram Moolenaar10455d42019-11-21 15:36:18 +01002817remove({list}, {idx} [, {end}]) any/List
Bram Moolenaar39536dd2019-01-29 22:58:21 +01002818 remove items {idx}-{end} from {list}
2819remove({blob}, {idx} [, {end}]) Number/Blob
2820 remove bytes {idx}-{end} from {blob}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002821remove({dict}, {key}) any remove entry {key} from {dict}
2822rename({from}, {to}) Number rename (move) file from {from} to {to}
2823repeat({expr}, {count}) String repeat {expr} {count} times
2824resolve({filename}) String get filename a shortcut points to
2825reverse({list}) List reverse {list} in-place
2826round({expr}) Float round off {expr}
Bram Moolenaare99be0e2019-03-26 22:51:09 +01002827rubyeval({expr}) any evaluate |Ruby| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002828screenattr({row}, {col}) Number attribute at screen position
2829screenchar({row}, {col}) Number character at screen position
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002830screenchars({row}, {col}) List List of characters at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002831screencol() Number current cursor column
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02002832screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002833screenrow() Number current cursor row
Bram Moolenaar2912abb2019-03-29 14:16:42 +01002834screenstring({row}, {col}) String characters at screen position
Bram Moolenaaradc17a52020-06-06 18:37:51 +02002835search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002836 Number search for {pattern}
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02002837searchcount([{options}]) Dict get or update search stats
Bram Moolenaar81edd172016-04-14 13:51:37 +02002838searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002839 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002840searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002841 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002842searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002843 List search for other end of start/end pair
Bram Moolenaaradc17a52020-06-06 18:37:51 +02002844searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002845 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002846server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002847 Number send reply string
2848serverlist() String get a list of available servers
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002849setbufline({expr}, {lnum}, {text})
2850 Number set line {lnum} to {text} in buffer
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02002851 {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002852setbufvar({expr}, {varname}, {val})
2853 none set {varname} in buffer {expr} to {val}
Bram Moolenaar08aac3c2020-08-28 21:04:24 +02002854setcellwidths({list}) none set character cell width overrides
Bram Moolenaar6f02b002021-01-10 20:22:54 +01002855setcharpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002856setcharsearch({dict}) Dict set character search from {dict}
2857setcmdpos({pos}) Number set cursor position in command-line
Bram Moolenaar6f02b002021-01-10 20:22:54 +01002858setcursorcharpos({list}) Number move cursor to position in {list}
Bram Moolenaar691ddee2019-05-09 14:52:41 +02002859setenv({name}, {val}) none set environment variable
Bram Moolenaar81edd172016-04-14 13:51:37 +02002860setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2861setline({lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaare46a4402020-06-30 20:38:27 +02002862setloclist({nr}, {list} [, {action}])
2863 Number modify location list using {list}
2864setloclist({nr}, {list}, {action}, {what})
2865 Number modify specific location list props
Bram Moolenaaraff74912019-03-30 18:11:49 +01002866setmatches({list} [, {win}]) Number restore a list of matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002867setpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaare46a4402020-06-30 20:38:27 +02002868setqflist({list} [, {action}]) Number modify quickfix list using {list}
2869setqflist({list}, {action}, {what})
2870 Number modify specific quickfix list props
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002871setreg({n}, {v} [, {opt}]) Number set register to value and type
Bram Moolenaar81edd172016-04-14 13:51:37 +02002872settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2873settabwinvar({tabnr}, {winnr}, {varname}, {val})
2874 none set {varname} in window {winnr} in tab
2875 page {tabnr} to {val}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002876settagstack({nr}, {dict} [, {action}])
2877 Number modify tag stack using {dict}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002878setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2879sha256({string}) String SHA256 checksum of {string}
2880shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002881 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002882 command argument
Bram Moolenaarf9514162018-11-22 03:08:29 +01002883shiftwidth([{col}]) Number effective value of 'shiftwidth'
Bram Moolenaar162b7142018-12-21 15:17:36 +01002884sign_define({name} [, {dict}]) Number define or update a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002885sign_define({list}) List define or update a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01002886sign_getdefined([{name}]) List get a list of defined signs
2887sign_getplaced([{expr} [, {dict}]])
2888 List get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01002889sign_jump({id}, {group}, {expr})
2890 Number jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01002891sign_place({id}, {group}, {name}, {expr} [, {dict}])
2892 Number place a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002893sign_placelist({list}) List place a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01002894sign_undefine([{name}]) Number undefine a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002895sign_undefine({list}) List undefine a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01002896sign_unplace({group} [, {dict}])
2897 Number unplace a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02002898sign_unplacelist({list}) List unplace a list of signs
Bram Moolenaar81edd172016-04-14 13:51:37 +02002899simplify({filename}) String simplify filename as much as possible
2900sin({expr}) Float sine of {expr}
2901sinh({expr}) Float hyperbolic sine of {expr}
Bram Moolenaar6601b622021-01-13 21:47:15 +01002902slice({expr}, {start} [, {end}]) String, List or Blob
2903 slice of a String, List or Blob
Bram Moolenaar81edd172016-04-14 13:51:37 +02002904sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002905 List sort {list}, using {func} to compare
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02002906sound_clear() none stop playing all sounds
Bram Moolenaar427f5b62019-06-09 13:43:51 +02002907sound_playevent({name} [, {callback}])
2908 Number play an event sound
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02002909sound_playfile({path} [, {callback}])
2910 Number play sound file {path}
Bram Moolenaar427f5b62019-06-09 13:43:51 +02002911sound_stop({id}) none stop playing sound {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002912soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002913spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002914spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002915 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002916split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002917 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002918sqrt({expr}) Float square root of {expr}
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +01002919srand([{expr}]) List get seed for |rand()|
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02002920state([{what}]) String current state of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002921str2float({expr}) Float convert String to Float
Bram Moolenaar9d401282019-04-06 13:18:12 +02002922str2list({expr} [, {utf8}]) List convert each character of {expr} to
2923 ASCII/UTF8 value
Bram Moolenaar60a8de22019-09-15 14:33:22 +02002924str2nr({expr} [, {base} [, {quoted}]])
2925 Number convert String to Number
Bram Moolenaar70ce8a12021-03-14 19:02:09 +01002926strcharlen({expr}) Number character length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002927strcharpart({str}, {start} [, {len}])
Bram Moolenaar6c53fca2020-08-23 17:34:46 +02002928 String {len} characters of {str} at
2929 character {start}
Bram Moolenaar70ce8a12021-03-14 19:02:09 +01002930strchars({expr} [, {skipcc}]) Number character count of the String {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002931strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaar10455d42019-11-21 15:36:18 +01002932strftime({format} [, {time}]) String format time with a specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002933strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002934stridx({haystack}, {needle} [, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002935 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002936string({expr}) String String representation of {expr} value
2937strlen({expr}) Number length of the String {expr}
Bram Moolenaar6c53fca2020-08-23 17:34:46 +02002938strpart({str}, {start} [, {len} [, {chars}]])
2939 String {len} bytes/chars of {str} at
2940 byte {start}
Bram Moolenaar10455d42019-11-21 15:36:18 +01002941strptime({format}, {timestring})
2942 Number Convert {timestring} to unix timestamp
Bram Moolenaar81edd172016-04-14 13:51:37 +02002943strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002944 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002945strtrans({expr}) String translate string to make it printable
2946strwidth({expr}) Number display cell length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002947submatch({nr} [, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002948 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002949substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002950 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar00f123a2018-08-21 20:28:54 +02002951swapinfo({fname}) Dict information about swap file {fname}
Bram Moolenaar110bd602018-09-16 18:46:59 +02002952swapname({expr}) String swap file of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002953synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2954synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002955 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002956synIDtrans({synID}) Number translated syntax ID of {synID}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002957synconcealed({lnum}, {col}) List info about concealing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002958synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2959system({expr} [, {input}]) String output of shell command/filter {expr}
2960systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002961tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002962tabpagenr([{arg}]) Number number of current or last tab page
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002963tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
Bram Moolenaar446cb832008-06-24 21:56:24 +00002964tagfiles() List tags files used
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002965taglist({expr} [, {filename}]) List list of tags matching {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002966tan({expr}) Float tangent of {expr}
2967tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002968tempname() String name for a temporary file
Bram Moolenaard96ff162018-02-18 22:13:29 +01002969term_dumpdiff({filename}, {filename} [, {options}])
2970 Number display difference between two dumps
2971term_dumpload({filename} [, {options}])
2972 Number displaying a screen dump
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01002973term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01002974 none dump terminal window contents
Bram Moolenaare41e3b42017-08-11 16:24:50 +02002975term_getaltscreen({buf}) Number get the alternate screen flag
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002976term_getansicolors({buf}) List get ANSI palette in GUI color mode
Bram Moolenaar45356542017-08-06 17:53:31 +02002977term_getattr({attr}, {what}) Number get the value of attribute {what}
Bram Moolenaar97870002017-07-30 18:28:38 +02002978term_getcursor({buf}) List get the cursor position of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002979term_getjob({buf}) Job get the job associated with a terminal
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002980term_getline({buf}, {row}) String get a line of text from a terminal
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02002981term_getscrolled({buf}) Number get the scroll count of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002982term_getsize({buf}) List get the size of a terminal
Bram Moolenaarb000e322017-07-30 19:38:21 +02002983term_getstatus({buf}) String get the status of a terminal
2984term_gettitle({buf}) String get the title of a terminal
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002985term_gettty({buf}, [{input}]) String get the tty name of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002986term_list() List get the list of terminal buffers
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002987term_scrape({buf}, {row}) List get row of a terminal screen
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002988term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002989term_setansicolors({buf}, {colors})
2990 none set ANSI palette in GUI color mode
Bram Moolenaarebacddb2020-06-04 15:22:21 +02002991term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002992term_setkill({buf}, {how}) none set signal to stop job in terminal
Bram Moolenaarb5b75622018-03-09 22:22:21 +01002993term_setrestore({buf}, {command}) none set command to restore terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002994term_setsize({buf}, {rows}, {cols})
2995 none set the size of a terminal
Bram Moolenaar911ead12019-04-21 00:03:35 +02002996term_start({cmd} [, {options}]) Number open a terminal window and run a job
Bram Moolenaarf3402b12017-08-06 19:07:08 +02002997term_wait({buf} [, {time}]) Number wait for screen to be updated
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +02002998terminalprops() Dict properties of the terminal
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002999test_alloc_fail({id}, {countdown}, {repeat})
3000 none make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02003001test_autochdir() none enable 'autochdir' during startup
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003002test_feedinput({string}) none add key sequence to input buffer
Bram Moolenaar574860b2016-05-24 17:33:34 +02003003test_garbagecollect_now() none free memory right now for testing
Bram Moolenaaradc67142019-06-22 01:40:42 +02003004test_garbagecollect_soon() none free memory soon for testing
Bram Moolenaareda65222019-05-16 20:29:44 +02003005test_getvalue({string}) any get value of an internal variable
Bram Moolenaare0c31f62017-03-01 15:07:05 +01003006test_ignore_error({expr}) none ignore a specific error
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01003007test_null_blob() Blob null value for testing
Bram Moolenaar574860b2016-05-24 17:33:34 +02003008test_null_channel() Channel null value for testing
3009test_null_dict() Dict null value for testing
Bram Moolenaare69f6d02020-04-01 22:11:01 +02003010test_null_function() Funcref null value for testing
Bram Moolenaar574860b2016-05-24 17:33:34 +02003011test_null_job() Job null value for testing
3012test_null_list() List null value for testing
3013test_null_partial() Funcref null value for testing
3014test_null_string() String null value for testing
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02003015test_option_not_set({name}) none reset flag indicating option was set
3016test_override({expr}, {val}) none test with Vim internal overrides
Bram Moolenaarc3e92c12019-03-23 14:23:07 +01003017test_refcount({expr}) Number get the reference count of {expr}
Bram Moolenaarab186732018-09-14 21:27:06 +02003018test_scrollbar({which}, {value}, {dragging})
3019 none scroll in the GUI for testing
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02003020test_setmouse({row}, {col}) none set the mouse position for testing
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003021test_settime({expr}) none set current time for testing
Bram Moolenaarebacddb2020-06-04 15:22:21 +02003022test_srand_seed([seed]) none set seed for testing srand()
3023test_unknown() any unknown value for testing
3024test_void() any void value for testing
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02003025timer_info([{id}]) List information about timers
Bram Moolenaarb73598e2016-08-07 18:22:53 +02003026timer_pause({id}, {pause}) none pause or unpause a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02003027timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01003028 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02003029timer_stop({timer}) none stop a timer
Bram Moolenaarb73598e2016-08-07 18:22:53 +02003030timer_stopall() none stop all timers
Bram Moolenaar81edd172016-04-14 13:51:37 +02003031tolower({expr}) String the String {expr} switched to lowercase
3032toupper({expr}) String the String {expr} switched to uppercase
3033tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00003034 to chars in {tostr}
Bram Moolenaar2245ae12020-05-31 22:20:36 +02003035trim({text} [, {mask} [, {dir}]])
3036 String trim characters in {mask} from {text}
Bram Moolenaar81edd172016-04-14 13:51:37 +02003037trunc({expr}) Float truncate Float {expr}
Bram Moolenaara47e05f2021-01-12 21:49:00 +01003038type({expr}) Number type of value {expr}
3039typename({expr}) String representation of the type of {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02003040undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02003041undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02003042uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01003043 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02003044values({dict}) List values in {dict}
3045virtcol({expr}) Number screen column of cursor or mark
3046visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01003047wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar868b7b62019-05-29 21:44:40 +02003048win_execute({id}, {command} [, {silent}])
3049 String execute {command} in window {id}
Bram Moolenaar81edd172016-04-14 13:51:37 +02003050win_findbuf({bufnr}) List find windows containing {bufnr}
3051win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02003052win_gettype([{nr}]) String type of window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02003053win_gotoid({expr}) Number go to window with ID {expr}
3054win_id2tabwin({expr}) List get tab and window nr from window ID
3055win_id2win({expr}) Number get window nr from window ID
Bram Moolenaar22044dc2017-12-02 15:43:37 +01003056win_screenpos({nr}) List get screen position of window {nr}
Bram Moolenaard20dcb32019-09-10 21:22:58 +02003057win_splitmove({nr}, {target} [, {options}])
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003058 Number move window {nr} to split of {target}
Bram Moolenaar81edd172016-04-14 13:51:37 +02003059winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003060wincol() Number window column of the cursor
Bram Moolenaar388a5d42020-05-26 21:20:45 +02003061windowsversion() String MS-Windows OS version
Bram Moolenaar81edd172016-04-14 13:51:37 +02003062winheight({nr}) Number height of window {nr}
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +02003063winlayout([{tabnr}]) List layout of windows in tab {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003064winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02003065winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003066winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02003067winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00003068winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02003069winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01003070wordcount() Dict get byte/char/word statistics
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003071writefile({object}, {fname} [, {flags}])
3072 Number write |Blob| or |List| of lines to file
Bram Moolenaara06ecab2016-07-16 14:47:36 +02003073xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00003074
Bram Moolenaar03413f42016-04-12 21:07:15 +02003075
Bram Moolenaar446cb832008-06-24 21:56:24 +00003076abs({expr}) *abs()*
3077 Return the absolute value of {expr}. When {expr} evaluates to
3078 a |Float| abs() returns a |Float|. When {expr} can be
3079 converted to a |Number| abs() returns a |Number|. Otherwise
3080 abs() gives an error message and returns -1.
3081 Examples: >
3082 echo abs(1.456)
3083< 1.456 >
3084 echo abs(-5.456)
3085< 5.456 >
3086 echo abs(-4)
3087< 4
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003088
3089 Can also be used as a |method|: >
3090 Compute()->abs()
3091
3092< {only available when compiled with the |+float| feature}
Bram Moolenaar446cb832008-06-24 21:56:24 +00003093
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003094
3095acos({expr}) *acos()*
3096 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003097 |Float| in the range of [0, pi].
3098 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003099 [-1, 1].
3100 Examples: >
3101 :echo acos(0)
3102< 1.570796 >
3103 :echo acos(-0.5)
3104< 2.094395
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003105
3106 Can also be used as a |method|: >
3107 Compute()->acos()
3108
3109< {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003110
3111
Bram Moolenaard8968242019-01-15 22:51:57 +01003112add({object}, {expr}) *add()*
3113 Append the item {expr} to |List| or |Blob| {object}. Returns
3114 the resulting |List| or |Blob|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003115 :let alist = add([1, 2, 3], item)
3116 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003117< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003118 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard8968242019-01-15 22:51:57 +01003119 When {object} is a |Blob| then {expr} must be a number.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003120 Use |insert()| to add an item at another position.
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003121
Bram Moolenaarac92e252019-08-03 21:58:38 +02003122 Can also be used as a |method|: >
3123 mylist->add(val1)->add(val2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003124
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003125
Bram Moolenaard6e256c2011-12-14 15:32:50 +01003126and({expr}, {expr}) *and()*
3127 Bitwise AND on the two arguments. The arguments are converted
3128 to a number. A List, Dict or Float argument causes an error.
3129 Example: >
3130 :let flag = and(bits, 0x80)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003131< Can also be used as a |method|: >
3132 :let flag = bits->and(0x80)
Bram Moolenaard6e256c2011-12-14 15:32:50 +01003133
3134
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003135append({lnum}, {text}) *append()*
3136 When {text} is a |List|: Append each item of the |List| as a
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003137 text line below line {lnum} in the current buffer.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003138 Otherwise append {text} as one text line below line {lnum} in
Bram Moolenaar748bf032005-02-02 23:04:36 +00003139 the current buffer.
Bram Moolenaar34453202021-01-31 13:08:38 +01003140 Any type of item is accepted and converted to a String.
Bram Moolenaar748bf032005-02-02 23:04:36 +00003141 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003142 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar58b85342016-08-14 19:54:54 +02003143 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003144 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003145 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaarca851592018-06-06 21:04:07 +02003146
Bram Moolenaar7ff78462020-07-10 22:00:53 +02003147< Can also be used as a |method| after a List, the base is
3148 passed as the second argument: >
Bram Moolenaar25e42232019-08-04 15:04:10 +02003149 mylist->append(lnum)
3150
3151
Bram Moolenaarca851592018-06-06 21:04:07 +02003152appendbufline({expr}, {lnum}, {text}) *appendbufline()*
3153 Like |append()| but append the text in buffer {expr}.
3154
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003155 This function works only for loaded buffers. First call
3156 |bufload()| if needed.
3157
Bram Moolenaarca851592018-06-06 21:04:07 +02003158 For the use of {expr}, see |bufname()|.
3159
3160 {lnum} is used like with |append()|. Note that using |line()|
3161 would use the current buffer, not the one appending to.
3162 Use "$" to append at the end of the buffer.
3163
3164 On success 0 is returned, on failure 1 is returned.
3165
3166 If {expr} is not a valid buffer or {lnum} is not valid, an
3167 error message is given. Example: >
3168 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003169<
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01003170 Can also be used as a |method| after a List, the base is
Bram Moolenaar7ff78462020-07-10 22:00:53 +02003171 passed as the second argument: >
Bram Moolenaar25e42232019-08-04 15:04:10 +02003172 mylist->appendbufline(buf, lnum)
3173
3174
3175argc([{winid}]) *argc()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02003176 The result is the number of files in the argument list. See
3177 |arglist|.
3178 If {winid} is not supplied, the argument list of the current
3179 window is used.
3180 If {winid} is -1, the global argument list is used.
3181 Otherwise {winid} specifies the window of which the argument
3182 list is used: either the window number or the window ID.
3183 Returns -1 if the {winid} argument is invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003184
3185 *argidx()*
3186argidx() The result is the current index in the argument list. 0 is
3187 the first file. argc() - 1 is the last one. See |arglist|.
3188
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003189 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003190arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003191 Return the argument list ID. This is a number which
3192 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02003193 global argument list. See |arglist|.
Bram Moolenaare6e39892018-10-25 12:32:11 +02003194 Returns -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003195
3196 Without arguments use the current window.
3197 With {winnr} only use this window in the current tab page.
3198 With {winnr} and {tabnr} use the window in the specified tab
3199 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02003200 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02003201
Bram Moolenaar071d4272004-06-13 20:20:40 +00003202 *argv()*
Bram Moolenaar7ceefb32020-05-01 16:07:38 +02003203argv([{nr} [, {winid}]])
Bram Moolenaare6e39892018-10-25 12:32:11 +02003204 The result is the {nr}th file in the argument list. See
3205 |arglist|. "argv(0)" is the first one. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003206 :let i = 0
3207 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00003208 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00003209 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
3210 : let i = i + 1
3211 :endwhile
Bram Moolenaare6e39892018-10-25 12:32:11 +02003212< Without the {nr} argument, or when {nr} is -1, a |List| with
3213 the whole |arglist| is returned.
3214
3215 The {winid} argument specifies the window ID, see |argc()|.
Bram Moolenaar69bf6342019-10-29 04:16:57 +01003216 For the Vim command line arguments see |v:argv|.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00003217
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003218asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003219 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003220 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003221 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003222 [-1, 1].
3223 Examples: >
3224 :echo asin(0.8)
3225< 0.927295 >
3226 :echo asin(-0.5)
3227< -0.523599
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003228
3229 Can also be used as a |method|: >
3230 Compute()->asin()
3231<
Bram Moolenaardb84e452010-08-15 13:50:43 +02003232 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003233
3234
Bram Moolenaar29634562020-01-09 21:46:04 +01003235assert_ functions are documented here: |assert-functions-details|
3236
3237
3238
Bram Moolenaar446cb832008-06-24 21:56:24 +00003239atan({expr}) *atan()*
3240 Return the principal value of the arc tangent of {expr}, in
3241 the range [-pi/2, +pi/2] radians, as a |Float|.
3242 {expr} must evaluate to a |Float| or a |Number|.
3243 Examples: >
3244 :echo atan(100)
3245< 1.560797 >
3246 :echo atan(-4.01)
3247< -1.326405
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003248
3249 Can also be used as a |method|: >
3250 Compute()->atan()
3251<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003252 {only available when compiled with the |+float| feature}
3253
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003254
3255atan2({expr1}, {expr2}) *atan2()*
3256 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003257 radians, as a |Float| in the range [-pi, pi].
3258 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003259 Examples: >
3260 :echo atan2(-1, 1)
3261< -0.785398 >
3262 :echo atan2(1, -1)
3263< 2.356194
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003264
3265 Can also be used as a |method|: >
3266 Compute()->atan(1)
3267<
Bram Moolenaardb84e452010-08-15 13:50:43 +02003268 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003269
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003270balloon_gettext() *balloon_gettext()*
3271 Return the current text in the balloon. Only for the string,
3272 not used for the List.
3273
Bram Moolenaar246fe032017-11-19 19:56:27 +01003274balloon_show({expr}) *balloon_show()*
3275 Show {expr} inside the balloon. For the GUI {expr} is used as
3276 a string. For a terminal {expr} can be a list, which contains
3277 the lines of the balloon. If {expr} is not a list it will be
3278 split with |balloon_split()|.
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003279 If {expr} is an empty string any existing balloon is removed.
Bram Moolenaar246fe032017-11-19 19:56:27 +01003280
Bram Moolenaar214641f2017-03-05 17:04:09 +01003281 Example: >
Bram Moolenaar59716a22017-03-01 20:32:44 +01003282 func GetBalloonContent()
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02003283 " ... initiate getting the content
Bram Moolenaar59716a22017-03-01 20:32:44 +01003284 return ''
3285 endfunc
3286 set balloonexpr=GetBalloonContent()
3287
3288 func BalloonCallback(result)
Bram Moolenaar214641f2017-03-05 17:04:09 +01003289 call balloon_show(a:result)
Bram Moolenaar59716a22017-03-01 20:32:44 +01003290 endfunc
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003291< Can also be used as a |method|: >
3292 GetText()->balloon_show()
Bram Moolenaar59716a22017-03-01 20:32:44 +01003293<
3294 The intended use is that fetching the content of the balloon
3295 is initiated from 'balloonexpr'. It will invoke an
3296 asynchronous method, in which a callback invokes
3297 balloon_show(). The 'balloonexpr' itself can return an
3298 empty string or a placeholder.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003299
3300 When showing a balloon is not possible nothing happens, no
3301 error message.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003302 {only available when compiled with the |+balloon_eval| or
3303 |+balloon_eval_term| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003304
Bram Moolenaar246fe032017-11-19 19:56:27 +01003305balloon_split({msg}) *balloon_split()*
3306 Split {msg} into lines to be displayed in a balloon. The
3307 splits are made for the current window size and optimize to
3308 show debugger output.
3309 Returns a |List| with the split lines.
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003310 Can also be used as a |method|: >
3311 GetText()->balloon_split()->balloon_show()
3312
3313< {only available when compiled with the |+balloon_eval_term|
Bram Moolenaar669a8282017-11-19 20:13:05 +01003314 feature}
Bram Moolenaar246fe032017-11-19 19:56:27 +01003315
Bram Moolenaar071d4272004-06-13 20:20:40 +00003316 *browse()*
3317browse({save}, {title}, {initdir}, {default})
3318 Put up a file requester. This only works when "has("browse")"
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003319 returns |TRUE| (only in some GUI versions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003320 The input fields are:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003321 {save} when |TRUE|, select file to write
Bram Moolenaar071d4272004-06-13 20:20:40 +00003322 {title} title for the requester
3323 {initdir} directory to start browsing in
3324 {default} default file name
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003325 An empty string is returned when the "Cancel" button is hit,
3326 something went wrong, or browsing is not possible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003327
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003328 *browsedir()*
3329browsedir({title}, {initdir})
3330 Put up a directory requester. This only works when
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003331 "has("browse")" returns |TRUE| (only in some GUI versions).
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003332 On systems where a directory browser is not supported a file
3333 browser is used. In that case: select a file in the directory
3334 to be used.
3335 The input fields are:
3336 {title} title for the requester
3337 {initdir} directory to start browsing in
3338 When the "Cancel" button is hit, something went wrong, or
3339 browsing is not possible, an empty string is returned.
3340
Bram Moolenaar15e248e2019-06-30 20:21:37 +02003341bufadd({name}) *bufadd()*
3342 Add a buffer to the buffer list with {name}.
3343 If a buffer for file {name} already exists, return that buffer
3344 number. Otherwise return the buffer number of the newly
3345 created buffer. When {name} is an empty string then a new
3346 buffer is always created.
Bram Moolenaaraad222c2019-09-06 22:46:09 +02003347 The buffer will not have 'buflisted' set and not be loaded
Bram Moolenaar5ca1ac32019-07-04 15:39:28 +02003348 yet. To add some text to the buffer use this: >
3349 let bufnr = bufadd('someName')
3350 call bufload(bufnr)
3351 call setbufline(bufnr, 1, ['some', 'text'])
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003352< Can also be used as a |method|: >
3353 let bufnr = 'somename'->bufadd()
Bram Moolenaar15e248e2019-06-30 20:21:37 +02003354
Bram Moolenaar071d4272004-06-13 20:20:40 +00003355bufexists({expr}) *bufexists()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003356 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003357 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003358 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaara2a80162017-11-21 23:09:50 +01003359 Number zero is the alternate buffer for the current window.
3360
Bram Moolenaar071d4272004-06-13 20:20:40 +00003361 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003362 exactly. The name can be:
3363 - Relative to the current directory.
3364 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003365 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003366 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003367 Unlisted buffers will be found.
3368 Note that help files are listed by their short name in the
3369 output of |:buffers|, but bufexists() requires using their
3370 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003371 bufexists() may report a buffer exists, but to use the name
3372 with a |:buffer| command you may need to use |expand()|. Esp
3373 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003374 Use "bufexists(0)" to test for the existence of an alternate
3375 file name.
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003376
3377 Can also be used as a |method|: >
3378 let exists = 'somename'->bufexists()
3379<
3380 Obsolete name: buffer_exists(). *buffer_exists()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003381
3382buflisted({expr}) *buflisted()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003383 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003384 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003385 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003386
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003387 Can also be used as a |method|: >
3388 let listed = 'somename'->buflisted()
3389
Bram Moolenaar15e248e2019-06-30 20:21:37 +02003390bufload({expr}) *bufload()*
3391 Ensure the buffer {expr} is loaded. When the buffer name
3392 refers to an existing file then the file is read. Otherwise
3393 the buffer will be empty. If the buffer was already loaded
3394 then there is no change.
3395 If there is an existing swap file for the file of the buffer,
3396 there will be no dialog, the buffer will be loaded anyway.
3397 The {expr} argument is used like with |bufexists()|.
3398
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003399 Can also be used as a |method|: >
3400 eval 'somename'->bufload()
3401
Bram Moolenaar071d4272004-06-13 20:20:40 +00003402bufloaded({expr}) *bufloaded()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003403 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003404 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003405 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003406
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003407 Can also be used as a |method|: >
3408 let loaded = 'somename'->bufloaded()
3409
Bram Moolenaara8eee212019-08-24 22:14:58 +02003410bufname([{expr}]) *bufname()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003411 The result is the name of a buffer, as it is displayed by the
3412 ":ls" command.
Bram Moolenaara8eee212019-08-24 22:14:58 +02003413 If {expr} is omitted the current buffer is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003414 If {expr} is a Number, that buffer number's name is given.
3415 Number zero is the alternate buffer for the current window.
3416 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar58b85342016-08-14 19:54:54 +02003417 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003418 set and 'cpoptions' is empty. When there is more than one
3419 match an empty string is returned.
3420 "" or "%" can be used for the current buffer, "#" for the
3421 alternate buffer.
3422 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003423 or middle of the buffer name is accepted. If you only want a
3424 full match then put "^" at the start and "$" at the end of the
3425 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003426 Listed buffers are found first. If there is a single match
3427 with a listed buffer, that one is returned. Next unlisted
3428 buffers are searched for.
3429 If the {expr} is a String, but you want to use it as a buffer
3430 number, force it to be a Number by adding zero to it: >
3431 :echo bufname("3" + 0)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003432< Can also be used as a |method|: >
3433 echo bufnr->bufname()
3434
Bram Moolenaar071d4272004-06-13 20:20:40 +00003435< If the buffer doesn't exist, or doesn't have a name, an empty
3436 string is returned. >
3437 bufname("#") alternate buffer name
3438 bufname(3) name of buffer 3
3439 bufname("%") name of current buffer
3440 bufname("file2") name of buffer where "file2" matches.
3441< *buffer_name()*
3442 Obsolete name: buffer_name().
3443
3444 *bufnr()*
Bram Moolenaara8eee212019-08-24 22:14:58 +02003445bufnr([{expr} [, {create}]])
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003446 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00003447 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003448 above.
Bram Moolenaard2842ea2019-09-26 23:08:54 +02003449
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003450 If the buffer doesn't exist, -1 is returned. Or, if the
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02003451 {create} argument is present and TRUE, a new, unlisted,
Bram Moolenaard2842ea2019-09-26 23:08:54 +02003452 buffer is created and its number is returned. Example: >
3453 let newbuf = bufnr('Scratch001', 1)
3454< Using an empty name uses the current buffer. To create a new
3455 buffer with an empty name use |bufadd()|.
3456
Bram Moolenaar071d4272004-06-13 20:20:40 +00003457 bufnr("$") is the last buffer: >
Bram Moolenaara8eee212019-08-24 22:14:58 +02003458 :let last_buffer = bufnr("$")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003459< The result is a Number, which is the highest buffer number
3460 of existing buffers. Note that not all buffers with a smaller
3461 number necessarily exist, because ":bwipeout" may have removed
3462 them. Use bufexists() to test for the existence of a buffer.
Bram Moolenaar073e4b92019-08-18 23:01:56 +02003463
3464 Can also be used as a |method|: >
3465 echo bufref->bufnr()
3466<
3467 Obsolete name: buffer_number(). *buffer_number()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003468 *last_buffer_nr()*
3469 Obsolete name for bufnr("$"): last_buffer_nr().
3470
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003471bufwinid({expr}) *bufwinid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02003472 The result is a Number, which is the |window-ID| of the first
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003473 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003474 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003475 there is no such window, -1 is returned. Example: >
3476
3477 echo "A window containing buffer 1 is " . (bufwinid(1))
3478<
3479 Only deals with the current tab page.
3480
Bram Moolenaare49fbff2019-08-21 22:50:07 +02003481 Can also be used as a |method|: >
3482 FindBuffer()->bufwinid()
3483
Bram Moolenaar071d4272004-06-13 20:20:40 +00003484bufwinnr({expr}) *bufwinnr()*
Bram Moolenaare49fbff2019-08-21 22:50:07 +02003485 Like |bufwinid()| but return the window number instead of the
3486 |window-ID|.
3487 If buffer {expr} doesn't exist or there is no such window, -1
3488 is returned. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003489
3490 echo "A window containing buffer 1 is " . (bufwinnr(1))
3491
3492< The number can be used with |CTRL-W_w| and ":wincmd w"
3493 |:wincmd|.
Bram Moolenaare49fbff2019-08-21 22:50:07 +02003494
3495 Can also be used as a |method|: >
3496 FindBuffer()->bufwinnr()
Bram Moolenaar071d4272004-06-13 20:20:40 +00003497
Bram Moolenaar071d4272004-06-13 20:20:40 +00003498byte2line({byte}) *byte2line()*
3499 Return the line number that contains the character at byte
3500 count {byte} in the current buffer. This includes the
3501 end-of-line character, depending on the 'fileformat' option
3502 for the current buffer. The first character has byte count
3503 one.
3504 Also see |line2byte()|, |go| and |:goto|.
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003505
3506 Can also be used as a |method|: >
3507 GetOffset()->byte2line()
3508
3509< {not available when compiled without the |+byte_offset|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003510 feature}
3511
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003512byteidx({expr}, {nr}) *byteidx()*
3513 Return byte index of the {nr}'th character in the string
Bram Moolenaar6c53fca2020-08-23 17:34:46 +02003514 {expr}. Use zero for the first character, it then returns
3515 zero.
Bram Moolenaar4466ad62020-11-21 13:16:30 +01003516 If there are no multibyte characters the returned value is
3517 equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003518 Composing characters are not counted separately, their byte
3519 length is added to the preceding base character. See
3520 |byteidxcomp()| below for counting composing characters
3521 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003522 Example : >
3523 echo matchstr(str, ".", byteidx(str, 3))
3524< will display the fourth character. Another way to do the
3525 same: >
3526 let s = strpart(str, byteidx(str, 3))
3527 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003528< Also see |strgetchar()| and |strcharpart()|.
3529
3530 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003531 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003532 in bytes is returned.
3533
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003534 Can also be used as a |method|: >
3535 GetName()->byteidx(idx)
3536
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003537byteidxcomp({expr}, {nr}) *byteidxcomp()*
3538 Like byteidx(), except that a composing character is counted
3539 as a separate character. Example: >
3540 let s = 'e' . nr2char(0x301)
3541 echo byteidx(s, 1)
3542 echo byteidxcomp(s, 1)
3543 echo byteidxcomp(s, 2)
3544< The first and third echo result in 3 ('e' plus composing
3545 character is 3 bytes), the second echo results in 1 ('e' is
3546 one byte).
Bram Moolenaar6f02b002021-01-10 20:22:54 +01003547 Only works differently from byteidx() when 'encoding' is set
3548 to a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003549
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003550 Can also be used as a |method|: >
3551 GetName()->byteidxcomp(idx)
3552
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003553call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003554 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003555 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003556 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003557 a:firstline and a:lastline are set to the cursor line.
3558 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003559 {dict} is for functions with the "dict" attribute. It will be
3560 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003561
Bram Moolenaar64b4d732019-08-22 22:18:17 +02003562 Can also be used as a |method|: >
3563 GetFunc()->call([arg, arg], dict)
3564
Bram Moolenaar446cb832008-06-24 21:56:24 +00003565ceil({expr}) *ceil()*
3566 Return the smallest integral value greater than or equal to
3567 {expr} as a |Float| (round up).
3568 {expr} must evaluate to a |Float| or a |Number|.
3569 Examples: >
3570 echo ceil(1.456)
3571< 2.0 >
3572 echo ceil(-5.456)
3573< -5.0 >
3574 echo ceil(4.0)
3575< 4.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003576
3577 Can also be used as a |method|: >
3578 Compute()->ceil()
3579<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003580 {only available when compiled with the |+float| feature}
3581
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003582
Bram Moolenaared997ad2019-07-21 16:42:00 +02003583ch_ functions are documented here: |channel-functions-details|
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02003584
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003585
Bram Moolenaar214641f2017-03-05 17:04:09 +01003586changenr() *changenr()*
3587 Return the number of the most recent change. This is the same
3588 number as what is displayed with |:undolist| and can be used
3589 with the |:undo| command.
3590 When a change was made it is the number of that change. After
3591 redo it is the number of the redone change. After undo it is
3592 one less than the number of the undone change.
3593
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003594char2nr({expr} [, {utf8}]) *char2nr()*
Bram Moolenaar214641f2017-03-05 17:04:09 +01003595 Return number value of the first char in {expr}. Examples: >
3596 char2nr(" ") returns 32
3597 char2nr("ABC") returns 65
3598< When {utf8} is omitted or zero, the current 'encoding' is used.
3599 Example for "utf-8": >
Bram Moolenaar98ef2332018-03-18 14:44:37 +01003600 char2nr("á") returns 225
3601 char2nr("á"[0]) returns 195
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02003602< With {utf8} set to TRUE, always treat as utf-8 characters.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003603 A combining character is a separate character.
3604 |nr2char()| does the opposite.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003605 To turn a string into a list of character numbers: >
3606 let str = "ABC"
3607 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
3608< Result: [65, 66, 67]
Bram Moolenaar214641f2017-03-05 17:04:09 +01003609
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003610 Can also be used as a |method|: >
3611 GetChar()->char2nr()
3612
Bram Moolenaar4e4473c2020-08-28 22:24:57 +02003613
3614charclass({string}) *charclass()*
3615 Return the character class of the first character in {string}.
3616 The character class is one of:
3617 0 blank
3618 1 punctuation
3619 2 word character
3620 3 emoji
3621 other specific Unicode class
3622 The class is used in patterns and word motions.
3623
Bram Moolenaar6f02b002021-01-10 20:22:54 +01003624 *charcol()*
3625charcol({expr}) Same as |col()| but returns the character index of the column
3626 position given with {expr} instead of the byte position.
3627
3628 Example:
3629 With the cursor on '세' in line 5 with text "여보세요": >
3630 charcol('.') returns 3
3631 col('.') returns 7
3632
3633< Can also be used as a |method|: >
3634 GetPos()->col()
3635<
Bram Moolenaar17793ef2020-12-28 12:56:58 +01003636 *charidx()*
3637charidx({string}, {idx} [, {countcc}])
3638 Return the character index of the byte at {idx} in {string}.
3639 The index of the first character is zero.
3640 If there are no multibyte characters the returned value is
3641 equal to {idx}.
3642 When {countcc} is omitted or zero, then composing characters
3643 are not counted separately, their byte length is added to the
3644 preceding base character.
3645 When {countcc} is set to 1, then composing characters are
3646 counted as separate characters.
3647 Returns -1 if the arguments are invalid or if {idx} is greater
3648 than the index of the last byte in {string}. An error is
3649 given if the first argument is not a string, the second
3650 argument is not a number or when the third argument is present
3651 and is not zero or one.
3652 See |byteidx()| and |byteidxcomp()| for getting the byte index
3653 from the character index.
3654 Examples: >
3655 echo charidx('áb́ć', 3) returns 1
3656 echo charidx('áb́ć', 6, 1) returns 4
3657 echo charidx('áb́ć', 16) returns -1
3658<
3659 Can also be used as a |method|: >
3660 GetName()->charidx(idx)
Bram Moolenaar4e4473c2020-08-28 22:24:57 +02003661
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003662chdir({dir}) *chdir()*
3663 Change the current working directory to {dir}. The scope of
3664 the directory change depends on the directory of the current
3665 window:
3666 - If the current window has a window-local directory
3667 (|:lcd|), then changes the window local directory.
3668 - Otherwise, if the current tabpage has a local
3669 directory (|:tcd|) then changes the tabpage local
3670 directory.
3671 - Otherwise, changes the global directory.
Bram Moolenaar560979e2020-02-04 22:53:05 +01003672 {dir} must be a String.
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003673 If successful, returns the previous working directory. Pass
3674 this to another chdir() to restore the directory.
3675 On failure, returns an empty string.
3676
3677 Example: >
3678 let save_dir = chdir(newdir)
Bram Moolenaar68e65602019-05-26 21:33:31 +02003679 if save_dir != ""
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003680 " ... do some work
3681 call chdir(save_dir)
3682 endif
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003683
3684< Can also be used as a |method|: >
3685 GetDir()->chdir()
Bram Moolenaar1063f3d2019-05-07 22:06:52 +02003686<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003687cindent({lnum}) *cindent()*
3688 Get the amount of indent for line {lnum} according the C
3689 indenting rules, as with 'cindent'.
3690 The indent is counted in spaces, the value of 'tabstop' is
3691 relevant. {lnum} is used just like in |getline()|.
3692 When {lnum} is invalid or Vim was not compiled the |+cindent|
3693 feature, -1 is returned.
3694 See |C-indenting|.
3695
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003696 Can also be used as a |method|: >
3697 GetLnum()->cindent()
3698
Bram Moolenaaraff74912019-03-30 18:11:49 +01003699clearmatches([{win}]) *clearmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01003700 Clears all matches previously defined for the current window
3701 by |matchadd()| and the |:match| commands.
Bram Moolenaaraff74912019-03-30 18:11:49 +01003702 If {win} is specified, use the window with this number or
3703 window ID instead of the current window.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003704
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003705 Can also be used as a |method|: >
3706 GetWin()->clearmatches()
3707<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003708 *col()*
3709col({expr}) The result is a Number, which is the byte index of the column
3710 position given with {expr}. The accepted positions are:
3711 . the cursor position
3712 $ the end of the cursor line (the result is the
3713 number of bytes in the cursor line plus one)
3714 'x position of mark x (if the mark is not set, 0 is
3715 returned)
3716 v In Visual mode: the start of the Visual area (the
3717 cursor is the end). When not in Visual mode
3718 returns the cursor position. Differs from |'<| in
3719 that it's updated right away.
3720 Additionally {expr} can be [lnum, col]: a |List| with the line
3721 and column number. Most useful when the column is "$", to get
3722 the last column of a specific line. When "lnum" or "col" is
3723 out of range then col() returns zero.
3724 To get the line number use |line()|. To get both use
3725 |getpos()|.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01003726 For the screen column position use |virtcol()|. For the
3727 character position use |charcol()|.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003728 Note that only marks in the current file can be used.
3729 Examples: >
3730 col(".") column of cursor
3731 col("$") length of cursor line plus one
3732 col("'t") column of mark t
3733 col("'" . markname) column of mark markname
3734< The first column is 1. 0 is returned for an error.
3735 For an uppercase mark the column may actually be in another
3736 buffer.
3737 For the cursor position, when 'virtualedit' is active, the
3738 column is one higher if the cursor is after the end of the
3739 line. This can be used to obtain the column in Insert mode: >
3740 :imap <F2> <C-O>:let save_ve = &ve<CR>
3741 \<C-O>:set ve=all<CR>
3742 \<C-O>:echo col(".") . "\n" <Bar>
3743 \let &ve = save_ve<CR>
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003744
3745< Can also be used as a |method|: >
3746 GetPos()->col()
Bram Moolenaar214641f2017-03-05 17:04:09 +01003747<
3748
3749complete({startcol}, {matches}) *complete()* *E785*
3750 Set the matches for Insert mode completion.
3751 Can only be used in Insert mode. You need to use a mapping
3752 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3753 or with an expression mapping.
3754 {startcol} is the byte offset in the line where the completed
3755 text start. The text up to the cursor is the original text
3756 that will be replaced by the matches. Use col('.') for an
3757 empty string. "col('.') - 1" will replace one character by a
3758 match.
3759 {matches} must be a |List|. Each |List| item is one match.
3760 See |complete-items| for the kind of items that are possible.
3761 Note that the after calling this function you need to avoid
3762 inserting anything that would cause completion to stop.
3763 The match can be selected with CTRL-N and CTRL-P as usual with
3764 Insert mode completion. The popup menu will appear if
3765 specified, see |ins-completion-menu|.
3766 Example: >
3767 inoremap <F5> <C-R>=ListMonths()<CR>
3768
3769 func! ListMonths()
3770 call complete(col('.'), ['January', 'February', 'March',
3771 \ 'April', 'May', 'June', 'July', 'August', 'September',
3772 \ 'October', 'November', 'December'])
3773 return ''
3774 endfunc
3775< This isn't very useful, but it shows how it works. Note that
3776 an empty string is returned to avoid a zero being inserted.
3777
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003778 Can also be used as a |method|, the base is passed as the
3779 second argument: >
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003780 GetMatches()->complete(col('.'))
3781
Bram Moolenaar214641f2017-03-05 17:04:09 +01003782complete_add({expr}) *complete_add()*
3783 Add {expr} to the list of matches. Only to be used by the
3784 function specified with the 'completefunc' option.
3785 Returns 0 for failure (empty string or out of memory),
3786 1 when the match was added, 2 when the match was already in
3787 the list.
3788 See |complete-functions| for an explanation of {expr}. It is
3789 the same as one item in the list that 'omnifunc' would return.
3790
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003791 Can also be used as a |method|: >
3792 GetMoreMatches()->complete_add()
3793
Bram Moolenaar214641f2017-03-05 17:04:09 +01003794complete_check() *complete_check()*
3795 Check for a key typed while looking for completion matches.
3796 This is to be used when looking for matches takes some time.
3797 Returns |TRUE| when searching for matches is to be aborted,
3798 zero otherwise.
3799 Only to be used by the function specified with the
3800 'completefunc' option.
3801
Bram Moolenaarfd133322019-03-29 12:20:27 +01003802 *complete_info()*
3803complete_info([{what}])
Bram Moolenaare46a4402020-06-30 20:38:27 +02003804 Returns a |Dictionary| with information about Insert mode
Bram Moolenaarfd133322019-03-29 12:20:27 +01003805 completion. See |ins-completion|.
3806 The items are:
3807 mode Current completion mode name string.
Bram Moolenaar723dd942019-04-04 13:11:03 +02003808 See |complete_info_mode| for the values.
Bram Moolenaarfd133322019-03-29 12:20:27 +01003809 pum_visible |TRUE| if popup menu is visible.
3810 See |pumvisible()|.
3811 items List of completion matches. Each item is a
3812 dictionary containing the entries "word",
3813 "abbr", "menu", "kind", "info" and "user_data".
3814 See |complete-items|.
3815 selected Selected item index. First index is zero.
3816 Index is -1 if no item is selected (showing
3817 typed text only)
3818 inserted Inserted string. [NOT IMPLEMENT YET]
3819
3820 *complete_info_mode*
3821 mode values are:
3822 "" Not in completion mode
3823 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
3824 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
3825 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
3826 "files" File names |i_CTRL-X_CTRL-F|
3827 "tags" Tags |i_CTRL-X_CTRL-]|
3828 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
3829 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
3830 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
3831 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
3832 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
3833 "function" User defined completion |i_CTRL-X_CTRL-U|
3834 "omni" Omni completion |i_CTRL-X_CTRL-O|
3835 "spell" Spelling suggestions |i_CTRL-X_s|
Bram Moolenaar73fef332020-06-21 22:12:03 +02003836 "eval" |complete()| completion
Bram Moolenaarfd133322019-03-29 12:20:27 +01003837 "unknown" Other internal modes
3838
3839 If the optional {what} list argument is supplied, then only
3840 the items listed in {what} are returned. Unsupported items in
3841 {what} are silently ignored.
3842
Bram Moolenaare9bd5722019-08-17 19:36:06 +02003843 To get the position and size of the popup menu, see
3844 |pum_getpos()|. It's also available in |v:event| during the
3845 |CompleteChanged| event.
3846
Bram Moolenaarfd133322019-03-29 12:20:27 +01003847 Examples: >
3848 " Get all items
3849 call complete_info()
3850 " Get only 'mode'
3851 call complete_info(['mode'])
3852 " Get only 'mode' and 'pum_visible'
3853 call complete_info(['mode', 'pum_visible'])
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003854
3855< Can also be used as a |method|: >
3856 GetItems()->complete_info()
Bram Moolenaarfd133322019-03-29 12:20:27 +01003857<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003858 *confirm()*
3859confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar647e24b2019-03-17 16:39:46 +01003860 confirm() offers the user a dialog, from which a choice can be
Bram Moolenaar214641f2017-03-05 17:04:09 +01003861 made. It returns the number of the choice. For the first
3862 choice this is 1.
3863 Note: confirm() is only supported when compiled with dialog
3864 support, see |+dialog_con| and |+dialog_gui|.
3865
3866 {msg} is displayed in a |dialog| with {choices} as the
3867 alternatives. When {choices} is missing or empty, "&OK" is
3868 used (and translated).
3869 {msg} is a String, use '\n' to include a newline. Only on
3870 some systems the string is wrapped when it doesn't fit.
3871
3872 {choices} is a String, with the individual choices separated
3873 by '\n', e.g. >
3874 confirm("Save changes?", "&Yes\n&No\n&Cancel")
3875< The letter after the '&' is the shortcut key for that choice.
3876 Thus you can type 'c' to select "Cancel". The shortcut does
3877 not need to be the first letter: >
3878 confirm("file has been modified", "&Save\nSave &All")
3879< For the console, the first letter of each choice is used as
Bram Moolenaar3132cdd2020-11-05 20:41:49 +01003880 the default shortcut key. Case is ignored.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003881
3882 The optional {default} argument is the number of the choice
3883 that is made if the user hits <CR>. Use 1 to make the first
3884 choice the default one. Use 0 to not set a default. If
3885 {default} is omitted, 1 is used.
3886
3887 The optional {type} argument gives the type of dialog. This
3888 is only used for the icon of the GTK, Mac, Motif and Win32
3889 GUI. It can be one of these values: "Error", "Question",
3890 "Info", "Warning" or "Generic". Only the first character is
3891 relevant. When {type} is omitted, "Generic" is used.
3892
3893 If the user aborts the dialog by pressing <Esc>, CTRL-C,
3894 or another valid interrupt key, confirm() returns 0.
3895
3896 An example: >
3897 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
3898 :if choice == 0
3899 : echo "make up your mind!"
3900 :elseif choice == 3
3901 : echo "tasteful"
3902 :else
3903 : echo "I prefer bananas myself."
3904 :endif
3905< In a GUI dialog, buttons are used. The layout of the buttons
3906 depends on the 'v' flag in 'guioptions'. If it is included,
3907 the buttons are always put vertically. Otherwise, confirm()
3908 tries to put the buttons in one horizontal line. If they
3909 don't fit, a vertical layout is used anyway. For some systems
3910 the horizontal layout is always used.
3911
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02003912 Can also be used as a |method|in: >
3913 BuildMessage()->confirm("&Yes\n&No")
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003914<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003915 *copy()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003916copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003917 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003918 When {expr} is a |List| a shallow copy is created. This means
3919 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003920 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003921 changing an item changes the contents of both |Lists|.
3922 A |Dictionary| is copied in a similar way as a |List|.
3923 Also see |deepcopy()|.
Bram Moolenaarac92e252019-08-03 21:58:38 +02003924 Can also be used as a |method|: >
3925 mylist->copy()
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003926
Bram Moolenaar446cb832008-06-24 21:56:24 +00003927cos({expr}) *cos()*
3928 Return the cosine of {expr}, measured in radians, as a |Float|.
3929 {expr} must evaluate to a |Float| or a |Number|.
3930 Examples: >
3931 :echo cos(100)
3932< 0.862319 >
3933 :echo cos(-4.01)
3934< -0.646043
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003935
3936 Can also be used as a |method|: >
3937 Compute()->cos()
3938<
Bram Moolenaar446cb832008-06-24 21:56:24 +00003939 {only available when compiled with the |+float| feature}
3940
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003941
3942cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003943 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003944 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003945 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003946 Examples: >
3947 :echo cosh(0.5)
3948< 1.127626 >
3949 :echo cosh(-0.5)
3950< -1.127626
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02003951
3952 Can also be used as a |method|: >
3953 Compute()->cosh()
3954<
Bram Moolenaardb84e452010-08-15 13:50:43 +02003955 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003956
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003957
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003958count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003959 Return the number of times an item with value {expr} appears
Bram Moolenaar9966b212017-07-28 16:46:57 +02003960 in |String|, |List| or |Dictionary| {comp}.
3961
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003962 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003963 {start} can only be used with a |List|.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003964
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003965 When {ic} is given and it's |TRUE| then case is ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003966
Bram Moolenaar9966b212017-07-28 16:46:57 +02003967 When {comp} is a string then the number of not overlapping
Bram Moolenaar338e47f2017-12-19 11:55:26 +01003968 occurrences of {expr} is returned. Zero is returned when
3969 {expr} is an empty string.
Bram Moolenaara74e4942019-08-04 17:35:53 +02003970
Bram Moolenaarac92e252019-08-03 21:58:38 +02003971 Can also be used as a |method|: >
3972 mylist->count(val)
Bram Moolenaara74e4942019-08-04 17:35:53 +02003973<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003974 *cscope_connection()*
3975cscope_connection([{num} , {dbpath} [, {prepend}]])
3976 Checks for the existence of a |cscope| connection. If no
3977 parameters are specified, then the function returns:
3978 0, if cscope was not available (not compiled in), or
3979 if there are no cscope connections;
3980 1, if there is at least one cscope connection.
3981
3982 If parameters are specified, then the value of {num}
3983 determines how existence of a cscope connection is checked:
3984
3985 {num} Description of existence check
3986 ----- ------------------------------
3987 0 Same as no parameters (e.g., "cscope_connection()").
3988 1 Ignore {prepend}, and use partial string matches for
3989 {dbpath}.
3990 2 Ignore {prepend}, and use exact string matches for
3991 {dbpath}.
3992 3 Use {prepend}, use partial string matches for both
3993 {dbpath} and {prepend}.
3994 4 Use {prepend}, use exact string matches for both
3995 {dbpath} and {prepend}.
3996
3997 Note: All string comparisons are case sensitive!
3998
3999 Examples. Suppose we had the following (from ":cs show"): >
4000
4001 # pid database name prepend path
4002 0 27664 cscope.out /usr/local
4003<
4004 Invocation Return Val ~
4005 ---------- ---------- >
4006 cscope_connection() 1
4007 cscope_connection(1, "out") 1
4008 cscope_connection(2, "out") 0
4009 cscope_connection(3, "out") 0
4010 cscope_connection(3, "out", "local") 1
4011 cscope_connection(4, "out") 0
4012 cscope_connection(4, "out", "local") 0
4013 cscope_connection(4, "cscope.out", "/usr/local") 1
4014<
Bram Moolenaar0b238792006-03-02 22:49:12 +00004015cursor({lnum}, {col} [, {off}]) *cursor()*
4016cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004017 Positions the cursor at the column (byte count) {col} in the
4018 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02004019
Bram Moolenaar0b238792006-03-02 22:49:12 +00004020 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02004021 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02004022 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02004023 [{lnum}, {col}, {off}]
4024 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02004025 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004026 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02004027
Bram Moolenaar6f02b002021-01-10 20:22:54 +01004028 To position the cursor using the character count, use
4029 |setcursorcharpos()|.
4030
Bram Moolenaar071d4272004-06-13 20:20:40 +00004031 Does not change the jumplist.
4032 If {lnum} is greater than the number of lines in the buffer,
4033 the cursor will be positioned at the last line in the buffer.
4034 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00004035 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00004036 the cursor will be positioned at the last character in the
4037 line.
4038 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004039 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02004040 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01004041
Bram Moolenaar0b238792006-03-02 22:49:12 +00004042 When 'virtualedit' is used {off} specifies the offset in
4043 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00004044 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00004045 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004046
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004047 Can also be used as a |method|: >
4048 GetCursorPos()->cursor()
4049
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02004050debugbreak({pid}) *debugbreak()*
4051 Specifically used to interrupt a program being debugged. It
4052 will cause process {pid} to get a SIGTRAP. Behavior for other
4053 processes is undefined. See |terminal-debugger|.
4054 {only available on MS-Windows}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004055
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004056 Can also be used as a |method|: >
4057 GetPid()->debugbreak()
4058
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004059deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004060 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004061 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004062 When {expr} is a |List| a full copy is created. This means
4063 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01004064 copy, and vice versa. When an item is a |List| or
4065 |Dictionary|, a copy for it is made, recursively. Thus
4066 changing an item in the copy does not change the contents of
4067 the original |List|.
4068 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar7ff78462020-07-10 22:00:53 +02004069
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004070 When {noref} is omitted or zero a contained |List| or
4071 |Dictionary| is only copied once. All references point to
4072 this single copy. With {noref} set to 1 every occurrence of a
4073 |List| or |Dictionary| results in a new copy. This also means
4074 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004075 *E724*
4076 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00004077 that refers back to a higher level making a deep copy with
4078 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004079 Also see |copy()|.
4080
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004081 Can also be used as a |method|: >
4082 GetObject()->deepcopy()
4083
Bram Moolenaarda440d22016-01-16 21:27:23 +01004084delete({fname} [, {flags}]) *delete()*
4085 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01004086 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01004087
4088 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01004089 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004090
Bram Moolenaarda440d22016-01-16 21:27:23 +01004091 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01004092 {fname} and everything in it, recursively. BE CAREFUL!
Bram Moolenaar36f44c22016-08-28 18:17:20 +02004093 Note: on MS-Windows it is not possible to delete a directory
4094 that is being used.
Bram Moolenaar818078d2016-08-27 21:58:42 +02004095
Bram Moolenaar43a34f92016-01-17 15:56:34 +01004096 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004097
Bram Moolenaar98a29d02021-01-18 19:55:44 +01004098 The result is a Number, which is 0/false if the delete
4099 operation was successful and -1/true when the deletion failed
4100 or partly failed.
Bram Moolenaarda440d22016-01-16 21:27:23 +01004101
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004102 Use |remove()| to delete an item from a |List|.
Bram Moolenaard79a2622018-06-07 18:17:46 +02004103 To delete a line from the buffer use |:delete| or
4104 |deletebufline()|.
4105
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004106 Can also be used as a |method|: >
4107 GetName()->delete()
4108
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004109deletebufline({expr}, {first} [, {last}]) *deletebufline()*
Bram Moolenaard79a2622018-06-07 18:17:46 +02004110 Delete lines {first} to {last} (inclusive) from buffer {expr}.
4111 If {last} is omitted then delete line {first} only.
4112 On success 0 is returned, on failure 1 is returned.
4113
Bram Moolenaar2e693a82019-10-16 22:35:02 +02004114 This function works only for loaded buffers. First call
4115 |bufload()| if needed.
4116
Bram Moolenaard79a2622018-06-07 18:17:46 +02004117 For the use of {expr}, see |bufname()| above.
4118
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004119 {first} and {last} are used like with |getline()|. Note that
Bram Moolenaard79a2622018-06-07 18:17:46 +02004120 when using |line()| this refers to the current buffer. Use "$"
4121 to refer to the last line in buffer {expr}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004122
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004123 Can also be used as a |method|: >
4124 GetBuffer()->deletebufline(1)
Bram Moolenaar2e693a82019-10-16 22:35:02 +02004125<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004126 *did_filetype()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004127did_filetype() Returns |TRUE| when autocommands are being executed and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004128 FileType event has been triggered at least once. Can be used
4129 to avoid triggering the FileType event again in the scripts
4130 that detect the file type. |FileType|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02004131 Returns |FALSE| when `:setf FALLBACK` was used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004132 When editing another file, the counter is reset, thus this
4133 really checks if the FileType event has been triggered for the
4134 current buffer. This allows an autocommand that starts
4135 editing another buffer to set 'filetype' and load a syntax
4136 file.
4137
Bram Moolenaar47136d72004-10-12 20:02:24 +00004138diff_filler({lnum}) *diff_filler()*
4139 Returns the number of filler lines above line {lnum}.
4140 These are the lines that were inserted at this point in
4141 another diff'ed window. These filler lines are shown in the
4142 display but don't exist in the buffer.
4143 {lnum} is used like with |getline()|. Thus "." is the current
4144 line, "'m" mark m, etc.
4145 Returns 0 if the current window is not in diff mode.
4146
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004147 Can also be used as a |method|: >
4148 GetLnum()->diff_filler()
4149
Bram Moolenaar47136d72004-10-12 20:02:24 +00004150diff_hlID({lnum}, {col}) *diff_hlID()*
4151 Returns the highlight ID for diff mode at line {lnum} column
4152 {col} (byte index). When the current line does not have a
4153 diff change zero is returned.
4154 {lnum} is used like with |getline()|. Thus "." is the current
4155 line, "'m" mark m, etc.
4156 {col} is 1 for the leftmost column, {lnum} is 1 for the first
4157 line.
4158 The highlight ID can be used with |synIDattr()| to obtain
4159 syntax information about the highlighting.
4160
Bram Moolenaar1a3a8912019-08-23 22:31:37 +02004161 Can also be used as a |method|: >
4162 GetLnum()->diff_hlID(col)
Bram Moolenaar691ddee2019-05-09 14:52:41 +02004163
Bram Moolenaar4132eb52020-02-14 16:53:00 +01004164
4165echoraw({expr}) *echoraw()*
4166 Output {expr} as-is, including unprintable characters. This
4167 can be used to output a terminal code. For example, to disable
4168 modifyOtherKeys: >
4169 call echoraw(&t_TE)
4170< and to enable it again: >
4171 call echoraw(&t_TI)
4172< Use with care, you can mess up the terminal this way.
4173
4174
Bram Moolenaar13065c42005-01-08 16:08:21 +00004175empty({expr}) *empty()*
4176 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004177 - A |List| or |Dictionary| is empty when it does not have any
4178 items.
Bram Moolenaard8968242019-01-15 22:51:57 +01004179 - A |String| is empty when its length is zero.
4180 - A |Number| and |Float| are empty when their value is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004181 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
Bram Moolenaard8968242019-01-15 22:51:57 +01004182 - A |Job| is empty when it failed to start.
4183 - A |Channel| is empty when it is closed.
Bram Moolenaard09091d2019-01-17 16:07:22 +01004184 - A |Blob| is empty when its length is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01004185
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004186 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004187 length with zero.
Bram Moolenaara4208962019-08-24 20:50:19 +02004188
Bram Moolenaarac92e252019-08-03 21:58:38 +02004189 Can also be used as a |method|: >
4190 mylist->empty()
Bram Moolenaar13065c42005-01-08 16:08:21 +00004191
Bram Moolenaar29634562020-01-09 21:46:04 +01004192environ() *environ()*
4193 Return all of environment variables as dictionary. You can
4194 check if an environment variable exists like this: >
4195 :echo has_key(environ(), 'HOME')
4196< Note that the variable name may be CamelCase; to ignore case
4197 use this: >
4198 :echo index(keys(environ()), 'HOME', 0, 1) != -1
4199
Bram Moolenaar071d4272004-06-13 20:20:40 +00004200escape({string}, {chars}) *escape()*
4201 Escape the characters in {chars} that occur in {string} with a
4202 backslash. Example: >
4203 :echo escape('c:\program files\vim', ' \')
4204< results in: >
4205 c:\\program\ files\\vim
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004206< Also see |shellescape()| and |fnameescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004207
Bram Moolenaara4208962019-08-24 20:50:19 +02004208 Can also be used as a |method|: >
4209 GetText()->escape(' \')
4210<
Bram Moolenaar446cb832008-06-24 21:56:24 +00004211 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004212eval({string}) Evaluate {string} and return the result. Especially useful to
4213 turn the result of |string()| back into the original value.
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01004214 This works for Numbers, Floats, Strings, Blobs and composites
4215 of them. Also works for |Funcref|s that refer to existing
Bram Moolenaar446cb832008-06-24 21:56:24 +00004216 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004217
Bram Moolenaar25e42232019-08-04 15:04:10 +02004218 Can also be used as a |method|: >
4219 argv->join()->eval()
4220
Bram Moolenaar071d4272004-06-13 20:20:40 +00004221eventhandler() *eventhandler()*
4222 Returns 1 when inside an event handler. That is that Vim got
4223 interrupted while waiting for the user to type a character,
4224 e.g., when dropping a file on Vim. This means interactive
4225 commands cannot be used. Otherwise zero is returned.
4226
4227executable({expr}) *executable()*
4228 This function checks if an executable with the name {expr}
4229 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004230 arguments.
4231 executable() uses the value of $PATH and/or the normal
4232 searchpath for programs. *PATHEXT*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01004233 On MS-Windows the ".exe", ".bat", etc. can optionally be
4234 included. Then the extensions in $PATHEXT are tried. Thus if
4235 "foo.exe" does not exist, "foo.exe.bat" can be found. If
Bram Moolenaar95da1362020-05-30 18:37:55 +02004236 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01004237 by itself can be used in $PATHEXT to try using the name
4238 without an extension. When 'shell' looks like a Unix shell,
4239 then the name is also tried without adding an extension.
4240 On MS-Windows it only checks if the file exists and is not a
4241 directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004242 On MS-Windows an executable in the same directory as Vim is
4243 always found. Since this directory is added to $PATH it
4244 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004245 The result is a Number:
4246 1 exists
4247 0 does not exist
4248 -1 not implemented on this system
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02004249 |exepath()| can be used to get the full path of an executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004250
Bram Moolenaara4208962019-08-24 20:50:19 +02004251 Can also be used as a |method|: >
4252 GetCommand()->executable()
4253
Bram Moolenaar79815f12016-07-09 17:07:29 +02004254execute({command} [, {silent}]) *execute()*
4255 Execute an Ex command or commands and return the output as a
4256 string.
4257 {command} can be a string or a List. In case of a List the
4258 lines are executed one by one.
4259 This is equivalent to: >
4260 redir => var
4261 {command}
4262 redir END
4263<
4264 The optional {silent} argument can have these values:
4265 "" no `:silent` used
4266 "silent" `:silent` used
4267 "silent!" `:silent!` used
Bram Moolenaar214641f2017-03-05 17:04:09 +01004268 The default is "silent". Note that with "silent!", unlike
Bram Moolenaar069c1e72016-07-15 21:25:08 +02004269 `:redir`, error messages are dropped. When using an external
4270 command the screen may be messed up, use `system()` instead.
Bram Moolenaar79815f12016-07-09 17:07:29 +02004271 *E930*
4272 It is not possible to use `:redir` anywhere in {command}.
4273
4274 To get a list of lines use |split()| on the result: >
Bram Moolenaar063b9d12016-07-09 20:21:48 +02004275 split(execute('args'), "\n")
Bram Moolenaar79815f12016-07-09 17:07:29 +02004276
Bram Moolenaar868b7b62019-05-29 21:44:40 +02004277< To execute a command in another window than the current one
4278 use `win_execute()`.
4279
4280 When used recursively the output of the recursive call is not
Bram Moolenaar79815f12016-07-09 17:07:29 +02004281 included in the output of the higher level call.
4282
Bram Moolenaara4208962019-08-24 20:50:19 +02004283 Can also be used as a |method|: >
4284 GetCommand()->execute()
4285
Bram Moolenaarc7f02552014-04-01 21:00:59 +02004286exepath({expr}) *exepath()*
4287 If {expr} is an executable and is either an absolute path, a
4288 relative path or found in $PATH, return the full path.
4289 Note that the current directory is used when {expr} starts
4290 with "./", which may be a problem for Vim: >
4291 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02004292< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02004293 an empty string is returned.
4294
Bram Moolenaara4208962019-08-24 20:50:19 +02004295 Can also be used as a |method|: >
4296 GetCommand()->exepath()
Bram Moolenaar2e693a82019-10-16 22:35:02 +02004297<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004298 *exists()*
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02004299exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
4300 zero otherwise.
4301
4302 For checking for a supported feature use |has()|.
4303 For checking if a file exists use |filereadable()|.
4304
4305 The {expr} argument is a string, which contains one of these:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004306 &option-name Vim option (only checks if it exists,
4307 not if it really works)
4308 +option-name Vim option that works.
4309 $ENVNAME environment variable (could also be
4310 done by comparing with an empty
4311 string)
4312 *funcname built-in function (see |functions|)
4313 or user defined function (see
Bram Moolenaar15c47602020-03-26 22:16:48 +01004314 |user-functions|) that is implemented.
4315 Also works for a variable that is a
4316 Funcref.
4317 ?funcname built-in function that could be
4318 implemented; to be used to check if
4319 "funcname" is valid
Bram Moolenaar071d4272004-06-13 20:20:40 +00004320 varname internal variable (see
Bram Moolenaar58b85342016-08-14 19:54:54 +02004321 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004322 for |curly-braces-names|, |Dictionary|
4323 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00004324 that evaluating an index may cause an
4325 error message for an invalid
4326 expression. E.g.: >
4327 :let l = [1, 2, 3]
4328 :echo exists("l[5]")
4329< 0 >
4330 :echo exists("l[xx]")
4331< E121: Undefined variable: xx
4332 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00004333 :cmdname Ex command: built-in command, user
4334 command or command modifier |:command|.
4335 Returns:
4336 1 for match with start of a command
4337 2 full match with a command
4338 3 matches several user commands
4339 To check for a supported command
4340 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00004341 :2match The |:2match| command.
4342 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004343 #event autocommand defined for this event
4344 #event#pattern autocommand defined for this event and
4345 pattern (the pattern is taken
4346 literally and compared to the
4347 autocommand patterns character by
4348 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004349 #group autocommand group exists
4350 #group#event autocommand defined for this group and
4351 event.
4352 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004353 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004354 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004355 ##event autocommand for this event is
4356 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004357
4358 Examples: >
4359 exists("&shortname")
4360 exists("$HOSTNAME")
4361 exists("*strftime")
4362 exists("*s:MyFunc")
4363 exists("bufcount")
4364 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004365 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004366 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00004367 exists("#filetypeindent")
4368 exists("#filetypeindent#FileType")
4369 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00004370 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004371< There must be no space between the symbol (&/$/*/#) and the
4372 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004373 There must be no extra characters after the name, although in
4374 a few cases this is ignored. That may become more strict in
4375 the future, thus don't count on it!
4376 Working example: >
4377 exists(":make")
4378< NOT working example: >
4379 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00004380
4381< Note that the argument must be a string, not the name of the
4382 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004383 exists(bufcount)
4384< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00004385 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004386
Bram Moolenaara4208962019-08-24 20:50:19 +02004387 Can also be used as a |method|: >
4388 Varname()->exists()
4389
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004390exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004391 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004392 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004393 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004394 Examples: >
4395 :echo exp(2)
4396< 7.389056 >
4397 :echo exp(-1)
4398< 0.367879
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004399
4400 Can also be used as a |method|: >
4401 Compute()->exp()
4402<
Bram Moolenaardb84e452010-08-15 13:50:43 +02004403 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004404
4405
Bram Moolenaar84f72352012-03-11 15:57:40 +01004406expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004407 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004408 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004409
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004410 If {list} is given and it is |TRUE|, a List will be returned.
Bram Moolenaar84f72352012-03-11 15:57:40 +01004411 Otherwise the result is a String and when there are several
4412 matches, they are separated by <NL> characters. [Note: in
4413 version 5.0 a space was used, which caused problems when a
4414 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004415
Bram Moolenaar58b85342016-08-14 19:54:54 +02004416 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02004417 for a non-existing file is not included, unless {expr} does
4418 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004419
4420 When {expr} starts with '%', '#' or '<', the expansion is done
4421 like for the |cmdline-special| variables with their associated
4422 modifiers. Here is a short overview:
4423
4424 % current file name
4425 # alternate file name
4426 #n alternate file name n
4427 <cfile> file name under the cursor
4428 <afile> autocmd file name
4429 <abuf> autocmd buffer number (as a String!)
4430 <amatch> autocmd matched name
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02004431 <cexpr> C expression under the cursor
Bram Moolenaara6878372014-03-22 21:02:50 +01004432 <sfile> sourced script file or function name
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02004433 <slnum> sourced script line number or function
4434 line number
4435 <sflnum> script file line number, also when in
4436 a function
Bram Moolenaaraa970ab2020-08-02 16:10:39 +02004437 <SID> "<SNR>123_" where "123" is the
4438 current script ID |<SID>|
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02004439 <stack> call stack
Bram Moolenaar071d4272004-06-13 20:20:40 +00004440 <cword> word under the cursor
4441 <cWORD> WORD under the cursor
4442 <client> the {clientid} of the last received
4443 message |server2client()|
4444 Modifiers:
4445 :p expand to full path
4446 :h head (last path component removed)
4447 :t tail (last path component only)
4448 :r root (one extension removed)
4449 :e extension only
4450
4451 Example: >
4452 :let &tags = expand("%:p:h") . "/tags"
4453< Note that when expanding a string that starts with '%', '#' or
4454 '<', any following text is ignored. This does NOT work: >
4455 :let doesntwork = expand("%:h.bak")
4456< Use this: >
4457 :let doeswork = expand("%:h") . ".bak"
4458< Also note that expanding "<cfile>" and others only returns the
4459 referenced file name without further expansion. If "<cfile>"
4460 is "~/.cshrc", you need to do another expand() to have the
4461 "~/" expanded into the path of the home directory: >
4462 :echo expand(expand("<cfile>"))
4463<
4464 There cannot be white space between the variables and the
4465 following modifier. The |fnamemodify()| function can be used
4466 to modify normal file names.
4467
4468 When using '%' or '#', and the current or alternate file name
4469 is not defined, an empty string is used. Using "%:p" in a
4470 buffer with no name, results in the current directory, with a
4471 '/' added.
4472
4473 When {expr} does not start with '%', '#' or '<', it is
4474 expanded like a file name is expanded on the command line.
4475 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004476 {nosuf} argument is given and it is |TRUE|.
Bram Moolenaar146e9c32012-03-07 19:18:23 +01004477 Names for non-existing files are included. The "**" item can
4478 be used to search in a directory tree. For example, to find
4479 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00004480 :echo expand("**/README")
4481<
Bram Moolenaar647e24b2019-03-17 16:39:46 +01004482 expand() can also be used to expand variables and environment
Bram Moolenaar071d4272004-06-13 20:20:40 +00004483 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02004484 slow, because a shell may be used to do the expansion. See
4485 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004486 The expanded variable is still handled like a list of file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004487 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004488 left unchanged. Thus ":echo expand('$FOOBAR')" results in
4489 "$FOOBAR".
4490
4491 See |glob()| for finding existing files. See |system()| for
4492 getting the raw output of an external command.
4493
Bram Moolenaara4208962019-08-24 20:50:19 +02004494 Can also be used as a |method|: >
4495 Getpattern()->expand()
4496
Bram Moolenaar80dad482019-06-09 17:22:31 +02004497expandcmd({expr}) *expandcmd()*
4498 Expand special items in {expr} like what is done for an Ex
4499 command such as `:edit`. This expands special keywords, like
4500 with |expand()|, and environment variables, anywhere in
Bram Moolenaar96f45c02019-10-26 19:53:45 +02004501 {expr}. "~user" and "~/path" are only expanded at the start.
4502 Returns the expanded string. Example: >
Bram Moolenaar80dad482019-06-09 17:22:31 +02004503 :echo expandcmd('make %<.o')
Bram Moolenaara4208962019-08-24 20:50:19 +02004504
4505< Can also be used as a |method|: >
4506 GetCommand()->expandcmd()
Bram Moolenaar80dad482019-06-09 17:22:31 +02004507<
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004508extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004509 {expr1} and {expr2} must be both |Lists| or both
4510 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004511
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004512 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar3132cdd2020-11-05 20:41:49 +01004513 If {expr3} is given insert the items of {expr2} before the
4514 item with index {expr3} in {expr1}. When {expr3} is zero
4515 insert before the first item. When {expr3} is equal to
4516 len({expr1}) then {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004517 Examples: >
4518 :echo sort(extend(mylist, [7, 5]))
4519 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00004520< When {expr1} is the same List as {expr2} then the number of
4521 items copied is equal to the original length of the List.
4522 E.g., when {expr3} is 1 you get N new copies of the first item
4523 (where N is the original length of the List).
Bram Moolenaar58b85342016-08-14 19:54:54 +02004524 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004525 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004526 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004527<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004528 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004529 Add all entries from {expr2} to {expr1}.
4530 If a key exists in both {expr1} and {expr2} then {expr3} is
4531 used to decide what to do:
4532 {expr3} = "keep": keep the value of {expr1}
4533 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004534 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004535 When {expr3} is omitted then "force" is assumed.
4536
4537 {expr1} is changed when {expr2} is not empty. If necessary
4538 make a copy of {expr1} first.
4539 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02004540 When {expr1} is locked and {expr2} is not empty the operation
4541 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004542 Returns {expr1}.
4543
Bram Moolenaarac92e252019-08-03 21:58:38 +02004544 Can also be used as a |method|: >
4545 mylist->extend(otherlist)
4546
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004547
Bram Moolenaarb0e6b512021-01-12 20:23:40 +01004548extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
4549 Like |extend()| but instead of adding items to {expr1} a new
4550 List or Dictionary is created and returned. {expr1} remains
4551 unchanged. Items can still be changed by {expr2}, if you
4552 don't want that use |deepcopy()| first.
4553
4554
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004555feedkeys({string} [, {mode}]) *feedkeys()*
4556 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004557 come from a mapping or were typed by the user.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004558
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004559 By default the string is added to the end of the typeahead
4560 buffer, thus if a mapping is still being executed the
4561 characters come after them. Use the 'i' flag to insert before
4562 other characters, they will be executed next, before any
4563 characters from a mapping.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004564
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004565 The function does not wait for processing of keys contained in
4566 {string}.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004567
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004568 To include special keys into {string}, use double-quotes
4569 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00004570 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004571 feedkeys('\<CR>') pushes 5 characters.
Bram Moolenaarbe0a2592019-05-09 13:50:16 +02004572 A special code that might be useful is <Ignore>, it exits the
4573 wait for a character without doing anything. *<Ignore>*
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004574
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004575 {mode} is a String, which can contain these character flags:
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004576 'm' Remap keys. This is default. If {mode} is absent,
4577 keys are remapped.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004578 'n' Do not remap keys.
4579 't' Handle keys as if typed; otherwise they are handled as
4580 if coming from a mapping. This matters for undo,
4581 opening folds, etc.
Bram Moolenaar5e66b422019-01-24 21:58:10 +01004582 'L' Lowlevel input. Only works for Unix or when using the
4583 GUI. Keys are used as if they were coming from the
4584 terminal. Other flags are not used. *E980*
Bram Moolenaar79296512020-03-22 16:17:14 +01004585 When a CTRL-C interrupts and 't' is included it sets
4586 the internal "got_int" flag.
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004587 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01004588 'x' Execute commands until typeahead is empty. This is
4589 similar to using ":normal!". You can call feedkeys()
4590 several times without 'x' and then one time with 'x'
4591 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02004592 typeahead. Note that when Vim ends in Insert mode it
4593 will behave as if <Esc> is typed, to avoid getting
4594 stuck, waiting for a character to be typed before the
4595 script continues.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004596 Note that if you manage to call feedkeys() while
Bram Moolenaar5b69c222019-01-11 14:50:06 +01004597 executing commands, thus calling it recursively, then
Bram Moolenaarebacddb2020-06-04 15:22:21 +02004598 all typeahead will be consumed by the last call.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004599 '!' When used with 'x' will not end Insert mode. Can be
4600 used in a test when a timer is set to exit Insert mode
4601 a little later. Useful for testing CursorHoldI.
4602
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004603 Return value is always 0.
4604
Bram Moolenaara4208962019-08-24 20:50:19 +02004605 Can also be used as a |method|: >
4606 GetInput()->feedkeys()
4607
Bram Moolenaar071d4272004-06-13 20:20:40 +00004608filereadable({file}) *filereadable()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004609 The result is a Number, which is |TRUE| when a file with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004610 name {file} exists, and can be read. If {file} doesn't exist,
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004611 or is a directory, the result is |FALSE|. {file} is any
Bram Moolenaar071d4272004-06-13 20:20:40 +00004612 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004613 If you don't care about the file being readable you can use
4614 |glob()|.
Bram Moolenaar25e42232019-08-04 15:04:10 +02004615 {file} is used as-is, you may want to expand wildcards first: >
4616 echo filereadable('~/.vimrc')
4617 0
4618 echo filereadable(expand('~/.vimrc'))
4619 1
Bram Moolenaara4208962019-08-24 20:50:19 +02004620
4621< Can also be used as a |method|: >
4622 GetName()->filereadable()
Bram Moolenaar25e42232019-08-04 15:04:10 +02004623< *file_readable()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004624 Obsolete name: file_readable().
4625
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004626
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004627filewritable({file}) *filewritable()*
4628 The result is a Number, which is 1 when a file with the
4629 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00004630 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004631 directory, and we can write to it, the result is 2.
4632
Bram Moolenaara4208962019-08-24 20:50:19 +02004633 Can also be used as a |method|: >
Bram Moolenaarebacddb2020-06-04 15:22:21 +02004634 GetName()->filewritable()
Bram Moolenaara4208962019-08-24 20:50:19 +02004635
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004636
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004637filter({expr1}, {expr2}) *filter()*
4638 {expr1} must be a |List| or a |Dictionary|.
4639 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004640 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004641 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004642
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004643 If {expr2} is a |string|, inside {expr2} |v:val| has the value
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004644 of the current item. For a |Dictionary| |v:key| has the key
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004645 of the current item and for a |List| |v:key| has the index of
4646 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004647 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004648 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004649< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004650 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004651< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004652 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004653< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004654
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004655 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004656 used as an expression again. Often it is good to use a
4657 |literal-string| to avoid having to double backslashes.
4658
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004659 If {expr2} is a |Funcref| it must take two arguments:
4660 1. the key or the index of the current item.
4661 2. the value of the current item.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004662 The function must return |TRUE| if the item should be kept.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004663 Example that keeps the odd items of a list: >
4664 func Odd(idx, val)
4665 return a:idx % 2 == 1
4666 endfunc
4667 call filter(mylist, function('Odd'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004668< It is shorter when using a |lambda|: >
4669 call filter(myList, {idx, val -> idx * val <= 42})
4670< If you do not use "val" you can leave it out: >
4671 call filter(myList, {idx -> idx % 2 == 1})
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004672<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004673 The operation is done in-place. If you want a |List| or
4674 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00004675 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004676
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004677< Returns {expr1}, the |List| or |Dictionary| that was filtered.
4678 When an error is encountered while evaluating {expr2} no
4679 further items in {expr1} are processed. When {expr2} is a
4680 Funcref errors inside a function are ignored, unless it was
4681 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004682
Bram Moolenaarac92e252019-08-03 21:58:38 +02004683 Can also be used as a |method|: >
4684 mylist->filter(expr2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004685
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004686finddir({name} [, {path} [, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00004687 Find directory {name} in {path}. Supports both downwards and
4688 upwards recursive directory searches. See |file-searching|
4689 for the syntax of {path}.
4690 Returns the path of the first found match. When the found
4691 directory is below the current directory a relative path is
4692 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004693 If {path} is omitted or empty then 'path' is used.
4694 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004695 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00004696 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004697 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004698 {only available when compiled with the |+file_in_path|
4699 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004700
Bram Moolenaara4208962019-08-24 20:50:19 +02004701 Can also be used as a |method|: >
4702 GetName()->finddir()
4703
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004704findfile({name} [, {path} [, {count}]]) *findfile()*
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004705 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004706 Uses 'suffixesadd'.
4707 Example: >
4708 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004709< Searches from the directory of the current file upwards until
4710 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004711
Bram Moolenaara4208962019-08-24 20:50:19 +02004712 Can also be used as a |method|: >
4713 GetName()->findfile()
4714
Bram Moolenaar077a1e62020-06-08 20:50:43 +02004715flatten({list} [, {maxdepth}]) *flatten()*
4716 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
4717 the result is a |List| without nesting, as if {maxdepth} is
4718 a very large number.
Bram Moolenaar3b690062021-02-01 20:14:51 +01004719 The {list} is changed in place, use |flattennew()| if you do
Bram Moolenaar077a1e62020-06-08 20:50:43 +02004720 not want that.
Bram Moolenaar3b690062021-02-01 20:14:51 +01004721 In Vim9 script flatten() cannot be used, you must always use
4722 |flattennew()|.
Bram Moolenaar73fef332020-06-21 22:12:03 +02004723 *E900*
Bram Moolenaar077a1e62020-06-08 20:50:43 +02004724 {maxdepth} means how deep in nested lists changes are made.
4725 {list} is not modified when {maxdepth} is 0.
4726 {maxdepth} must be positive number.
4727
4728 If there is an error the number zero is returned.
4729
4730 Example: >
4731 :echo flatten([1, [2, [3, 4]], 5])
4732< [1, 2, 3, 4, 5] >
4733 :echo flatten([1, [2, [3, 4]], 5], 1)
4734< [1, 2, [3, 4], 5]
4735
Bram Moolenaar3b690062021-02-01 20:14:51 +01004736flattennew({list} [, {maxdepth}]) *flattennew()*
4737 Like |flatten()| but first make a copy of {list}.
4738
4739
Bram Moolenaar446cb832008-06-24 21:56:24 +00004740float2nr({expr}) *float2nr()*
4741 Convert {expr} to a Number by omitting the part after the
4742 decimal point.
4743 {expr} must evaluate to a |Float| or a Number.
4744 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004745 result is truncated to 0x7fffffff or -0x7fffffff (or when
4746 64-bit Number support is enabled, 0x7fffffffffffffff or
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004747 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004748 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00004749 Examples: >
4750 echo float2nr(3.95)
4751< 3 >
4752 echo float2nr(-23.45)
4753< -23 >
4754 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004755< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004756 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004757< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004758 echo float2nr(1.0e-100)
4759< 0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004760
4761 Can also be used as a |method|: >
4762 Compute()->float2nr()
4763<
Bram Moolenaar446cb832008-06-24 21:56:24 +00004764 {only available when compiled with the |+float| feature}
4765
4766
4767floor({expr}) *floor()*
4768 Return the largest integral value less than or equal to
4769 {expr} as a |Float| (round down).
4770 {expr} must evaluate to a |Float| or a |Number|.
4771 Examples: >
4772 echo floor(1.856)
4773< 1.0 >
4774 echo floor(-5.456)
4775< -6.0 >
4776 echo floor(4.0)
4777< 4.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004778
4779 Can also be used as a |method|: >
4780 Compute()->floor()
4781<
Bram Moolenaar446cb832008-06-24 21:56:24 +00004782 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004783
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004784
4785fmod({expr1}, {expr2}) *fmod()*
4786 Return the remainder of {expr1} / {expr2}, even if the
4787 division is not representable. Returns {expr1} - i * {expr2}
4788 for some integer i such that if {expr2} is non-zero, the
4789 result has the same sign as {expr1} and magnitude less than
4790 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004791 returned is zero. The value returned is a |Float|.
4792 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004793 Examples: >
4794 :echo fmod(12.33, 1.22)
4795< 0.13 >
4796 :echo fmod(-12.33, 1.22)
4797< -0.13
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02004798
4799 Can also be used as a |method|: >
4800 Compute()->fmod(1.22)
4801<
Bram Moolenaardb84e452010-08-15 13:50:43 +02004802 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004803
4804
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004805fnameescape({string}) *fnameescape()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004806 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004807 characters that have a special meaning, such as '%' and '|'
4808 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004809 For most systems the characters escaped are
4810 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
4811 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004812 A leading '+' and '>' is also escaped (special after |:edit|
4813 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004814 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004815 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004816 :exe "edit " . fnameescape(fname)
4817< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004818 edit \+some\ str\%nge\|name
Bram Moolenaara4208962019-08-24 20:50:19 +02004819<
4820 Can also be used as a |method|: >
4821 GetName()->fnameescape()
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004822
Bram Moolenaar071d4272004-06-13 20:20:40 +00004823fnamemodify({fname}, {mods}) *fnamemodify()*
4824 Modify file name {fname} according to {mods}. {mods} is a
4825 string of characters like it is used for file names on the
4826 command line. See |filename-modifiers|.
4827 Example: >
4828 :echo fnamemodify("main.c", ":p:h")
4829< results in: >
4830 /home/mool/vim/vim/src
Bram Moolenaar4072ba52020-12-23 13:56:35 +01004831< If {mods} is empty then {fname} is returned.
4832 Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00004833 |expand()| first then.
4834
Bram Moolenaara4208962019-08-24 20:50:19 +02004835 Can also be used as a |method|: >
4836 GetName()->fnamemodify(':p:h')
4837
Bram Moolenaar071d4272004-06-13 20:20:40 +00004838foldclosed({lnum}) *foldclosed()*
4839 The result is a Number. If the line {lnum} is in a closed
4840 fold, the result is the number of the first line in that fold.
4841 If the line {lnum} is not in a closed fold, -1 is returned.
4842
Bram Moolenaara4208962019-08-24 20:50:19 +02004843 Can also be used as a |method|: >
4844 GetLnum()->foldclosed()
4845
Bram Moolenaar071d4272004-06-13 20:20:40 +00004846foldclosedend({lnum}) *foldclosedend()*
4847 The result is a Number. If the line {lnum} is in a closed
4848 fold, the result is the number of the last line in that fold.
4849 If the line {lnum} is not in a closed fold, -1 is returned.
4850
Bram Moolenaara4208962019-08-24 20:50:19 +02004851 Can also be used as a |method|: >
4852 GetLnum()->foldclosedend()
4853
Bram Moolenaar071d4272004-06-13 20:20:40 +00004854foldlevel({lnum}) *foldlevel()*
4855 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar58b85342016-08-14 19:54:54 +02004856 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004857 returned. If there is no fold at line {lnum}, zero is
4858 returned. It doesn't matter if the folds are open or closed.
4859 When used while updating folds (from 'foldexpr') -1 is
4860 returned for lines where folds are still to be updated and the
4861 foldlevel is unknown. As a special case the level of the
4862 previous line is usually available.
4863
Bram Moolenaara4208962019-08-24 20:50:19 +02004864 Can also be used as a |method|: >
4865 GetLnum()->foldlevel()
Bram Moolenaar2e693a82019-10-16 22:35:02 +02004866<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004867 *foldtext()*
4868foldtext() Returns a String, to be displayed for a closed fold. This is
4869 the default function used for the 'foldtext' option and should
4870 only be called from evaluating 'foldtext'. It uses the
4871 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
4872 The returned string looks like this: >
4873 +-- 45 lines: abcdef
Bram Moolenaar42205552017-03-18 19:42:22 +01004874< The number of leading dashes depends on the foldlevel. The
4875 "45" is the number of lines in the fold. "abcdef" is the text
4876 in the first non-blank line of the fold. Leading white space,
4877 "//" or "/*" and the text from the 'foldmarker' and
4878 'commentstring' options is removed.
4879 When used to draw the actual foldtext, the rest of the line
4880 will be filled with the fold char from the 'fillchars'
4881 setting.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004882 {not available when compiled without the |+folding| feature}
4883
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004884foldtextresult({lnum}) *foldtextresult()*
4885 Returns the text that is displayed for the closed fold at line
4886 {lnum}. Evaluates 'foldtext' in the appropriate context.
4887 When there is no closed fold at {lnum} an empty string is
4888 returned.
4889 {lnum} is used like with |getline()|. Thus "." is the current
4890 line, "'m" mark m, etc.
4891 Useful when exporting folded text, e.g., to HTML.
4892 {not available when compiled without the |+folding| feature}
4893
Bram Moolenaara4208962019-08-24 20:50:19 +02004894
4895 Can also be used as a |method|: >
4896 GetLnum()->foldtextresult()
4897<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004898 *foreground()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004899foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00004900 a client to a Vim server. |remote_send()|
4901 On Win32 systems this might not work, the OS does not always
4902 allow a window to bring itself to the foreground. Use
4903 |remote_foreground()| instead.
4904 {only in the Win32, Athena, Motif and GTK GUI versions and the
4905 Win32 console version}
4906
Bram Moolenaar038e09e2021-02-06 12:38:51 +01004907fullcommand({name}) *fullcommand()*
4908 Get the full command name from a short abbreviated command
4909 name; see |20.2| for details on command abbreviations.
4910
4911 {name} may start with a `:` and can include a [range], these
4912 are skipped and not returned.
4913 Returns an empty string if a command doesn't exist or if it's
4914 ambiguous (for user-defined functions).
4915
4916 For example `fullcommand('s')`, `fullcommand('sub')`,
4917 `fullcommand(':%substitute')` all return "substitute".
4918
4919 Can also be used as a |method|: >
4920 GetName()->fullcommand()
4921<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004922 *funcref()*
4923funcref({name} [, {arglist}] [, {dict}])
4924 Just like |function()|, but the returned Funcref will lookup
4925 the function by reference, not by name. This matters when the
4926 function {name} is redefined later.
4927
4928 Unlike |function()|, {name} must be an existing user function.
4929 Also for autoloaded functions. {name} cannot be a builtin
4930 function.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004931
Bram Moolenaara4208962019-08-24 20:50:19 +02004932 Can also be used as a |method|: >
4933 GetFuncname()->funcref([arg])
4934<
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004935 *function()* *E700* *E922* *E923*
4936function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004937 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01004938 {name} can be the name of a user defined function or an
4939 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004940
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004941 {name} can also be a Funcref or a partial. When it is a
Bram Moolenaar975b5272016-03-15 23:10:59 +01004942 partial the dict stored in it will be used and the {dict}
4943 argument is not allowed. E.g.: >
4944 let FuncWithArg = function(dict.Func, [arg])
4945 let Broken = function(dict.Func, [arg], dict)
4946<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004947 When using the Funcref the function will be found by {name},
4948 also when it was redefined later. Use |funcref()| to keep the
4949 same function.
4950
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004951 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02004952 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004953 the Funcref and will be used when the Funcref is called.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004954
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004955 The arguments are passed to the function in front of other
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004956 arguments, but after any argument from |method|. Example: >
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004957 func Callback(arg1, arg2, name)
4958 ...
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004959 let Partial = function('Callback', ['one', 'two'])
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004960 ...
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004961 call Partial('name')
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004962< Invokes the function as with: >
4963 call Callback('one', 'two', 'name')
4964
Bram Moolenaar088e8e32019-08-08 22:15:18 +02004965< With a |method|: >
4966 func Callback(one, two, three)
4967 ...
4968 let Partial = function('Callback', ['two'])
4969 ...
4970 eval 'one'->Partial('three')
4971< Invokes the function as with: >
4972 call Callback('one', 'two', 'three')
4973
Bram Moolenaar03602ec2016-03-20 20:57:45 +01004974< The function() call can be nested to add more arguments to the
4975 Funcref. The extra arguments are appended to the list of
4976 arguments. Example: >
4977 func Callback(arg1, arg2, name)
4978 ...
4979 let Func = function('Callback', ['one'])
4980 let Func2 = function(Func, ['two'])
4981 ...
4982 call Func2('name')
4983< Invokes the function as with: >
4984 call Callback('one', 'two', 'name')
4985
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004986< The Dictionary is only useful when calling a "dict" function.
4987 In that case the {dict} is passed in as "self". Example: >
4988 function Callback() dict
4989 echo "called for " . self.name
4990 endfunction
4991 ...
4992 let context = {"name": "example"}
4993 let Func = function('Callback', context)
4994 ...
4995 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01004996< The use of function() is not needed when there are no extra
4997 arguments, these two are equivalent: >
4998 let Func = function('Callback', context)
4999 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01005000
5001< The argument list and the Dictionary can be combined: >
5002 function Callback(arg1, count) dict
5003 ...
5004 let context = {"name": "example"}
5005 let Func = function('Callback', ['one'], context)
5006 ...
5007 call Func(500)
5008< Invokes the function as with: >
5009 call context.Callback('one', 500)
Bram Moolenaara4208962019-08-24 20:50:19 +02005010<
5011 Can also be used as a |method|: >
5012 GetFuncname()->function([arg])
Bram Moolenaar1735bc92016-03-14 23:05:14 +01005013
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005014
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01005015garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02005016 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
5017 that have circular references.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005018
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02005019 There is hardly ever a need to invoke this function, as it is
5020 automatically done when Vim runs out of memory or is waiting
5021 for the user to press a key after 'updatetime'. Items without
5022 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005023 This is useful if you have deleted a very big |List| and/or
5024 |Dictionary| with circular references in a script that runs
5025 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02005026
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01005027 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00005028 collection will also be done when exiting Vim, if it wasn't
5029 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00005030
Bram Moolenaar574860b2016-05-24 17:33:34 +02005031 The garbage collection is not done immediately but only when
5032 it's safe to perform. This is when waiting for the user to
5033 type a character. To force garbage collection immediately use
5034 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02005035
Bram Moolenaar677ee682005-01-27 14:41:15 +00005036get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005037 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005038 available return {default}. Return zero when {default} is
5039 omitted.
Bram Moolenaar7ff78462020-07-10 22:00:53 +02005040 Preferably used as a |method|: >
Bram Moolenaarac92e252019-08-03 21:58:38 +02005041 mylist->get(idx)
Bram Moolenaard8968242019-01-15 22:51:57 +01005042get({blob}, {idx} [, {default}])
5043 Get byte {idx} from |Blob| {blob}. When this byte is not
5044 available return {default}. Return -1 when {default} is
5045 omitted.
Bram Moolenaar7ff78462020-07-10 22:00:53 +02005046 Preferably used as a |method|: >
5047 myblob->get(idx)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005048get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005049 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005050 item is not available return {default}. Return zero when
Bram Moolenaar54775062019-07-31 21:07:14 +02005051 {default} is omitted. Useful example: >
5052 let val = get(g:, 'var_name', 'default')
5053< This gets the value of g:var_name if it exists, and uses
5054 'default' when it does not exist.
Bram Moolenaar7ff78462020-07-10 22:00:53 +02005055 Preferably used as a |method|: >
5056 mydict->get(key)
Bram Moolenaar03e19a02016-05-24 22:29:49 +02005057get({func}, {what})
5058 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02005059 {what} are:
Bram Moolenaar214641f2017-03-05 17:04:09 +01005060 "name" The function name
5061 "func" The function
5062 "dict" The dictionary
5063 "args" The list with arguments
Bram Moolenaar7ff78462020-07-10 22:00:53 +02005064 Preferably used as a |method|: >
5065 myfunc->get(what)
5066<
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005067 *getbufinfo()*
5068getbufinfo([{expr}])
5069getbufinfo([{dict}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02005070 Get information about buffers as a List of Dictionaries.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005071
5072 Without an argument information about all the buffers is
5073 returned.
5074
Bram Moolenaare46a4402020-06-30 20:38:27 +02005075 When the argument is a |Dictionary| only the buffers matching
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005076 the specified criteria are returned. The following keys can
5077 be specified in {dict}:
5078 buflisted include only listed buffers.
5079 bufloaded include only loaded buffers.
Bram Moolenaar8e6a31d2017-12-10 21:06:22 +01005080 bufmodified include only modified buffers.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005081
5082 Otherwise, {expr} specifies a particular buffer to return
5083 information for. For the use of {expr}, see |bufname()|
5084 above. If the buffer is found the returned List has one item.
5085 Otherwise the result is an empty list.
5086
5087 Each returned List item is a dictionary with the following
5088 entries:
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005089 bufnr Buffer number.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005090 changed TRUE if the buffer is modified.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005091 changedtick Number of changes made to the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005092 hidden TRUE if the buffer is hidden.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005093 lastused Timestamp in seconds, like
Bram Moolenaar52410572019-10-27 05:12:45 +01005094 |localtime()|, when the buffer was
5095 last used.
5096 {only with the |+viminfo| feature}
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005097 listed TRUE if the buffer is listed.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005098 lnum Line number used for the buffer when
5099 opened in the current window.
5100 linecount Number of lines in the buffer (only
Bram Moolenaara9e96792019-12-17 22:40:15 +01005101 valid when loaded)
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005102 loaded TRUE if the buffer is loaded.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005103 name Full path to the file in the buffer.
5104 signs List of signs placed in the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005105 Each list item is a dictionary with
5106 the following fields:
5107 id sign identifier
5108 lnum line number
5109 name sign name
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005110 variables A reference to the dictionary with
Bram Moolenaar30567352016-08-27 21:25:44 +02005111 buffer-local variables.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005112 windows List of |window-ID|s that display this
Bram Moolenaar30567352016-08-27 21:25:44 +02005113 buffer
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005114 popups List of popup |window-ID|s that
Bram Moolenaar5ca1ac32019-07-04 15:39:28 +02005115 display this buffer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005116
5117 Examples: >
5118 for buf in getbufinfo()
5119 echo buf.name
5120 endfor
5121 for buf in getbufinfo({'buflisted':1})
Bram Moolenaar30567352016-08-27 21:25:44 +02005122 if buf.changed
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005123 ....
5124 endif
5125 endfor
5126<
Bram Moolenaar30567352016-08-27 21:25:44 +02005127 To get buffer-local options use: >
Bram Moolenaard473c8c2018-08-11 18:00:22 +02005128 getbufvar({bufnr}, '&option_name')
Bram Moolenaar30567352016-08-27 21:25:44 +02005129<
Bram Moolenaar6434fc52020-07-18 22:24:22 +02005130 Can also be used as a |method|: >
5131 GetBufnr()->getbufinfo()
5132<
5133
Bram Moolenaar45360022005-07-21 21:08:21 +00005134 *getbufline()*
5135getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005136 Return a |List| with the lines starting from {lnum} to {end}
5137 (inclusive) in the buffer {expr}. If {end} is omitted, a
5138 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00005139
5140 For the use of {expr}, see |bufname()| above.
5141
Bram Moolenaar661b1822005-07-28 22:36:45 +00005142 For {lnum} and {end} "$" can be used for the last line of the
5143 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00005144
5145 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005146 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00005147
5148 When {end} is greater than the number of lines in the buffer,
5149 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005150 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00005151 returned.
5152
Bram Moolenaar661b1822005-07-28 22:36:45 +00005153 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005154 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00005155
5156 Example: >
5157 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005158
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005159< Can also be used as a |method|: >
5160 GetBufnr()->getbufline(lnum)
5161
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005162getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005163 The result is the value of option or local buffer variable
5164 {varname} in buffer {expr}. Note that the name without "b:"
5165 must be used.
Bram Moolenaar1b884a02020-12-10 21:11:27 +01005166 When {varname} is empty returns a |Dictionary| with all the
Bram Moolenaarc236c162008-07-13 17:41:49 +00005167 buffer-local variables.
Bram Moolenaar1b884a02020-12-10 21:11:27 +01005168 When {varname} is equal to "&" returns a |Dictionary| with all
Bram Moolenaar30567352016-08-27 21:25:44 +02005169 the buffer-local options.
5170 Otherwise, when {varname} starts with "&" returns the value of
5171 a buffer-local option.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00005172 This also works for a global or buffer-local option, but it
5173 doesn't work for a global variable, window-local variable or
5174 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005175 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005176 When the buffer or variable doesn't exist {def} or an empty
5177 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005178 Examples: >
5179 :let bufmodified = getbufvar(1, "&mod")
5180 :echo "todo myvar = " . getbufvar("todo", "myvar")
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005181
5182< Can also be used as a |method|: >
5183 GetBufnr()->getbufvar(varname)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005184<
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005185getchangelist([{expr}]) *getchangelist()*
Bram Moolenaar07ad8162018-02-13 13:59:59 +01005186 Returns the |changelist| for the buffer {expr}. For the use
5187 of {expr}, see |bufname()| above. If buffer {expr} doesn't
5188 exist, an empty list is returned.
5189
5190 The returned list contains two entries: a list with the change
5191 locations and the current position in the list. Each
5192 entry in the change list is a dictionary with the following
5193 entries:
5194 col column number
5195 coladd column offset for 'virtualedit'
5196 lnum line number
5197 If buffer {expr} is the current buffer, then the current
5198 position refers to the position in the list. For other
5199 buffers, it is set to the length of the list.
5200
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005201 Can also be used as a |method|: >
5202 GetBufnr()->getchangelist()
5203
Bram Moolenaar071d4272004-06-13 20:20:40 +00005204getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00005205 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005206 If [expr] is omitted, wait until a character is available.
5207 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00005208 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005209 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00005210 not consumed. Return zero if no character available.
5211
Bram Moolenaardfb18412013-12-11 18:53:29 +01005212 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaarc577d812017-07-08 22:37:34 +02005213 special key is returned. If it is a single character, the
Bram Moolenaar91170f82006-05-05 21:15:17 +00005214 result is a number. Use nr2char() to convert it to a String.
5215 Otherwise a String is returned with the encoded character.
Bram Moolenaarc577d812017-07-08 22:37:34 +02005216 For a special key it's a String with a sequence of bytes
5217 starting with 0x80 (decimal: 128). This is the same value as
5218 the String "\<Key>", e.g., "\<Left>". The returned value is
5219 also a String when a modifier (shift, control, alt) was used
5220 that is not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00005221
Bram Moolenaar822ff862014-06-12 21:46:14 +02005222 When [expr] is 0 and Esc is typed, there will be a short delay
5223 while Vim waits to see if this is the start of an escape
5224 sequence.
5225
Bram Moolenaardfb18412013-12-11 18:53:29 +01005226 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00005227 one-byte character it is the character itself as a number.
5228 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00005229
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01005230 Use getcharmod() to obtain any additional modifiers.
5231
Bram Moolenaar219b8702006-11-01 14:32:36 +00005232 When the user clicks a mouse button, the mouse event will be
5233 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaardb3a2052019-11-16 18:22:41 +01005234 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
Bram Moolenaarae97b942020-07-09 19:16:35 +02005235 |getmousepos()| can also be used. Mouse move events will be
5236 ignored.
5237 This example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00005238 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00005239 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00005240 exe v:mouse_win . "wincmd w"
5241 exe v:mouse_lnum
5242 exe "normal " . v:mouse_col . "|"
5243 endif
5244<
Bram Moolenaar690afe12017-01-28 18:34:47 +01005245 When using bracketed paste only the first character is
5246 returned, the rest of the pasted text is dropped.
5247 |xterm-bracketed-paste|.
5248
Bram Moolenaar071d4272004-06-13 20:20:40 +00005249 There is no prompt, you will somehow have to make clear to the
Bram Moolenaar4072ba52020-12-23 13:56:35 +01005250 user that a character has to be typed. The screen is not
5251 redrawn, e.g. when resizing the window. When using a popup
5252 window it should work better with a |popup-filter|.
5253
Bram Moolenaar071d4272004-06-13 20:20:40 +00005254 There is no mapping for the character.
5255 Key codes are replaced, thus when the user presses the <Del>
5256 key you get the code for the <Del> key, not the raw character
5257 sequence. Examples: >
5258 getchar() == "\<Del>"
5259 getchar() == "\<S-Left>"
5260< This example redefines "f" to ignore case: >
5261 :nmap f :call FindChar()<CR>
5262 :function FindChar()
5263 : let c = nr2char(getchar())
5264 : while col('.') < col('$') - 1
5265 : normal l
5266 : if getline('.')[col('.') - 1] ==? c
5267 : break
5268 : endif
5269 : endwhile
5270 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01005271<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01005272 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01005273 |<CursorHold>|. Often you will want to ignore this and get
5274 another character: >
5275 :function GetKey()
5276 : let c = getchar()
5277 : while c == "\<CursorHold>"
5278 : let c = getchar()
5279 : endwhile
5280 : return c
5281 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00005282
5283getcharmod() *getcharmod()*
5284 The result is a Number which is the state of the modifiers for
5285 the last obtained character with getchar() or in another way.
5286 These values are added together:
5287 2 shift
5288 4 control
5289 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01005290 16 meta (when it's different from ALT)
5291 32 mouse double click
5292 64 mouse triple click
5293 96 mouse quadruple click (== 32 + 64)
5294 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005295 Only the modifiers that have not been included in the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005296 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005297 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005298
Bram Moolenaar6f02b002021-01-10 20:22:54 +01005299 *getcharpos()*
5300getcharpos({expr})
5301 Get the position for {expr}. Same as |getpos()| but the column
5302 number in the returned List is a character index instead of
5303 a byte index.
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01005304 If |getpos()| returns a very large column number, such as
5305 2147483647, then getcharpos() will return the character index
5306 of the last character.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01005307
5308 Example:
5309 With the cursor on '세' in line 5 with text "여보세요": >
5310 getcharpos('.') returns [0, 5, 3, 0]
5311 getpos('.') returns [0, 5, 7, 0]
5312<
5313 Can also be used as a |method|: >
5314 GetMark()->getcharpos()
5315
Bram Moolenaardbd24b52015-08-11 14:26:19 +02005316getcharsearch() *getcharsearch()*
5317 Return the current character search information as a {dict}
5318 with the following entries:
5319
5320 char character previously used for a character
5321 search (|t|, |f|, |T|, or |F|); empty string
5322 if no character search has been performed
5323 forward direction of character search; 1 for forward,
5324 0 for backward
5325 until type of character search; 1 for a |t| or |T|
5326 character search, 0 for an |f| or |F|
5327 character search
5328
5329 This can be useful to always have |;| and |,| search
5330 forward/backward regardless of the direction of the previous
5331 character search: >
5332 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
5333 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
5334< Also see |setcharsearch()|.
5335
Bram Moolenaar071d4272004-06-13 20:20:40 +00005336getcmdline() *getcmdline()*
5337 Return the current command-line. Only works when the command
5338 line is being edited, thus requires use of |c_CTRL-\_e| or
5339 |c_CTRL-R_=|.
5340 Example: >
5341 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005342< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005343 Returns an empty string when entering a password or using
5344 |inputsecret()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005345
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005346getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005347 Return the position of the cursor in the command line as a
5348 byte count. The first column is 1.
5349 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02005350 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
5351 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005352 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
5353
5354getcmdtype() *getcmdtype()*
5355 Return the current command-line type. Possible return values
5356 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00005357 : normal Ex command
5358 > debug mode command |debug-mode|
5359 / forward search command
5360 ? backward search command
5361 @ |input()| command
5362 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02005363 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005364 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02005365 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
5366 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005367 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005368
Bram Moolenaarfb539272014-08-22 19:21:47 +02005369getcmdwintype() *getcmdwintype()*
5370 Return the current |command-line-window| type. Possible return
5371 values are the same as |getcmdtype()|. Returns an empty string
5372 when not in the command-line window.
5373
Bram Moolenaare9d58a62016-08-13 15:07:41 +02005374getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005375 Return a list of command-line completion matches. {type}
5376 specifies what for. The following completion types are
5377 supported:
5378
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02005379 arglist file names in argument list
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005380 augroup autocmd groups
5381 buffer buffer names
5382 behave :behave suboptions
5383 color color schemes
5384 command Ex command (and arguments)
Bram Moolenaar1f1fd442020-06-07 18:45:14 +02005385 cmdline |cmdline-completion| result
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005386 compiler compilers
5387 cscope |:cscope| suboptions
Bram Moolenaarae7dba82019-12-29 13:56:33 +01005388 diff_buffer |:diffget| and |:diffput| completion
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005389 dir directory names
5390 environment environment variable names
5391 event autocommand events
5392 expression Vim expression
5393 file file and directory names
5394 file_in_path file and directory names in |'path'|
5395 filetype filetype names |'filetype'|
5396 function function name
5397 help help subjects
5398 highlight highlight groups
5399 history :history suboptions
5400 locale locale names (as output of locale -a)
Bram Moolenaar73fef332020-06-21 22:12:03 +02005401 mapclear buffer argument
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005402 mapping mapping name
5403 menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02005404 messages |:messages| suboptions
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005405 option options
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02005406 packadd optional package |pack-add| names
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005407 shellcmd Shell command
5408 sign |:sign| suboptions
5409 syntax syntax file names |'syntax'|
5410 syntime |:syntime| suboptions
5411 tag tags
5412 tag_listfiles tags, file names
5413 user user names
5414 var user variables
5415
Bram Moolenaar1f1fd442020-06-07 18:45:14 +02005416 If {pat} is an empty string, then all the matches are
5417 returned. Otherwise only items matching {pat} are returned.
5418 See |wildcards| for the use of special characters in {pat}.
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005419
Bram Moolenaare9d58a62016-08-13 15:07:41 +02005420 If the optional {filtered} flag is set to 1, then 'wildignore'
5421 is applied to filter the results. Otherwise all the matches
5422 are returned. The 'wildignorecase' option always applies.
5423
Bram Moolenaar1f1fd442020-06-07 18:45:14 +02005424 If {type} is "cmdline", then the |cmdline-completion| result is
5425 returned. For example, to complete the possible values after
5426 a ":call" command: >
Bram Moolenaar73fef332020-06-21 22:12:03 +02005427 echo getcompletion('call ', 'cmdline')
Bram Moolenaar1f1fd442020-06-07 18:45:14 +02005428<
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02005429 If there are no matches, an empty list is returned. An
5430 invalid value for {type} produces an error.
5431
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005432 Can also be used as a |method|: >
5433 GetPattern()->getcompletion('color')
5434<
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005435 *getcurpos()*
Bram Moolenaar99ca9c42020-09-22 21:55:41 +02005436getcurpos([{winid}])
5437 Get the position of the cursor. This is like getpos('.'), but
Bram Moolenaard1caa942020-04-10 22:10:56 +02005438 includes an extra "curswant" item in the list:
5439 [0, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005440 The "curswant" number is the preferred column when moving the
Bram Moolenaar6f02b002021-01-10 20:22:54 +01005441 cursor vertically. Also see |getcursorcharpos()| and
5442 |getpos()|.
5443 The first "bufnum" item is always zero. The byte position of
5444 the cursor is returned in 'col'. To get the character
5445 position, use |getcursorcharpos()|.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005446
Bram Moolenaar99ca9c42020-09-22 21:55:41 +02005447 The optional {winid} argument can specify the window. It can
5448 be the window number or the |window-ID|. The last known
5449 cursor position is returned, this may be invalid for the
5450 current value of the buffer if it is not the current window.
5451 If {winid} is invalid a list with zeroes is returned.
5452
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02005453 This can be used to save and restore the cursor position: >
5454 let save_cursor = getcurpos()
5455 MoveTheCursorAround
5456 call setpos('.', save_cursor)
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005457< Note that this only works within the window. See
5458 |winrestview()| for restoring more state.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01005459
5460 Can also be used as a |method|: >
5461 GetWinid()->getcurpos()
5462
5463< *getcursorcharpos()*
5464getcursorcharpos([{winid}])
5465 Same as |getcurpos()| but the column number in the returned
5466 List is a character index instead of a byte index.
5467
5468 Example:
5469 With the cursor on '보' in line 3 with text "여보세요": >
5470 getcursorcharpos() returns [0, 3, 2, 0, 3]
5471 getcurpos() returns [0, 3, 4, 0, 3]
5472
5473< Can also be used as a |method|: >
5474 GetWinid()->getcursorcharpos()
5475
5476< *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01005477getcwd([{winnr} [, {tabnr}]])
5478 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00005479 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005480
5481 With {winnr} return the local current directory of this window
Bram Moolenaar54591292018-02-09 20:53:59 +01005482 in the current tab page. {winnr} can be the window number or
5483 the |window-ID|.
5484 If {winnr} is -1 return the name of the global working
5485 directory. See also |haslocaldir()|.
5486
Bram Moolenaarc9703302016-01-17 21:49:33 +01005487 With {winnr} and {tabnr} return the local current directory of
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005488 the window in the specified tab page. If {winnr} is -1 return
5489 the working directory of the tabpage.
5490 If {winnr} is zero use the current window, if {tabnr} is zero
5491 use the current tabpage.
5492 Without any arguments, return the working directory of the
5493 current window.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005494 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005495
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005496 Examples: >
5497 " Get the working directory of the current window
5498 :echo getcwd()
5499 :echo getcwd(0)
5500 :echo getcwd(0, 0)
5501 " Get the working directory of window 3 in tabpage 2
5502 :echo getcwd(3, 2)
5503 " Get the global working directory
5504 :echo getcwd(-1)
5505 " Get the working directory of tabpage 3
5506 :echo getcwd(-1, 3)
5507 " Get the working directory of current tabpage
5508 :echo getcwd(-1, 0)
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005509
5510< Can also be used as a |method|: >
5511 GetWinnr()->getcwd()
Bram Moolenaar00aa0692019-04-27 20:37:57 +02005512<
Bram Moolenaar691ddee2019-05-09 14:52:41 +02005513getenv({name}) *getenv()*
5514 Return the value of environment variable {name}.
5515 When the variable does not exist |v:null| is returned. That
Bram Moolenaar54775062019-07-31 21:07:14 +02005516 is different from a variable set to an empty string, although
5517 some systems interpret the empty value as the variable being
5518 deleted. See also |expr-env|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005519
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005520 Can also be used as a |method|: >
5521 GetVarname()->getenv()
5522
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005523getfontname([{name}]) *getfontname()*
5524 Without an argument returns the name of the normal font being
5525 used. Like what is used for the Normal highlight group
5526 |hl-Normal|.
5527 With an argument a check is done whether {name} is a valid
5528 font name. If not then an empty string is returned.
5529 Otherwise the actual font name is returned, or {name} if the
5530 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00005531 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005532 gvimrc file. Use the |GUIEnter| autocommand to use this
5533 function just after the GUI has started.
Bram Moolenaar3df01732017-02-17 22:47:16 +01005534 Note that the GTK GUI accepts any font name, thus checking for
5535 a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00005536
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005537getfperm({fname}) *getfperm()*
5538 The result is a String, which is the read, write, and execute
5539 permissions of the given file {fname}.
5540 If {fname} does not exist or its directory cannot be read, an
5541 empty string is returned.
5542 The result is of the form "rwxrwxrwx", where each group of
5543 "rwx" flags represent, in turn, the permissions of the owner
5544 of the file, the group the file belongs to, and other users.
5545 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02005546 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005547 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02005548 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005549< This will hopefully (from a security point of view) display
5550 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00005551
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005552 Can also be used as a |method|: >
5553 GetFilename()->getfperm()
5554<
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02005555 For setting permissions use |setfperm()|.
Bram Moolenaar80492532016-03-08 17:08:53 +01005556
Bram Moolenaar691ddee2019-05-09 14:52:41 +02005557getfsize({fname}) *getfsize()*
5558 The result is a Number, which is the size in bytes of the
5559 given file {fname}.
5560 If {fname} is a directory, 0 is returned.
5561 If the file {fname} can't be found, -1 is returned.
5562 If the size of {fname} is too big to fit in a Number then -2
5563 is returned.
5564
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005565 Can also be used as a |method|: >
5566 GetFilename()->getfsize()
5567
Bram Moolenaar071d4272004-06-13 20:20:40 +00005568getftime({fname}) *getftime()*
5569 The result is a Number, which is the last modification time of
5570 the given file {fname}. The value is measured as seconds
5571 since 1st Jan 1970, and may be passed to strftime(). See also
5572 |localtime()| and |strftime()|.
5573 If the file {fname} can't be found -1 is returned.
5574
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005575 Can also be used as a |method|: >
5576 GetFilename()->getftime()
5577
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005578getftype({fname}) *getftype()*
5579 The result is a String, which is a description of the kind of
5580 file of the given file {fname}.
5581 If {fname} does not exist an empty string is returned.
5582 Here is a table over different kinds of files and their
5583 results:
5584 Normal file "file"
5585 Directory "dir"
5586 Symbolic link "link"
5587 Block device "bdev"
5588 Character device "cdev"
5589 Socket "socket"
5590 FIFO "fifo"
5591 All other "other"
5592 Example: >
5593 getftype("/home")
5594< Note that a type such as "link" will only be returned on
5595 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01005596 "file" are returned. On MS-Windows a symbolic link to a
5597 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00005598
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005599 Can also be used as a |method|: >
5600 GetFilename()->getftype()
5601
Bram Moolenaara3a12462019-09-07 15:08:38 +02005602getimstatus() *getimstatus()*
5603 The result is a Number, which is |TRUE| when the IME status is
5604 active.
5605 See 'imstatusfunc'.
5606
Bram Moolenaard96ff162018-02-18 22:13:29 +01005607getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
Bram Moolenaar4f505882018-02-10 21:06:32 +01005608 Returns the |jumplist| for the specified window.
5609
5610 Without arguments use the current window.
5611 With {winnr} only use this window in the current tab page.
5612 {winnr} can also be a |window-ID|.
5613 With {winnr} and {tabnr} use the window in the specified tab
5614 page.
5615
5616 The returned list contains two entries: a list with the jump
5617 locations and the last used jump position number in the list.
5618 Each entry in the jump location list is a dictionary with
5619 the following entries:
5620 bufnr buffer number
5621 col column number
5622 coladd column offset for 'virtualedit'
5623 filename filename if available
5624 lnum line number
5625
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005626 Can also be used as a |method|: >
5627 GetWinnr()->getjumplist()
5628
5629< *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005630getline({lnum} [, {end}])
5631 Without {end} the result is a String, which is line {lnum}
5632 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005633 getline(1)
5634< When {lnum} is a String that doesn't start with a
Bram Moolenaarf2732452018-06-03 14:47:35 +02005635 digit, |line()| is called to translate the String into a Number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005636 To get the line under the cursor: >
5637 getline(".")
5638< When {lnum} is smaller than 1 or bigger than the number of
5639 lines in the buffer, an empty string is returned.
5640
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005641 When {end} is given the result is a |List| where each item is
5642 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005643 including line {end}.
5644 {end} is used in the same way as {lnum}.
5645 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005646 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005647 Example: >
5648 :let start = line('.')
5649 :let end = search("^$") - 1
5650 :let lines = getline(start, end)
5651
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005652< Can also be used as a |method|: >
5653 ComputeLnum()->getline()
5654
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005655< To get lines from another buffer see |getbufline()|
5656
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005657getloclist({nr} [, {what}]) *getloclist()*
Bram Moolenaare46a4402020-06-30 20:38:27 +02005658 Returns a |List| with all the entries in the location list for
Bram Moolenaar7571d552016-08-18 22:54:46 +02005659 window {nr}. {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02005660 When {nr} is zero the current window is used.
5661
Bram Moolenaar17c7c012006-01-26 22:25:15 +00005662 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00005663 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005664 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005665
Bram Moolenaard823fa92016-08-12 16:29:27 +02005666 If the optional {what} dictionary argument is supplied, then
5667 returns the items listed in {what} as a dictionary. Refer to
5668 |getqflist()| for the supported items in {what}.
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005669
5670 In addition to the items supported by |getqflist()| in {what},
5671 the following item is supported by |getloclist()|:
5672
Bram Moolenaar68e65602019-05-26 21:33:31 +02005673 filewinid id of the window used to display files
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005674 from the location list. This field is
5675 applicable only when called from a
5676 location list window. See
5677 |location-list-file-window| for more
5678 details.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005679
Bram Moolenaar1b884a02020-12-10 21:11:27 +01005680 Returns a |Dictionary| with default values if there is no
5681 location list for the window {nr}.
Bram Moolenaar99ca9c42020-09-22 21:55:41 +02005682 Returns an empty Dictionary if window {nr} does not exist.
Bram Moolenaare46a4402020-06-30 20:38:27 +02005683
5684 Examples (See also |getqflist-examples|): >
5685 :echo getloclist(3, {'all': 0})
5686 :echo getloclist(5, {'filewinid': 0})
5687
5688
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02005689getmarklist([{expr}]) *getmarklist()*
Bram Moolenaarcfb4b472020-05-31 15:41:57 +02005690 Without the {expr} argument returns a |List| with information
5691 about all the global marks. |mark|
5692
5693 If the optional {expr} argument is specified, returns the
5694 local marks defined in buffer {expr}. For the use of {expr},
5695 see |bufname()|.
5696
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02005697 Each item in the returned List is a |Dict| with the following:
Bram Moolenaarcfb4b472020-05-31 15:41:57 +02005698 name - name of the mark prefixed by "'"
5699 pos - a |List| with the position of the mark:
5700 [bufnum, lnum, col, off]
5701 Refer to |getpos()| for more information.
5702 file - file name
5703
5704 Refer to |getpos()| for getting information about a specific
5705 mark.
5706
Bram Moolenaarf17e7ea2020-06-01 14:14:44 +02005707 Can also be used as a |method|: >
5708 GetBufnr()->getmarklist()
Bram Moolenaarcfb4b472020-05-31 15:41:57 +02005709
Bram Moolenaaraff74912019-03-30 18:11:49 +01005710getmatches([{win}]) *getmatches()*
Bram Moolenaarfd133322019-03-29 12:20:27 +01005711 Returns a |List| with all matches previously defined for the
5712 current window by |matchadd()| and the |:match| commands.
5713 |getmatches()| is useful in combination with |setmatches()|,
5714 as |setmatches()| can restore a list of matches saved by
5715 |getmatches()|.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005716 Example: >
5717 :echo getmatches()
5718< [{'group': 'MyGroup1', 'pattern': 'TODO',
5719 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5720 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5721 :let m = getmatches()
5722 :call clearmatches()
5723 :echo getmatches()
5724< [] >
5725 :call setmatches(m)
5726 :echo getmatches()
5727< [{'group': 'MyGroup1', 'pattern': 'TODO',
5728 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
5729 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
5730 :unlet m
5731<
Bram Moolenaardb3a2052019-11-16 18:22:41 +01005732getmousepos() *getmousepos()*
Bram Moolenaare46a4402020-06-30 20:38:27 +02005733 Returns a |Dictionary| with the last known position of the
Bram Moolenaardb3a2052019-11-16 18:22:41 +01005734 mouse. This can be used in a mapping for a mouse click or in
5735 a filter of a popup window. The items are:
5736 screenrow screen row
5737 screencol screen column
5738 winid Window ID of the click
5739 winrow row inside "winid"
5740 wincol column inside "winid"
5741 line text line inside "winid"
5742 column text column inside "winid"
5743 All numbers are 1-based.
5744
5745 If not over a window, e.g. when in the command line, then only
5746 "screenrow" and "screencol" are valid, the others are zero.
5747
5748 When on the status line below a window or the vertical
Bram Moolenaarebacddb2020-06-04 15:22:21 +02005749 separator right of a window, the "line" and "column" values
Bram Moolenaardb3a2052019-11-16 18:22:41 +01005750 are zero.
5751
5752 When the position is after the text then "column" is the
5753 length of the text in bytes.
5754
5755 If the mouse is over a popup window then that window is used.
5756
5757
5758 When using |getchar()| the Vim variables |v:mouse_lnum|,
5759 |v:mouse_col| and |v:mouse_winid| also provide these values.
5760
Bram Moolenaar822ff862014-06-12 21:46:14 +02005761 *getpid()*
5762getpid() Return a Number which is the process ID of the Vim process.
5763 On Unix and MS-Windows this is a unique number, until Vim
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005764 exits.
Bram Moolenaar822ff862014-06-12 21:46:14 +02005765
5766 *getpos()*
5767getpos({expr}) Get the position for {expr}. For possible values of {expr}
5768 see |line()|. For getting the cursor position see
5769 |getcurpos()|.
5770 The result is a |List| with four numbers:
5771 [bufnum, lnum, col, off]
5772 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
5773 is the buffer number of the mark.
5774 "lnum" and "col" are the position in the buffer. The first
5775 column is 1.
5776 The "off" number is zero, unless 'virtualedit' is used. Then
5777 it is the offset in screen columns from the start of the
5778 character. E.g., a position within a <Tab> or after the last
5779 character.
5780 Note that for '< and '> Visual mode matters: when it is "V"
5781 (visual line mode) the column of '< is zero and the column of
5782 '> is a large number.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01005783 The column number in the returned List is the byte position
5784 within the line. To get the character position in the line,
5785 use |getcharpos()|
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01005786 The column number can be very large, e.g. 2147483647, in which
5787 case it means "after the end of the line".
Bram Moolenaar822ff862014-06-12 21:46:14 +02005788 This can be used to save and restore the position of a mark: >
5789 let save_a_mark = getpos("'a")
5790 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01005791 call setpos("'a", save_a_mark)
Bram Moolenaar6f02b002021-01-10 20:22:54 +01005792< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Bram Moolenaar822ff862014-06-12 21:46:14 +02005793
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005794 Can also be used as a |method|: >
5795 GetMark()->getpos()
5796
Bram Moolenaard823fa92016-08-12 16:29:27 +02005797getqflist([{what}]) *getqflist()*
Bram Moolenaar1b884a02020-12-10 21:11:27 +01005798 Returns a |List| with all the current quickfix errors. Each
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005799 list item is a dictionary with these entries:
5800 bufnr number of buffer that has the file name, use
5801 bufname() to get the name
Bram Moolenaard76ce852018-05-01 15:02:04 +02005802 module module name
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005803 lnum line number in the buffer (first line is 1)
5804 col column number (first column is 1)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005805 vcol |TRUE|: "col" is visual column
5806 |FALSE|: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005807 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005808 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005809 text description of the error
5810 type type of the error, 'E', '1', etc.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005811 valid |TRUE|: recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005812
Bram Moolenaar7571d552016-08-18 22:54:46 +02005813 When there is no error list or it's empty, an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005814 returned. Quickfix list entries with non-existing buffer
5815 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00005816
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005817 Useful application: Find pattern matches in multiple files and
5818 do something with them: >
5819 :vimgrep /theword/jg *.c
5820 :for d in getqflist()
5821 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
5822 :endfor
Bram Moolenaard823fa92016-08-12 16:29:27 +02005823<
5824 If the optional {what} dictionary argument is supplied, then
5825 returns only the items listed in {what} as a dictionary. The
5826 following string items are supported in {what}:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005827 changedtick get the total number of changes made
Bram Moolenaar15142e22018-04-30 22:19:58 +02005828 to the list |quickfix-changedtick|
5829 context get the |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02005830 efm errorformat to use when parsing "lines". If
Bram Moolenaar2f058492017-11-30 20:27:52 +01005831 not present, then the 'errorformat' option
Bram Moolenaar36538222017-09-02 19:51:44 +02005832 value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005833 id get information for the quickfix list with
5834 |quickfix-ID|; zero means the id for the
Bram Moolenaar2f058492017-11-30 20:27:52 +01005835 current list or the list specified by "nr"
Bram Moolenaar858ba062020-05-31 23:11:59 +02005836 idx get information for the quickfix entry at this
5837 index in the list specified by 'id' or 'nr'.
5838 If set to zero, then uses the current entry.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005839 See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02005840 items quickfix list entries
Bram Moolenaar15142e22018-04-30 22:19:58 +02005841 lines parse a list of lines using 'efm' and return
5842 the resulting entries. Only a |List| type is
5843 accepted. The current quickfix list is not
5844 modified. See |quickfix-parse|.
Bram Moolenaar890680c2016-09-27 21:28:56 +02005845 nr get information for this quickfix list; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02005846 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02005847 the last quickfix list
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005848 qfbufnr number of the buffer displayed in the quickfix
5849 window. Returns 0 if the quickfix buffer is
5850 not present. See |quickfix-buffer|.
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02005851 size number of entries in the quickfix list
Bram Moolenaar15142e22018-04-30 22:19:58 +02005852 title get the list title |quickfix-title|
Bram Moolenaar74240d32017-12-10 15:26:15 +01005853 winid get the quickfix |window-ID|
Bram Moolenaard823fa92016-08-12 16:29:27 +02005854 all all of the above quickfix properties
Bram Moolenaar74240d32017-12-10 15:26:15 +01005855 Non-string items in {what} are ignored. To get the value of a
Bram Moolenaara6d48492017-12-12 22:45:31 +01005856 particular item, set it to zero.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005857 If "nr" is not present then the current quickfix list is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005858 If both "nr" and a non-zero "id" are specified, then the list
5859 specified by "id" is used.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005860 To get the number of lists in the quickfix stack, set "nr" to
5861 "$" in {what}. The "nr" value in the returned dictionary
Bram Moolenaar875feea2017-06-11 16:07:51 +02005862 contains the quickfix stack size.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005863 When "lines" is specified, all the other items except "efm"
5864 are ignored. The returned dictionary contains the entry
5865 "items" with the list of entries.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005866
Bram Moolenaard823fa92016-08-12 16:29:27 +02005867 The returned dictionary contains the following entries:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005868 changedtick total number of changes made to the
5869 list |quickfix-changedtick|
Bram Moolenaar15142e22018-04-30 22:19:58 +02005870 context quickfix list context. See |quickfix-context|
Bram Moolenaara6d48492017-12-12 22:45:31 +01005871 If not present, set to "".
5872 id quickfix list ID |quickfix-ID|. If not
5873 present, set to 0.
Bram Moolenaar858ba062020-05-31 23:11:59 +02005874 idx index of the quickfix entry in the list. If not
Bram Moolenaara6d48492017-12-12 22:45:31 +01005875 present, set to 0.
5876 items quickfix list entries. If not present, set to
5877 an empty list.
5878 nr quickfix list number. If not present, set to 0
Bram Moolenaar647e24b2019-03-17 16:39:46 +01005879 qfbufnr number of the buffer displayed in the quickfix
5880 window. If not present, set to 0.
Bram Moolenaara6d48492017-12-12 22:45:31 +01005881 size number of entries in the quickfix list. If not
5882 present, set to 0.
5883 title quickfix list title text. If not present, set
5884 to "".
Bram Moolenaar74240d32017-12-10 15:26:15 +01005885 winid quickfix |window-ID|. If not present, set to 0
Bram Moolenaard823fa92016-08-12 16:29:27 +02005886
Bram Moolenaar15142e22018-04-30 22:19:58 +02005887 Examples (See also |getqflist-examples|): >
Bram Moolenaard823fa92016-08-12 16:29:27 +02005888 :echo getqflist({'all': 1})
5889 :echo getqflist({'nr': 2, 'title': 1})
Bram Moolenaar2c809b72017-09-01 18:34:02 +02005890 :echo getqflist({'lines' : ["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02005891<
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005892getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005893 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005894 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005895 :let cliptext = getreg('*')
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005896< When {regname} was not set the result is an empty string.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005897
5898 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005899 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005900 getreg('=', 1) returns the expression itself, so that it can
5901 be restored with |setreg()|. For other registers the extra
5902 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005903
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005904 If {list} is present and |TRUE|, the result type is changed
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005905 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005906 about zero bytes possibly present inside register: without
5907 third argument both NLs and zero bytes are represented as NLs
5908 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005909 When the register was not set an empty list is returned.
5910
Bram Moolenaar071d4272004-06-13 20:20:40 +00005911 If {regname} is not specified, |v:register| is used.
Bram Moolenaar942db232021-02-13 18:14:48 +01005912 In |Vim9-script| {regname} must be one character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005913
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005914 Can also be used as a |method|: >
5915 GetRegname()->getreg()
5916
Bram Moolenaarbb861e22020-06-07 18:16:36 +02005917getreginfo([{regname}]) *getreginfo()*
5918 Returns detailed information about register {regname} as a
5919 Dictionary with the following entries:
5920 regcontents List of lines contained in register
5921 {regname}, like
5922 |getreg|({regname}, 1, 1).
5923 regtype the type of register {regname}, as in
5924 |getregtype()|.
5925 isunnamed Boolean flag, v:true if this register
5926 is currently pointed to by the unnamed
5927 register.
5928 points_to for the unnamed register, gives the
5929 single letter name of the register
5930 currently pointed to (see |quotequote|).
5931 For example, after deleting a line
5932 with `dd`, this field will be "1",
5933 which is the register that got the
5934 deleted text.
5935
5936 If {regname} is invalid or not set, an empty Dictionary
5937 will be returned.
5938 If {regname} is not specified, |v:register| is used.
Bram Moolenaar207f0092020-08-30 17:20:20 +02005939 The returned Dictionary can be passed to |setreg()|.
Bram Moolenaar942db232021-02-13 18:14:48 +01005940 In |Vim9-script| {regname} must be one character.
Bram Moolenaarbb861e22020-06-07 18:16:36 +02005941
5942 Can also be used as a |method|: >
5943 GetRegname()->getreginfo()
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005944
Bram Moolenaar071d4272004-06-13 20:20:40 +00005945getregtype([{regname}]) *getregtype()*
5946 The result is a String, which is type of register {regname}.
5947 The value will be one of:
5948 "v" for |characterwise| text
5949 "V" for |linewise| text
5950 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01005951 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00005952 <CTRL-V> is one character with value 0x16.
5953 If {regname} is not specified, |v:register| is used.
Bram Moolenaar942db232021-02-13 18:14:48 +01005954 In |Vim9-script| {regname} must be one character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005955
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005956 Can also be used as a |method|: >
5957 GetRegname()->getregtype()
5958
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005959gettabinfo([{arg}]) *gettabinfo()*
5960 If {arg} is not specified, then information about all the tab
Bram Moolenaare46a4402020-06-30 20:38:27 +02005961 pages is returned as a |List|. Each List item is a |Dictionary|.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005962 Otherwise, {arg} specifies the tab page number and information
5963 about that one is returned. If the tab page does not exist an
5964 empty List is returned.
5965
Bram Moolenaare46a4402020-06-30 20:38:27 +02005966 Each List item is a |Dictionary| with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02005967 tabnr tab page number.
Bram Moolenaar30567352016-08-27 21:25:44 +02005968 variables a reference to the dictionary with
5969 tabpage-local variables
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005970 windows List of |window-ID|s in the tab page.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005971
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005972 Can also be used as a |method|: >
5973 GetTabnr()->gettabinfo()
5974
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005975gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005976 Get the value of a tab-local variable {varname} in tab page
5977 {tabnr}. |t:var|
5978 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02005979 When {varname} is empty a dictionary with all tab-local
5980 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005981 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005982 When the tab or variable doesn't exist {def} or an empty
5983 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005984
Bram Moolenaar4c313b12019-08-24 22:58:31 +02005985 Can also be used as a |method|: >
5986 GetTabnr()->gettabvar(varname)
5987
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005988gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005989 Get the value of window-local variable {varname} in window
5990 {winnr} in tab page {tabnr}.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005991 When {varname} is empty a dictionary with all window-local
5992 variables is returned.
Bram Moolenaar30567352016-08-27 21:25:44 +02005993 When {varname} is equal to "&" get the values of all
Bram Moolenaare46a4402020-06-30 20:38:27 +02005994 window-local options in a |Dictionary|.
Bram Moolenaar30567352016-08-27 21:25:44 +02005995 Otherwise, when {varname} starts with "&" get the value of a
5996 window-local option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005997 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005998 Tabs are numbered starting with one. For the current tabpage
5999 use |getwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02006000 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006001 When {winnr} is zero the current window is used.
6002 This also works for a global option, buffer-local option and
6003 window-local option, but it doesn't work for a global variable
6004 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01006005 When the tab, window or variable doesn't exist {def} or an
6006 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006007 Examples: >
6008 :let list_is_on = gettabwinvar(1, 2, '&list')
6009 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00006010<
Bram Moolenaarb477af22018-07-15 20:20:18 +02006011 To obtain all window-local variables use: >
6012 gettabwinvar({tabnr}, {winnr}, '&')
6013
Bram Moolenaar4c313b12019-08-24 22:58:31 +02006014< Can also be used as a |method|: >
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006015 GetTabnr()->gettabwinvar(winnr, varname)
Bram Moolenaar4c313b12019-08-24 22:58:31 +02006016
Bram Moolenaarf49cc602018-11-11 15:21:05 +01006017gettagstack([{nr}]) *gettagstack()*
6018 The result is a Dict, which is the tag stack of window {nr}.
6019 {nr} can be the window number or the |window-ID|.
6020 When {nr} is not specified, the current window is used.
6021 When window {nr} doesn't exist, an empty Dict is returned.
6022
6023 The returned dictionary contains the following entries:
6024 curidx Current index in the stack. When at
6025 top of the stack, set to (length + 1).
6026 Index of bottom of the stack is 1.
6027 items List of items in the stack. Each item
6028 is a dictionary containing the
6029 entries described below.
6030 length Number of entries in the stack.
6031
6032 Each item in the stack is a dictionary with the following
6033 entries:
6034 bufnr buffer number of the current jump
6035 from cursor position before the tag jump.
6036 See |getpos()| for the format of the
6037 returned list.
6038 matchnr current matching tag number. Used when
6039 multiple matching tags are found for a
6040 name.
6041 tagname name of the tag
6042
6043 See |tagstack| for more information about the tag stack.
6044
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006045 Can also be used as a |method|: >
6046 GetWinnr()->gettagstack()
6047
Bram Moolenaar0b39c3f2020-08-30 15:52:10 +02006048
6049gettext({text}) *gettext()*
6050 Translate {text} if possible.
6051 This is mainly for use in the distributed Vim scripts. When
6052 generating message translations the {text} is extracted by
6053 xgettext, the translator can add the translated message in the
6054 .po file and Vim will lookup the translation when gettext() is
6055 called.
6056 For {text} double quoted strings are preferred, because
6057 xgettext does not understand escaping in single quoted
6058 strings.
6059
6060
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006061getwininfo([{winid}]) *getwininfo()*
Bram Moolenaare46a4402020-06-30 20:38:27 +02006062 Returns information about windows as a |List| with Dictionaries.
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006063
6064 If {winid} is given Information about the window with that ID
Bram Moolenaare46a4402020-06-30 20:38:27 +02006065 is returned, as a |List| with one item. If the window does not
Bram Moolenaar73fef332020-06-21 22:12:03 +02006066 exist the result is an empty list.
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006067
6068 Without {winid} information about all the windows in all the
6069 tab pages is returned.
6070
Bram Moolenaare46a4402020-06-30 20:38:27 +02006071 Each List item is a |Dictionary| with the following entries:
Bram Moolenaar8fcb60f2019-03-04 13:18:30 +01006072 botline last displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006073 bufnr number of buffer in the window
6074 height window height (excluding winbar)
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006075 loclist 1 if showing a location list
6076 {only with the +quickfix feature}
6077 quickfix 1 if quickfix or location list window
6078 {only with the +quickfix feature}
6079 terminal 1 if a terminal window
6080 {only with the +terminal feature}
6081 tabnr tab page number
Bram Moolenaar10455d42019-11-21 15:36:18 +01006082 topline first displayed buffer line
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006083 variables a reference to the dictionary with
6084 window-local variables
6085 width window width
Bram Moolenaarb477af22018-07-15 20:20:18 +02006086 winbar 1 if the window has a toolbar, 0
6087 otherwise
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02006088 wincol leftmost screen column of the window,
6089 col from |win_screenpos()|
6090 winid |window-ID|
6091 winnr window number
6092 winrow topmost screen column of the window,
6093 row from |win_screenpos()|
6094
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006095 Can also be used as a |method|: >
6096 GetWinnr()->getwininfo()
6097
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01006098getwinpos([{timeout}]) *getwinpos()*
Bram Moolenaare46a4402020-06-30 20:38:27 +02006099 The result is a |List| with two numbers, the result of
Bram Moolenaar10455d42019-11-21 15:36:18 +01006100 |getwinposx()| and |getwinposy()| combined:
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01006101 [x-pos, y-pos]
6102 {timeout} can be used to specify how long to wait in msec for
6103 a response from the terminal. When omitted 100 msec is used.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006104 Use a longer time for a remote terminal.
6105 When using a value less than 10 and no response is received
6106 within that time, a previously reported position is returned,
6107 if available. This can be used to poll for the position and
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006108 do some work in the meantime: >
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006109 while 1
6110 let res = getwinpos(1)
6111 if res[0] >= 0
6112 break
6113 endif
6114 " Do some work here
6115 endwhile
6116<
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006117
6118 Can also be used as a |method|: >
6119 GetTimeout()->getwinpos()
6120<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006121 *getwinposx()*
6122getwinposx() The result is a Number, which is the X coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006123 the left hand side of the GUI Vim window. Also works for an
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01006124 xterm (uses a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006125 The result will be -1 if the information is not available.
6126 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006127
6128 *getwinposy()*
6129getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01006130 the top of the GUI Vim window. Also works for an xterm (uses
6131 a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006132 The result will be -1 if the information is not available.
6133 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006134
Bram Moolenaar63dbda12013-02-20 21:12:10 +01006135getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00006136 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006137 Examples: >
6138 :let list_is_on = getwinvar(2, '&list')
6139 :echo "myvar = " . getwinvar(1, 'myvar')
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006140
6141< Can also be used as a |method|: >
6142 GetWinnr()->getwinvar(varname)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006143<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01006144glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00006145 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006146 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01006147
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006148 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00006149 the 'suffixes' and 'wildignore' options apply: Names matching
6150 one of the patterns in 'wildignore' will be skipped and
6151 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01006152 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01006153
Bram Moolenaare46a4402020-06-30 20:38:27 +02006154 When {list} is present and it is |TRUE| the result is a |List|
Bram Moolenaar84f72352012-03-11 15:57:40 +01006155 with all matching files. The advantage of using a List is,
6156 you also get filenames containing newlines correctly.
6157 Otherwise the result is a String and when there are several
6158 matches, they are separated by <NL> characters.
6159
6160 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01006161
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02006162 You can also use |readdir()| if you need to do complicated
6163 things, such as limiting the number of matches.
6164
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006165 A name for a non-existing file is not included. A symbolic
6166 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01006167 However, when the {alllinks} argument is present and it is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006168 |TRUE| then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006169
6170 For most systems backticks can be used to get files names from
6171 any external command. Example: >
6172 :let tagfiles = glob("`find . -name tags -print`")
6173 :let &tags = substitute(tagfiles, "\n", ",", "g")
6174< The result of the program inside the backticks should be one
Bram Moolenaar58b85342016-08-14 19:54:54 +02006175 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006176
6177 See |expand()| for expanding special Vim variables. See
6178 |system()| for getting the raw output of an external command.
6179
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006180 Can also be used as a |method|: >
6181 GetExpr()->glob()
6182
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01006183glob2regpat({expr}) *glob2regpat()*
6184 Convert a file pattern, as used by glob(), into a search
6185 pattern. The result can be used to match with a string that
6186 is a file name. E.g. >
6187 if filename =~ glob2regpat('Make*.mak')
6188< This is equivalent to: >
6189 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01006190< When {expr} is an empty string the result is "^$", match an
6191 empty string.
Bram Moolenaard823fa92016-08-12 16:29:27 +02006192 Note that the result depends on the system. On MS-Windows
Bram Moolenaar58b85342016-08-14 19:54:54 +02006193 a backslash usually means a path separator.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01006194
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006195 Can also be used as a |method|: >
6196 GetExpr()->glob2regpat()
6197< *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006198globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006199 Perform glob() for {expr} on all directories in {path} and
6200 concatenate the results. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006201 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02006202<
6203 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00006204 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00006205 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006206 To add a comma inside a directory name escape it with a
6207 backslash. Note that on MS-Windows a directory may have a
6208 trailing backslash, remove it if you put a comma after it.
6209 If the expansion fails for one of the directories, there is no
6210 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02006211
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006212 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00006213 the 'suffixes' and 'wildignore' options apply: Names matching
6214 one of the patterns in 'wildignore' will be skipped and
6215 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006216
Bram Moolenaare46a4402020-06-30 20:38:27 +02006217 When {list} is present and it is |TRUE| the result is a |List|
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02006218 with all matching files. The advantage of using a List is, you
6219 also get filenames containing newlines correctly. Otherwise
6220 the result is a String and when there are several matches,
6221 they are separated by <NL> characters. Example: >
6222 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
6223<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006224 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01006225
Bram Moolenaar02743632005-07-25 20:42:36 +00006226 The "**" item can be used to search in a directory tree.
6227 For example, to find all "README.txt" files in the directories
6228 in 'runtimepath' and below: >
6229 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00006230< Upwards search and limiting the depth of "**" is not
6231 supported, thus using 'path' will not always work properly.
6232
Bram Moolenaar5d69fdb2019-08-31 19:13:58 +02006233 Can also be used as a |method|, the base is passed as the
6234 second argument: >
6235 GetExpr()->globpath(&rtp)
6236<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006237 *has()*
Bram Moolenaar79296512020-03-22 16:17:14 +01006238has({feature} [, {check}])
6239 When {check} is omitted or is zero: The result is a Number,
6240 which is 1 if the feature {feature} is supported, zero
6241 otherwise. The {feature} argument is a string, case is
6242 ignored. See |feature-list| below.
6243
6244 When {check} is present and not zero: The result is a Number,
6245 which is 1 if the feature {feature} could ever be supported,
6246 zero otherwise. This is useful to check for a typo in
Bram Moolenaar191acfd2020-03-27 20:42:43 +01006247 {feature} and to detect dead code. Keep in mind that an older
6248 Vim version will not know about a feature added later and
Bram Moolenaar207f0092020-08-30 17:20:20 +02006249 features that have been abandoned will not be known by the
Bram Moolenaar191acfd2020-03-27 20:42:43 +01006250 current Vim version.
Bram Moolenaar79296512020-03-22 16:17:14 +01006251
Bram Moolenaar071d4272004-06-13 20:20:40 +00006252 Also see |exists()|.
Bram Moolenaar79296512020-03-22 16:17:14 +01006253
Bram Moolenaarb17893a2020-03-14 08:19:51 +01006254 Note that to skip code that has a syntax error when the
6255 feature is not available, Vim may skip the rest of the line
Bram Moolenaar7ceefb32020-05-01 16:07:38 +02006256 and miss a following `endif`. Therefore put the `endif` on a
Bram Moolenaarb17893a2020-03-14 08:19:51 +01006257 separate line: >
6258 if has('feature')
6259 let x = this->breaks->without->the->feature
6260 endif
Bram Moolenaarff781552020-03-19 20:37:11 +01006261< If the `endif` would be moved to the second line as "| endif" it
6262 would not be found.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006263
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006264
6265has_key({dict}, {key}) *has_key()*
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006266 The result is a Number, which is TRUE if |Dictionary| {dict}
6267 has an entry with key {key}. FALSE otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006268
Bram Moolenaara74e4942019-08-04 17:35:53 +02006269 Can also be used as a |method|: >
6270 mydict->has_key(key)
6271
Bram Moolenaarc9703302016-01-17 21:49:33 +01006272haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
Bram Moolenaar00aa0692019-04-27 20:37:57 +02006273 The result is a Number:
6274 1 when the window has set a local directory via |:lcd|
6275 2 when the tab-page has set a local directory via |:tcd|
6276 0 otherwise.
Bram Moolenaarc9703302016-01-17 21:49:33 +01006277
6278 Without arguments use the current window.
6279 With {winnr} use this window in the current tab page.
6280 With {winnr} and {tabnr} use the window in the specified tab
6281 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02006282 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02006283 If {winnr} is -1 it is ignored and only the tabpage is used.
Bram Moolenaarc9703302016-01-17 21:49:33 +01006284 Return 0 if the arguments are invalid.
Bram Moolenaar00aa0692019-04-27 20:37:57 +02006285 Examples: >
6286 if haslocaldir() == 1
6287 " window local directory case
6288 elseif haslocaldir() == 2
6289 " tab-local directory case
6290 else
6291 " global directory case
6292 endif
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006293
Bram Moolenaar00aa0692019-04-27 20:37:57 +02006294 " current window
6295 :echo haslocaldir()
6296 :echo haslocaldir(0)
6297 :echo haslocaldir(0, 0)
6298 " window n in current tab page
6299 :echo haslocaldir(n)
6300 :echo haslocaldir(n, 0)
6301 " window n in tab page m
6302 :echo haslocaldir(n, m)
6303 " tab page m
6304 :echo haslocaldir(-1, m)
6305<
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006306 Can also be used as a |method|: >
6307 GetWinnr()->haslocaldir()
6308
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006309hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006310 The result is a Number, which is TRUE if there is a mapping
6311 that contains {what} in somewhere in the rhs (what it is
6312 mapped to) and this mapping exists in one of the modes
6313 indicated by {mode}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006314 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00006315 instead of mappings. Don't forget to specify Insert and/or
6316 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006317 Both the global mappings and the mappings local to the current
6318 buffer are checked for a match.
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006319 If no matching mapping is found FALSE is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006320 The following characters are recognized in {mode}:
6321 n Normal mode
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006322 v Visual and Select mode
6323 x Visual mode
6324 s Select mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00006325 o Operator-pending mode
6326 i Insert mode
6327 l Language-Argument ("r", "f", "t", etc.)
6328 c Command-line mode
6329 When {mode} is omitted, "nvo" is used.
6330
6331 This function is useful to check if a mapping already exists
Bram Moolenaar58b85342016-08-14 19:54:54 +02006332 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006333 :if !hasmapto('\ABCdoit')
6334 : map <Leader>d \ABCdoit
6335 :endif
6336< This installs the mapping to "\ABCdoit" only if there isn't
6337 already a mapping to "\ABCdoit".
6338
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006339 Can also be used as a |method|: >
6340 GetRHS()->hasmapto()
6341
Bram Moolenaar071d4272004-06-13 20:20:40 +00006342histadd({history}, {item}) *histadd()*
6343 Add the String {item} to the history {history} which can be
6344 one of: *hist-names*
6345 "cmd" or ":" command line history
6346 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00006347 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00006348 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02006349 "debug" or ">" debug command history
Bram Moolenaar3e496b02016-09-25 22:11:48 +02006350 empty the current or last used history
Bram Moolenaar30b65812012-07-12 22:01:11 +02006351 The {history} string does not need to be the whole name, one
6352 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006353 If {item} does already exist in the history, it will be
6354 shifted to become the newest entry.
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006355 The result is a Number: TRUE if the operation was successful,
6356 otherwise FALSE is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006357
6358 Example: >
6359 :call histadd("input", strftime("%Y %b %d"))
6360 :let date=input("Enter date: ")
6361< This function is not available in the |sandbox|.
6362
Bram Moolenaar2e693a82019-10-16 22:35:02 +02006363 Can also be used as a |method|, the base is passed as the
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006364 second argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02006365 GetHistory()->histadd('search')
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006366
Bram Moolenaar071d4272004-06-13 20:20:40 +00006367histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006368 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006369 for the possible values of {history}.
6370
Bram Moolenaarc236c162008-07-13 17:41:49 +00006371 If the parameter {item} evaluates to a String, it is used as a
6372 regular expression. All entries matching that expression will
6373 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006374 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00006375 If {item} evaluates to a Number, it will be interpreted as
6376 an index, see |:history-indexing|. The respective entry will
6377 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006378
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006379 The result is TRUE for a successful operation, otherwise FALSE
6380 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006381
6382 Examples:
6383 Clear expression register history: >
6384 :call histdel("expr")
6385<
6386 Remove all entries starting with "*" from the search history: >
6387 :call histdel("/", '^\*')
6388<
6389 The following three are equivalent: >
6390 :call histdel("search", histnr("search"))
6391 :call histdel("search", -1)
6392 :call histdel("search", '^'.histget("search", -1).'$')
6393<
6394 To delete the last search pattern and use the last-but-one for
6395 the "n" command and 'hlsearch': >
6396 :call histdel("search", -1)
6397 :let @/ = histget("search", -1)
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006398<
6399 Can also be used as a |method|: >
6400 GetHistory()->histdel()
Bram Moolenaar071d4272004-06-13 20:20:40 +00006401
6402histget({history} [, {index}]) *histget()*
6403 The result is a String, the entry with Number {index} from
6404 {history}. See |hist-names| for the possible values of
6405 {history}, and |:history-indexing| for {index}. If there is
6406 no such entry, an empty String is returned. When {index} is
6407 omitted, the most recent item from the history is used.
6408
6409 Examples:
6410 Redo the second last search from history. >
6411 :execute '/' . histget("search", -2)
6412
6413< Define an Ex command ":H {num}" that supports re-execution of
6414 the {num}th entry from the output of |:history|. >
6415 :command -nargs=1 H execute histget("cmd", 0+<args>)
6416<
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006417 Can also be used as a |method|: >
6418 GetHistory()->histget()
6419
Bram Moolenaar071d4272004-06-13 20:20:40 +00006420histnr({history}) *histnr()*
6421 The result is the Number of the current entry in {history}.
6422 See |hist-names| for the possible values of {history}.
6423 If an error occurred, -1 is returned.
6424
6425 Example: >
6426 :let inp_index = histnr("expr")
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006427
6428< Can also be used as a |method|: >
6429 GetHistory()->histnr()
Bram Moolenaar071d4272004-06-13 20:20:40 +00006430<
6431hlexists({name}) *hlexists()*
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006432 The result is a Number, which is TRUE if a highlight group
Bram Moolenaar071d4272004-06-13 20:20:40 +00006433 called {name} exists. This is when the group has been
6434 defined in some way. Not necessarily when highlighting has
6435 been defined for it, it may also have been used for a syntax
6436 item.
6437 *highlight_exists()*
6438 Obsolete name: highlight_exists().
6439
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006440 Can also be used as a |method|: >
6441 GetName()->hlexists()
6442<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006443 *hlID()*
6444hlID({name}) The result is a Number, which is the ID of the highlight group
6445 with name {name}. When the highlight group doesn't exist,
6446 zero is returned.
6447 This can be used to retrieve information about the highlight
Bram Moolenaar58b85342016-08-14 19:54:54 +02006448 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006449 "Comment" group: >
6450 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
6451< *highlightID()*
6452 Obsolete name: highlightID().
6453
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006454 Can also be used as a |method|: >
6455 GetName()->hlID()
6456
Bram Moolenaar071d4272004-06-13 20:20:40 +00006457hostname() *hostname()*
6458 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006459 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00006460 256 characters long are truncated.
6461
6462iconv({expr}, {from}, {to}) *iconv()*
6463 The result is a String, which is the text {expr} converted
6464 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006465 When the conversion completely fails an empty string is
6466 returned. When some characters could not be converted they
6467 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006468 The encoding names are whatever the iconv() library function
6469 can accept, see ":!man 3 iconv".
6470 Most conversions require Vim to be compiled with the |+iconv|
6471 feature. Otherwise only UTF-8 to latin1 conversion and back
6472 can be done.
6473 This can be used to display messages with special characters,
6474 no matter what 'encoding' is set to. Write the message in
6475 UTF-8 and use: >
6476 echo iconv(utf8_str, "utf-8", &enc)
6477< Note that Vim uses UTF-8 for all Unicode encodings, conversion
6478 from/to UCS-2 is automatically changed to use UTF-8. You
6479 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006480
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006481 Can also be used as a |method|: >
6482 GetText()->iconv('latin1', 'utf-8')
6483<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006484 *indent()*
6485indent({lnum}) The result is a Number, which is indent of line {lnum} in the
6486 current buffer. The indent is counted in spaces, the value
6487 of 'tabstop' is relevant. {lnum} is used just like in
6488 |getline()|.
6489 When {lnum} is invalid -1 is returned.
6490
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006491 Can also be used as a |method|: >
6492 GetLnum()->indent()
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006493
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006494index({object}, {expr} [, {start} [, {ic}]]) *index()*
6495 If {object} is a |List| return the lowest index where the item
6496 has a value equal to {expr}. There is no automatic
6497 conversion, so the String "4" is different from the Number 4.
6498 And the number 4 is different from the Float 4.0. The value
6499 of 'ignorecase' is not used here, case always matters.
6500
6501 If {object} is |Blob| return the lowest index where the byte
6502 value is equal to {expr}.
6503
Bram Moolenaar748bf032005-02-02 23:04:36 +00006504 If {start} is given then start looking at the item with index
6505 {start} (may be negative for an item relative to the end).
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006506 When {ic} is given and it is |TRUE|, ignore case. Otherwise
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006507 case must match.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006508 -1 is returned when {expr} is not found in {object}.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006509 Example: >
6510 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006511 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006512
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006513< Can also be used as a |method|: >
6514 GetObject()->index(what)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00006515
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006516input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006517 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006518 the command-line. The {prompt} argument is either a prompt
6519 string, or a blank string (for no prompt). A '\n' can be used
6520 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006521 The highlighting set with |:echohl| is used for the prompt.
6522 The input is entered just like a command-line, with the same
Bram Moolenaar58b85342016-08-14 19:54:54 +02006523 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006524 for lines typed for input().
6525 Example: >
6526 :if input("Coffee or beer? ") == "beer"
6527 : echo "Cheers!"
6528 :endif
6529<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006530 If the optional {text} argument is present and not empty, this
6531 is used for the default reply, as if the user typed this.
6532 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006533 :let color = input("Color? ", "white")
6534
6535< The optional {completion} argument specifies the type of
6536 completion supported for the input. Without it completion is
Bram Moolenaar58b85342016-08-14 19:54:54 +02006537 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006538 that can be supplied to a user-defined command using the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006539 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006540 more information. Example: >
6541 let fname = input("File: ", "", "file")
6542<
6543 NOTE: This function must not be used in a startup file, for
6544 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00006545 Note: When input() is called from within a mapping it will
6546 consume remaining characters from that mapping, because a
6547 mapping is handled like the characters were typed.
6548 Use |inputsave()| before input() and |inputrestore()|
6549 after input() to avoid that. Another solution is to avoid
6550 that further characters follow in the mapping, e.g., by using
6551 |:execute| or |:normal|.
6552
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006553 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006554 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
6555 :function GetFoo()
6556 : call inputsave()
6557 : let g:Foo = input("enter search pattern: ")
6558 : call inputrestore()
6559 :endfunction
6560
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006561< Can also be used as a |method|: >
6562 GetPrompt()->input()
6563
Bram Moolenaar071d4272004-06-13 20:20:40 +00006564inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006565 Like |input()|, but when the GUI is running and text dialogs
6566 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006567 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02006568 :let n = inputdialog("value for shiftwidth", shiftwidth())
6569 :if n != ""
6570 : let &sw = n
6571 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00006572< When the dialog is cancelled {cancelreturn} is returned. When
6573 omitted an empty string is returned.
6574 Hitting <Enter> works like pressing the OK button. Hitting
6575 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006576 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006577
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006578 Can also be used as a |method|: >
6579 GetPrompt()->inputdialog()
6580
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006581inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006582 {textlist} must be a |List| of strings. This |List| is
6583 displayed, one string per line. The user will be prompted to
6584 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006585 The user can also select an item by clicking on it with the
Bram Moolenaar65e0d772020-06-14 17:29:55 +02006586 mouse, if the mouse is enabled in the command line ('mouse' is
6587 "a" or includes "c"). For the first string 0 is returned.
6588 When clicking above the first item a negative number is
6589 returned. When clicking on the prompt one more than the
6590 length of {textlist} is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006591 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar58b85342016-08-14 19:54:54 +02006592 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006593 the start of the string. And put a prompt in the first item.
6594 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00006595 let color = inputlist(['Select color:', '1. red',
6596 \ '2. green', '3. blue'])
6597
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006598< Can also be used as a |method|: >
6599 GetChoices()->inputlist()
6600
Bram Moolenaar071d4272004-06-13 20:20:40 +00006601inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006602 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006603 Should be called the same number of times inputsave() is
6604 called. Calling it more often is harmless though.
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006605 Returns TRUE when there is nothing to restore, FALSE otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006606
6607inputsave() *inputsave()*
6608 Preserve typeahead (also from mappings) and clear it, so that
6609 a following prompt gets input from the user. Should be
6610 followed by a matching inputrestore() after the prompt. Can
6611 be used several times, in which case there must be just as
6612 many inputrestore() calls.
Bram Moolenaar98a29d02021-01-18 19:55:44 +01006613 Returns TRUE when out of memory, FALSE otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006614
6615inputsecret({prompt} [, {text}]) *inputsecret()*
6616 This function acts much like the |input()| function with but
6617 two exceptions:
6618 a) the user's response will be displayed as a sequence of
6619 asterisks ("*") thereby keeping the entry secret, and
6620 b) the user's response will not be recorded on the input
6621 |history| stack.
6622 The result is a String, which is whatever the user actually
6623 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00006624 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006625
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006626 Can also be used as a |method|: >
6627 GetPrompt()->inputsecret()
6628
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006629insert({object}, {item} [, {idx}]) *insert()*
6630 When {object} is a |List| or a |Blob| insert {item} at the start
6631 of it.
6632
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006633 If {idx} is specified insert {item} before the item with index
Bram Moolenaar58b85342016-08-14 19:54:54 +02006634 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006635 like omitting {idx}. A negative {idx} is also possible, see
6636 |list-index|. -1 inserts just before the last item.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01006637
6638 Returns the resulting |List| or |Blob|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006639 :let mylist = insert([2, 3, 5], 1)
6640 :call insert(mylist, 4, -1)
6641 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00006642< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006643 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006644 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006645
Bram Moolenaarac92e252019-08-03 21:58:38 +02006646 Can also be used as a |method|: >
6647 mylist->insert(item)
6648
Bram Moolenaar67a2deb2019-11-25 00:05:32 +01006649interrupt() *interrupt()*
6650 Interrupt script execution. It works more or less like the
6651 user typing CTRL-C, most commands won't execute and control
6652 returns to the user. This is useful to abort execution
6653 from lower down, e.g. in an autocommand. Example: >
6654 :function s:check_typoname(file)
6655 : if fnamemodify(a:file, ':t') == '['
6656 : echomsg 'Maybe typo'
6657 : call interrupt()
6658 : endif
6659 :endfunction
6660 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
6661
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006662invert({expr}) *invert()*
6663 Bitwise invert. The argument is converted to a number. A
6664 List, Dict or Float argument causes an error. Example: >
6665 :let bits = invert(bits)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02006666< Can also be used as a |method|: >
6667 :let bits = bits->invert()
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006668
Bram Moolenaar071d4272004-06-13 20:20:40 +00006669isdirectory({directory}) *isdirectory()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006670 The result is a Number, which is |TRUE| when a directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00006671 with the name {directory} exists. If {directory} doesn't
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006672 exist, or isn't a directory, the result is |FALSE|. {directory}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006673 is any expression, which is used as a String.
6674
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006675 Can also be used as a |method|: >
6676 GetName()->isdirectory()
6677
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02006678isinf({expr}) *isinf()*
6679 Return 1 if {expr} is a positive infinity, or -1 a negative
6680 infinity, otherwise 0. >
6681 :echo isinf(1.0 / 0.0)
6682< 1 >
6683 :echo isinf(-1.0 / 0.0)
6684< -1
6685
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02006686 Can also be used as a |method|: >
6687 Compute()->isinf()
6688<
Bram Moolenaarfda1bff2019-04-04 13:44:37 +02006689 {only available when compiled with the |+float| feature}
6690
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006691islocked({expr}) *islocked()* *E786*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006692 The result is a Number, which is |TRUE| when {expr} is the
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006693 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006694 {expr} must be the name of a variable, |List| item or
6695 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006696 :let alist = [0, ['a', 'b'], 2, 3]
6697 :lockvar 1 alist
6698 :echo islocked('alist') " 1
6699 :echo islocked('alist[1]') " 0
6700
6701< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006702 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006703
Bram Moolenaarf9f24ce2019-08-31 21:17:39 +02006704 Can also be used as a |method|: >
6705 GetName()->islocked()
6706
Bram Moolenaarf3913272016-02-25 00:00:01 +01006707isnan({expr}) *isnan()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006708 Return |TRUE| if {expr} is a float with value NaN. >
Bram Moolenaarf3913272016-02-25 00:00:01 +01006709 echo isnan(0.0 / 0.0)
Bram Moolenaar0f248b02019-04-04 15:36:05 +02006710< 1
Bram Moolenaarf3913272016-02-25 00:00:01 +01006711
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02006712 Can also be used as a |method|: >
6713 Compute()->isnan()
6714<
Bram Moolenaarf3913272016-02-25 00:00:01 +01006715 {only available when compiled with the |+float| feature}
6716
Bram Moolenaar677ee682005-01-27 14:41:15 +00006717items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006718 Return a |List| with all the key-value pairs of {dict}. Each
6719 |List| item is a list with two items: the key of a {dict}
6720 entry and the value of this entry. The |List| is in arbitrary
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006721 order. Also see |keys()| and |values()|.
6722 Example: >
6723 for [key, value] in items(mydict)
6724 echo key . ': ' . value
6725 endfor
Bram Moolenaar677ee682005-01-27 14:41:15 +00006726
Bram Moolenaarac92e252019-08-03 21:58:38 +02006727< Can also be used as a |method|: >
6728 mydict->items()
Bram Moolenaar38a55632016-02-15 22:07:32 +01006729
Bram Moolenaared997ad2019-07-21 16:42:00 +02006730job_ functions are documented here: |job-functions-details|
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01006731
Bram Moolenaar835dc632016-02-07 14:27:38 +01006732
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006733join({list} [, {sep}]) *join()*
6734 Join the items in {list} together into one String.
6735 When {sep} is specified it is put in between the items. If
6736 {sep} is omitted a single space is used.
6737 Note that {sep} is not added at the end. You might want to
6738 add it there too: >
6739 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006740< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006741 converted into a string like with |string()|.
6742 The opposite function is |split()|.
6743
Bram Moolenaarac92e252019-08-03 21:58:38 +02006744 Can also be used as a |method|: >
6745 mylist->join()
6746
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006747js_decode({string}) *js_decode()*
6748 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006749 - Object key names do not have to be in quotes.
Bram Moolenaaree142ad2017-01-11 21:50:08 +01006750 - Strings can be in single quotes.
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006751 - Empty items in an array (between two commas) are allowed and
6752 result in v:none items.
6753
Bram Moolenaar02b31112019-08-31 22:16:38 +02006754 Can also be used as a |method|: >
6755 ReadObject()->js_decode()
6756
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006757js_encode({expr}) *js_encode()*
6758 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006759 - Object key names are not in quotes.
6760 - v:none items in an array result in an empty item between
6761 commas.
6762 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006763 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006764 Will be encoded as:
6765 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006766 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006767 [1,null,{"one":1},null] ~
6768 This encoding is valid for JavaScript. It is more efficient
6769 than JSON, especially when using an array with optional items.
6770
Bram Moolenaar02b31112019-08-31 22:16:38 +02006771 Can also be used as a |method|: >
6772 GetObject()->js_encode()
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006773
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006774json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006775 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006776 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01006777 JSON and Vim values.
6778 The decoding is permissive:
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006779 - A trailing comma in an array and object is ignored, e.g.
6780 "[1, 2, ]" is the same as "[1, 2]".
Bram Moolenaard09091d2019-01-17 16:07:22 +01006781 - Integer keys are accepted in objects, e.g. {1:2} is the
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006782 same as {"1":2}.
Bram Moolenaar705ada12016-01-24 17:56:50 +01006783 - More floating point numbers are recognized, e.g. "1." for
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006784 "1.0", or "001.2" for "1.2". Special floating point values
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006785 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
6786 are accepted.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006787 - Leading zeroes in integer numbers are ignored, e.g. "012"
6788 for "12" or "-012" for "-12".
6789 - Capitalization is ignored in literal names null, true or
6790 false, e.g. "NULL" for "null", "True" for "true".
6791 - Control characters U+0000 through U+001F which are not
6792 escaped in strings are accepted, e.g. " " (tab
6793 character in string) for "\t".
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006794 - An empty JSON expression or made of only spaces is accepted
6795 and results in v:none.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02006796 - Backslash in an invalid 2-character sequence escape is
6797 ignored, e.g. "\a" is decoded as "a".
6798 - A correct surrogate pair in JSON strings should normally be
6799 a 12 character sequence such as "\uD834\uDD1E", but
6800 json_decode() silently accepts truncated surrogate pairs
6801 such as "\uD834" or "\uD834\u"
6802 *E938*
6803 A duplicate key in an object, valid in rfc7159, is not
6804 accepted by json_decode() as the result must be a valid Vim
6805 type, e.g. this fails: {"a":"b", "a":"c"}
6806
Bram Moolenaar02b31112019-08-31 22:16:38 +02006807 Can also be used as a |method|: >
6808 ReadObject()->json_decode()
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006809
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01006810json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01006811 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006812 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01006813 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006814 Vim values are converted as follows:
Bram Moolenaard09091d2019-01-17 16:07:22 +01006815 |Number| decimal number
6816 |Float| floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006817 Float nan "NaN"
6818 Float inf "Infinity"
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01006819 Float -inf "-Infinity"
Bram Moolenaard09091d2019-01-17 16:07:22 +01006820 |String| in double quotes (possibly null)
6821 |Funcref| not possible, error
6822 |List| as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006823 used recursively: []
Bram Moolenaard09091d2019-01-17 16:07:22 +01006824 |Dict| as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02006825 used recursively: {}
Bram Moolenaard09091d2019-01-17 16:07:22 +01006826 |Blob| as an array of the individual bytes
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006827 v:false "false"
6828 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01006829 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006830 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01006831 Note that NaN and Infinity are passed on as values. This is
6832 missing in the JSON standard, but several implementations do
6833 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01006834
Bram Moolenaar02b31112019-08-31 22:16:38 +02006835 Can also be used as a |method|: >
6836 GetObject()->json_encode()
6837
Bram Moolenaard8b02732005-01-14 21:48:43 +00006838keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006839 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01006840 arbitrary order. Also see |items()| and |values()|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00006841
Bram Moolenaarac92e252019-08-03 21:58:38 +02006842 Can also be used as a |method|: >
6843 mydict->keys()
6844
6845< *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006846len({expr}) The result is a Number, which is the length of the argument.
6847 When {expr} is a String or a Number the length in bytes is
6848 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006849 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006850 returned.
Bram Moolenaard09091d2019-01-17 16:07:22 +01006851 When {expr} is a |Blob| the number of bytes is returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006852 When {expr} is a |Dictionary| the number of entries in the
6853 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00006854 Otherwise an error is given.
6855
Bram Moolenaarac92e252019-08-03 21:58:38 +02006856 Can also be used as a |method|: >
6857 mylist->len()
6858
6859< *libcall()* *E364* *E368*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006860libcall({libname}, {funcname}, {argument})
6861 Call function {funcname} in the run-time library {libname}
6862 with single argument {argument}.
6863 This is useful to call functions in a library that you
6864 especially made to be used with Vim. Since only one argument
6865 is possible, calling standard library functions is rather
6866 limited.
6867 The result is the String returned by the function. If the
6868 function returns NULL, this will appear as an empty string ""
6869 to Vim.
6870 If the function returns a number, use libcallnr()!
6871 If {argument} is a number, it is passed to the function as an
6872 int; if {argument} is a string, it is passed as a
6873 null-terminated string.
6874 This function will fail in |restricted-mode|.
6875
6876 libcall() allows you to write your own 'plug-in' extensions to
6877 Vim without having to recompile the program. It is NOT a
6878 means to call system functions! If you try to do so Vim will
6879 very probably crash.
6880
6881 For Win32, the functions you write must be placed in a DLL
6882 and use the normal C calling convention (NOT Pascal which is
6883 used in Windows System DLLs). The function must take exactly
6884 one parameter, either a character pointer or a long integer,
6885 and must return a character pointer or NULL. The character
6886 pointer returned must point to memory that will remain valid
6887 after the function has returned (e.g. in static data in the
6888 DLL). If it points to allocated memory, that memory will
6889 leak away. Using a static buffer in the function should work,
6890 it's then freed when the DLL is unloaded.
6891
6892 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00006893 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006894 because Vim thinks it's a pointer.
6895 For Win32 systems, {libname} should be the filename of the DLL
6896 without the ".DLL" suffix. A full path is only required if
6897 the DLL is not in the usual places.
6898 For Unix: When compiling your own plugins, remember that the
6899 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006900 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006901 feature is present}
6902 Examples: >
6903 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar02b31112019-08-31 22:16:38 +02006904
Bram Moolenaar2e693a82019-10-16 22:35:02 +02006905< Can also be used as a |method|, the base is passed as the
6906 third argument: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02006907 GetValue()->libcall("libc.so", "getenv")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006908<
6909 *libcallnr()*
6910libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006911 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00006912 int instead of a string.
6913 {only in Win32 on some Unix versions, when the |+libcall|
6914 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006915 Examples: >
6916 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006917 :call libcallnr("libc.so", "printf", "Hello World!\n")
6918 :call libcallnr("libc.so", "sleep", 10)
6919<
Bram Moolenaar2e693a82019-10-16 22:35:02 +02006920 Can also be used as a |method|, the base is passed as the
6921 third argument: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02006922 GetValue()->libcallnr("libc.so", "printf")
6923<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006924
6925line({expr} [, {winid}]) *line()*
6926 The result is a Number, which is the line number of the file
Bram Moolenaar071d4272004-06-13 20:20:40 +00006927 position given with {expr}. The accepted positions are:
6928 . the cursor position
6929 $ the last line in the current buffer
6930 'x position of mark x (if the mark is not set, 0 is
6931 returned)
Bram Moolenaara1d5fa62017-04-03 22:02:55 +02006932 w0 first line visible in current window (one if the
6933 display isn't updated, e.g. in silent Ex mode)
6934 w$ last line visible in current window (this is one
6935 less than "w0" if no lines are visible)
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00006936 v In Visual mode: the start of the Visual area (the
6937 cursor is the end). When not in Visual mode
6938 returns the cursor position. Differs from |'<| in
6939 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006940 Note that a mark in another file can be used. The line number
6941 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006942 To get the column number use |col()|. To get both use
6943 |getpos()|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006944 With the optional {winid} argument the values are obtained for
6945 that window instead of the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006946 Examples: >
6947 line(".") line number of the cursor
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02006948 line(".", winid) idem, in window "winid"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006949 line("'t") line number of mark t
6950 line("'" . marker) line number of mark marker
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006951<
6952 To jump to the last known position when opening a file see
6953 |last-position-jump|.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006954
Bram Moolenaar02b31112019-08-31 22:16:38 +02006955 Can also be used as a |method|: >
6956 GetValue()->line()
6957
Bram Moolenaar071d4272004-06-13 20:20:40 +00006958line2byte({lnum}) *line2byte()*
6959 Return the byte count from the start of the buffer for line
6960 {lnum}. This includes the end-of-line character, depending on
6961 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006962 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006963 This can also be used to get the byte count for the line just
6964 below the last line: >
6965 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006966< This is the buffer size plus one. If 'fileencoding' is empty
6967 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006968 When {lnum} is invalid, or the |+byte_offset| feature has been
6969 disabled at compile time, -1 is returned.
6970 Also see |byte2line()|, |go| and |:goto|.
6971
Bram Moolenaar02b31112019-08-31 22:16:38 +02006972 Can also be used as a |method|: >
6973 GetLnum()->line2byte()
6974
Bram Moolenaar071d4272004-06-13 20:20:40 +00006975lispindent({lnum}) *lispindent()*
6976 Get the amount of indent for line {lnum} according the lisp
6977 indenting rules, as with 'lisp'.
6978 The indent is counted in spaces, the value of 'tabstop' is
6979 relevant. {lnum} is used just like in |getline()|.
6980 When {lnum} is invalid or Vim was not compiled the
6981 |+lispindent| feature, -1 is returned.
6982
Bram Moolenaar02b31112019-08-31 22:16:38 +02006983 Can also be used as a |method|: >
6984 GetLnum()->lispindent()
6985
Bram Moolenaar9d401282019-04-06 13:18:12 +02006986list2str({list} [, {utf8}]) *list2str()*
6987 Convert each number in {list} to a character string can
6988 concatenate them all. Examples: >
6989 list2str([32]) returns " "
6990 list2str([65, 66, 67]) returns "ABC"
6991< The same can be done (slowly) with: >
6992 join(map(list, {nr, val -> nr2char(val)}), '')
6993< |str2list()| does the opposite.
6994
6995 When {utf8} is omitted or zero, the current 'encoding' is used.
6996 With {utf8} is 1, always return utf-8 characters.
6997 With utf-8 composing characters work as expected: >
6998 list2str([97, 769]) returns "á"
6999<
Bram Moolenaar02b31112019-08-31 22:16:38 +02007000 Can also be used as a |method|: >
7001 GetList()->list2str()
7002
Bram Moolenaara3347722019-05-11 21:14:24 +02007003listener_add({callback} [, {buf}]) *listener_add()*
7004 Add a callback function that will be invoked when changes have
7005 been made to buffer {buf}.
7006 {buf} refers to a buffer name or number. For the accepted
7007 values, see |bufname()|. When {buf} is omitted the current
7008 buffer is used.
7009 Returns a unique ID that can be passed to |listener_remove()|.
7010
Bram Moolenaaraad222c2019-09-06 22:46:09 +02007011 The {callback} is invoked with five arguments:
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007012 a:bufnr the buffer that was changed
7013 a:start first changed line number
7014 a:end first line number below the change
Bram Moolenaar96f45c02019-10-26 19:53:45 +02007015 a:added number of lines added, negative if lines were
7016 deleted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007017 a:changes a List of items with details about the changes
7018
7019 Example: >
7020 func Listener(bufnr, start, end, added, changes)
7021 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
7022 endfunc
7023 call listener_add('Listener', bufnr)
7024
7025< The List cannot be changed. Each item in a:changes is a
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02007026 dictionary with these entries:
Bram Moolenaara3347722019-05-11 21:14:24 +02007027 lnum the first line number of the change
7028 end the first line below the change
7029 added number of lines added; negative if lines were
7030 deleted
7031 col first column in "lnum" that was affected by
7032 the change; one if unknown or the whole line
7033 was affected; this is a byte index, first
7034 character has a value of one.
7035 When lines are inserted the values are:
Bram Moolenaar68e65602019-05-26 21:33:31 +02007036 lnum line above which the new line is added
Bram Moolenaara3347722019-05-11 21:14:24 +02007037 end equal to "lnum"
7038 added number of lines inserted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007039 col 1
Bram Moolenaara3347722019-05-11 21:14:24 +02007040 When lines are deleted the values are:
7041 lnum the first deleted line
7042 end the line below the first deleted line, before
7043 the deletion was done
7044 added negative, number of lines deleted
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007045 col 1
Bram Moolenaara3347722019-05-11 21:14:24 +02007046 When lines are changed:
7047 lnum the first changed line
7048 end the line below the last changed line
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007049 added 0
7050 col first column with a change or 1
Bram Moolenaara3347722019-05-11 21:14:24 +02007051
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007052 The entries are in the order the changes were made, thus the
7053 most recent change is at the end. The line numbers are valid
7054 when the callback is invoked, but later changes may make them
7055 invalid, thus keeping a copy for later might not work.
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02007056
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007057 The {callback} is invoked just before the screen is updated,
7058 when |listener_flush()| is called or when a change is being
7059 made that changes the line count in a way it causes a line
7060 number in the list of changes to become invalid.
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02007061
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007062 The {callback} is invoked with the text locked, see
7063 |textlock|. If you do need to make changes to the buffer, use
7064 a timer to do this later |timer_start()|.
Bram Moolenaara3347722019-05-11 21:14:24 +02007065
7066 The {callback} is not invoked when the buffer is first loaded.
7067 Use the |BufReadPost| autocmd event to handle the initial text
7068 of a buffer.
7069 The {callback} is also not invoked when the buffer is
7070 unloaded, use the |BufUnload| autocmd event for that.
7071
Bram Moolenaar2e693a82019-10-16 22:35:02 +02007072 Can also be used as a |method|, the base is passed as the
7073 second argument: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02007074 GetBuffer()->listener_add(callback)
7075
Bram Moolenaarfe1ade02019-05-14 21:20:36 +02007076listener_flush([{buf}]) *listener_flush()*
7077 Invoke listener callbacks for buffer {buf}. If there are no
7078 pending changes then no callbacks are invoked.
7079
7080 {buf} refers to a buffer name or number. For the accepted
7081 values, see |bufname()|. When {buf} is omitted the current
7082 buffer is used.
7083
Bram Moolenaar02b31112019-08-31 22:16:38 +02007084 Can also be used as a |method|: >
7085 GetBuffer()->listener_flush()
7086
Bram Moolenaara3347722019-05-11 21:14:24 +02007087listener_remove({id}) *listener_remove()*
7088 Remove a listener previously added with listener_add().
Bram Moolenaar98a29d02021-01-18 19:55:44 +01007089 Returns FALSE when {id} could not be found, TRUE when {id} was
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02007090 removed.
Bram Moolenaara3347722019-05-11 21:14:24 +02007091
Bram Moolenaar02b31112019-08-31 22:16:38 +02007092 Can also be used as a |method|: >
7093 GetListenerId()->listener_remove()
7094
Bram Moolenaar071d4272004-06-13 20:20:40 +00007095localtime() *localtime()*
7096 Return the current time, measured as seconds since 1st Jan
Bram Moolenaar10455d42019-11-21 15:36:18 +01007097 1970. See also |strftime()|, |strptime()| and |getftime()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007098
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007099
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007100log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007101 Return the natural logarithm (base e) of {expr} as a |Float|.
7102 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007103 (0, inf].
7104 Examples: >
7105 :echo log(10)
7106< 2.302585 >
7107 :echo log(exp(5))
7108< 5.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02007109
7110 Can also be used as a |method|: >
7111 Compute()->log()
7112<
Bram Moolenaardb84e452010-08-15 13:50:43 +02007113 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02007114
7115
Bram Moolenaar446cb832008-06-24 21:56:24 +00007116log10({expr}) *log10()*
7117 Return the logarithm of Float {expr} to base 10 as a |Float|.
7118 {expr} must evaluate to a |Float| or a |Number|.
7119 Examples: >
7120 :echo log10(1000)
7121< 3.0 >
7122 :echo log10(0.01)
7123< -2.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02007124
7125 Can also be used as a |method|: >
7126 Compute()->log10()
7127<
Bram Moolenaar446cb832008-06-24 21:56:24 +00007128 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007129
7130luaeval({expr} [, {expr}]) *luaeval()*
7131 Evaluate Lua expression {expr} and return its result converted
7132 to Vim data structures. Second {expr} may hold additional
Bram Moolenaard38b0552012-04-25 19:07:41 +02007133 argument accessible as _A inside first {expr}.
7134 Strings are returned as they are.
7135 Boolean objects are converted to numbers.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007136 Numbers are converted to |Float| values if vim was compiled
Bram Moolenaard38b0552012-04-25 19:07:41 +02007137 with |+float| and to numbers otherwise.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007138 Dictionaries and lists obtained by vim.eval() are returned
Bram Moolenaard38b0552012-04-25 19:07:41 +02007139 as-is.
7140 Other objects are returned as zero without any errors.
7141 See |lua-luaeval| for more details.
Bram Moolenaar02b31112019-08-31 22:16:38 +02007142
7143 Can also be used as a |method|: >
7144 GetExpr()->luaeval()
7145
7146< {only available when compiled with the |+lua| feature}
Bram Moolenaard38b0552012-04-25 19:07:41 +02007147
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02007148map({expr1}, {expr2}) *map()*
Bram Moolenaarea696852020-11-09 18:31:39 +01007149 {expr1} must be a |List|, |Blob| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02007150 Replace each item in {expr1} with the result of evaluating
Bram Moolenaarea696852020-11-09 18:31:39 +01007151 {expr2}. For a |Blob| each byte is replaced.
7152 If the item type changes you may want to use |mapnew()| to
7153 create a new List or Dictionary. This is required when using
7154 Vim9 script.
7155
7156 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007157
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02007158 If {expr2} is a |string|, inside {expr2} |v:val| has the value
7159 of the current item. For a |Dictionary| |v:key| has the key
7160 of the current item and for a |List| |v:key| has the index of
7161 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007162 Example: >
7163 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007164< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007165
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02007166 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007167 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007168 |literal-string| to avoid having to double backslashes. You
7169 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007170
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02007171 If {expr2} is a |Funcref| it is called with two arguments:
7172 1. The key or the index of the current item.
7173 2. the value of the current item.
7174 The function must return the new value of the item. Example
7175 that changes each value by "key-value": >
7176 func KeyValue(key, val)
7177 return a:key . '-' . a:val
7178 endfunc
7179 call map(myDict, function('KeyValue'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02007180< It is shorter when using a |lambda|: >
7181 call map(myDict, {key, val -> key . '-' . val})
7182< If you do not use "val" you can leave it out: >
7183 call map(myDict, {key -> 'item: ' . key})
Bram Moolenaar088e8e32019-08-08 22:15:18 +02007184< If you do not use "key" you can use a short name: >
7185 call map(myDict, {_, val -> 'item: ' . val})
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02007186<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007187 The operation is done in-place. If you want a |List| or
7188 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02007189 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00007190
Bram Moolenaarea696852020-11-09 18:31:39 +01007191< Returns {expr1}, the |List|, |Blob| or |Dictionary| that was
7192 filtered. When an error is encountered while evaluating
7193 {expr2} no further items in {expr1} are processed. When
7194 {expr2} is a Funcref errors inside a function are ignored,
7195 unless it was defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007196
Bram Moolenaarac92e252019-08-03 21:58:38 +02007197 Can also be used as a |method|: >
7198 mylist->map(expr2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007199
Bram Moolenaar4c9243f2020-05-22 13:10:44 +02007200
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007201maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
Bram Moolenaarbd743252010-10-20 21:23:33 +02007202 When {dict} is omitted or zero: Return the rhs of mapping
7203 {name} in mode {mode}. The returned String has special
7204 characters translated like in the output of the ":map" command
7205 listing.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007206
Bram Moolenaarbd743252010-10-20 21:23:33 +02007207 When there is no mapping for {name}, an empty String is
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02007208 returned. When the mapping for {name} is empty, then "<Nop>"
7209 is returned.
Bram Moolenaarbd743252010-10-20 21:23:33 +02007210
7211 The {name} can have special key names, like in the ":map"
7212 command.
7213
Bram Moolenaard12f5c12006-01-25 22:10:52 +00007214 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00007215 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02007216 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007217 "o" Operator-pending
7218 "i" Insert
7219 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02007220 "s" Select
7221 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00007222 "l" langmap |language-mapping|
Bram Moolenaar37c64c72017-09-19 22:06:03 +02007223 "t" Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +00007224 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00007225 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02007226
Bram Moolenaare381d3d2016-07-07 14:50:41 +02007227 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007228 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02007229
Bram Moolenaare381d3d2016-07-07 14:50:41 +02007230 When {dict} is there and it is |TRUE| return a dictionary
Bram Moolenaarbd743252010-10-20 21:23:33 +02007231 containing all the information of the mapping with the
7232 following items:
Bram Moolenaar9c652532020-05-24 13:10:18 +02007233 "lhs" The {lhs} of the mapping as it would be typed
7234 "lhsraw" The {lhs} of the mapping as raw bytes
7235 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
7236 form, only present when it differs from "lhsraw"
Bram Moolenaarbd743252010-10-20 21:23:33 +02007237 "rhs" The {rhs} of the mapping as typed.
7238 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02007239 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaar2da0f0c2020-04-01 19:22:12 +02007240 "script" 1 if mapping was defined with <script>.
Bram Moolenaarbd743252010-10-20 21:23:33 +02007241 "expr" 1 for an expression mapping (|:map-<expr>|).
7242 "buffer" 1 for a buffer local mapping (|:map-local|).
7243 "mode" Modes for which the mapping is defined. In
7244 addition to the modes mentioned above, these
7245 characters will be used:
7246 " " Normal, Visual and Operator-pending
7247 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01007248 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02007249 "sid" The script local ID, used for <sid> mappings
7250 (|<SID>|).
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02007251 "lnum" The line number in "sid", zero if unknown.
Bram Moolenaardfb18412013-12-11 18:53:29 +01007252 "nowait" Do not wait for other, longer mappings.
7253 (|:map-<nowait>|).
Bram Moolenaar4c9243f2020-05-22 13:10:44 +02007254
7255 The dictionary can be used to restore a mapping with
7256 |mapset()|.
Bram Moolenaarbd743252010-10-20 21:23:33 +02007257
Bram Moolenaar071d4272004-06-13 20:20:40 +00007258 The mappings local to the current buffer are checked first,
7259 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00007260 This function can be used to map a key even when it's already
7261 mapped, and have it do the original mapping too. Sketch: >
7262 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
7263
Bram Moolenaara1449832019-09-01 20:16:52 +02007264< Can also be used as a |method|: >
7265 GetKey()->maparg('n')
Bram Moolenaar071d4272004-06-13 20:20:40 +00007266
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007267mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007268 Check if there is a mapping that matches with {name} in mode
7269 {mode}. See |maparg()| for {mode} and special names in
7270 {name}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02007271 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007272 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007273 A match happens with a mapping that starts with {name} and
7274 with a mapping which is equal to the start of {name}.
7275
Bram Moolenaar446cb832008-06-24 21:56:24 +00007276 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00007277 mapcheck("a") yes yes yes
7278 mapcheck("abc") yes yes yes
7279 mapcheck("ax") yes no no
7280 mapcheck("b") no no no
7281
7282 The difference with maparg() is that mapcheck() finds a
7283 mapping that matches with {name}, while maparg() only finds a
7284 mapping for {name} exactly.
7285 When there is no mapping that starts with {name}, an empty
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02007286 String is returned. If there is one, the RHS of that mapping
Bram Moolenaar071d4272004-06-13 20:20:40 +00007287 is returned. If there are several mappings that start with
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02007288 {name}, the RHS of one of them is returned. This will be
7289 "<Nop>" if the RHS is empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007290 The mappings local to the current buffer are checked first,
7291 then the global mappings.
7292 This function can be used to check if a mapping can be added
7293 without being ambiguous. Example: >
7294 :if mapcheck("_vv") == ""
7295 : map _vv :set guifont=7x13<CR>
7296 :endif
7297< This avoids adding the "_vv" mapping when there already is a
7298 mapping for "_v" or for "_vvv".
7299
Bram Moolenaara1449832019-09-01 20:16:52 +02007300 Can also be used as a |method|: >
7301 GetKey()->mapcheck('n')
7302
Bram Moolenaar9c652532020-05-24 13:10:18 +02007303
Bram Moolenaarea696852020-11-09 18:31:39 +01007304mapnew({expr1}, {expr2}) *mapnew()*
7305 Like |map()| but instead of replacing items in {expr1} a new
7306 List or Dictionary is created and returned. {expr1} remains
Bram Moolenaar1b884a02020-12-10 21:11:27 +01007307 unchanged. Items can still be changed by {expr2}, if you
7308 don't want that use |deepcopy()| first.
Bram Moolenaarea696852020-11-09 18:31:39 +01007309
7310
7311mapset({mode}, {abbr}, {dict}) *mapset()*
Bram Moolenaar4c9243f2020-05-22 13:10:44 +02007312 Restore a mapping from a dictionary returned by |maparg()|.
Bram Moolenaar9c652532020-05-24 13:10:18 +02007313 {mode} and {abbr} should be the same as for the call to
7314 |maparg()|. *E460*
Bram Moolenaar4c9243f2020-05-22 13:10:44 +02007315 {mode} is used to define the mode in which the mapping is set,
7316 not the "mode" entry in {dict}.
7317 Example for saving and restoring a mapping: >
7318 let save_map = maparg('K', 'n', 0, 1)
7319 nnoremap K somethingelse
7320 ...
7321 call mapset('n', 0, save_map)
Bram Moolenaar9c652532020-05-24 13:10:18 +02007322< Note that if you are going to replace a map in several modes,
7323 e.g. with `:map!`, you need to save the mapping for all of
Bram Moolenaarebacddb2020-06-04 15:22:21 +02007324 them, since they can differ.
Bram Moolenaar9c652532020-05-24 13:10:18 +02007325
7326
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007327match({expr}, {pat} [, {start} [, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007328 When {expr} is a |List| then this returns the index of the
7329 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007330 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02007331
Bram Moolenaar58b85342016-08-14 19:54:54 +02007332 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007333 Number, which gives the index (byte offset) in {expr} where
7334 {pat} matches.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02007335
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007336 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00007337 If there is no match -1 is returned.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02007338
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02007339 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00007340 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007341 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007342 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007343< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00007344 *strpbrk()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02007345 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00007346 :let sepidx = match(line, '[.,;: \t]')
7347< *strcasestr()*
7348 Vim doesn't have a strcasestr() function. But you can add
7349 "\c" to the pattern to ignore case: >
7350 :let idx = match(haystack, '\cneedle')
7351<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007352 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007353 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007354 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007355 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007356 :echo match("testing", "ing", 2)
7357< result is again "4". >
7358 :echo match("testing", "ing", 4)
7359< result is again "4". >
7360 :echo match("testing", "t", 2)
7361< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00007362 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00007363 {start} bytes later, thus "^" will match at {start}. Except
7364 when {count} is given, then it's like matches before the
7365 {start} byte are ignored (this is a bit complicated to keep it
7366 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007367 For a String, if {start} < 0, it will be set to 0. For a list
7368 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00007369 If {start} is out of range ({start} > strlen({expr}) for a
7370 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007371
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00007372 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00007373 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00007374 character further. Thus this example results in 1: >
7375 echo match("testing", "..", 0, 2)
7376< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00007377 Note that when {count} is added the way {start} works changes,
7378 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00007379
Bram Moolenaar071d4272004-06-13 20:20:40 +00007380 See |pattern| for the patterns that are accepted.
7381 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar58b85342016-08-14 19:54:54 +02007382 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00007383 done like 'magic' is set and 'cpoptions' is empty.
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01007384 Note that a match at the start is preferred, thus when the
7385 pattern is using "*" (any number of matches) it tends to find
7386 zero matches at the start instead of a number of matches
7387 further down in the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007388
Bram Moolenaara1449832019-09-01 20:16:52 +02007389 Can also be used as a |method|: >
7390 GetList()->match('word')
7391<
Bram Moolenaar95e51472018-07-28 16:55:56 +02007392 *matchadd()* *E798* *E799* *E801* *E957*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007393matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007394 Defines a pattern to be highlighted in the current window (a
7395 "match"). It will be highlighted with {group}. Returns an
7396 identification number (ID), which can be used to delete the
Bram Moolenaaraff74912019-03-30 18:11:49 +01007397 match using |matchdelete()|. The ID is bound to the window.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01007398 Matching is case sensitive and magic, unless case sensitivity
7399 or magicness are explicitly overridden in {pattern}. The
7400 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02007401 The "Conceal" value is special, it causes the match to be
7402 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007403
7404 The optional {priority} argument assigns a priority to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02007405 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007406 highlighting overrule that of a match with a lower priority.
7407 A priority is specified as an integer (negative numbers are no
7408 exception). If the {priority} argument is not specified, the
7409 default priority is 10. The priority of 'hlsearch' is zero,
7410 hence all matches with a priority greater than zero will
7411 overrule it. Syntax highlighting (see 'syntax') is a separate
7412 mechanism, and regardless of the chosen priority a match will
7413 always overrule syntax highlighting.
7414
7415 The optional {id} argument allows the request for a specific
7416 match ID. If a specified ID is already taken, an error
7417 message will appear and the match will not be added. An ID
7418 is specified as a positive integer (zero excluded). IDs 1, 2
7419 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02007420 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007421 |matchadd()| automatically chooses a free ID.
7422
Bram Moolenaar85084ef2016-01-17 22:26:33 +01007423 The optional {dict} argument allows for further custom
7424 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02007425 conceal character that will be shown for |hl-Conceal|
7426 highlighted matches. The dict can have the following members:
7427
7428 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01007429 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02007430 matches, see |:syn-cchar|)
Bram Moolenaar95e51472018-07-28 16:55:56 +02007431 window Instead of the current window use the
7432 window with this number or window ID.
Bram Moolenaar6561d522015-07-21 15:48:27 +02007433
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007434 The number of matches is not limited, as it is the case with
7435 the |:match| commands.
7436
7437 Example: >
7438 :highlight MyGroup ctermbg=green guibg=green
7439 :let m = matchadd("MyGroup", "TODO")
7440< Deletion of the pattern: >
7441 :call matchdelete(m)
7442
7443< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar58b85342016-08-14 19:54:54 +02007444 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007445 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007446
Bram Moolenaara1449832019-09-01 20:16:52 +02007447 Can also be used as a |method|: >
7448 GetGroup()->matchadd('TODO')
7449<
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02007450 *matchaddpos()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007451matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02007452 Same as |matchadd()|, but requires a list of positions {pos}
7453 instead of a pattern. This command is faster than |matchadd()|
7454 because it does not require to handle regular expressions and
7455 sets buffer line boundaries to redraw screen. It is supposed
7456 to be used when fast match additions and deletions are
7457 required, for example to highlight matching parentheses.
7458
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01007459 {pos} is a list of positions. Each position can be one of
7460 these:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02007461 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02007462 line has number 1.
7463 - A list with one number, e.g., [23]. The whole line with this
7464 number will be highlighted.
7465 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02007466 the line number, the second one is the column number (first
7467 column is 1, the value must correspond to the byte index as
7468 |col()| would return). The character at this position will
7469 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02007470 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02007471 the third number gives the length of the highlight in bytes.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007472
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01007473 The maximum number of positions in {pos} is 8.
Bram Moolenaarb3414592014-06-17 17:48:32 +02007474
7475 Example: >
7476 :highlight MyGroup ctermbg=green guibg=green
7477 :let m = matchaddpos("MyGroup", [[23, 24], 34])
7478< Deletion of the pattern: >
7479 :call matchdelete(m)
7480
7481< Matches added by |matchaddpos()| are returned by
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01007482 |getmatches()|.
Bram Moolenaarb3414592014-06-17 17:48:32 +02007483
Bram Moolenaara1449832019-09-01 20:16:52 +02007484 Can also be used as a |method|: >
7485 GetGroup()->matchaddpos([23, 11])
7486
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007487matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007488 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007489 |:2match| or |:3match| command.
7490 Return a |List| with two elements:
7491 The name of the highlight group used
7492 The pattern used.
7493 When {nr} is not 1, 2 or 3 returns an empty |List|.
7494 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007495 This is useful to save and restore a |:match|.
7496 Highlighting matches using the |:match| commands are limited
7497 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007498
Bram Moolenaara1449832019-09-01 20:16:52 +02007499 Can also be used as a |method|: >
7500 GetMatch()->matcharg()
7501
Bram Moolenaaraff74912019-03-30 18:11:49 +01007502matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007503 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00007504 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007505 otherwise -1. See example for |matchadd()|. All matches can
7506 be deleted in one operation by |clearmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01007507 If {win} is specified, use the window with this number or
7508 window ID instead of the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007509
Bram Moolenaara1449832019-09-01 20:16:52 +02007510 Can also be used as a |method|: >
7511 GetMatch()->matchdelete()
7512
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007513matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007514 Same as |match()|, but return the index of first character
7515 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007516 :echo matchend("testing", "ing")
7517< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00007518 *strspn()* *strcspn()*
7519 Vim doesn't have a strspn() or strcspn() function, but you can
7520 do it with matchend(): >
7521 :let span = matchend(line, '[a-zA-Z]')
7522 :let span = matchend(line, '[^a-zA-Z]')
7523< Except that -1 is returned when there are no matches.
7524
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007525 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007526 :echo matchend("testing", "ing", 2)
7527< results in "7". >
7528 :echo matchend("testing", "ing", 5)
7529< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007530 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007531
Bram Moolenaara1449832019-09-01 20:16:52 +02007532 Can also be used as a |method|: >
7533 GetText()->matchend('word')
7534
Bram Moolenaar635414d2020-09-11 22:25:15 +02007535
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007536matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
Bram Moolenaar1b884a02020-12-10 21:11:27 +01007537 If {list} is a list of strings, then returns a |List| with all
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007538 the strings in {list} that fuzzy match {str}. The strings in
7539 the returned list are sorted based on the matching score.
7540
Bram Moolenaar8ded5b62020-10-23 16:50:30 +02007541 The optional {dict} argument always supports the following
7542 items:
7543 matchseq When this item is present and {str} contains
7544 multiple words separated by white space, then
7545 returns only matches that contain the words in
7546 the given sequence.
7547
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007548 If {list} is a list of dictionaries, then the optional {dict}
Bram Moolenaar8ded5b62020-10-23 16:50:30 +02007549 argument supports the following additional items:
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007550 key key of the item which is fuzzy matched against
7551 {str}. The value of this item should be a
7552 string.
7553 text_cb |Funcref| that will be called for every item
7554 in {list} to get the text for fuzzy matching.
7555 This should accept a dictionary item as the
7556 argument and return the text for that item to
7557 use for fuzzy matching.
7558
7559 {str} is treated as a literal string and regular expression
7560 matching is NOT supported. The maximum supported {str} length
7561 is 256.
Bram Moolenaar635414d2020-09-11 22:25:15 +02007562
Bram Moolenaar8ded5b62020-10-23 16:50:30 +02007563 When {str} has multiple words each separated by white space,
7564 then the list of strings that have all the words is returned.
7565
Bram Moolenaar635414d2020-09-11 22:25:15 +02007566 If there are no matching strings or there is an error, then an
7567 empty list is returned. If length of {str} is greater than
7568 256, then returns an empty list.
7569
7570 Example: >
7571 :echo matchfuzzy(["clay", "crow"], "cay")
7572< results in ["clay"]. >
7573 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
7574< results in a list of buffer names fuzzy matching "ndl". >
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007575 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
7576< results in a list of buffer information dicts with buffer
7577 names fuzzy matching "ndl". >
7578 :echo getbufinfo()->matchfuzzy("spl",
7579 \ {'text_cb' : {v -> v.name}})
7580< results in a list of buffer information dicts with buffer
7581 names fuzzy matching "spl". >
Bram Moolenaar635414d2020-09-11 22:25:15 +02007582 :echo v:oldfiles->matchfuzzy("test")
7583< results in a list of file names fuzzy matching "test". >
7584 :let l = readfile("buffer.c")->matchfuzzy("str")
Bram Moolenaar8ded5b62020-10-23 16:50:30 +02007585< results in a list of lines in "buffer.c" fuzzy matching "str". >
7586 :echo ['one two', 'two one']->matchfuzzy('two one')
7587< results in ['two one', 'one two']. >
7588 :echo ['one two', 'two one']->matchfuzzy('two one',
7589 \ {'matchseq': 1})
7590< results in ['two one'].
Bram Moolenaar635414d2020-09-11 22:25:15 +02007591
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007592matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
7593 Same as |matchfuzzy()|, but returns the list of matched
Bram Moolenaar9d19e4f2021-01-02 18:31:32 +01007594 strings, the list of character positions where characters
7595 in {str} matches and a list of matching scores. You can
7596 use |byteidx()|to convert a character position to a byte
7597 position.
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007598
7599 If {str} matches multiple times in a string, then only the
7600 positions for the best match is returned.
7601
7602 If there are no matching strings or there is an error, then a
Bram Moolenaar9d19e4f2021-01-02 18:31:32 +01007603 list with three empty list items is returned.
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007604
7605 Example: >
7606 :echo matchfuzzypos(['testing'], 'tsg')
Bram Moolenaar9d19e4f2021-01-02 18:31:32 +01007607< results in [['testing'], [[0, 2, 6]], [99]] >
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007608 :echo matchfuzzypos(['clay', 'lacy'], 'la')
Bram Moolenaar9d19e4f2021-01-02 18:31:32 +01007609< results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +02007610 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
Bram Moolenaar9d19e4f2021-01-02 18:31:32 +01007611< results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
Bram Moolenaar635414d2020-09-11 22:25:15 +02007612
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007613matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007614 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007615 list is the matched string, same as what matchstr() would
7616 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00007617 in |:substitute|. When an optional submatch didn't match an
7618 empty string is used. Example: >
7619 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
7620< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007621 When there is no match an empty list is returned.
7622
Bram Moolenaara1449832019-09-01 20:16:52 +02007623 Can also be used as a |method|: >
7624 GetList()->matchlist('word')
7625
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007626matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007627 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007628 :echo matchstr("testing", "ing")
7629< results in "ing".
7630 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007631 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007632 :echo matchstr("testing", "ing", 2)
7633< results in "ing". >
7634 :echo matchstr("testing", "ing", 5)
7635< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007636 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00007637 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007638
Bram Moolenaara1449832019-09-01 20:16:52 +02007639 Can also be used as a |method|: >
7640 GetText()->matchstr('word')
7641
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007642matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02007643 Same as |matchstr()|, but return the matched string, the start
7644 position and the end position of the match. Example: >
7645 :echo matchstrpos("testing", "ing")
7646< results in ["ing", 4, 7].
7647 When there is no match ["", -1, -1] is returned.
7648 The {start}, if given, has the same meaning as for |match()|. >
7649 :echo matchstrpos("testing", "ing", 2)
7650< results in ["ing", 4, 7]. >
7651 :echo matchstrpos("testing", "ing", 5)
7652< result is ["", -1, -1].
7653 When {expr} is a |List| then the matching item, the index
7654 of first item where {pat} matches, the start position and the
7655 end position of the match are returned. >
7656 :echo matchstrpos([1, '__x'], '\a')
7657< result is ["x", 1, 2, 3].
7658 The type isn't changed, it's not necessarily a String.
7659
Bram Moolenaara1449832019-09-01 20:16:52 +02007660 Can also be used as a |method|: >
7661 GetText()->matchstrpos('word')
Bram Moolenaar2e693a82019-10-16 22:35:02 +02007662<
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +01007663
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007664 *max()*
Bram Moolenaar6f02b002021-01-10 20:22:54 +01007665max({expr}) Return the maximum value of all items in {expr}. Example: >
7666 echo max([apples, pears, oranges])
7667
7668< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
Bram Moolenaar29634562020-01-09 21:46:04 +01007669 it returns the maximum of all values in the Dictionary.
7670 If {expr} is neither a List nor a Dictionary, or one of the
Bram Moolenaar690afe12017-01-28 18:34:47 +01007671 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02007672 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007673
Bram Moolenaarac92e252019-08-03 21:58:38 +02007674 Can also be used as a |method|: >
7675 mylist->max()
7676
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +01007677
7678menu_info({name} [, {mode}]) *menu_info()*
7679 Return information about the specified menu {name} in
7680 mode {mode}. The menu name should be specified without the
7681 shortcut character ('&').
7682
7683 {mode} can be one of these strings:
7684 "n" Normal
7685 "v" Visual (including Select)
7686 "o" Operator-pending
7687 "i" Insert
7688 "c" Cmd-line
7689 "s" Select
7690 "x" Visual
7691 "t" Terminal-Job
7692 "" Normal, Visual and Operator-pending
7693 "!" Insert and Cmd-line
7694 When {mode} is omitted, the modes for "" are used.
7695
7696 Returns a |Dictionary| containing the following items:
7697 accel menu item accelerator text |menu-text|
7698 display display name (name without '&')
7699 enabled v:true if this menu item is enabled
7700 Refer to |:menu-enable|
7701 icon name of the icon file (for toolbar)
7702 |toolbar-icon|
7703 iconidx index of a built-in icon
7704 modes modes for which the menu is defined. In
7705 addition to the modes mentioned above, these
7706 characters will be used:
7707 " " Normal, Visual and Operator-pending
7708 name menu item name.
7709 noremenu v:true if the {rhs} of the menu item is not
7710 remappable else v:false.
7711 priority menu order priority |menu-priority|
7712 rhs right-hand-side of the menu item. The returned
7713 string has special characters translated like
7714 in the output of the ":menu" command listing.
7715 When the {rhs} of a menu item is empty, then
7716 "<Nop>" is returned.
7717 script v:true if script-local remapping of {rhs} is
7718 allowed else v:false. See |:menu-script|.
7719 shortcut shortcut key (character after '&' in
7720 the menu name) |menu-shortcut|
7721 silent v:true if the menu item is created
7722 with <silent> argument |:menu-silent|
7723 submenus |List| containing the names of
7724 all the submenus. Present only if the menu
7725 item has submenus.
7726
7727 Returns an empty dictionary if the menu item is not found.
7728
7729 Examples: >
Bram Moolenaarff781552020-03-19 20:37:11 +01007730 :echo menu_info('Edit.Cut')
7731 :echo menu_info('File.Save', 'n')
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +01007732<
7733 Can also be used as a |method|: >
Bram Moolenaarff781552020-03-19 20:37:11 +01007734 GetMenuName()->menu_info('v')
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +01007735
7736
Bram Moolenaarac92e252019-08-03 21:58:38 +02007737< *min()*
Bram Moolenaar6f02b002021-01-10 20:22:54 +01007738min({expr}) Return the minimum value of all items in {expr}. Example: >
7739 echo min([apples, pears, oranges])
7740
7741< {expr} can be a |List| or a |Dictionary|. For a Dictionary,
Bram Moolenaar29634562020-01-09 21:46:04 +01007742 it returns the minimum of all values in the Dictionary.
7743 If {expr} is neither a List nor a Dictionary, or one of the
Bram Moolenaar690afe12017-01-28 18:34:47 +01007744 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02007745 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00007746
Bram Moolenaarac92e252019-08-03 21:58:38 +02007747 Can also be used as a |method|: >
7748 mylist->min()
7749
7750< *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007751mkdir({name} [, {path} [, {prot}]])
7752 Create directory {name}.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007753
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007754 If {path} is "p" then intermediate directories are created as
7755 necessary. Otherwise it must be "".
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007756
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007757 If {prot} is given it is used to set the protection bits of
Bram Moolenaar6f02b002021-01-10 20:22:54 +01007758 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
7759 the user, readable for others). Use 0o700 to make it
7760 unreadable for others. This is only used for the last part of
7761 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
7762 created with 0o755.
Bram Moolenaared39e1d2008-08-09 17:55:22 +00007763 Example: >
Bram Moolenaar6f02b002021-01-10 20:22:54 +01007764 :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007765
Bram Moolenaared39e1d2008-08-09 17:55:22 +00007766< This function is not available in the |sandbox|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007767
Bram Moolenaar78a16b02018-04-14 13:51:55 +02007768 There is no error if the directory already exists and the "p"
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007769 flag is passed (since patch 8.0.1708). However, without the
Bram Moolenaar10455d42019-11-21 15:36:18 +01007770 "p" option the call will fail.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007771
Bram Moolenaar98a29d02021-01-18 19:55:44 +01007772 The function result is a Number, which is TRUE if the call was
7773 successful or FALSE if the directory creation failed or partly
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007774 failed.
7775
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007776 Not available on all systems. To check use: >
7777 :if exists("*mkdir")
Bram Moolenaara1449832019-09-01 20:16:52 +02007778
7779< Can also be used as a |method|: >
7780 GetName()->mkdir()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007781<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007782 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00007783mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00007784 If [expr] is supplied and it evaluates to a non-zero Number or
7785 a non-empty String (|non-zero-arg|), then the full mode is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02007786 returned, otherwise only the first letter is returned.
Bram Moolenaar0e57dd82019-09-16 22:56:03 +02007787 Also see |state()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007788
Bram Moolenaar612cc382018-07-29 15:34:26 +02007789 n Normal, Terminal-Normal
7790 no Operator-pending
Bram Moolenaar5976f8f2018-12-27 23:44:44 +01007791 nov Operator-pending (forced characterwise |o_v|)
7792 noV Operator-pending (forced linewise |o_V|)
7793 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007794 CTRL-V is one character
Bram Moolenaar612cc382018-07-29 15:34:26 +02007795 niI Normal using |i_CTRL-O| in |Insert-mode|
7796 niR Normal using |i_CTRL-O| in |Replace-mode|
7797 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
7798 v Visual by character
7799 V Visual by line
7800 CTRL-V Visual blockwise
7801 s Select by character
7802 S Select by line
7803 CTRL-S Select blockwise
7804 i Insert
7805 ic Insert mode completion |compl-generic|
7806 ix Insert mode |i_CTRL-X| completion
7807 R Replace |R|
7808 Rc Replace mode completion |compl-generic|
7809 Rv Virtual Replace |gR|
7810 Rx Replace mode |i_CTRL-X| completion
7811 c Command-line editing
7812 cv Vim Ex mode |gQ|
7813 ce Normal Ex mode |Q|
7814 r Hit-enter prompt
7815 rm The -- more -- prompt
7816 r? A |:confirm| query of some sort
7817 ! Shell or external command is executing
7818 t Terminal-Job mode: keys go to the job
Bram Moolenaar446cb832008-06-24 21:56:24 +00007819 This is useful in the 'statusline' option or when used
7820 with |remote_expr()| In most other places it always returns
7821 "c" or "n".
Bram Moolenaar612cc382018-07-29 15:34:26 +02007822 Note that in the future more modes and more specific modes may
7823 be added. It's better not to compare the whole string but only
7824 the leading character(s).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007825 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007826
Bram Moolenaara1449832019-09-01 20:16:52 +02007827 Can also be used as a |method|: >
7828 DoFull()->mode()
7829
Bram Moolenaar7e506b62010-01-19 15:55:06 +01007830mzeval({expr}) *mzeval()*
7831 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02007832 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01007833 Numbers and strings are returned as they are.
7834 Pairs (including lists and improper lists) and vectors are
7835 returned as Vim |Lists|.
7836 Hash tables are represented as Vim |Dictionary| type with keys
7837 converted to strings.
7838 All other types are converted to string with display function.
7839 Examples: >
7840 :mz (define l (list 1 2 3))
7841 :mz (define h (make-hash)) (hash-set! h "list" l)
7842 :echo mzeval("l")
7843 :echo mzeval("h")
7844<
Bram Moolenaara1449832019-09-01 20:16:52 +02007845 Can also be used as a |method|: >
7846 GetExpr()->mzeval()
7847<
Bram Moolenaar7e506b62010-01-19 15:55:06 +01007848 {only available when compiled with the |+mzscheme| feature}
7849
Bram Moolenaar071d4272004-06-13 20:20:40 +00007850nextnonblank({lnum}) *nextnonblank()*
7851 Return the line number of the first line at or below {lnum}
7852 that is not blank. Example: >
7853 if getline(nextnonblank(1)) =~ "Java"
7854< When {lnum} is invalid or there is no non-blank line at or
7855 below it, zero is returned.
7856 See also |prevnonblank()|.
7857
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007858 Can also be used as a |method|: >
7859 GetLnum()->nextnonblank()
7860
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007861nr2char({expr} [, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007862 Return a string with a single character, which has the number
7863 value {expr}. Examples: >
7864 nr2char(64) returns "@"
7865 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01007866< When {utf8} is omitted or zero, the current 'encoding' is used.
7867 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007868 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01007869< With {utf8} set to 1, always return utf-8 characters.
7870 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00007871 nr2char(10), because NULs are represented with newline
7872 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00007873 string, thus results in an empty string.
Bram Moolenaaraff74912019-03-30 18:11:49 +01007874 To turn a list of character numbers into a string: >
7875 let list = [65, 66, 67]
7876 let str = join(map(list, {_, val -> nr2char(val)}), '')
7877< Result: "ABC"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007878
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007879 Can also be used as a |method|: >
7880 GetNumber()->nr2char()
Bram Moolenaar073e4b92019-08-18 23:01:56 +02007881
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007882or({expr}, {expr}) *or()*
7883 Bitwise OR on the two arguments. The arguments are converted
7884 to a number. A List, Dict or Float argument causes an error.
7885 Example: >
7886 :let bits = or(bits, 0x80)
Bram Moolenaar073e4b92019-08-18 23:01:56 +02007887< Can also be used as a |method|: >
7888 :let bits = bits->or(0x80)
Bram Moolenaard6e256c2011-12-14 15:32:50 +01007889
7890
Bram Moolenaar6a33ef02020-09-25 22:42:48 +02007891pathshorten({expr} [, {len}]) *pathshorten()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007892 Shorten directory names in the path {expr} and return the
7893 result. The tail, the file name, is kept as-is. The other
Bram Moolenaar6a33ef02020-09-25 22:42:48 +02007894 components in the path are reduced to {len} letters in length.
7895 If {len} is omitted or smaller than 1 then 1 is used (single
7896 letters). Leading '~' and '.' characters are kept. Examples: >
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007897 :echo pathshorten('~/.vim/autoload/myfile.vim')
7898< ~/.v/a/myfile.vim ~
Bram Moolenaar6a33ef02020-09-25 22:42:48 +02007899>
7900 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
7901< ~/.vi/au/myfile.vim ~
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007902 It doesn't matter if the path exists or not.
7903
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007904 Can also be used as a |method|: >
7905 GetDirectories()->pathshorten()
7906
Bram Moolenaare9b892e2016-01-17 21:15:58 +01007907perleval({expr}) *perleval()*
7908 Evaluate Perl expression {expr} in scalar context and return
7909 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01007910 converted, it is returned as a string Perl representation.
7911 Note: If you want an array or hash, {expr} must return a
7912 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01007913 Example: >
7914 :echo perleval('[1 .. 4]')
7915< [1, 2, 3, 4]
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007916
7917 Can also be used as a |method|: >
7918 GetExpr()->perleval()
7919
7920< {only available when compiled with the |+perl| feature}
Bram Moolenaare9b892e2016-01-17 21:15:58 +01007921
Bram Moolenaar931a2772019-07-04 16:54:54 +02007922
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02007923popup_ functions are documented here: |popup-functions|
Bram Moolenaar931a2772019-07-04 16:54:54 +02007924
7925
Bram Moolenaar446cb832008-06-24 21:56:24 +00007926pow({x}, {y}) *pow()*
7927 Return the power of {x} to the exponent {y} as a |Float|.
7928 {x} and {y} must evaluate to a |Float| or a |Number|.
7929 Examples: >
7930 :echo pow(3, 3)
7931< 27.0 >
7932 :echo pow(2, 16)
7933< 65536.0 >
7934 :echo pow(32, 0.20)
7935< 2.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02007936
7937 Can also be used as a |method|: >
7938 Compute()->pow(3)
7939<
Bram Moolenaar446cb832008-06-24 21:56:24 +00007940 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007941
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007942prevnonblank({lnum}) *prevnonblank()*
7943 Return the line number of the first line at or above {lnum}
7944 that is not blank. Example: >
7945 let ind = indent(prevnonblank(v:lnum - 1))
7946< When {lnum} is invalid or there is no non-blank line at or
7947 above it, zero is returned.
7948 Also see |nextnonblank()|.
7949
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02007950 Can also be used as a |method|: >
7951 GetLnum()->prevnonblank()
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007952
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007953printf({fmt}, {expr1} ...) *printf()*
7954 Return a String with {fmt}, where "%" items are replaced by
7955 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007956 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007957< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007958 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007959
Bram Moolenaarfd8ca212019-08-10 00:13:30 +02007960 When used as a |method| the base is passed as the second
7961 argument: >
7962 Compute()->printf("result: %d")
7963
7964< Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007965 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01007966 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00007967 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00007968 %.9s string truncated to 9 bytes
7969 %c single byte
7970 %d decimal number
7971 %5d decimal number padded with spaces to 5 characters
7972 %x hex number
7973 %04x hex number padded with zeros to at least 4 characters
7974 %X hex number using upper case letters
7975 %o octal number
Bram Moolenaar91984b92016-08-16 21:58:41 +02007976 %08b binary number padded with zeros to at least 8 chars
Bram Moolenaar04186092016-08-29 21:55:35 +02007977 %f floating point number as 12.23, inf, -inf or nan
7978 %F floating point number as 12.23, INF, -INF or NAN
7979 %e floating point number as 1.23e3, inf, -inf or nan
7980 %E floating point number as 1.23E3, INF, -INF or NAN
Bram Moolenaar446cb832008-06-24 21:56:24 +00007981 %g floating point number, as %f or %e depending on value
Bram Moolenaar3df01732017-02-17 22:47:16 +01007982 %G floating point number, as %F or %E depending on value
Bram Moolenaar446cb832008-06-24 21:56:24 +00007983 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007984
7985 Conversion specifications start with '%' and end with the
7986 conversion type. All other characters are copied unchanged to
7987 the result.
7988
7989 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007990 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007991
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007992 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007993
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007994 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00007995 Zero or more of the following flags:
7996
Bram Moolenaar4be06f92005-07-29 22:36:03 +00007997 # The value should be converted to an "alternate
7998 form". For c, d, and s conversions, this option
7999 has no effect. For o conversions, the precision
8000 of the number is increased to force the first
8001 character of the output string to a zero (except
8002 if a zero value is printed with an explicit
8003 precision of zero).
Bram Moolenaar91984b92016-08-16 21:58:41 +02008004 For b and B conversions, a non-zero result has
8005 the string "0b" (or "0B" for B conversions)
8006 prepended to it.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008007 For x and X conversions, a non-zero result has
8008 the string "0x" (or "0X" for X conversions)
8009 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008010
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008011 0 (zero) Zero padding. For all conversions the converted
8012 value is padded on the left with zeros rather
8013 than blanks. If a precision is given with a
Bram Moolenaar91984b92016-08-16 21:58:41 +02008014 numeric conversion (d, b, B, o, x, and X), the 0
8015 flag is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008016
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008017 - A negative field width flag; the converted value
8018 is to be left adjusted on the field boundary.
8019 The converted value is padded on the right with
8020 blanks, rather than on the left with blanks or
8021 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008022
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008023 ' ' (space) A blank should be left before a positive
8024 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008025
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008026 + A sign must always be placed before a number
Bram Moolenaar58b85342016-08-14 19:54:54 +02008027 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008028 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008029
8030 field-width
8031 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00008032 field width. If the converted value has fewer bytes
8033 than the field width, it will be padded with spaces on
8034 the left (or right, if the left-adjustment flag has
8035 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008036
8037 .precision
8038 An optional precision, in the form of a period '.'
8039 followed by an optional digit string. If the digit
8040 string is omitted, the precision is taken as zero.
8041 This gives the minimum number of digits to appear for
8042 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00008043 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008044 For floating point it is the number of digits after
8045 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008046
8047 type
8048 A character that specifies the type of conversion to
8049 be applied, see below.
8050
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008051 A field width or precision, or both, may be indicated by an
8052 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar58b85342016-08-14 19:54:54 +02008053 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008054 negative field width is treated as a left adjustment flag
8055 followed by a positive field width; a negative precision is
8056 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008057 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008058< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008059 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008060
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008061 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008062
Bram Moolenaar91984b92016-08-16 21:58:41 +02008063 *printf-d* *printf-b* *printf-B* *printf-o*
8064 *printf-x* *printf-X*
8065 dbBoxX The Number argument is converted to signed decimal
8066 (d), unsigned binary (b and B), unsigned octal (o), or
8067 unsigned hexadecimal (x and X) notation. The letters
8068 "abcdef" are used for x conversions; the letters
8069 "ABCDEF" are used for X conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008070 The precision, if any, gives the minimum number of
8071 digits that must appear; if the converted value
8072 requires fewer digits, it is padded on the left with
8073 zeros.
8074 In no case does a non-existent or small field width
8075 cause truncation of a numeric field; if the result of
8076 a conversion is wider than the field width, the field
8077 is expanded to contain the conversion result.
Bram Moolenaar30567352016-08-27 21:25:44 +02008078 The 'h' modifier indicates the argument is 16 bits.
8079 The 'l' modifier indicates the argument is 32 bits.
8080 The 'L' modifier indicates the argument is 64 bits.
8081 Generally, these modifiers are not useful. They are
8082 ignored when type is known from the argument.
8083
8084 i alias for d
8085 D alias for ld
8086 U alias for lu
8087 O alias for lo
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008088
Bram Moolenaar446cb832008-06-24 21:56:24 +00008089 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008090 c The Number argument is converted to a byte, and the
8091 resulting character is written.
8092
Bram Moolenaar446cb832008-06-24 21:56:24 +00008093 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008094 s The text of the String argument is used. If a
8095 precision is specified, no more bytes than the number
8096 specified are used.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008097 If the argument is not a String type, it is
8098 automatically converted to text with the same format
8099 as ":echo".
Bram Moolenaar0122c402015-02-03 19:13:34 +01008100 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01008101 S The text of the String argument is used. If a
8102 precision is specified, no more display cells than the
Bram Moolenaar4c92e752019-02-17 21:18:32 +01008103 number specified are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008104
Bram Moolenaar446cb832008-06-24 21:56:24 +00008105 *printf-f* *E807*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008106 f F The Float argument is converted into a string of the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008107 form 123.456. The precision specifies the number of
8108 digits after the decimal point. When the precision is
8109 zero the decimal point is omitted. When the precision
8110 is not specified 6 is used. A really big number
Bram Moolenaar04186092016-08-29 21:55:35 +02008111 (out of range or dividing by zero) results in "inf"
Bram Moolenaarf8be4612017-06-23 20:52:40 +02008112 or "-inf" with %f (INF or -INF with %F).
8113 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
Bram Moolenaar446cb832008-06-24 21:56:24 +00008114 Example: >
8115 echo printf("%.2f", 12.115)
8116< 12.12
8117 Note that roundoff depends on the system libraries.
8118 Use |round()| when in doubt.
8119
8120 *printf-e* *printf-E*
8121 e E The Float argument is converted into a string of the
8122 form 1.234e+03 or 1.234E+03 when using 'E'. The
8123 precision specifies the number of digits after the
8124 decimal point, like with 'f'.
8125
8126 *printf-g* *printf-G*
8127 g G The Float argument is converted like with 'f' if the
8128 value is between 0.001 (inclusive) and 10000000.0
8129 (exclusive). Otherwise 'e' is used for 'g' and 'E'
8130 for 'G'. When no precision is specified superfluous
8131 zeroes and '+' signs are removed, except for the zero
8132 immediately after the decimal point. Thus 10000000.0
8133 results in 1.0e7.
8134
8135 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008136 % A '%' is written. No argument is converted. The
8137 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008138
Bram Moolenaarc236c162008-07-13 17:41:49 +00008139 When a Number argument is expected a String argument is also
8140 accepted and automatically converted.
8141 When a Float or String argument is expected a Number argument
8142 is also accepted and automatically converted.
8143 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008144
Bram Moolenaar83bab712005-08-01 21:58:57 +00008145 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008146 The number of {exprN} arguments must exactly match the number
8147 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00008148 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00008149
8150
Bram Moolenaar077cc7a2020-09-04 16:35:35 +02008151prompt_getprompt({buf}) *prompt_getprompt()*
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01008152 Returns the effective prompt text for buffer {buf}. {buf} can
8153 be a buffer name or number. See |prompt-buffer|.
Bram Moolenaar077cc7a2020-09-04 16:35:35 +02008154
8155 If the buffer doesn't exist or isn't a prompt buffer, an empty
8156 string is returned.
8157
8158 Can also be used as a |method|: >
8159 GetBuffer()->prompt_getprompt()
8160
8161
Bram Moolenaarf2732452018-06-03 14:47:35 +02008162prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02008163 Set prompt callback for buffer {buf} to {expr}. When {expr}
8164 is an empty string the callback is removed. This has only
Bram Moolenaarf2732452018-06-03 14:47:35 +02008165 effect if {buf} has 'buftype' set to "prompt".
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02008166
Bram Moolenaarf2732452018-06-03 14:47:35 +02008167 The callback is invoked when pressing Enter. The current
8168 buffer will always be the prompt buffer. A new line for a
8169 prompt is added before invoking the callback, thus the prompt
8170 for which the callback was invoked will be in the last but one
8171 line.
8172 If the callback wants to add text to the buffer, it must
8173 insert it above the last line, since that is where the current
8174 prompt is. This can also be done asynchronously.
8175 The callback is invoked with one argument, which is the text
8176 that was entered at the prompt. This can be an empty string
8177 if the user only typed Enter.
8178 Example: >
Bram Moolenaara8eee212019-08-24 22:14:58 +02008179 call prompt_setcallback(bufnr(), function('s:TextEntered'))
Bram Moolenaarf2732452018-06-03 14:47:35 +02008180 func s:TextEntered(text)
8181 if a:text == 'exit' || a:text == 'quit'
8182 stopinsert
8183 close
8184 else
8185 call append(line('$') - 1, 'Entered: "' . a:text . '"')
8186 " Reset 'modified' to allow the buffer to be closed.
8187 set nomodified
8188 endif
8189 endfunc
8190
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02008191< Can also be used as a |method|: >
8192 GetBuffer()->prompt_setcallback(callback)
8193
8194
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02008195prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8196 Set a callback for buffer {buf} to {expr}. When {expr} is an
8197 empty string the callback is removed. This has only effect if
8198 {buf} has 'buftype' set to "prompt".
8199
8200 This callback will be invoked when pressing CTRL-C in Insert
8201 mode. Without setting a callback Vim will exit Insert mode,
8202 as in any buffer.
8203
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02008204 Can also be used as a |method|: >
8205 GetBuffer()->prompt_setinterrupt(callback)
8206
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02008207prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8208 Set prompt for buffer {buf} to {text}. You most likely want
8209 {text} to end in a space.
8210 The result is only visible if {buf} has 'buftype' set to
8211 "prompt". Example: >
Bram Moolenaara8eee212019-08-24 22:14:58 +02008212 call prompt_setprompt(bufnr(), 'command: ')
Bram Moolenaar98aefe72018-12-13 22:20:09 +01008213<
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02008214 Can also be used as a |method|: >
8215 GetBuffer()->prompt_setprompt('command: ')
8216
Bram Moolenaar077cc7a2020-09-04 16:35:35 +02008217prop_ functions are documented here: |text-prop-functions|
Bram Moolenaarf2732452018-06-03 14:47:35 +02008218
Bram Moolenaare9bd5722019-08-17 19:36:06 +02008219pum_getpos() *pum_getpos()*
8220 If the popup menu (see |ins-completion-menu|) is not visible,
8221 returns an empty |Dictionary|, otherwise, returns a
8222 |Dictionary| with the following keys:
8223 height nr of items visible
8224 width screen cells
8225 row top screen row (0 first row)
8226 col leftmost screen column (0 first col)
8227 size total nr of items
Bram Moolenaar96f45c02019-10-26 19:53:45 +02008228 scrollbar |TRUE| if scrollbar is visible
Bram Moolenaare9bd5722019-08-17 19:36:06 +02008229
8230 The values are the same as in |v:event| during
8231 |CompleteChanged|.
8232
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008233pumvisible() *pumvisible()*
8234 Returns non-zero when the popup menu is visible, zero
8235 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008236 This can be used to avoid some things that would remove the
8237 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008238
Bram Moolenaar30b65812012-07-12 22:01:11 +02008239py3eval({expr}) *py3eval()*
8240 Evaluate Python expression {expr} and return its result
8241 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008242 Numbers and strings are returned as they are (strings are
8243 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02008244 'encoding').
8245 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008246 Dictionaries are represented as Vim |Dictionary| type with
Bram Moolenaar30b65812012-07-12 22:01:11 +02008247 keys converted to strings.
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02008248
8249 Can also be used as a |method|: >
8250 GetExpr()->py3eval()
8251
8252< {only available when compiled with the |+python3| feature}
Bram Moolenaar30b65812012-07-12 22:01:11 +02008253
8254 *E858* *E859*
8255pyeval({expr}) *pyeval()*
8256 Evaluate Python expression {expr} and return its result
8257 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008258 Numbers and strings are returned as they are (strings are
Bram Moolenaar30b65812012-07-12 22:01:11 +02008259 copied though).
8260 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008261 Dictionaries are represented as Vim |Dictionary| type,
Bram Moolenaard09acef2012-09-21 14:54:30 +02008262 non-string keys result in error.
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02008263
8264 Can also be used as a |method|: >
8265 GetExpr()->pyeval()
8266
8267< {only available when compiled with the |+python| feature}
Bram Moolenaar30b65812012-07-12 22:01:11 +02008268
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01008269pyxeval({expr}) *pyxeval()*
8270 Evaluate Python expression {expr} and return its result
8271 converted to Vim data structures.
8272 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8273 See also: |pyeval()|, |py3eval()|
Bram Moolenaar3f4f3d82019-09-04 20:05:59 +02008274
8275 Can also be used as a |method|: >
8276 GetExpr()->pyxeval()
8277
8278< {only available when compiled with the |+python| or the
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01008279 |+python3| feature}
8280
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00008281 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00008282range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008283 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00008284 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8285 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8286 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8287 {max}] (increasing {expr} with {stride} each time, not
8288 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00008289 When the maximum is one before the start the result is an
8290 empty list. When the maximum is more than one before the
8291 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00008292 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008293 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00008294 range(2, 4) " [2, 3, 4]
8295 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008296 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00008297 range(0) " []
8298 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00008299<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008300 Can also be used as a |method|: >
8301 GetExpr()->range()
8302<
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +01008303
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02008304rand([{expr}]) *rand()* *random*
Bram Moolenaarf8c1f922019-11-28 22:13:14 +01008305 Return a pseudo-random Number generated with an xoshiro128**
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01008306 algorithm using seed {expr}. The returned number is 32 bits,
8307 also on 64 bits systems, for consistency.
8308 {expr} can be initialized by |srand()| and will be updated by
8309 rand(). If {expr} is omitted, an internal seed value is used
8310 and updated.
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +01008311
8312 Examples: >
8313 :echo rand()
8314 :let seed = srand()
8315 :echo rand(seed)
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01008316 :echo rand(seed) % 16 " random number 0 - 15
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +01008317<
Bram Moolenaarc423ad72021-01-13 20:38:03 +01008318
8319readblob({fname}) *readblob()*
8320 Read file {fname} in binary mode and return a |Blob|.
8321 When the file can't be opened an error message is given and
8322 the result is an empty |Blob|.
8323 Also see |readfile()| and |writefile()|.
8324
8325
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008326readdir({directory} [, {expr} [, {dict}]]) *readdir()*
Bram Moolenaar543c9b12019-04-05 22:50:40 +02008327 Return a list with file and directory names in {directory}.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02008328 You can also use |glob()| if you don't need to do complicated
8329 things, such as limiting the number of matches.
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008330 The list will be sorted (case sensitive), see the {dict}
8331 argument below for changing the sort order.
Bram Moolenaar543c9b12019-04-05 22:50:40 +02008332
8333 When {expr} is omitted all entries are included.
8334 When {expr} is given, it is evaluated to check what to do:
8335 If {expr} results in -1 then no further entries will
8336 be handled.
8337 If {expr} results in 0 then this entry will not be
8338 added to the list.
8339 If {expr} results in 1 then this entry will be added
8340 to the list.
Bram Moolenaar6c9ba042020-06-01 16:09:41 +02008341 The entries "." and ".." are always excluded.
Bram Moolenaar543c9b12019-04-05 22:50:40 +02008342 Each time {expr} is evaluated |v:val| is set to the entry name.
8343 When {expr} is a function the name is passed as the argument.
8344 For example, to get a list of files ending in ".txt": >
8345 readdir(dirname, {n -> n =~ '.txt$'})
8346< To skip hidden and backup files: >
8347 readdir(dirname, {n -> n !~ '^\.\|\~$'})
8348
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008349< The optional {dict} argument allows for further custom
8350 values. Currently this is used to specify if and how sorting
8351 should be performed. The dict can have the following members:
8352
8353 sort How to sort the result returned from the system.
8354 Valid values are:
8355 "none" do not sort (fastest method)
8356 "case" sort case sensitive (byte value of
8357 each character, technically, using
8358 strcmp()) (default)
8359 "icase" sort case insensitive (technically
8360 using strcasecmp())
8361 "collate" sort using the collation order
8362 of the "POSIX" or "C" |locale|
8363 (technically using strcoll())
8364 Other values are silently ignored.
8365
8366 For example, to get a list of all files in the current
8367 directory without sorting the individual entries: >
8368 readdir('.', '1', #{sort: 'none'})
Bram Moolenaar543c9b12019-04-05 22:50:40 +02008369< If you want to get a directory tree: >
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008370 function! s:tree(dir)
8371 return {a:dir : map(readdir(a:dir),
Bram Moolenaar543c9b12019-04-05 22:50:40 +02008372 \ {_, x -> isdirectory(x) ?
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008373 \ {x : s:tree(a:dir . '/' . x)} : x})}
8374 endfunction
8375 echo s:tree(".")
Bram Moolenaar543c9b12019-04-05 22:50:40 +02008376<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008377 Can also be used as a |method|: >
8378 GetDirName()->readdir()
8379<
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008380readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
Bram Moolenaar6c9ba042020-06-01 16:09:41 +02008381 Extended version of |readdir()|.
8382 Return a list of Dictionaries with file and directory
8383 information in {directory}.
8384 This is useful if you want to get the attributes of file and
8385 directory at the same time as getting a list of a directory.
8386 This is much faster than calling |readdir()| then calling
8387 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8388 each file and directory especially on MS-Windows.
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008389 The list will by default be sorted by name (case sensitive),
8390 the sorting can be changed by using the optional {dict}
8391 argument, see |readdir()|.
Bram Moolenaar6c9ba042020-06-01 16:09:41 +02008392
8393 The Dictionary for file and directory information has the
8394 following items:
8395 group Group name of the entry. (Only on Unix)
8396 name Name of the entry.
8397 perm Permissions of the entry. See |getfperm()|.
8398 size Size of the entry. See |getfsize()|.
8399 time Timestamp of the entry. See |getftime()|.
8400 type Type of the entry.
8401 On Unix, almost same as |getftype()| except:
8402 Symlink to a dir "linkd"
8403 Other symlink "link"
8404 On MS-Windows:
8405 Normal file "file"
8406 Directory "dir"
8407 Junction "junction"
8408 Symlink to a dir "linkd"
8409 Other symlink "link"
8410 Other reparse point "reparse"
8411 user User name of the entry's owner. (Only on Unix)
8412 On Unix, if the entry is a symlink, the Dictionary includes
8413 the information of the target (except the "type" item).
8414 On MS-Windows, it includes the information of the symlink
8415 itself because of performance reasons.
8416
8417 When {expr} is omitted all entries are included.
8418 When {expr} is given, it is evaluated to check what to do:
8419 If {expr} results in -1 then no further entries will
8420 be handled.
8421 If {expr} results in 0 then this entry will not be
8422 added to the list.
8423 If {expr} results in 1 then this entry will be added
8424 to the list.
8425 The entries "." and ".." are always excluded.
Bram Moolenaare46a4402020-06-30 20:38:27 +02008426 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
Bram Moolenaar6c9ba042020-06-01 16:09:41 +02008427 of the entry.
8428 When {expr} is a function the entry is passed as the argument.
8429 For example, to get a list of files ending in ".txt": >
8430 readdirex(dirname, {e -> e.name =~ '.txt$'})
8431<
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02008432 For example, to get a list of all files in the current
8433 directory without sorting the individual entries: >
8434 readdirex(dirname, '1', #{sort: 'none'})
8435
8436<
Bram Moolenaar6c9ba042020-06-01 16:09:41 +02008437 Can also be used as a |method|: >
8438 GetDirName()->readdirex()
8439<
Bram Moolenaarc423ad72021-01-13 20:38:03 +01008440
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008441 *readfile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01008442readfile({fname} [, {type} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008443 Read file {fname} and return a |List|, each line of the file
Bram Moolenaar6100d022016-10-02 16:51:57 +02008444 as an item. Lines are broken at NL characters. Macintosh
8445 files separated with CR will result in a single long line
8446 (unless a NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02008447 All NUL characters are replaced with a NL character.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01008448 When {type} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008449 - When the last line ends in a NL an extra empty list item is
8450 added.
8451 - No CR characters are removed.
8452 Otherwise:
8453 - CR characters that appear before a NL are removed.
8454 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02008455 - When 'encoding' is Unicode any UTF-8 byte order mark is
8456 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008457 When {max} is given this specifies the maximum number of lines
8458 to be read. Useful if you only want to check the first ten
8459 lines of a file: >
8460 :for line in readfile(fname, '', 10)
8461 : if line =~ 'Date' | echo line | endif
8462 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00008463< When {max} is negative -{max} lines from the end of the file
8464 are returned, or as many as there are.
8465 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00008466 Note that without {max} the whole file is read into memory.
8467 Also note that there is no recognition of encoding. Read a
8468 file into a buffer if you need to.
Bram Moolenaarc423ad72021-01-13 20:38:03 +01008469 Deprecated (use |readblob()| instead): When {type} contains
8470 "B" a |Blob| is returned with the binary data of the file
8471 unmodified.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00008472 When the file can't be opened an error message is given and
8473 the result is an empty list.
8474 Also see |writefile()|.
8475
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008476 Can also be used as a |method|: >
8477 GetFileName()->readfile()
8478
Bram Moolenaar85629982020-06-01 18:39:20 +02008479reduce({object}, {func} [, {initial}]) *reduce()* *E998*
8480 {func} is called for every item in {object}, which can be a
8481 |List| or a |Blob|. {func} is called with two arguments: the
8482 result so far and current item. After processing all items
8483 the result is returned.
8484
8485 {initial} is the initial result. When omitted, the first item
8486 in {object} is used and {func} is first called for the second
8487 item. If {initial} is not given and {object} is empty no
8488 result can be computed, an E998 error is given.
8489
8490 Examples: >
8491 echo reduce([1, 3, 5], { acc, val -> acc + val })
8492 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
8493 echo reduce(0z1122, { acc, val -> 2 * acc + val })
8494<
8495 Can also be used as a |method|: >
8496 echo mylist->reduce({ acc, val -> acc + val }, 0)
8497
8498
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02008499reg_executing() *reg_executing()*
8500 Returns the single letter name of the register being executed.
8501 Returns an empty string when no register is being executed.
8502 See |@|.
8503
8504reg_recording() *reg_recording()*
8505 Returns the single letter name of the register being recorded.
Bram Moolenaar62e1bb42019-04-08 16:25:07 +02008506 Returns an empty string when not recording. See |q|.
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02008507
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008508reltime([{start} [, {end}]]) *reltime()*
Bram Moolenaar3132cdd2020-11-05 20:41:49 +01008509 Return an item that represents a time value. The item is a
8510 list with items that depend on the system. In Vim 9 script
8511 list<any> can be used.
8512 The item can be passed to |reltimestr()| to convert it to a
8513 string or |reltimefloat()| to convert to a Float.
8514
8515 Without an argument reltime() returns the current time.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008516 With one argument is returns the time passed since the time
8517 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00008518 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008519 and {end}.
Bram Moolenaar3132cdd2020-11-05 20:41:49 +01008520
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008521 The {start} and {end} arguments must be values returned by
8522 reltime().
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008523
8524 Can also be used as a |method|: >
8525 GetStart()->reltime()
8526<
Bram Moolenaardb84e452010-08-15 13:50:43 +02008527 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008528
Bram Moolenaar03413f42016-04-12 21:07:15 +02008529reltimefloat({time}) *reltimefloat()*
8530 Return a Float that represents the time value of {time}.
8531 Example: >
8532 let start = reltime()
8533 call MyFunction()
8534 let seconds = reltimefloat(reltime(start))
8535< See the note of reltimestr() about overhead.
8536 Also see |profiling|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008537
8538 Can also be used as a |method|: >
8539 reltime(start)->reltimefloat()
8540
8541< {only available when compiled with the |+reltime| feature}
Bram Moolenaar03413f42016-04-12 21:07:15 +02008542
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008543reltimestr({time}) *reltimestr()*
8544 Return a String that represents the time value of {time}.
8545 This is the number of seconds, a dot and the number of
8546 microseconds. Example: >
8547 let start = reltime()
8548 call MyFunction()
8549 echo reltimestr(reltime(start))
8550< Note that overhead for the commands will be added to the time.
8551 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008552 Leading spaces are used to make the string align nicely. You
8553 can use split() to remove it. >
8554 echo split(reltimestr(reltime(start)))[0]
8555< Also see |profiling|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008556
8557 Can also be used as a |method|: >
8558 reltime(start)->reltimestr()
8559
8560< {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008561
Bram Moolenaar071d4272004-06-13 20:20:40 +00008562 *remote_expr()* *E449*
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01008563remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar58b85342016-08-14 19:54:54 +02008564 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00008565 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00008566 The result must be a String or a |List|. A |List| is turned
8567 into a String by joining the items with a line break in
8568 between (not at the end), like with join(expr, "\n").
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01008569 If {idvar} is present and not empty, it is taken as the name
8570 of a variable and a {serverid} for later use with
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01008571 |remote_read()| is stored there.
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01008572 If {timeout} is given the read times out after this many
8573 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008574 See also |clientserver| |RemoteReply|.
8575 This function is not available in the |sandbox|.
8576 {only available when compiled with the |+clientserver| feature}
8577 Note: Any errors will cause a local error message to be issued
8578 and the result will be the empty string.
Bram Moolenaar01164a62017-11-02 22:58:42 +01008579
8580 Variables will be evaluated in the global namespace,
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008581 independent of a function currently being active. Except
Bram Moolenaar01164a62017-11-02 22:58:42 +01008582 when in debug mode, then local function variables and
8583 arguments can be evaluated.
8584
Bram Moolenaar071d4272004-06-13 20:20:40 +00008585 Examples: >
8586 :echo remote_expr("gvim", "2+2")
8587 :echo remote_expr("gvim1", "b:current_syntax")
8588<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008589 Can also be used as a |method|: >
8590 ServerName()->remote_expr(expr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008591
8592remote_foreground({server}) *remote_foreground()*
8593 Move the Vim server with the name {server} to the foreground.
8594 This works like: >
8595 remote_expr({server}, "foreground()")
8596< Except that on Win32 systems the client does the work, to work
8597 around the problem that the OS doesn't always allow the server
8598 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00008599 Note: This does not restore the window if it was minimized,
8600 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008601 This function is not available in the |sandbox|.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008602
8603 Can also be used as a |method|: >
8604 ServerName()->remote_foreground()
8605
8606< {only in the Win32, Athena, Motif and GTK GUI versions and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00008607 Win32 console version}
8608
8609
8610remote_peek({serverid} [, {retvar}]) *remote_peek()*
8611 Returns a positive number if there are available strings
8612 from {serverid}. Copies any reply string into the variable
Bram Moolenaar58b85342016-08-14 19:54:54 +02008613 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00008614 name of a variable.
8615 Returns zero if none are available.
8616 Returns -1 if something is wrong.
8617 See also |clientserver|.
8618 This function is not available in the |sandbox|.
8619 {only available when compiled with the |+clientserver| feature}
8620 Examples: >
8621 :let repl = ""
8622 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
8623
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008624< Can also be used as a |method|: >
8625 ServerId()->remote_peek()
8626
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01008627remote_read({serverid}, [{timeout}]) *remote_read()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008628 Return the oldest available reply from {serverid} and consume
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01008629 it. Unless a {timeout} in seconds is given, it blocks until a
8630 reply is available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008631 See also |clientserver|.
8632 This function is not available in the |sandbox|.
8633 {only available when compiled with the |+clientserver| feature}
8634 Example: >
8635 :echo remote_read(id)
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008636
8637< Can also be used as a |method|: >
8638 ServerId()->remote_read()
Bram Moolenaar071d4272004-06-13 20:20:40 +00008639<
8640 *remote_send()* *E241*
8641remote_send({server}, {string} [, {idvar}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02008642 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00008643 keys and the function returns immediately. At the Vim server
8644 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008645 If {idvar} is present, it is taken as the name of a variable
8646 and a {serverid} for later use with remote_read() is stored
8647 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008648 See also |clientserver| |RemoteReply|.
8649 This function is not available in the |sandbox|.
8650 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01008651
Bram Moolenaar071d4272004-06-13 20:20:40 +00008652 Note: Any errors will be reported in the server and may mess
8653 up the display.
8654 Examples: >
8655 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
8656 \ remote_read(serverid)
8657
8658 :autocmd NONE RemoteReply *
8659 \ echo remote_read(expand("<amatch>"))
8660 :echo remote_send("gvim", ":sleep 10 | echo ".
8661 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008662<
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008663 Can also be used as a |method|: >
8664 ServerName()->remote_send(keys)
8665<
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01008666 *remote_startserver()* *E941* *E942*
8667remote_startserver({name})
8668 Become the server {name}. This fails if already running as a
8669 server, when |v:servername| is not empty.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008670
8671 Can also be used as a |method|: >
8672 ServerName()->remote_startserver()
8673
8674< {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01008675
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008676remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008677 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008678 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008679 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaare46a4402020-06-30 20:38:27 +02008680 return a |List| with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008681 item as {end} a list with one item is returned. When {end}
8682 points to an item before {idx} this is an error.
8683 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008684 Example: >
8685 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008686 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01008687<
8688 Use |delete()| to remove a file.
8689
Bram Moolenaarac92e252019-08-03 21:58:38 +02008690 Can also be used as a |method|: >
8691 mylist->remove(idx)
8692
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01008693remove({blob}, {idx} [, {end}])
8694 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
8695 return the byte.
8696 With {end}: Remove bytes from {idx} to {end} (inclusive) and
8697 return a |Blob| with these bytes. When {idx} points to the same
8698 byte as {end} a |Blob| with one byte is returned. When {end}
8699 points to a byte before {idx} this is an error.
8700 Example: >
8701 :echo "last byte: " . remove(myblob, -1)
8702 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01008703
Bram Moolenaard8b02732005-01-14 21:48:43 +00008704remove({dict}, {key})
Bram Moolenaar54775062019-07-31 21:07:14 +02008705 Remove the entry from {dict} with key {key} and return it.
8706 Example: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00008707 :echo "removed " . remove(dict, "one")
8708< If there is no {key} in {dict} this is an error.
8709
Bram Moolenaar071d4272004-06-13 20:20:40 +00008710rename({from}, {to}) *rename()*
8711 Rename the file by the name {from} to the name {to}. This
8712 should also work to move files across file systems. The
8713 result is a Number, which is 0 if the file was renamed
8714 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00008715 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008716 This function is not available in the |sandbox|.
8717
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008718 Can also be used as a |method|: >
8719 GetOldName()->rename(newname)
8720
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00008721repeat({expr}, {count}) *repeat()*
8722 Repeat {expr} {count} times and return the concatenated
8723 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00008724 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00008725< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008726 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar58b85342016-08-14 19:54:54 +02008727 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00008728 :let longlist = repeat(['a', 'b'], 3)
8729< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00008730
Bram Moolenaarac92e252019-08-03 21:58:38 +02008731 Can also be used as a |method|: >
8732 mylist->repeat(count)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008733
Bram Moolenaar071d4272004-06-13 20:20:40 +00008734resolve({filename}) *resolve()* *E655*
8735 On MS-Windows, when {filename} is a shortcut (a .lnk file),
8736 returns the path the shortcut points to in a simplified form.
Bram Moolenaardce1e892019-02-10 23:18:53 +01008737 When {filename} is a symbolic link or junction point, return
8738 the full path to the target. If the target of junction is
8739 removed, return {filename}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008740 On Unix, repeat resolving symbolic links in all path
8741 components of {filename} and return the simplified result.
8742 To cope with link cycles, resolving of symbolic links is
8743 stopped after 100 iterations.
8744 On other systems, return the simplified {filename}.
8745 The simplification step is done as by |simplify()|.
8746 resolve() keeps a leading path component specifying the
8747 current directory (provided the result is still a relative
8748 path name) and also keeps a trailing path separator.
8749
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008750 Can also be used as a |method|: >
8751 GetName()->resolve()
Bram Moolenaarac92e252019-08-03 21:58:38 +02008752
8753reverse({object}) *reverse()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01008754 Reverse the order of items in {object} in-place.
8755 {object} can be a |List| or a |Blob|.
8756 Returns {object}.
8757 If you want an object to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008758 :let revlist = reverse(copy(mylist))
Bram Moolenaarac92e252019-08-03 21:58:38 +02008759< Can also be used as a |method|: >
8760 mylist->reverse()
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008761
Bram Moolenaar446cb832008-06-24 21:56:24 +00008762round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00008763 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00008764 as a |Float|. If {expr} lies halfway between two integral
8765 values, then use the larger one (away from zero).
8766 {expr} must evaluate to a |Float| or a |Number|.
8767 Examples: >
8768 echo round(0.456)
8769< 0.0 >
8770 echo round(4.5)
8771< 5.0 >
8772 echo round(-4.5)
8773< -5.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02008774
8775 Can also be used as a |method|: >
8776 Compute()->round()
8777<
Bram Moolenaar446cb832008-06-24 21:56:24 +00008778 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008779
Bram Moolenaare99be0e2019-03-26 22:51:09 +01008780rubyeval({expr}) *rubyeval()*
8781 Evaluate Ruby expression {expr} and return its result
8782 converted to Vim data structures.
8783 Numbers, floats and strings are returned as they are (strings
8784 are copied though).
8785 Arrays are represented as Vim |List| type.
8786 Hashes are represented as Vim |Dictionary| type.
8787 Other objects are represented as strings resulted from their
8788 "Object#to_s" method.
Bram Moolenaara0d1fef2019-09-04 22:29:14 +02008789
8790 Can also be used as a |method|: >
8791 GetRubyExpr()->rubyeval()
8792
8793< {only available when compiled with the |+ruby| feature}
Bram Moolenaare99be0e2019-03-26 22:51:09 +01008794
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008795screenattr({row}, {col}) *screenattr()*
Bram Moolenaar36f44c22016-08-28 18:17:20 +02008796 Like |screenchar()|, but return the attribute. This is a rather
Bram Moolenaar9a773482013-06-11 18:40:13 +02008797 arbitrary number that can only be used to compare to the
8798 attribute at other positions.
8799
Bram Moolenaar196b4662019-09-06 21:34:30 +02008800 Can also be used as a |method|: >
8801 GetRow()->screenattr(col)
8802
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008803screenchar({row}, {col}) *screenchar()*
Bram Moolenaar9a773482013-06-11 18:40:13 +02008804 The result is a Number, which is the character at position
8805 [row, col] on the screen. This works for every possible
8806 screen position, also status lines, window separators and the
8807 command line. The top left position is row one, column one
8808 The character excludes composing characters. For double-byte
8809 encodings it may only be the first byte.
8810 This is mainly to be used for testing.
8811 Returns -1 when row or col is out of range.
8812
Bram Moolenaar196b4662019-09-06 21:34:30 +02008813 Can also be used as a |method|: >
8814 GetRow()->screenchar(col)
8815
Bram Moolenaar2912abb2019-03-29 14:16:42 +01008816screenchars({row}, {col}) *screenchars()*
Bram Moolenaare46a4402020-06-30 20:38:27 +02008817 The result is a |List| of Numbers. The first number is the same
Bram Moolenaar2912abb2019-03-29 14:16:42 +01008818 as what |screenchar()| returns. Further numbers are
8819 composing characters on top of the base character.
8820 This is mainly to be used for testing.
8821 Returns an empty List when row or col is out of range.
8822
Bram Moolenaar196b4662019-09-06 21:34:30 +02008823 Can also be used as a |method|: >
8824 GetRow()->screenchars(col)
8825
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008826screencol() *screencol()*
8827 The result is a Number, which is the current screen column of
8828 the cursor. The leftmost column has number 1.
8829 This function is mainly used for testing.
8830
8831 Note: Always returns the current screen column, thus if used
8832 in a command (e.g. ":echo screencol()") it will return the
8833 column inside the command line, which is 1 when the command is
8834 executed. To get the cursor position in the file use one of
8835 the following mappings: >
8836 nnoremap <expr> GG ":echom ".screencol()."\n"
8837 nnoremap <silent> GG :echom screencol()<CR>
Bram Moolenaar957cf672020-11-12 14:21:06 +01008838 nnoremap GG <Cmd>echom screencol()<CR>
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008839<
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02008840screenpos({winid}, {lnum}, {col}) *screenpos()*
8841 The result is a Dict with the screen position of the text
8842 character in window {winid} at buffer line {lnum} and column
8843 {col}. {col} is a one-based byte index.
8844 The Dict has these members:
8845 row screen row
8846 col first screen column
8847 endcol last screen column
8848 curscol cursor screen column
8849 If the specified position is not visible, all values are zero.
8850 The "endcol" value differs from "col" when the character
8851 occupies more than one screen cell. E.g. for a Tab "col" can
8852 be 1 and "endcol" can be 8.
8853 The "curscol" value is where the cursor would be placed. For
8854 a Tab it would be the same as "endcol", while for a double
8855 width character it would be the same as "col".
8856
Bram Moolenaar196b4662019-09-06 21:34:30 +02008857 Can also be used as a |method|: >
8858 GetWinid()->screenpos(lnum, col)
8859
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008860screenrow() *screenrow()*
8861 The result is a Number, which is the current screen row of the
8862 cursor. The top line has number one.
8863 This function is mainly used for testing.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02008864 Alternatively you can use |winline()|.
Bram Moolenaar34feacb2012-12-05 19:01:43 +01008865
8866 Note: Same restrictions as with |screencol()|.
8867
Bram Moolenaar2912abb2019-03-29 14:16:42 +01008868screenstring({row}, {col}) *screenstring()*
8869 The result is a String that contains the base character and
8870 any composing characters at position [row, col] on the screen.
8871 This is like |screenchars()| but returning a String with the
8872 characters.
8873 This is mainly to be used for testing.
8874 Returns an empty String when row or col is out of range.
8875
Bram Moolenaar196b4662019-09-06 21:34:30 +02008876 Can also be used as a |method|: >
8877 GetRow()->screenstring(col)
Bram Moolenaaradc17a52020-06-06 18:37:51 +02008878<
8879 *search()*
8880search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00008881 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00008882 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00008883
Bram Moolenaar2df58b42012-11-28 18:21:11 +01008884 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008885 If there is no match a 0 is returned and the cursor doesn't
8886 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01008887
Bram Moolenaar071d4272004-06-13 20:20:40 +00008888 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01008889 'b' search Backward instead of forward
8890 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008891 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00008892 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01008893 'p' return number of matching sub-Pattern (see below)
8894 's' Set the ' mark at the previous location of the cursor
8895 'w' Wrap around the end of the file
8896 'W' don't Wrap around the end of the file
8897 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00008898 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
8899
Bram Moolenaar02743632005-07-25 20:42:36 +00008900 If the 's' flag is supplied, the ' mark is set, only if the
8901 cursor is moved. The 's' flag cannot be combined with the 'n'
8902 flag.
8903
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008904 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008905
Bram Moolenaar4466ad62020-11-21 13:16:30 +01008906 When the 'z' flag is not given, forward searching always
8907 starts in column zero and then matches before the cursor are
8908 skipped. When the 'c' flag is present in 'cpo' the next
8909 search starts after the match. Without the 'c' flag the next
8910 search starts one column further. This matters for
8911 overlapping matches.
8912 When searching backwards and the 'z' flag is given then the
8913 search starts in column zero, thus no match in the current
8914 line will be found (unless wrapping around the end of the
8915 file).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008916
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008917 When the {stopline} argument is given then the search stops
8918 after searching this line. This is useful to restrict the
8919 search to a range of lines. Examples: >
8920 let match = search('(', 'b', line("w0"))
8921 let end = search('END', '', line("w$"))
8922< When {stopline} is used and it is not zero this also implies
8923 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00008924 A zero value is equal to not giving the argument.
8925
8926 When the {timeout} argument is given the search stops when
Bram Moolenaar58b85342016-08-14 19:54:54 +02008927 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00008928 {timeout} is 500 the search stops after half a second.
8929 The value must not be negative. A zero value is like not
8930 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02008931 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008932
Bram Moolenaaradc17a52020-06-06 18:37:51 +02008933 If the {skip} expression is given it is evaluated with the
8934 cursor positioned on the start of a match. If it evaluates to
8935 non-zero this match is skipped. This can be used, for
8936 example, to skip a match in a comment or a string.
8937 {skip} can be a string, which is evaluated as an expression, a
8938 function reference or a lambda.
8939 When {skip} is omitted or empty, every match is accepted.
8940 When evaluating {skip} causes an error the search is aborted
8941 and -1 returned.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00008942 *search()-sub-match*
8943 With the 'p' flag the returned value is one more than the
8944 first sub-match in \(\). One if none of them matched but the
8945 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00008946 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008947
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008948 The cursor will be positioned at the match, unless the 'n'
8949 flag is used.
8950
Bram Moolenaar071d4272004-06-13 20:20:40 +00008951 Example (goes over all files in the argument list): >
8952 :let n = 1
8953 :while n <= argc() " loop over all files in arglist
8954 : exe "argument " . n
8955 : " start at the last char in the file and wrap for the
8956 : " first search to find match at start of file
8957 : normal G$
8958 : let flags = "w"
8959 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00008960 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00008961 : let flags = "W"
8962 : endwhile
8963 : update " write the file if modified
8964 : let n = n + 1
8965 :endwhile
8966<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008967 Example for using some flags: >
8968 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
8969< This will search for the keywords "if", "else", and "endif"
8970 under or after the cursor. Because of the 'p' flag, it
8971 returns 1, 2, or 3 depending on which keyword is found, or 0
8972 if the search fails. With the cursor on the first word of the
8973 line:
8974 if (foo == 0) | let foo = foo + 1 | endif ~
8975 the function returns 1. Without the 'c' flag, the function
8976 finds the "endif" and returns 3. The same thing happens
8977 without the 'e' flag if the cursor is on the "f" of "if".
8978 The 'n' flag tells the function not to move the cursor.
8979
Bram Moolenaar196b4662019-09-06 21:34:30 +02008980 Can also be used as a |method|: >
8981 GetPattern()->search()
Bram Moolenaar92d640f2005-09-05 22:11:52 +00008982
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02008983searchcount([{options}]) *searchcount()*
8984 Get or update the last search count, like what is displayed
8985 without the "S" flag in 'shortmess'. This works even if
8986 'shortmess' does contain the "S" flag.
8987
Bram Moolenaare46a4402020-06-30 20:38:27 +02008988 This returns a |Dictionary|. The dictionary is empty if the
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02008989 previous pattern was not set and "pattern" was not specified.
8990
8991 key type meaning ~
8992 current |Number| current position of match;
8993 0 if the cursor position is
8994 before the first match
8995 exact_match |Boolean| 1 if "current" is matched on
8996 "pos", otherwise 0
8997 total |Number| total count of matches found
8998 incomplete |Number| 0: search was fully completed
8999 1: recomputing was timed out
9000 2: max count exceeded
9001
9002 For {options} see further down.
9003
9004 To get the last search count when |n| or |N| was pressed, call
9005 this function with `recompute: 0` . This sometimes returns
9006 wrong information because |n| and |N|'s maximum count is 99.
9007 If it exceeded 99 the result must be max count + 1 (100). If
9008 you want to get correct information, specify `recompute: 1`: >
9009
9010 " result == maxcount + 1 (100) when many matches
9011 let result = searchcount(#{recompute: 0})
9012
9013 " Below returns correct result (recompute defaults
9014 " to 1)
9015 let result = searchcount()
9016<
9017 The function is useful to add the count to |statusline|: >
9018 function! LastSearchCount() abort
9019 let result = searchcount(#{recompute: 0})
9020 if empty(result)
9021 return ''
9022 endif
9023 if result.incomplete ==# 1 " timed out
9024 return printf(' /%s [?/??]', @/)
9025 elseif result.incomplete ==# 2 " max count exceeded
9026 if result.total > result.maxcount &&
9027 \ result.current > result.maxcount
9028 return printf(' /%s [>%d/>%d]', @/,
Bram Moolenaar73fef332020-06-21 22:12:03 +02009029 \ result.current, result.total)
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009030 elseif result.total > result.maxcount
9031 return printf(' /%s [%d/>%d]', @/,
Bram Moolenaar73fef332020-06-21 22:12:03 +02009032 \ result.current, result.total)
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009033 endif
9034 endif
9035 return printf(' /%s [%d/%d]', @/,
Bram Moolenaar73fef332020-06-21 22:12:03 +02009036 \ result.current, result.total)
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009037 endfunction
9038 let &statusline .= '%{LastSearchCount()}'
9039
9040 " Or if you want to show the count only when
9041 " 'hlsearch' was on
9042 " let &statusline .=
9043 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9044<
9045 You can also update the search count, which can be useful in a
9046 |CursorMoved| or |CursorMovedI| autocommand: >
9047
9048 autocmd CursorMoved,CursorMovedI *
9049 \ let s:searchcount_timer = timer_start(
9050 \ 200, function('s:update_searchcount'))
9051 function! s:update_searchcount(timer) abort
9052 if a:timer ==# s:searchcount_timer
9053 call searchcount(#{
9054 \ recompute: 1, maxcount: 0, timeout: 100})
9055 redrawstatus
9056 endif
9057 endfunction
9058<
9059 This can also be used to count matched texts with specified
9060 pattern in the current buffer using "pattern": >
9061
9062 " Count '\<foo\>' in this buffer
9063 " (Note that it also updates search count)
9064 let result = searchcount(#{pattern: '\<foo\>'})
9065
9066 " To restore old search count by old pattern,
9067 " search again
9068 call searchcount()
9069<
Bram Moolenaare46a4402020-06-30 20:38:27 +02009070 {options} must be a |Dictionary|. It can contain:
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009071 key type meaning ~
9072 recompute |Boolean| if |TRUE|, recompute the count
9073 like |n| or |N| was executed.
9074 otherwise returns the last
Bram Moolenaarebacddb2020-06-04 15:22:21 +02009075 computed result (when |n| or
9076 |N| was used when "S" is not
9077 in 'shortmess', or this
9078 function was called).
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009079 (default: |TRUE|)
9080 pattern |String| recompute if this was given
9081 and different with |@/|.
9082 this works as same as the
9083 below command is executed
9084 before calling this function >
9085 let @/ = pattern
9086< (default: |@/|)
9087 timeout |Number| 0 or negative number is no
9088 timeout. timeout milliseconds
9089 for recomputing the result
9090 (default: 0)
9091 maxcount |Number| 0 or negative number is no
9092 limit. max count of matched
9093 text while recomputing the
9094 result. if search exceeded
9095 total count, "total" value
9096 becomes `maxcount + 1`
Bram Moolenaar7e6a5152021-01-02 16:39:53 +01009097 (default: 99)
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009098 pos |List| `[lnum, col, off]` value
9099 when recomputing the result.
9100 this changes "current" result
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02009101 value. see |cursor()|,
9102 |getpos()|
Bram Moolenaare8f5ec02020-06-01 17:28:35 +02009103 (default: cursor's position)
9104
9105
Bram Moolenaarf75a9632005-09-13 21:20:47 +00009106searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9107 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009108
Bram Moolenaarf75a9632005-09-13 21:20:47 +00009109 With a non-zero {global} argument it works like |gD|, find
9110 first match in the file. Otherwise it works like |gd|, find
9111 first match in the function.
9112
9113 With a non-zero {thisblock} argument matches in a {} block
9114 that ends before the cursor position are ignored. Avoids
9115 finding variable declarations only valid in another scope.
9116
Bram Moolenaar92d640f2005-09-05 22:11:52 +00009117 Moves the cursor to the found match.
9118 Returns zero for success, non-zero for failure.
9119 Example: >
9120 if searchdecl('myvar') == 0
9121 echo getline('.')
9122 endif
9123<
Bram Moolenaar196b4662019-09-06 21:34:30 +02009124 Can also be used as a |method|: >
9125 GetName()->searchdecl()
9126<
Bram Moolenaar071d4272004-06-13 20:20:40 +00009127 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00009128searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9129 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00009130 Search for the match of a nested start-end pair. This can be
9131 used to find the "endif" that matches an "if", while other
9132 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009133 The search starts at the cursor. The default is to search
9134 forward, include 'b' in {flags} to search backward.
9135 If a match is found, the cursor is positioned at it and the
9136 line number is returned. If no match is found 0 or -1 is
9137 returned and the cursor doesn't move. No error message is
9138 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009139
9140 {start}, {middle} and {end} are patterns, see |pattern|. They
9141 must not contain \( \) pairs. Use of \%( \) is allowed. When
9142 {middle} is not empty, it is found when searching from either
9143 direction, but only when not in a nested start-end pair. A
9144 typical use is: >
9145 searchpair('\<if\>', '\<else\>', '\<endif\>')
9146< By leaving {middle} empty the "else" is skipped.
9147
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00009148 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9149 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009150 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00009151 outer pair. Implies the 'W' flag.
9152 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00009153 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009154 Note: it's nearly always a good idea to use the 'W' flag, to
9155 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009156
9157 When a match for {start}, {middle} or {end} is found, the
9158 {skip} expression is evaluated with the cursor positioned on
9159 the start of the match. It should return non-zero if this
9160 match is to be skipped. E.g., because it is inside a comment
9161 or a string.
9162 When {skip} is omitted or empty, every match is accepted.
9163 When evaluating {skip} causes an error the search is aborted
9164 and -1 returned.
Bram Moolenaar48570482017-10-30 21:48:41 +01009165 {skip} can be a string, a lambda, a funcref or a partial.
Bram Moolenaar675e8d62018-06-24 20:42:01 +02009166 Anything else makes the function fail.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009167
Bram Moolenaar76929292008-01-06 19:07:36 +00009168 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00009169
Bram Moolenaar071d4272004-06-13 20:20:40 +00009170 The value of 'ignorecase' is used. 'magic' is ignored, the
9171 patterns are used like it's on.
9172
9173 The search starts exactly at the cursor. A match with
9174 {start}, {middle} or {end} at the next character, in the
9175 direction of searching, is the first one found. Example: >
9176 if 1
9177 if 2
9178 endif 2
9179 endif 1
9180< When starting at the "if 2", with the cursor on the "i", and
9181 searching forwards, the "endif 2" is found. When starting on
9182 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar58b85342016-08-14 19:54:54 +02009183 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00009184 then this is considered to be a nested if/endif from "if 2" to
9185 "endif 2".
9186 When searching backwards and {end} is more than one character,
9187 it may be useful to put "\zs" at the end of the pattern, so
9188 that when the cursor is inside a match with the end it finds
9189 the matching start.
9190
9191 Example, to find the "endif" command in a Vim script: >
9192
9193 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9194 \ 'getline(".") =~ "^\\s*\""')
9195
9196< The cursor must be at or after the "if" for which a match is
9197 to be found. Note that single-quote strings are used to avoid
9198 having to double the backslashes. The skip expression only
9199 catches comments at the start of a line, not after a command.
9200 Also, a word "en" or "if" halfway a line is considered a
9201 match.
9202 Another example, to search for the matching "{" of a "}": >
9203
9204 :echo searchpair('{', '', '}', 'bW')
9205
9206< This works when the cursor is at or before the "}" for which a
9207 match is to be found. To reject matches that syntax
9208 highlighting recognized as strings: >
9209
9210 :echo searchpair('{', '', '}', 'bW',
9211 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9212<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00009213 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00009214searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9215 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009216 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009217 column position of the match. The first element of the |List|
9218 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00009219 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009220 returns [0, 0]. >
9221
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00009222 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9223<
9224 See |match-parens| for a bigger and more useful example.
9225
Bram Moolenaaradc17a52020-06-06 18:37:51 +02009226 *searchpos()*
9227searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
Bram Moolenaara23ccb82006-02-27 00:08:02 +00009228 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009229 column position of the match. The first element of the |List|
9230 is the line number and the second element is the byte index of
9231 the column position of the match. If no match is found,
9232 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00009233 Example: >
9234 :let [lnum, col] = searchpos('mypattern', 'n')
9235
9236< When the 'p' flag is given then there is an extra item with
9237 the sub-pattern match number |search()-sub-match|. Example: >
9238 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9239< In this example "submatch" is 2 when a lowercase letter is
9240 found |/\l|, 3 when an uppercase letter is found |/\u|.
9241
Bram Moolenaar196b4662019-09-06 21:34:30 +02009242 Can also be used as a |method|: >
9243 GetPattern()->searchpos()
9244
Bram Moolenaar81edd172016-04-14 13:51:37 +02009245server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009246 Send a reply string to {clientid}. The most recent {clientid}
9247 that sent a string can be retrieved with expand("<client>").
9248 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar98a29d02021-01-18 19:55:44 +01009249 Returns zero for success, -1 for failure.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009250 Note:
9251 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00009252 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00009253 before calling any commands that waits for input.
9254 See also |clientserver|.
9255 Example: >
9256 :echo server2client(expand("<client>"), "HELLO")
Bram Moolenaar196b4662019-09-06 21:34:30 +02009257
9258< Can also be used as a |method|: >
9259 GetClientId()->server2client(string)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009260<
9261serverlist() *serverlist()*
9262 Return a list of available server names, one per line.
9263 When there are no servers or the information is not available
9264 an empty string is returned. See also |clientserver|.
9265 {only available when compiled with the |+clientserver| feature}
9266 Example: >
9267 :echo serverlist()
9268<
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009269setbufline({expr}, {lnum}, {text}) *setbufline()*
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009270 Set line {lnum} to {text} in buffer {expr}. This works like
9271 |setline()| for the specified buffer.
9272
9273 This function works only for loaded buffers. First call
9274 |bufload()| if needed.
9275
9276 To insert lines use |appendbufline()|.
9277 Any text properties in {lnum} are cleared.
9278
9279 {text} can be a string to set one line, or a list of strings
9280 to set multiple lines. If the list extends below the last
9281 line then those lines are added.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009282
9283 For the use of {expr}, see |bufname()| above.
9284
9285 {lnum} is used like with |setline()|.
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009286 When {lnum} is just below the last line the {text} will be
9287 added below the last line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009288
Bram Moolenaar6bf2c622019-07-04 17:12:09 +02009289 When {expr} is not a valid buffer, the buffer is not loaded or
9290 {lnum} is not valid then 1 is returned. On success 0 is
9291 returned.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009292
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009293 Can also be used as a |method|, the base is passed as the
9294 third argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02009295 GetText()->setbufline(buf, lnum)
9296
Bram Moolenaar071d4272004-06-13 20:20:40 +00009297setbufvar({expr}, {varname}, {val}) *setbufvar()*
9298 Set option or local variable {varname} in buffer {expr} to
9299 {val}.
9300 This also works for a global or local window option, but it
9301 doesn't work for a global or local window variable.
9302 For a local window option the global value is unchanged.
9303 For the use of {expr}, see |bufname()| above.
9304 Note that the variable name without "b:" must be used.
9305 Examples: >
9306 :call setbufvar(1, "&mod", 1)
9307 :call setbufvar("todo", "myvar", "foobar")
9308< This function is not available in the |sandbox|.
9309
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009310 Can also be used as a |method|, the base is passed as the
9311 third argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02009312 GetValue()->setbufvar(buf, varname)
9313
Bram Moolenaar08aac3c2020-08-28 21:04:24 +02009314
9315setcellwidths({list}) *setcellwidths()*
9316 Specify overrides for cell widths of character ranges. This
9317 tells Vim how wide characters are, counted in screen cells.
9318 This overrides 'ambiwidth'. Example: >
9319 setcellwidths([[0xad, 0xad, 1],
Bram Moolenaar207f0092020-08-30 17:20:20 +02009320 \ [0x2194, 0x2199, 2]])
Bram Moolenaar08aac3c2020-08-28 21:04:24 +02009321
9322< *E1109* *E1110* *E1111* *E1112* *E1113*
9323 The {list} argument is a list of lists with each three
9324 numbers. These three numbers are [low, high, width]. "low"
9325 and "high" can be the same, in which case this refers to one
9326 character. Otherwise it is the range of characters from "low"
9327 to "high" (inclusive). "width" is either 1 or 2, indicating
9328 the character width in screen cells.
9329 An error is given if the argument is invalid, also when a
9330 range overlaps with another.
9331 Only characters with value 0x100 and higher can be used.
9332
9333 To clear the overrides pass an empty list: >
9334 setcellwidths([]);
Bram Moolenaar207f0092020-08-30 17:20:20 +02009335< You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
9336 the effect for known emoji characters.
Bram Moolenaar08aac3c2020-08-28 21:04:24 +02009337
Bram Moolenaar6f02b002021-01-10 20:22:54 +01009338setcharpos({expr}, {list}) *setcharpos()*
9339 Same as |setpos()| but uses the specified column number as the
9340 character index instead of the byte index in the line.
9341
9342 Example:
9343 With the text "여보세요" in line 8: >
9344 call setcharpos('.', [0, 8, 4, 0])
9345< positions the cursor on the fourth character '요'. >
9346 call setpos('.', [0, 8, 4, 0])
9347< positions the cursor on the second character '보'.
9348
9349 Can also be used as a |method|: >
9350 GetPosition()->setcharpos('.')
Bram Moolenaar08aac3c2020-08-28 21:04:24 +02009351
Bram Moolenaar12969c02015-09-08 23:36:10 +02009352setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02009353 Set the current character search information to {dict},
9354 which contains one or more of the following entries:
9355
9356 char character which will be used for a subsequent
9357 |,| or |;| command; an empty string clears the
9358 character search
9359 forward direction of character search; 1 for forward,
9360 0 for backward
9361 until type of character search; 1 for a |t| or |T|
9362 character search, 0 for an |f| or |F|
9363 character search
9364
9365 This can be useful to save/restore a user's character search
9366 from a script: >
9367 :let prevsearch = getcharsearch()
9368 :" Perform a command which clobbers user's search
9369 :call setcharsearch(prevsearch)
9370< Also see |getcharsearch()|.
9371
Bram Moolenaar196b4662019-09-06 21:34:30 +02009372 Can also be used as a |method|: >
9373 SavedSearch()->setcharsearch()
9374
Bram Moolenaar071d4272004-06-13 20:20:40 +00009375setcmdpos({pos}) *setcmdpos()*
9376 Set the cursor position in the command line to byte position
Bram Moolenaar58b85342016-08-14 19:54:54 +02009377 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009378 Use |getcmdpos()| to obtain the current position.
9379 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00009380 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9381 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9382 set after the command line is set to the expression. For
9383 |c_CTRL-R_=| it is set after evaluating the expression but
9384 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009385 When the number is too big the cursor is put at the end of the
9386 line. A number smaller than one has undefined results.
Bram Moolenaar98a29d02021-01-18 19:55:44 +01009387 Returns FALSE when successful, TRUE when not editing the
9388 command line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009389
Bram Moolenaar196b4662019-09-06 21:34:30 +02009390 Can also be used as a |method|: >
9391 GetPos()->setcmdpos()
9392
Bram Moolenaar6f02b002021-01-10 20:22:54 +01009393setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9394setcursorcharpos({list})
9395 Same as |cursor()| but uses the specified column number as the
9396 character index instead of the byte index in the line.
9397
9398 Example:
9399 With the text "여보세요" in line 4: >
9400 call setcursorcharpos(4, 3)
9401< positions the cursor on the third character '세'. >
9402 call cursor(4, 3)
9403< positions the cursor on the first character '여'.
9404
9405 Can also be used as a |method|: >
9406 GetCursorPos()->setcursorcharpos()
9407
Bram Moolenaar691ddee2019-05-09 14:52:41 +02009408setenv({name}, {val}) *setenv()*
9409 Set environment variable {name} to {val}.
9410 When {val} is |v:null| the environment variable is deleted.
9411 See also |expr-env|.
9412
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009413 Can also be used as a |method|, the base is passed as the
9414 second argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02009415 GetPath()->setenv('PATH')
9416
Bram Moolenaar80492532016-03-08 17:08:53 +01009417setfperm({fname}, {mode}) *setfperm()* *chmod*
9418 Set the file permissions for {fname} to {mode}.
9419 {mode} must be a string with 9 characters. It is of the form
9420 "rwxrwxrwx", where each group of "rwx" flags represent, in
9421 turn, the permissions of the owner of the file, the group the
9422 file belongs to, and other users. A '-' character means the
9423 permission is off, any other character means on. Multi-byte
9424 characters are not supported.
9425
9426 For example "rw-r-----" means read-write for the user,
9427 readable by the group, not accessible by others. "xx-x-----"
9428 would do the same thing.
9429
9430 Returns non-zero for success, zero for failure.
9431
Bram Moolenaar4c313b12019-08-24 22:58:31 +02009432 Can also be used as a |method|: >
9433 GetFilename()->setfperm(mode)
9434<
Bram Moolenaar80492532016-03-08 17:08:53 +01009435 To read permissions see |getfperm()|.
9436
9437
Bram Moolenaar446cb832008-06-24 21:56:24 +00009438setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01009439 Set line {lnum} of the current buffer to {text}. To insert
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009440 lines use |append()|. To set lines in another buffer use
Bram Moolenaarb328cca2019-01-06 16:24:01 +01009441 |setbufline()|. Any text properties in {lnum} are cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009442
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00009443 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009444 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009445 added below the last line.
Bram Moolenaar34453202021-01-31 13:08:38 +01009446 {text} can be any type or a List of any type, each item is
9447 converted to a String.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009448
Bram Moolenaar98a29d02021-01-18 19:55:44 +01009449 If this succeeds, FALSE is returned. If this fails (most likely
9450 because {lnum} is invalid) TRUE is returned.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009451
9452 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009453 :call setline(5, strftime("%c"))
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02009454
Bram Moolenaar446cb832008-06-24 21:56:24 +00009455< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00009456 will be set to the items in the list. Example: >
9457 :call setline(5, ['aaa', 'bbb', 'ccc'])
9458< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02009459 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00009460 : call setline(n, l)
9461 :endfor
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009462
Bram Moolenaar071d4272004-06-13 20:20:40 +00009463< Note: The '[ and '] marks are not set.
9464
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009465 Can also be used as a |method|, the base is passed as the
9466 second argument: >
Bram Moolenaar196b4662019-09-06 21:34:30 +02009467 GetText()->setline(lnum)
9468
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009469setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00009470 Create or replace or add to the location list for window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02009471 {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02009472 When {nr} is zero the current window is used.
9473
9474 For a location list window, the displayed location list is
9475 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00009476 Otherwise, same as |setqflist()|.
9477 Also see |location-list|.
9478
Bram Moolenaar7ff78462020-07-10 22:00:53 +02009479 For {action} see |setqflist-action|.
9480
Bram Moolenaard823fa92016-08-12 16:29:27 +02009481 If the optional {what} dictionary argument is supplied, then
9482 only the items listed in {what} are set. Refer to |setqflist()|
9483 for the list of supported keys in {what}.
9484
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009485 Can also be used as a |method|, the base is passed as the
9486 second argument: >
9487 GetLoclist()->setloclist(winnr)
9488
Bram Moolenaaraff74912019-03-30 18:11:49 +01009489setmatches({list} [, {win}]) *setmatches()*
Bram Moolenaar99fa7212020-04-26 15:59:55 +02009490 Restores a list of matches saved by |getmatches()| for the
9491 current window. Returns 0 if successful, otherwise -1. All
Bram Moolenaarfd133322019-03-29 12:20:27 +01009492 current matches are cleared before the list is restored. See
9493 example for |getmatches()|.
Bram Moolenaaraff74912019-03-30 18:11:49 +01009494 If {win} is specified, use the window with this number or
9495 window ID instead of the current window.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009496
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009497 Can also be used as a |method|: >
9498 GetMatches()->setmatches()
9499<
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009500 *setpos()*
9501setpos({expr}, {list})
9502 Set the position for {expr}. Possible values:
9503 . the cursor
9504 'x mark x
9505
Bram Moolenaar493c1782014-05-28 14:34:46 +02009506 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009507 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02009508 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009509
Bram Moolenaar58b85342016-08-14 19:54:54 +02009510 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarf13e00b2017-01-28 18:23:54 +01009511 current buffer. When setting an uppercase mark "bufnum" is
9512 used for the mark position. For other marks it specifies the
9513 buffer to set the mark in. You can use the |bufnr()| function
9514 to turn a file name into a buffer number.
9515 For setting the cursor and the ' mark "bufnum" is ignored,
9516 since these are associated with a window, not a buffer.
Bram Moolenaardb552d602006-03-23 22:59:57 +00009517 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009518
9519 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009520 column is 1. Use a zero "lnum" to delete a mark. If "col" is
Bram Moolenaar6f02b002021-01-10 20:22:54 +01009521 smaller than 1 then 1 is used. To use the character count
9522 instead of the byte count, use |setcharpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009523
9524 The "off" number is only used when 'virtualedit' is set. Then
9525 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00009526 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009527 character.
9528
Bram Moolenaar493c1782014-05-28 14:34:46 +02009529 The "curswant" number is only used when setting the cursor
9530 position. It sets the preferred column for when moving the
9531 cursor vertically. When the "curswant" number is missing the
9532 preferred column is not set. When it is present and setting a
9533 mark position it is not used.
9534
Bram Moolenaardfb18412013-12-11 18:53:29 +01009535 Note that for '< and '> changing the line number may result in
9536 the marks to be effectively be swapped, so that '< is always
9537 before '>.
9538
Bram Moolenaar08250432008-02-13 11:42:46 +00009539 Returns 0 when the position could be set, -1 otherwise.
9540 An error message is given if {expr} is invalid.
9541
Bram Moolenaar6f02b002021-01-10 20:22:54 +01009542 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00009543
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009544 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02009545 vertically; if you set the cursor position with this, |j| and
9546 |k| motions will jump to previous columns! Use |cursor()| to
9547 also set the preferred column. Also see the "curswant" key in
9548 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009549
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009550 Can also be used as a |method|: >
9551 GetPosition()->setpos('.')
9552
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009553setqflist({list} [, {action} [, {what}]]) *setqflist()*
Bram Moolenaarae338332017-08-11 20:25:26 +02009554 Create or replace or add to the quickfix list.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009555
Bram Moolenaarb17893a2020-03-14 08:19:51 +01009556 If the optional {what} dictionary argument is supplied, then
9557 only the items listed in {what} are set. The first {list}
9558 argument is ignored. See below for the supported items in
9559 {what}.
Bram Moolenaar7ff78462020-07-10 22:00:53 +02009560 *setqflist-what*
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02009561 When {what} is not present, the items in {list} are used. Each
Bram Moolenaarae338332017-08-11 20:25:26 +02009562 item must be a dictionary. Non-dictionary items in {list} are
9563 ignored. Each dictionary item can contain the following
9564 entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009565
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00009566 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00009567 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00009568 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00009569 present or it is invalid.
Bram Moolenaard76ce852018-05-01 15:02:04 +02009570 module name of a module; if given it will be used in
9571 quickfix error window instead of the filename.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009572 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009573 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00009574 col column number
9575 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009576 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00009577 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009578 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00009579 type single-character error type, 'E', 'W', etc.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02009580 valid recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009581
Bram Moolenaar582fd852005-03-28 20:58:01 +00009582 The "col", "vcol", "nr", "type" and "text" entries are
9583 optional. Either "lnum" or "pattern" entry can be used to
9584 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00009585 If the "filename" and "bufnr" entries are not present or
9586 neither the "lnum" or "pattern" entries are present, then the
9587 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009588 If both "pattern" and "lnum" are present then "pattern" will
9589 be used.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02009590 If the "valid" entry is not supplied, then the valid flag is
9591 set when "bufnr" is a valid buffer or "filename" exists.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02009592 If you supply an empty {list}, the quickfix list will be
9593 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00009594 Note that the list is not exactly the same as what
9595 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009596
Bram Moolenaar7ff78462020-07-10 22:00:53 +02009597 {action} values: *setqflist-action* *E927*
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02009598 'a' The items from {list} are added to the existing
9599 quickfix list. If there is no existing list, then a
9600 new list is created.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009601
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02009602 'r' The items from the current quickfix list are replaced
9603 with the items from {list}. This can also be used to
9604 clear the list: >
9605 :call setqflist([], 'r')
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009606<
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02009607 'f' All the quickfix lists in the quickfix stack are
9608 freed.
9609
Bram Moolenaar511972d2016-06-04 18:09:59 +02009610 If {action} is not present or is set to ' ', then a new list
Bram Moolenaar55b69262017-08-13 13:42:01 +02009611 is created. The new quickfix list is added after the current
9612 quickfix list in the stack and all the following lists are
9613 freed. To add a new quickfix list at the end of the stack,
Bram Moolenaar36538222017-09-02 19:51:44 +02009614 set "nr" in {what} to "$".
Bram Moolenaar35c54e52005-05-20 21:25:31 +00009615
Bram Moolenaarb17893a2020-03-14 08:19:51 +01009616 The following items can be specified in dictionary {what}:
Bram Moolenaar15142e22018-04-30 22:19:58 +02009617 context quickfix list context. See |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02009618 efm errorformat to use when parsing text from
9619 "lines". If this is not present, then the
9620 'errorformat' option value is used.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01009621 See |quickfix-parse|
Bram Moolenaara539f4f2017-08-30 20:33:55 +02009622 id quickfix list identifier |quickfix-ID|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01009623 idx index of the current entry in the quickfix
9624 list specified by 'id' or 'nr'. If set to '$',
9625 then the last entry in the list is set as the
9626 current entry. See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02009627 items list of quickfix entries. Same as the {list}
9628 argument.
Bram Moolenaar2c809b72017-09-01 18:34:02 +02009629 lines use 'errorformat' to parse a list of lines and
9630 add the resulting entries to the quickfix list
9631 {nr} or {id}. Only a |List| value is supported.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01009632 See |quickfix-parse|
Bram Moolenaar875feea2017-06-11 16:07:51 +02009633 nr list number in the quickfix stack; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02009634 means the current quickfix list and "$" means
Bram Moolenaar5b69c222019-01-11 14:50:06 +01009635 the last quickfix list.
Bram Moolenaar858ba062020-05-31 23:11:59 +02009636 quickfixtextfunc
9637 function to get the text to display in the
Bram Moolenaard43906d2020-07-20 21:31:32 +02009638 quickfix window. The value can be the name of
9639 a function or a funcref or a lambda. Refer to
Bram Moolenaar858ba062020-05-31 23:11:59 +02009640 |quickfix-window-function| for an explanation
9641 of how to write the function and an example.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01009642 title quickfix list title text. See |quickfix-title|
Bram Moolenaard823fa92016-08-12 16:29:27 +02009643 Unsupported keys in {what} are ignored.
9644 If the "nr" item is not present, then the current quickfix list
Bram Moolenaar86f100dc2017-06-28 21:26:27 +02009645 is modified. When creating a new quickfix list, "nr" can be
9646 set to a value one greater than the quickfix stack size.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02009647 When modifying a quickfix list, to guarantee that the correct
Bram Moolenaar36538222017-09-02 19:51:44 +02009648 list is modified, "id" should be used instead of "nr" to
Bram Moolenaara539f4f2017-08-30 20:33:55 +02009649 specify the list.
Bram Moolenaard823fa92016-08-12 16:29:27 +02009650
Bram Moolenaar15142e22018-04-30 22:19:58 +02009651 Examples (See also |setqflist-examples|): >
Bram Moolenaar2c809b72017-09-01 18:34:02 +02009652 :call setqflist([], 'r', {'title': 'My search'})
9653 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
Bram Moolenaar15142e22018-04-30 22:19:58 +02009654 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02009655<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009656 Returns zero for success, -1 for failure.
9657
9658 This function can be used to create a quickfix list
9659 independent of the 'errorformat' setting. Use a command like
Bram Moolenaar94237492017-04-23 18:40:21 +02009660 `:cc 1` to jump to the first position.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00009661
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009662 Can also be used as a |method|, the base is passed as the
9663 second argument: >
9664 GetErrorlist()->setqflist()
9665<
Bram Moolenaar071d4272004-06-13 20:20:40 +00009666 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01009667setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00009668 Set the register {regname} to {value}.
Bram Moolenaar0e05de42020-03-25 22:23:46 +01009669 If {regname} is "" or "@", the unnamed register '"' is used.
Bram Moolenaar942db232021-02-13 18:14:48 +01009670 In |Vim9-script| {regname} must be one character.
Bram Moolenaare46a4402020-06-30 20:38:27 +02009671
Bram Moolenaarbb861e22020-06-07 18:16:36 +02009672 {value} may be any value returned by |getreg()| or
9673 |getreginfo()|, including a |List| or |Dict|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009674 If {options} contains "a" or {regname} is upper case,
9675 then the value is appended.
Bram Moolenaare46a4402020-06-30 20:38:27 +02009676
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02009677 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009678 "c" or "v" |characterwise| mode
9679 "l" or "V" |linewise| mode
9680 "b" or "<CTRL-V>" |blockwise-visual| mode
9681 If a number immediately follows "b" or "<CTRL-V>" then this is
9682 used as the width of the selection - if it is not specified
9683 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00009684 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009685
9686 If {options} contains no register settings, then the default
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009687 is to use character mode unless {value} ends in a <NL> for
9688 string {value} and linewise mode for list {value}. Blockwise
Bram Moolenaar5a50c222014-04-02 22:17:10 +02009689 mode is never selected automatically.
9690 Returns zero for success, non-zero for failure.
9691
9692 *E883*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009693 Note: you may not use |List| containing more than one item to
9694 set search and expression registers. Lists containing no
Bram Moolenaar5a50c222014-04-02 22:17:10 +02009695 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009696
9697 Examples: >
9698 :call setreg(v:register, @*)
9699 :call setreg('*', @%, 'ac')
9700 :call setreg('a', "1\n2\n3", 'b5')
Bram Moolenaarbb861e22020-06-07 18:16:36 +02009701 :call setreg('"', { 'points_to': 'a'})
Bram Moolenaar071d4272004-06-13 20:20:40 +00009702
9703< This example shows using the functions to save and restore a
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009704 register: >
Bram Moolenaarbb861e22020-06-07 18:16:36 +02009705 :let var_a = getreginfo()
9706 :call setreg('a', var_a)
Bram Moolenaare46a4402020-06-30 20:38:27 +02009707< or: >
Bram Moolenaar5a50c222014-04-02 22:17:10 +02009708 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009709 :let var_amode = getregtype('a')
9710 ....
9711 :call setreg('a', var_a, var_amode)
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009712< Note: you may not reliably restore register value
9713 without using the third argument to |getreg()| as without it
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009714 newlines are represented as newlines AND Nul bytes are
9715 represented as newlines as well, see |NL-used-for-Nul|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009716
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009717 You can also change the type of a register by appending
Bram Moolenaar071d4272004-06-13 20:20:40 +00009718 nothing: >
9719 :call setreg('a', '', 'al')
9720
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009721< Can also be used as a |method|, the base is passed as the
9722 second argument: >
9723 GetText()->setreg('a')
9724
Bram Moolenaar06b5d512010-05-22 15:37:44 +02009725settabvar({tabnr}, {varname}, {val}) *settabvar()*
9726 Set tab-local variable {varname} to {val} in tab page {tabnr}.
9727 |t:var|
Bram Moolenaarb4230122019-05-30 18:40:53 +02009728 Note that autocommands are blocked, side effects may not be
9729 triggered, e.g. when setting 'filetype'.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02009730 Note that the variable name without "t:" must be used.
9731 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02009732 This function is not available in the |sandbox|.
9733
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009734 Can also be used as a |method|, the base is passed as the
9735 third argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009736 GetValue()->settabvar(tab, name)
9737
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00009738settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
9739 Set option or local variable {varname} in window {winnr} to
9740 {val}.
9741 Tabs are numbered starting with one. For the current tabpage
9742 use |setwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02009743 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00009744 When {winnr} is zero the current window is used.
Bram Moolenaarb4230122019-05-30 18:40:53 +02009745 Note that autocommands are blocked, side effects may not be
9746 triggered, e.g. when setting 'filetype' or 'syntax'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009747 This also works for a global or local buffer option, but it
9748 doesn't work for a global or local buffer variable.
9749 For a local buffer option the global value is unchanged.
9750 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00009751 Examples: >
9752 :call settabwinvar(1, 1, "&list", 0)
9753 :call settabwinvar(3, 2, "myvar", "foobar")
9754< This function is not available in the |sandbox|.
9755
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009756 Can also be used as a |method|, the base is passed as the
9757 fourth argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009758 GetValue()->settabvar(tab, winnr, name)
9759
Bram Moolenaarf49cc602018-11-11 15:21:05 +01009760settagstack({nr}, {dict} [, {action}]) *settagstack()*
9761 Modify the tag stack of the window {nr} using {dict}.
9762 {nr} can be the window number or the |window-ID|.
9763
9764 For a list of supported items in {dict}, refer to
Bram Moolenaar271fa082020-01-02 14:02:16 +01009765 |gettagstack()|. "curidx" takes effect before changing the tag
9766 stack.
Bram Moolenaarf49cc602018-11-11 15:21:05 +01009767 *E962*
Bram Moolenaar271fa082020-01-02 14:02:16 +01009768 How the tag stack is modified depends on the {action}
9769 argument:
9770 - If {action} is not present or is set to 'r', then the tag
9771 stack is replaced.
9772 - If {action} is set to 'a', then new entries from {dict} are
9773 pushed (added) onto the tag stack.
9774 - If {action} is set to 't', then all the entries from the
9775 current entry in the tag stack or "curidx" in {dict} are
9776 removed and then new entries are pushed to the stack.
9777
9778 The current index is set to one after the length of the tag
9779 stack after the modification.
Bram Moolenaarf49cc602018-11-11 15:21:05 +01009780
9781 Returns zero for success, -1 for failure.
9782
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02009783 Examples (for more examples see |tagstack-examples|):
Bram Moolenaard1caa942020-04-10 22:10:56 +02009784 Empty the tag stack of window 3: >
Bram Moolenaarf49cc602018-11-11 15:21:05 +01009785 call settagstack(3, {'items' : []})
9786
Bram Moolenaarf49cc602018-11-11 15:21:05 +01009787< Save and restore the tag stack: >
9788 let stack = gettagstack(1003)
9789 " do something else
9790 call settagstack(1003, stack)
9791 unlet stack
9792<
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009793 Can also be used as a |method|, the base is passed as the
9794 second argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009795 GetStack()->settagstack(winnr)
9796
9797setwinvar({winnr}, {varname}, {val}) *setwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00009798 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009799 Examples: >
9800 :call setwinvar(1, "&list", 0)
9801 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009802
Bram Moolenaar2e693a82019-10-16 22:35:02 +02009803< Can also be used as a |method|, the base is passed as the
9804 third argument: >
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009805 GetValue()->setwinvar(winnr, name)
9806
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01009807sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01009808 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01009809 checksum of {string}.
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009810
9811 Can also be used as a |method|: >
9812 GetText()->sha256()
9813
9814< {only available when compiled with the |+cryptv| feature}
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01009815
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009816shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009817 Escape {string} for use as a shell command argument.
Bram Moolenaar25e42232019-08-04 15:04:10 +02009818 On MS-Windows, when 'shellslash' is not set, it will enclose
9819 {string} in double quotes and double all double quotes within
9820 {string}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02009821 Otherwise it will enclose {string} in single quotes and
9822 replace all "'" with "'\''".
Bram Moolenaar875feea2017-06-11 16:07:51 +02009823
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009824 When the {special} argument is present and it's a non-zero
9825 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00009826 items such as "!", "%", "#" and "<cword>" will be preceded by
9827 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009828 command.
Bram Moolenaar875feea2017-06-11 16:07:51 +02009829
Bram Moolenaare37d50a2008-08-06 17:06:04 +00009830 The "!" character will be escaped (again with a |non-zero-arg|
9831 {special}) when 'shell' contains "csh" in the tail. That is
9832 because for csh and tcsh "!" is used for history replacement
9833 even when inside single quotes.
Bram Moolenaar875feea2017-06-11 16:07:51 +02009834
9835 With a |non-zero-arg| {special} the <NL> character is also
9836 escaped. When 'shell' containing "csh" in the tail it's
Bram Moolenaare37d50a2008-08-06 17:06:04 +00009837 escaped a second time.
Bram Moolenaar875feea2017-06-11 16:07:51 +02009838
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009839 Example of use with a |:!| command: >
9840 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
9841< This results in a directory listing for the file under the
9842 cursor. Example of use with |system()|: >
9843 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01009844< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00009845
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009846 Can also be used as a |method|: >
9847 GetCommand()->shellescape()
Bram Moolenaar60a495f2006-10-03 12:44:42 +00009848
Bram Moolenaarf9514162018-11-22 03:08:29 +01009849shiftwidth([{col}]) *shiftwidth()*
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02009850 Returns the effective value of 'shiftwidth'. This is the
9851 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01009852 'tabstop' value. This function was introduced with patch
Bram Moolenaarf9514162018-11-22 03:08:29 +01009853 7.3.694 in 2012, everybody should have it by now (however it
9854 did not allow for the optional {col} argument until 8.1.542).
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02009855
Bram Moolenaarf9514162018-11-22 03:08:29 +01009856 When there is one argument {col} this is used as column number
9857 for which to return the 'shiftwidth' value. This matters for the
9858 'vartabstop' feature. If the 'vartabstop' setting is enabled and
9859 no {col} argument is given, column 1 will be assumed.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01009860
Bram Moolenaaraad222c2019-09-06 22:46:09 +02009861 Can also be used as a |method|: >
9862 GetColumn()->shiftwidth()
9863
Bram Moolenaared997ad2019-07-21 16:42:00 +02009864sign_ functions are documented here: |sign-functions-details|
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02009865
Bram Moolenaar162b7142018-12-21 15:17:36 +01009866
Bram Moolenaar071d4272004-06-13 20:20:40 +00009867simplify({filename}) *simplify()*
9868 Simplify the file name as much as possible without changing
9869 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
9870 Unix) are not resolved. If the first path component in
9871 {filename} designates the current directory, this will be
9872 valid for the result as well. A trailing path separator is
Bram Moolenaar73fef332020-06-21 22:12:03 +02009873 not removed either. On Unix "//path" is unchanged, but
9874 "///path" is simplified to "/path" (this follows the Posix
9875 standard).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009876 Example: >
9877 simplify("./dir/.././/file/") == "./file/"
9878< Note: The combination "dir/.." is only removed if "dir" is
9879 a searchable directory or does not exist. On Unix, it is also
9880 removed when "dir" is a symbolic link within the same
9881 directory. In order to resolve all the involved symbolic
9882 links before simplifying the path name, use |resolve()|.
9883
Bram Moolenaar7035fd92020-04-08 20:03:52 +02009884 Can also be used as a |method|: >
9885 GetName()->simplify()
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009886
Bram Moolenaar446cb832008-06-24 21:56:24 +00009887sin({expr}) *sin()*
9888 Return the sine of {expr}, measured in radians, as a |Float|.
9889 {expr} must evaluate to a |Float| or a |Number|.
9890 Examples: >
9891 :echo sin(100)
9892< -0.506366 >
9893 :echo sin(-4.01)
9894< 0.763301
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009895
9896 Can also be used as a |method|: >
9897 Compute()->sin()
9898<
Bram Moolenaar446cb832008-06-24 21:56:24 +00009899 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009900
Bram Moolenaar446cb832008-06-24 21:56:24 +00009901
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009902sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009903 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009904 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009905 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009906 Examples: >
9907 :echo sinh(0.5)
9908< 0.521095 >
9909 :echo sinh(-0.9)
9910< -1.026517
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02009911
9912 Can also be used as a |method|: >
9913 Compute()->sinh()
9914<
Bram Moolenaardb84e452010-08-15 13:50:43 +02009915 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009916
9917
Bram Moolenaar6601b622021-01-13 21:47:15 +01009918slice({expr}, {start} [, {end}]) *slice()*
9919 Similar to using a |slice| "expr[start : end]", but "end" is
9920 used exclusive. And for a string the indexes are used as
9921 character indexes instead of byte indexes, like in
9922 |vim9script|.
9923 When {end} is omitted the slice continues to the last item.
9924 When {end} is -1 the last item is omitted.
9925
9926 Can also be used as a |method|: >
9927 GetList()->slice(offset)
9928
9929
Bram Moolenaar5f894962011-06-19 02:55:37 +02009930sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01009931 Sort the items in {list} in-place. Returns {list}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009932
Bram Moolenaar327aa022014-03-25 18:24:23 +01009933 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009934 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02009935
Bram Moolenaar946e27a2014-06-25 18:50:27 +02009936< When {func} is omitted, is empty or zero, then sort() uses the
9937 string representation of each item to sort on. Numbers sort
9938 after Strings, |Lists| after Numbers. For sorting text in the
9939 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01009940
Bram Moolenaar34401cc2014-08-29 15:12:19 +02009941 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02009942 ignored.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009943
Bram Moolenaar3132cdd2020-11-05 20:41:49 +01009944 When {func} is given and it is 'l' then the current collation
9945 locale is used for ordering. Implementation details: strcoll()
9946 is used to compare strings. See |:language| check or set the
9947 collation locale. |v:collate| can also be used to check the
9948 current locale. Sorting using the locale typically ignores
9949 case. Example: >
9950 " ö is sorted similarly to o with English locale.
9951 :language collate en_US.UTF8
9952 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
9953< ['n', 'o', 'O', 'ö', 'p', 'z'] ~
9954>
9955 " ö is sorted after z with Swedish locale.
9956 :language collate sv_SE.UTF8
9957 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
9958< ['n', 'o', 'O', 'p', 'z', 'ö'] ~
9959 This does not work properly on Mac.
Bram Moolenaar55e29612020-11-01 13:57:44 +01009960
Bram Moolenaar946e27a2014-06-25 18:50:27 +02009961 When {func} is given and it is 'n' then all items will be
Bram Moolenaar3132cdd2020-11-05 20:41:49 +01009962 sorted numerical (Implementation detail: this uses the
Bram Moolenaar946e27a2014-06-25 18:50:27 +02009963 strtod() function to parse numbers, Strings, Lists, Dicts and
9964 Funcrefs will be considered as being 0).
9965
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01009966 When {func} is given and it is 'N' then all items will be
9967 sorted numerical. This is like 'n' but a string containing
9968 digits will be used as the number they represent.
9969
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01009970 When {func} is given and it is 'f' then all items will be
9971 sorted numerical. All values must be a Number or a Float.
9972
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009973 When {func} is a |Funcref| or a function name, this function
9974 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009975 items as argument and must return zero if they are equal, 1 or
9976 bigger if the first one sorts after the second one, -1 or
9977 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01009978
9979 {dict} is for functions with the "dict" attribute. It will be
9980 used to set the local variable "self". |Dictionary-function|
9981
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02009982 The sort is stable, items which compare equal (as number or as
9983 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02009984 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02009985 same order as they were originally.
9986
Bram Moolenaarac92e252019-08-03 21:58:38 +02009987 Can also be used as a |method|: >
9988 mylist->sort()
9989
9990< Also see |uniq()|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01009991
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009992 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00009993 func MyCompare(i1, i2)
9994 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
9995 endfunc
9996 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009997< A shorter compare version for this specific simple case, which
9998 ignores overflow: >
9999 func MyCompare(i1, i2)
10000 return a:i1 - a:i2
10001 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010002<
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020010003sound_clear() *sound_clear()*
10004 Stop playing all sounds.
Bram Moolenaar9b283522019-06-17 22:19:33 +020010005 {only available when compiled with the |+sound| feature}
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020010006
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010007 *sound_playevent()*
10008sound_playevent({name} [, {callback}])
10009 Play a sound identified by {name}. Which event names are
10010 supported depends on the system. Often the XDG sound names
10011 are used. On Ubuntu they may be found in
10012 /usr/share/sounds/freedesktop/stereo. Example: >
10013 call sound_playevent('bell')
Bram Moolenaar9b283522019-06-17 22:19:33 +020010014< On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10015 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10016 SystemStart, SystemWelcome, etc.
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010017
Bram Moolenaar9b283522019-06-17 22:19:33 +020010018 When {callback} is specified it is invoked when the sound is
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010019 finished. The first argument is the sound ID, the second
10020 argument is the status:
10021 0 sound was played to the end
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020010022 1 sound was interrupted
Bram Moolenaar6c1e1572019-06-22 02:13:00 +020010023 2 error occurred after sound started
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010024 Example: >
10025 func Callback(id, status)
10026 echomsg "sound " .. a:id .. " finished with " .. a:status
10027 endfunc
10028 call sound_playevent('bell', 'Callback')
10029
Bram Moolenaar9b283522019-06-17 22:19:33 +020010030< MS-Windows: {callback} doesn't work for this function.
10031
10032 Returns the sound ID, which can be passed to `sound_stop()`.
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010033 Returns zero if the sound could not be played.
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010034
10035 Can also be used as a |method|: >
10036 GetSoundName()->sound_playevent()
10037
10038< {only available when compiled with the |+sound| feature}
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010039
10040 *sound_playfile()*
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020010041sound_playfile({path} [, {callback}])
10042 Like `sound_playevent()` but play sound file {path}. {path}
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010043 must be a full path. On Ubuntu you may find files to play
10044 with this command: >
10045 :!find /usr/share/sounds -type f | grep -v index.theme
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010046
10047< Can also be used as a |method|: >
10048 GetSoundPath()->sound_playfile()
10049
Bram Moolenaar12ee7ff2019-06-10 22:47:40 +020010050< {only available when compiled with the |+sound| feature}
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010051
10052
10053sound_stop({id}) *sound_stop()*
10054 Stop playing sound {id}. {id} must be previously returned by
10055 `sound_playevent()` or `sound_playfile()`.
Bram Moolenaar9b283522019-06-17 22:19:33 +020010056
10057 On MS-Windows, this does not work for event sound started by
10058 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10059
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010060 Can also be used as a |method|: >
10061 soundid->sound_stop()
10062
10063< {only available when compiled with the |+sound| feature}
Bram Moolenaar427f5b62019-06-09 13:43:51 +020010064
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +000010065 *soundfold()*
10066soundfold({word})
10067 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +000010068 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +000010069 soundfolding. 'spell' must be set. When no sound folding is
10070 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +000010071 This can be used for making spelling suggestions. Note that
10072 the method can be quite slow.
10073
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010074 Can also be used as a |method|: >
10075 GetWord()->soundfold()
10076<
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010077 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +000010078spellbadword([{sentence}])
10079 Without argument: The result is the badly spelled word under
10080 or after the cursor. The cursor is moved to the start of the
10081 bad word. When no bad word is found in the cursor line the
10082 result is an empty string and the cursor doesn't move.
10083
10084 With argument: The result is the first word in {sentence} that
10085 is badly spelled. If there are no spelling mistakes the
10086 result is an empty string.
10087
10088 The return value is a list with two items:
10089 - The badly spelled word or an empty string.
10090 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010091 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +000010092 "rare" rare word
10093 "local" word only valid in another region
10094 "caps" word should start with Capital
10095 Example: >
10096 echo spellbadword("the quik brown fox")
10097< ['quik', 'bad'] ~
10098
Bram Moolenaar152e79e2020-06-10 15:32:08 +020010099 The spelling information for the current window and the value
10100 of 'spelllang' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010101
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010102 Can also be used as a |method|: >
10103 GetText()->spellbadword()
10104<
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010105 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +000010106spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010107 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010108 When {max} is given up to this number of suggestions are
10109 returned. Otherwise up to 25 suggestions are returned.
10110
Bram Moolenaarc54b8a72005-09-30 21:20:29 +000010111 When the {capital} argument is given and it's non-zero only
10112 suggestions with a leading capital will be given. Use this
10113 after a match with 'spellcapcheck'.
10114
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010115 {word} can be a badly spelled word followed by other text.
10116 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +000010117 suggestions also include the following text, thus you can
10118 replace a line.
10119
10120 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +000010121 returned. {word} itself is not included in the suggestions,
10122 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010123
10124 The spelling information for the current window is used. The
Bram Moolenaar152e79e2020-06-10 15:32:08 +020010125 values of 'spelllang' and 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +000010126
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010127 Can also be used as a |method|: >
10128 GetWord()->spellsuggest()
Bram Moolenaara14de3d2005-01-07 21:48:26 +000010129
Bram Moolenaar2389c3c2005-05-22 22:07:59 +000010130split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010131 Make a |List| out of {expr}. When {pattern} is omitted or
10132 empty each white-separated sequence of characters becomes an
10133 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +000010134 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +010010135 removing the matched characters. 'ignorecase' is not used
10136 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +000010137 When the first or last item is empty it is omitted, unless the
10138 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +000010139 Other empty items are kept when {pattern} matches at least one
10140 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +000010141 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +000010142 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +000010143< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000010144 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +020010145< If you want to keep the separator you can also use '\zs' at
10146 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +000010147 :echo split('abc:def:ghi', ':\zs')
10148< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +000010149 Splitting a table where the first element can be empty: >
10150 :let items = split(line, ':', 1)
10151< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +000010152
Bram Moolenaara74e4942019-08-04 17:35:53 +020010153 Can also be used as a |method|: >
10154 GetString()->split()
Bram Moolenaara14de3d2005-01-07 21:48:26 +000010155
Bram Moolenaar446cb832008-06-24 21:56:24 +000010156sqrt({expr}) *sqrt()*
10157 Return the non-negative square root of Float {expr} as a
10158 |Float|.
10159 {expr} must evaluate to a |Float| or a |Number|. When {expr}
10160 is negative the result is NaN (Not a Number).
10161 Examples: >
10162 :echo sqrt(100)
10163< 10.0 >
10164 :echo sqrt(-4.01)
10165< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +000010166 "nan" may be different, it depends on system libraries.
Bram Moolenaar93cf85f2019-08-17 21:36:28 +020010167
10168 Can also be used as a |method|: >
10169 Compute()->sqrt()
10170<
Bram Moolenaar446cb832008-06-24 21:56:24 +000010171 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010172
Bram Moolenaar446cb832008-06-24 21:56:24 +000010173
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +010010174srand([{expr}]) *srand()*
10175 Initialize seed used by |rand()|:
10176 - If {expr} is not given, seed values are initialized by
Bram Moolenaarf8c1f922019-11-28 22:13:14 +010010177 reading from /dev/urandom, if possible, or using time(NULL)
10178 a.k.a. epoch time otherwise; this only has second accuracy.
10179 - If {expr} is given it must be a Number. It is used to
10180 initialize the seed values. This is useful for testing or
10181 when a predictable sequence is intended.
Bram Moolenaar06b0b4b2019-11-25 15:40:55 +010010182
10183 Examples: >
10184 :let seed = srand()
10185 :let seed = srand(userinput)
10186 :echo rand(seed)
10187
Bram Moolenaar0e57dd82019-09-16 22:56:03 +020010188state([{what}]) *state()*
10189 Return a string which contains characters indicating the
10190 current state. Mostly useful in callbacks that want to do
10191 work that may not always be safe. Roughly this works like:
10192 - callback uses state() to check if work is safe to do.
Bram Moolenaar589edb32019-09-20 14:38:13 +020010193 Yes: then do it right away.
10194 No: add to work queue and add a |SafeState| and/or
10195 |SafeStateAgain| autocommand (|SafeState| triggers at
10196 toplevel, |SafeStateAgain| triggers after handling
10197 messages and callbacks).
10198 - When SafeState or SafeStateAgain is triggered and executes
10199 your autocommand, check with `state()` if the work can be
10200 done now, and if yes remove it from the queue and execute.
10201 Remove the autocommand if the queue is now empty.
Bram Moolenaar0e57dd82019-09-16 22:56:03 +020010202 Also see |mode()|.
10203
10204 When {what} is given only characters in this string will be
10205 added. E.g, this checks if the screen has scrolled: >
Bram Moolenaar589edb32019-09-20 14:38:13 +020010206 if state('s') == ''
10207 " screen has not scrolled
Bram Moolenaar0e57dd82019-09-16 22:56:03 +020010208<
Bram Moolenaard103ee72019-09-18 21:15:31 +020010209 These characters indicate the state, generally indicating that
10210 something is busy:
Bram Moolenaar589edb32019-09-20 14:38:13 +020010211 m halfway a mapping, :normal command, feedkeys() or
10212 stuffed command
Bram Moolenaare46a4402020-06-30 20:38:27 +020010213 o operator pending, e.g. after |d|
Bram Moolenaar589edb32019-09-20 14:38:13 +020010214 a Insert mode autocomplete active
10215 x executing an autocommand
Bram Moolenaar2e693a82019-10-16 22:35:02 +020010216 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
Bram Moolenaare46a4402020-06-30 20:38:27 +020010217 ch_readraw() when reading json
10218 S not triggering SafeState or SafeStateAgain, e.g. after
10219 |f| or a count
Bram Moolenaar589edb32019-09-20 14:38:13 +020010220 c callback invoked, including timer (repeats for
10221 recursiveness up to "ccc")
10222 s screen has scrolled for messages
Bram Moolenaar0e57dd82019-09-16 22:56:03 +020010223
Bram Moolenaar81edd172016-04-14 13:51:37 +020010224str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +000010225 Convert String {expr} to a Float. This mostly works the same
10226 as when using a floating point number in an expression, see
10227 |floating-point-format|. But it's a bit more permissive.
10228 E.g., "1e40" is accepted, while in an expression you need to
Bram Moolenaard47d5222018-12-09 20:43:55 +010010229 write "1.0e40". The hexadecimal form "0x123" is also
10230 accepted, but not others, like binary or octal.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010231 Text after the number is silently ignored.
10232 The decimal point is always '.', no matter what the locale is
10233 set to. A comma ends the number: "12,345.67" is converted to
10234 12.0. You can strip out thousands separators with
10235 |substitute()|: >
10236 let f = str2float(substitute(text, ',', '', 'g'))
Bram Moolenaar93cf85f2019-08-17 21:36:28 +020010237<
10238 Can also be used as a |method|: >
10239 let f = text->substitute(',', '', 'g')->str2float()
10240<
10241 {only available when compiled with the |+float| feature}
Bram Moolenaar446cb832008-06-24 21:56:24 +000010242
Bram Moolenaar9d401282019-04-06 13:18:12 +020010243str2list({expr} [, {utf8}]) *str2list()*
10244 Return a list containing the number values which represent
10245 each character in String {expr}. Examples: >
10246 str2list(" ") returns [32]
10247 str2list("ABC") returns [65, 66, 67]
10248< |list2str()| does the opposite.
10249
10250 When {utf8} is omitted or zero, the current 'encoding' is used.
10251 With {utf8} set to 1, always treat the String as utf-8
10252 characters. With utf-8 composing characters are handled
10253 properly: >
10254 str2list("á") returns [97, 769]
Bram Moolenaar446cb832008-06-24 21:56:24 +000010255
Bram Moolenaara74e4942019-08-04 17:35:53 +020010256< Can also be used as a |method|: >
10257 GetString()->str2list()
10258
10259
Bram Moolenaar60a8de22019-09-15 14:33:22 +020010260str2nr({expr} [, {base} [, {quoted}]]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000010261 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +010010262 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar60a8de22019-09-15 14:33:22 +020010263 When {quoted} is present and non-zero then embedded single
10264 quotes are ignored, thus "1'000'000" is a million.
Bram Moolenaara74e4942019-08-04 17:35:53 +020010265
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000010266 When {base} is omitted base 10 is used. This also means that
10267 a leading zero doesn't cause octal conversion to be used, as
Bram Moolenaara74e4942019-08-04 17:35:53 +020010268 with the default String to Number conversion. Example: >
Bram Moolenaar2e693a82019-10-16 22:35:02 +020010269 let nr = str2nr('0123')
Bram Moolenaara74e4942019-08-04 17:35:53 +020010270<
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000010271 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +010010272 different base the result will be zero. Similarly, when
Bram Moolenaarc17e66c2020-06-02 21:38:22 +020010273 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10274 {base} is 2 a leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000010275 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010276
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010277 Can also be used as a |method|: >
10278 GetText()->str2nr()
10279
Bram Moolenaar70ce8a12021-03-14 19:02:09 +010010280
10281strcharlen({expr}) *strcharlen()*
10282 The result is a Number, which is the number of characters
10283 in String {expr}. Composing characters are ignored.
10284 |strchars()| can count the number of characters, counting
10285 composing characters separately.
10286
10287 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10288
10289 Can also be used as a |method|: >
10290 GetText()->strcharlen()
10291
10292
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010293strcharpart({src}, {start} [, {len}]) *strcharpart()*
10294 Like |strpart()| but using character index and length instead
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +010010295 of byte index and length. Composing characters are counted
10296 separately.
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010297 When a character index is used where a character does not
10298 exist it is assumed to be one character. For example: >
10299 strcharpart('abc', -1, 2)
10300< results in 'a'.
10301
10302 Can also be used as a |method|: >
10303 GetText()->strcharpart(5)
Bram Moolenaar97b2ad32006-03-18 21:40:56 +000010304
Bram Moolenaar70ce8a12021-03-14 19:02:09 +010010305
Bram Moolenaar979243b2015-06-26 19:35:49 +020010306strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +020010307 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +020010308 in String {expr}.
10309 When {skipcc} is omitted or zero, composing characters are
10310 counted separately.
10311 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaar70ce8a12021-03-14 19:02:09 +010010312 |strcharlen()| does the same.
10313
Bram Moolenaardc536092010-07-18 15:45:49 +020010314 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010315
Bram Moolenaar86ae7202015-07-10 19:31:35 +020010316 {skipcc} is only available after 7.4.755. For backward
10317 compatibility, you can define a wrapper function: >
10318 if has("patch-7.4.755")
10319 function s:strchars(str, skipcc)
10320 return strchars(a:str, a:skipcc)
10321 endfunction
10322 else
10323 function s:strchars(str, skipcc)
10324 if a:skipcc
10325 return strlen(substitute(a:str, ".", "x", "g"))
10326 else
10327 return strchars(a:str)
10328 endif
10329 endfunction
10330 endif
10331<
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010332 Can also be used as a |method|: >
10333 GetText()->strchars()
Bram Moolenaar86ae7202015-07-10 19:31:35 +020010334
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010335strdisplaywidth({expr} [, {col}]) *strdisplaywidth()*
Bram Moolenaardc536092010-07-18 15:45:49 +020010336 The result is a Number, which is the number of display cells
Bram Moolenaar4c92e752019-02-17 21:18:32 +010010337 String {expr} occupies on the screen when it starts at {col}
10338 (first column is zero). When {col} is omitted zero is used.
10339 Otherwise it is the screen column where to start. This
10340 matters for Tab characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +020010341 The option settings of the current window are used. This
10342 matters for anything that's displayed differently, such as
10343 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +020010344 When {expr} contains characters with East Asian Width Class
10345 Ambiguous, this function's return value depends on 'ambiwidth'.
10346 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +020010347
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010348 Can also be used as a |method|: >
10349 GetText()->strdisplaywidth()
10350
Bram Moolenaar071d4272004-06-13 20:20:40 +000010351strftime({format} [, {time}]) *strftime()*
10352 The result is a String, which is a formatted date and time, as
10353 specified by the {format} string. The given {time} is used,
10354 or the current time if no time is given. The accepted
10355 {format} depends on your system, thus this is not portable!
10356 See the manual page of the C function strftime() for the
10357 format. The maximum length of the result is 80 characters.
Bram Moolenaar10455d42019-11-21 15:36:18 +010010358 See also |localtime()|, |getftime()| and |strptime()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010359 The language can be changed with the |:language| command.
10360 Examples: >
10361 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10362 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10363 :echo strftime("%y%m%d %T") 970427 11:53:55
10364 :echo strftime("%H:%M") 11:55
10365 :echo strftime("%c", getftime("file.c"))
10366 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +000010367< Not available on all systems. To check use: >
10368 :if exists("*strftime")
10369
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010370< Can also be used as a |method|: >
10371 GetFormat()->strftime()
10372
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +020010373strgetchar({str}, {index}) *strgetchar()*
10374 Get character {index} from {str}. This uses a character
10375 index, not a byte index. Composing characters are considered
10376 separate characters here.
10377 Also see |strcharpart()| and |strchars()|.
10378
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010379 Can also be used as a |method|: >
10380 GetText()->strgetchar(5)
10381
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010382stridx({haystack}, {needle} [, {start}]) *stridx()*
10383 The result is a Number, which gives the byte index in
10384 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +000010385 If {start} is specified, the search starts at index {start}.
10386 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +010010387 :let colon1 = stridx(line, ":")
10388 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +000010389< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010390 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010391 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +000010392 See also |strridx()|.
10393 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010394 :echo stridx("An Example", "Example") 3
10395 :echo stridx("Starting point", "Start") 0
10396 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010397< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +000010398 stridx() works similar to the C function strstr(). When used
10399 with a single character it works similar to strchr().
10400
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010401 Can also be used as a |method|: >
10402 GetHaystack()->stridx(needle)
Bram Moolenaar2e693a82019-10-16 22:35:02 +020010403<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000010404 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +000010405string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +010010406 Float, String, Blob or a composition of them, then the result
10407 can be parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000010408 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010409 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +000010410 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +000010411 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +000010412 Funcref function('name')
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +010010413 Blob 0z00112233.44556677.8899
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +000010414 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +000010415 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010416
Bram Moolenaare46a4402020-06-30 20:38:27 +020010417 When a |List| or |Dictionary| has a recursive reference it is
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010418 replaced by "[...]" or "{...}". Using eval() on the result
10419 will then fail.
10420
Bram Moolenaarac92e252019-08-03 21:58:38 +020010421 Can also be used as a |method|: >
10422 mylist->string()
10423
10424< Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000010425
Bram Moolenaar071d4272004-06-13 20:20:40 +000010426 *strlen()*
10427strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +000010428 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000010429 If the argument is a Number it is first converted to a String.
10430 For other types an error is given.
Bram Moolenaar6c53fca2020-08-23 17:34:46 +020010431 If you want to count the number of multibyte characters use
Bram Moolenaar641e48c2015-06-25 16:09:26 +020010432 |strchars()|.
10433 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010434
Bram Moolenaara74e4942019-08-04 17:35:53 +020010435 Can also be used as a |method|: >
10436 GetString()->strlen()
10437
Bram Moolenaar6c53fca2020-08-23 17:34:46 +020010438strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010439 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +000010440 byte {start}, with the byte length {len}.
Bram Moolenaar6c53fca2020-08-23 17:34:46 +020010441 When {chars} is present and TRUE then {len} is the number of
10442 characters positions (composing characters are not counted
10443 separately, thus "1" means one base character and any
10444 following composing characters).
10445 To count {start} as characters instead of bytes use
10446 |strcharpart()|.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +020010447
10448 When bytes are selected which do not exist, this doesn't
10449 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010450 If {len} is missing, the copy continues from {start} till the
10451 end of the {src}. >
10452 strpart("abcdefg", 3, 2) == "de"
10453 strpart("abcdefg", -2, 4) == "ab"
10454 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +000010455 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +020010456
Bram Moolenaar071d4272004-06-13 20:20:40 +000010457< Note: To get the first character, {start} must be 0. For
Bram Moolenaar6c53fca2020-08-23 17:34:46 +020010458 example, to get the character under the cursor: >
10459 strpart(getline("."), col(".") - 1, 1, v:true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010460<
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010461 Can also be used as a |method|: >
10462 GetText()->strpart(5)
10463
Bram Moolenaar10455d42019-11-21 15:36:18 +010010464strptime({format}, {timestring}) *strptime()*
10465 The result is a Number, which is a unix timestamp representing
10466 the date and time in {timestring}, which is expected to match
10467 the format specified in {format}.
10468
10469 The accepted {format} depends on your system, thus this is not
10470 portable! See the manual page of the C function strptime()
10471 for the format. Especially avoid "%c". The value of $TZ also
10472 matters.
10473
10474 If the {timestring} cannot be parsed with {format} zero is
10475 returned. If you do not know the format of {timestring} you
10476 can try different {format} values until you get a non-zero
10477 result.
10478
10479 See also |strftime()|.
10480 Examples: >
10481 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
10482< 862156163 >
10483 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
10484< Sun Apr 27 11:53:55 1997 >
10485 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
10486< Sun Apr 27 12:53:55 1997
10487
10488 Not available on all systems. To check use: >
10489 :if exists("*strptime")
10490
10491
Bram Moolenaar677ee682005-01-27 14:41:15 +000010492strridx({haystack}, {needle} [, {start}]) *strridx()*
10493 The result is a Number, which gives the byte index in
10494 {haystack} of the last occurrence of the String {needle}.
10495 When {start} is specified, matches beyond this index are
10496 ignored. This can be used to find a match before a previous
10497 match: >
10498 :let lastcomma = strridx(line, ",")
10499 :let comma2 = strridx(line, ",", lastcomma - 1)
10500< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010501 For pattern searches use |match()|.
10502 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +000010503 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000010504 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010505 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010506< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +000010507 When used with a single character it works similar to the C
10508 function strrchr().
10509
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010510 Can also be used as a |method|: >
10511 GetHaystack()->strridx(needle)
10512
Bram Moolenaar071d4272004-06-13 20:20:40 +000010513strtrans({expr}) *strtrans()*
10514 The result is a String, which is {expr} with all unprintable
10515 characters translated into printable characters |'isprint'|.
10516 Like they are shown in a window. Example: >
10517 echo strtrans(@a)
10518< This displays a newline in register a as "^@" instead of
10519 starting a new line.
10520
Bram Moolenaara74e4942019-08-04 17:35:53 +020010521 Can also be used as a |method|: >
10522 GetString()->strtrans()
10523
Bram Moolenaar72597a52010-07-18 15:31:08 +020010524strwidth({expr}) *strwidth()*
10525 The result is a Number, which is the number of display cells
10526 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +020010527 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +020010528 When {expr} contains characters with East Asian Width Class
10529 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +020010530 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +020010531
Bram Moolenaara74e4942019-08-04 17:35:53 +020010532 Can also be used as a |method|: >
10533 GetString()->strwidth()
10534
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010535submatch({nr} [, {list}]) *submatch()* *E935*
Bram Moolenaar251e1912011-06-19 05:09:16 +020010536 Only for an expression in a |:substitute| command or
10537 substitute() function.
10538 Returns the {nr}'th submatch of the matched text. When {nr}
10539 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +020010540 Note that a NL in the string can stand for a line break of a
10541 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +020010542 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +020010543
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010544 If {list} is present and non-zero then submatch() returns
10545 a list of strings, similar to |getline()| with two arguments.
Bram Moolenaar41571762014-04-02 19:00:58 +020010546 NL characters in the text represent NUL characters in the
10547 text.
10548 Only returns more than one item for |:substitute|, inside
10549 |substitute()| this list will always contain one or zero
10550 items, since there are no real line breaks.
10551
Bram Moolenaar6100d022016-10-02 16:51:57 +020010552 When substitute() is used recursively only the submatches in
10553 the current (deepest) call can be obtained.
10554
Bram Moolenaar2f058492017-11-30 20:27:52 +010010555 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010556 :s/\d\+/\=submatch(0) + 1/
Bram Moolenaar2f058492017-11-30 20:27:52 +010010557 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
Bram Moolenaar071d4272004-06-13 20:20:40 +000010558< This finds the first number in the line and adds one to it.
10559 A line break is included as a newline character.
10560
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010561 Can also be used as a |method|: >
10562 GetNr()->submatch()
10563
Bram Moolenaar071d4272004-06-13 20:20:40 +000010564substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
10565 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +020010566 the first match of {pat} is replaced with {sub}.
10567 When {flags} is "g", all matches of {pat} in {expr} are
10568 replaced. Otherwise {flags} should be "".
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010569
Bram Moolenaar251e1912011-06-19 05:09:16 +020010570 This works like the ":substitute" command (without any flags).
10571 But the matching with {pat} is always done like the 'magic'
10572 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +010010573 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
10574 if you want to ignore or match case and ignore 'ignorecase'.
10575 'smartcase' is not used. See |string-match| for how {pat} is
10576 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +020010577
10578 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010579 Note that some codes in {sub} have a special meaning
Bram Moolenaar58b85342016-08-14 19:54:54 +020010580 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +000010581 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +020010582
Bram Moolenaar071d4272004-06-13 20:20:40 +000010583 When {pat} does not match in {expr}, {expr} is returned
10584 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +020010585
Bram Moolenaar071d4272004-06-13 20:20:40 +000010586 Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010587 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +000010588< This removes the last component of the 'path' option. >
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010589 :echo substitute("testing", ".*", "\\U\\0", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +000010590< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +020010591
10592 When {sub} starts with "\=", the remainder is interpreted as
10593 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010594 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaar20f90cf2011-05-19 12:22:51 +020010595 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +000010596
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010597< When {sub} is a Funcref that function is called, with one
10598 optional argument. Example: >
10599 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
10600< The optional argument is a list which contains the whole
Bram Moolenaar58b85342016-08-14 19:54:54 +020010601 matched string and up to nine submatches, like what
10602 |submatch()| returns. Example: >
10603 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
Bram Moolenaardf48fb42016-07-22 21:50:18 +020010604
Bram Moolenaara74e4942019-08-04 17:35:53 +020010605< Can also be used as a |method|: >
10606 GetString()->substitute(pat, sub, flags)
10607
Bram Moolenaar20aac6c2018-09-02 21:07:30 +020010608swapinfo({fname}) *swapinfo()*
Bram Moolenaar00f123a2018-08-21 20:28:54 +020010609 The result is a dictionary, which holds information about the
10610 swapfile {fname}. The available fields are:
Bram Moolenaar95bafa22018-10-02 13:26:25 +020010611 version Vim version
Bram Moolenaar00f123a2018-08-21 20:28:54 +020010612 user user name
10613 host host name
10614 fname original file name
Bram Moolenaar95bafa22018-10-02 13:26:25 +020010615 pid PID of the Vim process that created the swap
Bram Moolenaar00f123a2018-08-21 20:28:54 +020010616 file
10617 mtime last modification time in seconds
10618 inode Optional: INODE number of the file
Bram Moolenaar47ad5652018-08-21 21:09:07 +020010619 dirty 1 if file was modified, 0 if not
Bram Moolenaarfc65cab2018-08-28 22:58:02 +020010620 Note that "user" and "host" are truncated to at most 39 bytes.
Bram Moolenaar00f123a2018-08-21 20:28:54 +020010621 In case of failure an "error" item is added with the reason:
10622 Cannot open file: file not found or in accessible
10623 Cannot read file: cannot read first block
Bram Moolenaar47ad5652018-08-21 21:09:07 +020010624 Not a swap file: does not contain correct block ID
10625 Magic number mismatch: Info in first block is invalid
Bram Moolenaar00f123a2018-08-21 20:28:54 +020010626
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010627 Can also be used as a |method|: >
10628 GetFilename()->swapinfo()
10629
Bram Moolenaar110bd602018-09-16 18:46:59 +020010630swapname({expr}) *swapname()*
10631 The result is the swap file path of the buffer {expr}.
10632 For the use of {expr}, see |bufname()| above.
10633 If buffer {expr} is the current buffer, the result is equal to
Bram Moolenaare7b1ea02020-08-07 19:54:59 +020010634 |:swapname| (unless there is no swap file).
Bram Moolenaar110bd602018-09-16 18:46:59 +020010635 If buffer {expr} has no swap file, returns an empty string.
10636
Bram Moolenaarf6ed61e2019-09-07 19:05:09 +020010637 Can also be used as a |method|: >
10638 GetBufname()->swapname()
10639
Bram Moolenaar47136d72004-10-12 20:02:24 +000010640synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010641 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +000010642 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010643 The syntax ID can be used with |synIDattr()| and
10644 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +000010645
Bram Moolenaar47136d72004-10-12 20:02:24 +000010646 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +000010647 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +020010648 Note that when the position is after the last character,
10649 that's where the cursor can be in Insert mode, synID() returns
10650 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +000010651
Bram Moolenaar79815f12016-07-09 17:07:29 +020010652 When {trans} is |TRUE|, transparent items are reduced to the
Bram Moolenaar58b85342016-08-14 19:54:54 +020010653 item that they reveal. This is useful when wanting to know
Bram Moolenaar79815f12016-07-09 17:07:29 +020010654 the effective color. When {trans} is |FALSE|, the transparent
Bram Moolenaar071d4272004-06-13 20:20:40 +000010655 item is returned. This is useful when wanting to know which
10656 syntax item is effective (e.g. inside parens).
10657 Warning: This function can be very slow. Best speed is
10658 obtained by going through the file in forward direction.
10659
10660 Example (echoes the name of the syntax item under the cursor): >
10661 :echo synIDattr(synID(line("."), col("."), 1), "name")
10662<
Bram Moolenaar7510fe72010-07-25 12:46:44 +020010663
Bram Moolenaar071d4272004-06-13 20:20:40 +000010664synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
10665 The result is a String, which is the {what} attribute of
10666 syntax ID {synID}. This can be used to obtain information
10667 about a syntax item.
10668 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar58b85342016-08-14 19:54:54 +020010669 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +000010670 used, the attributes for the currently active highlighting are
10671 used (GUI, cterm or term).
10672 Use synIDtrans() to follow linked highlight groups.
10673 {what} result
10674 "name" the name of the syntax item
10675 "fg" foreground color (GUI: color name used to set
10676 the color, cterm: color number as a string,
10677 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +000010678 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +010010679 "font" font name (only available in the GUI)
10680 |highlight-font|
Bram Moolenaar391c3622020-09-29 20:59:17 +020010681 "sp" special color for the GUI (as with "fg")
10682 |highlight-guisp|
10683 "ul" underline color for cterm: number as a string
Bram Moolenaar071d4272004-06-13 20:20:40 +000010684 "fg#" like "fg", but for the GUI and the GUI is
10685 running the name in "#RRGGBB" form
10686 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +000010687 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +000010688 "bold" "1" if bold
10689 "italic" "1" if italic
10690 "reverse" "1" if reverse
10691 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +010010692 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +000010693 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010694 "undercurl" "1" if undercurled
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +020010695 "strike" "1" if strikethrough
Bram Moolenaar071d4272004-06-13 20:20:40 +000010696
10697 Example (echoes the color of the syntax item under the
10698 cursor): >
10699 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
10700<
Bram Moolenaara74e4942019-08-04 17:35:53 +020010701 Can also be used as a |method|: >
10702 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
10703
10704
Bram Moolenaar071d4272004-06-13 20:20:40 +000010705synIDtrans({synID}) *synIDtrans()*
10706 The result is a Number, which is the translated syntax ID of
10707 {synID}. This is the syntax group ID of what is being used to
10708 highlight the character. Highlight links given with
10709 ":highlight link" are followed.
10710
Bram Moolenaara74e4942019-08-04 17:35:53 +020010711 Can also be used as a |method|: >
10712 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
10713
Bram Moolenaar483c5d82010-10-20 18:45:33 +020010714synconcealed({lnum}, {col}) *synconcealed()*
Bram Moolenaare46a4402020-06-30 20:38:27 +020010715 The result is a |List| with currently three items:
Bram Moolenaar4d785892017-06-22 22:00:50 +020010716 1. The first item in the list is 0 if the character at the
10717 position {lnum} and {col} is not part of a concealable
10718 region, 1 if it is.
10719 2. The second item in the list is a string. If the first item
10720 is 1, the second item contains the text which will be
10721 displayed in place of the concealed text, depending on the
10722 current setting of 'conceallevel' and 'listchars'.
Bram Moolenaarcc0750d2017-06-24 22:29:24 +020010723 3. The third and final item in the list is a number
10724 representing the specific syntax region matched in the
10725 line. When the character is not concealed the value is
10726 zero. This allows detection of the beginning of a new
10727 concealable region if there are two consecutive regions
10728 with the same replacement character. For an example, if
10729 the text is "123456" and both "23" and "45" are concealed
Bram Moolenaar95bafa22018-10-02 13:26:25 +020010730 and replaced by the character "X", then:
Bram Moolenaarcc0750d2017-06-24 22:29:24 +020010731 call returns ~
Bram Moolenaarc572da52017-08-27 16:52:01 +020010732 synconcealed(lnum, 1) [0, '', 0]
10733 synconcealed(lnum, 2) [1, 'X', 1]
10734 synconcealed(lnum, 3) [1, 'X', 1]
10735 synconcealed(lnum, 4) [1, 'X', 2]
10736 synconcealed(lnum, 5) [1, 'X', 2]
10737 synconcealed(lnum, 6) [0, '', 0]
Bram Moolenaar483c5d82010-10-20 18:45:33 +020010738
10739
Bram Moolenaar9d188ab2008-01-10 21:24:39 +000010740synstack({lnum}, {col}) *synstack()*
10741 Return a |List|, which is the stack of syntax items at the
10742 position {lnum} and {col} in the current window. Each item in
10743 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +000010744 The first item in the List is the outer region, following are
10745 items contained in that one. The last one is what |synID()|
10746 returns, unless not the whole item is highlighted or it is a
10747 transparent item.
10748 This function is useful for debugging a syntax file.
10749 Example that shows the syntax stack under the cursor: >
10750 for id in synstack(line("."), col("."))
10751 echo synIDattr(id, "name")
10752 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +020010753< When the position specified with {lnum} and {col} is invalid
10754 nothing is returned. The position just after the last
10755 character in a line and the first column in an empty line are
10756 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +000010757
Bram Moolenaarc0197e22004-09-13 20:26:32 +000010758system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +020010759 Get the output of the shell command {expr} as a string. See
Bram Moolenaare46a4402020-06-30 20:38:27 +020010760 |systemlist()| to get the output as a |List|.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +020010761
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010762 When {input} is given and is a string this string is written
10763 to a file and passed as stdin to the command. The string is
10764 written as-is, you need to take care of using the correct line
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +020010765 separators yourself.
10766 If {input} is given and is a |List| it is written to the file
10767 in a way |writefile()| does with {binary} set to "b" (i.e.
10768 with a newline between each list item with newlines inside
Bram Moolenaar12c44922017-01-08 13:26:03 +010010769 list items converted to NULs).
10770 When {input} is given and is a number that is a valid id for
10771 an existing buffer then the content of the buffer is written
10772 to the file line by line, each line terminated by a NL and
10773 NULs characters where the text has a NL.
Bram Moolenaar069c1e72016-07-15 21:25:08 +020010774
10775 Pipes are not used, the 'shelltemp' option is not used.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +020010776
Bram Moolenaar04186092016-08-29 21:55:35 +020010777 When prepended by |:silent| the terminal will not be set to
Bram Moolenaar52a72462014-08-29 15:53:52 +020010778 cooked mode. This is meant to be used for commands that do
10779 not need the user to type. It avoids stray characters showing
10780 up on the screen which require |CTRL-L| to remove. >
10781 :silent let f = system('ls *.vim')
10782<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010783 Note: Use |shellescape()| or |::S| with |expand()| or
10784 |fnamemodify()| to escape special characters in a command
10785 argument. Newlines in {expr} may cause the command to fail.
10786 The characters in 'shellquote' and 'shellxquote' may also
Bram Moolenaar26df0922014-02-23 23:39:13 +010010787 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010788 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010789
Bram Moolenaar05bb9532008-07-04 09:44:11 +000010790 The result is a String. Example: >
10791 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +010010792 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +000010793
10794< To make the result more system-independent, the shell output
10795 is filtered to replace <CR> with <NL> for Macintosh, and
10796 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +020010797 To avoid the string being truncated at a NUL, all NUL
10798 characters are replaced with SOH (0x01).
10799
Bram Moolenaar071d4272004-06-13 20:20:40 +000010800 The command executed is constructed using several options:
10801 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
10802 ({tmp} is an automatically generated file name).
Bram Moolenaar6f345a12019-12-17 21:27:18 +010010803 For Unix, braces are put around {expr} to allow for
Bram Moolenaar071d4272004-06-13 20:20:40 +000010804 concatenated commands.
10805
Bram Moolenaar433f7c82006-03-21 21:29:36 +000010806 The command will be executed in "cooked" mode, so that a
10807 CTRL-C will interrupt the command (on Unix at least).
10808
Bram Moolenaar071d4272004-06-13 20:20:40 +000010809 The resulting error code can be found in |v:shell_error|.
10810 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +000010811
10812 Note that any wrong value in the options mentioned above may
10813 make the function fail. It has also been reported to fail
10814 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010815 Unlike ":!cmd" there is no automatic check for changed files.
10816 Use |:checktime| to force a check.
10817
Bram Moolenaara74e4942019-08-04 17:35:53 +020010818 Can also be used as a |method|: >
10819 :echo GetCmd()->system()
10820
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010821
Bram Moolenaar39c29ed2014-04-05 19:44:40 +020010822systemlist({expr} [, {input}]) *systemlist()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010823 Same as |system()|, but returns a |List| with lines (parts of
10824 output separated by NL) with NULs transformed into NLs. Output
10825 is the same as |readfile()| will output with {binary} argument
Bram Moolenaar5be4cee2019-09-27 19:34:08 +020010826 set to "b", except that there is no extra empty item when the
10827 result ends in a NL.
10828 Note that on MS-Windows you may get trailing CR characters.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +020010829
Bram Moolenaar5be4cee2019-09-27 19:34:08 +020010830 To see the difference between "echo hello" and "echo -n hello"
10831 use |system()| and |split()|: >
10832 echo system('echo hello')->split('\n', 1)
10833<
Bram Moolenaar975b5272016-03-15 23:10:59 +010010834 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +020010835
Bram Moolenaara74e4942019-08-04 17:35:53 +020010836 Can also be used as a |method|: >
10837 :echo GetCmd()->systemlist()
10838
Bram Moolenaar39c29ed2014-04-05 19:44:40 +020010839
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010840tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010841 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010842 buffer associated with each window in the current tab page.
Bram Moolenaardc1f1642016-08-16 18:33:43 +020010843 {arg} specifies the number of the tab page to be used. When
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010844 omitted the current tab page is used.
10845 When {arg} is invalid the number zero is returned.
10846 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +020010847 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010848 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +020010849 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010850 endfor
10851< Note that a buffer may appear in more than one window.
10852
Bram Moolenaarce90e362019-09-08 18:58:44 +020010853 Can also be used as a |method|: >
10854 GetTabpage()->tabpagebuflist()
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010855
10856tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000010857 The result is a Number, which is the number of the current
10858 tab page. The first tab page has number 1.
Bram Moolenaar62a23252020-08-09 14:04:42 +020010859
10860 The optional argument {arg} supports the following values:
10861 $ the number of the last tab page (the tab page
10862 count).
10863 # the number of the last accessed tab page
10864 (where |g<Tab>| goes to). if there is no
10865 previous tab page 0 is returned.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000010866 The number can be used with the |:tab| command.
10867
10868
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010010869tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +020010870 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +000010871 {tabarg} specifies the number of tab page to be used.
10872 {arg} is used like with |winnr()|:
10873 - When omitted the current window number is returned. This is
10874 the window which will be used when going to this tab page.
10875 - When "$" the number of windows is returned.
10876 - When "#" the previous window nr is returned.
10877 Useful examples: >
10878 tabpagewinnr(1) " current window of tab page 1
10879 tabpagewinnr(4, '$') " number of windows in tab page 4
10880< When {tabarg} is invalid zero is returned.
10881
Bram Moolenaarce90e362019-09-08 18:58:44 +020010882 Can also be used as a |method|: >
10883 GetTabpage()->tabpagewinnr()
10884<
Bram Moolenaarfa1d1402006-03-25 21:59:56 +000010885 *tagfiles()*
10886tagfiles() Returns a |List| with the file names used to search for tags
10887 for the current buffer. This is the 'tags' option expanded.
10888
10889
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010890taglist({expr} [, {filename}]) *taglist()*
Bram Moolenaar1b884a02020-12-10 21:11:27 +010010891 Returns a |List| of tags matching the regular expression {expr}.
Bram Moolenaarc6aafba2017-03-21 17:09:10 +010010892
10893 If {filename} is passed it is used to prioritize the results
10894 in the same way that |:tselect| does. See |tag-priority|.
10895 {filename} should be the full path of the file.
10896
Bram Moolenaard8c00872005-07-22 21:52:15 +000010897 Each list item is a dictionary with at least the following
10898 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +000010899 name Name of the tag.
10900 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010901 defined. It is either relative to the
10902 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010903 cmd Ex command used to locate the tag in
10904 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +000010905 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010906 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010907 kind values. Only available when
10908 using a tags file generated by
10909 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +000010910 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010911 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010912 More entries may be present, depending on the content of the
10913 tags file: access, implementation, inherits and signature.
10914 Refer to the ctags documentation for information about these
10915 fields. For C code the fields "struct", "class" and "enum"
10916 may appear, they give the name of the entity the tag is
10917 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +000010918
Bram Moolenaar214641f2017-03-05 17:04:09 +010010919 The ex-command "cmd" can be either an ex search pattern, a
Bram Moolenaar4317d9b2005-03-18 20:25:31 +000010920 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010921
10922 If there are no matching tags, then an empty list is returned.
10923
10924 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +010010925 used in {expr}. This also make the function work faster.
10926 Refer to |tag-regexp| for more information about the tag
10927 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +000010928
10929 Refer to |'tags'| for information about how the tags file is
10930 located by Vim. Refer to |tags-file-format| for the format of
10931 the tags file generated by the different ctags tools.
10932
Bram Moolenaarce90e362019-09-08 18:58:44 +020010933 Can also be used as a |method|: >
10934 GetTagpattern()->taglist()
10935
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010936tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +020010937 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010938 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +020010939 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010940 Examples: >
10941 :echo tan(10)
10942< 0.648361 >
10943 :echo tan(-4.01)
10944< -1.181502
Bram Moolenaar93cf85f2019-08-17 21:36:28 +020010945
10946 Can also be used as a |method|: >
10947 Compute()->tan()
10948<
Bram Moolenaardb84e452010-08-15 13:50:43 +020010949 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010950
10951
10952tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +020010953 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010954 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +020010955 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010956 Examples: >
10957 :echo tanh(0.5)
10958< 0.462117 >
10959 :echo tanh(-1)
10960< -0.761594
Bram Moolenaar93cf85f2019-08-17 21:36:28 +020010961
10962 Can also be used as a |method|: >
10963 Compute()->tanh()
10964<
Bram Moolenaardb84e452010-08-15 13:50:43 +020010965 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +020010966
10967
Bram Moolenaar574860b2016-05-24 17:33:34 +020010968tempname() *tempname()* *temp-file-name*
10969 The result is a String, which is the name of a file that
Bram Moolenaar58b85342016-08-14 19:54:54 +020010970 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar574860b2016-05-24 17:33:34 +020010971 is different for at least 26 consecutive calls. Example: >
10972 :let tmpfile = tempname()
10973 :exe "redir > " . tmpfile
10974< For Unix, the file will be in a private directory |tempfile|.
10975 For MS-Windows forward slashes are used when the 'shellslash'
10976 option is set or when 'shellcmdflag' starts with '-'.
10977
Bram Moolenaared997ad2019-07-21 16:42:00 +020010978
Bram Moolenaar6bf2c622019-07-04 17:12:09 +020010979term_ functions are documented here: |terminal-function-details|
Bram Moolenaar574860b2016-05-24 17:33:34 +020010980
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +020010981
10982terminalprops() *terminalprops()*
Bram Moolenaar1b884a02020-12-10 21:11:27 +010010983 Returns a |Dictionary| with properties of the terminal that Vim
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +020010984 detected from the response to |t_RV| request. See
10985 |v:termresponse| for the response itself. If |v:termresponse|
10986 is empty most values here will be 'u' for unknown.
Bram Moolenaarcb80aa22020-10-26 21:12:46 +010010987 cursor_style whether sending |t_RS| works **
10988 cursor_blink_mode whether sending |t_RC| works **
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +020010989 underline_rgb whether |t_8u| works **
10990 mouse mouse type supported
10991
10992 ** value 'u' for unknown, 'y' for yes, 'n' for no
10993
10994 If the |+termresponse| feature is missing then the result is
10995 an empty dictionary.
10996
Bram Moolenaar73fef332020-06-21 22:12:03 +020010997 If "cursor_style" is 'y' then |t_RS| will be sent to request the
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +020010998 current cursor style.
Bram Moolenaar73fef332020-06-21 22:12:03 +020010999 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +020011000 request the cursor blink status.
11001 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11002 is not empty, Vim will detect the working of sending |t_RS|
11003 and |t_RC| on startup.
11004
11005 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11006 This avoids sending it to xterm, which would clear the colors.
11007
11008 For "mouse" the value 'u' is unknown
11009
11010 Also see:
11011 - 'ambiwidth' - detected by using |t_u7|.
11012 - |v:termstyleresp| and |v:termblinkresp| for the response to
11013 |t_RS| and |t_RC|.
11014
11015
Bram Moolenaar54775062019-07-31 21:07:14 +020011016test_ functions are documented here: |test-functions-details|
Bram Moolenaar8e8df252016-05-25 21:23:21 +020011017
Bram Moolenaar574860b2016-05-24 17:33:34 +020011018
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020011019 *timer_info()*
11020timer_info([{id}])
11021 Return a list with information about timers.
11022 When {id} is given only information about this timer is
11023 returned. When timer {id} does not exist an empty list is
11024 returned.
11025 When {id} is omitted information about all timers is returned.
11026
Bram Moolenaare46a4402020-06-30 20:38:27 +020011027 For each timer the information is stored in a |Dictionary| with
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020011028 these items:
11029 "id" the timer ID
11030 "time" time the timer was started with
11031 "remaining" time until the timer fires
11032 "repeat" number of times the timer will still fire;
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011033 -1 means forever
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020011034 "callback" the callback
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011035 "paused" 1 if the timer is paused, 0 otherwise
11036
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011037 Can also be used as a |method|: >
11038 GetTimer()->timer_info()
11039
11040< {only available when compiled with the |+timers| feature}
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011041
11042timer_pause({timer}, {paused}) *timer_pause()*
11043 Pause or unpause a timer. A paused timer does not invoke its
Bram Moolenaardc1f1642016-08-16 18:33:43 +020011044 callback when its time expires. Unpausing a timer may cause
11045 the callback to be invoked almost immediately if enough time
11046 has passed.
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011047
11048 Pausing a timer is useful to avoid the callback to be called
11049 for a short time.
11050
11051 If {paused} evaluates to a non-zero Number or a non-empty
11052 String, then the timer is paused, otherwise it is unpaused.
11053 See |non-zero-arg|.
11054
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011055 Can also be used as a |method|: >
11056 GetTimer()->timer_pause(1)
11057
11058< {only available when compiled with the |+timers| feature}
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020011059
Bram Moolenaardc1f1642016-08-16 18:33:43 +020011060 *timer_start()* *timer* *timers*
Bram Moolenaar975b5272016-03-15 23:10:59 +010011061timer_start({time}, {callback} [, {options}])
11062 Create a timer and return the timer ID.
11063
11064 {time} is the waiting time in milliseconds. This is the
11065 minimum time before invoking the callback. When the system is
11066 busy or Vim is not waiting for input the time will be longer.
11067
11068 {callback} is the function to call. It can be the name of a
Bram Moolenaarf37506f2016-08-31 22:22:10 +020011069 function or a |Funcref|. It is called with one argument, which
Bram Moolenaar975b5272016-03-15 23:10:59 +010011070 is the timer ID. The callback is only invoked when Vim is
11071 waiting for input.
Bram Moolenaar4072ba52020-12-23 13:56:35 +010011072 If you want to show a message look at |popup_notification()|
Bram Moolenaar7e6a5152021-01-02 16:39:53 +010011073 to avoid interfering with what the user is doing.
Bram Moolenaar975b5272016-03-15 23:10:59 +010011074
11075 {options} is a dictionary. Supported entries:
11076 "repeat" Number of times to repeat calling the
Bram Moolenaarabd468e2016-09-08 22:22:43 +020011077 callback. -1 means forever. When not present
11078 the callback will be called once.
Bram Moolenaarc577d812017-07-08 22:37:34 +020011079 If the timer causes an error three times in a
11080 row the repeat is cancelled. This avoids that
11081 Vim becomes unusable because of all the error
11082 messages.
Bram Moolenaar975b5272016-03-15 23:10:59 +010011083
11084 Example: >
11085 func MyHandler(timer)
11086 echo 'Handler called'
11087 endfunc
11088 let timer = timer_start(500, 'MyHandler',
11089 \ {'repeat': 3})
11090< This will invoke MyHandler() three times at 500 msec
11091 intervals.
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011092
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011093 Can also be used as a |method|: >
11094 GetMsec()->timer_start(callback)
11095
11096< Not available in the |sandbox|.
Bram Moolenaar975b5272016-03-15 23:10:59 +010011097 {only available when compiled with the |+timers| feature}
11098
Bram Moolenaar03602ec2016-03-20 20:57:45 +010011099timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +020011100 Stop a timer. The timer callback will no longer be invoked.
11101 {timer} is an ID returned by timer_start(), thus it must be a
Bram Moolenaar8e97bd72016-08-06 22:05:07 +020011102 Number. If {timer} does not exist there is no error.
Bram Moolenaar03602ec2016-03-20 20:57:45 +010011103
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011104 Can also be used as a |method|: >
11105 GetTimer()->timer_stop()
11106
11107< {only available when compiled with the |+timers| feature}
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011108
11109timer_stopall() *timer_stopall()*
11110 Stop all timers. The timer callbacks will no longer be
Bram Moolenaar809ce4d2019-07-13 21:21:40 +020011111 invoked. Useful if a timer is misbehaving. If there are no
11112 timers there is no error.
Bram Moolenaarb73598e2016-08-07 18:22:53 +020011113
11114 {only available when compiled with the |+timers| feature}
11115
Bram Moolenaar071d4272004-06-13 20:20:40 +000011116tolower({expr}) *tolower()*
11117 The result is a copy of the String given, with all uppercase
11118 characters turned into lowercase (just like applying |gu| to
11119 the string).
11120
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011121 Can also be used as a |method|: >
11122 GetText()->tolower()
11123
Bram Moolenaar071d4272004-06-13 20:20:40 +000011124toupper({expr}) *toupper()*
11125 The result is a copy of the String given, with all lowercase
11126 characters turned into uppercase (just like applying |gU| to
11127 the string).
11128
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011129 Can also be used as a |method|: >
11130 GetText()->toupper()
11131
Bram Moolenaar8299df92004-07-10 09:47:34 +000011132tr({src}, {fromstr}, {tostr}) *tr()*
11133 The result is a copy of the {src} string with all characters
11134 which appear in {fromstr} replaced by the character in that
11135 position in the {tostr} string. Thus the first character in
11136 {fromstr} is translated into the first character in {tostr}
11137 and so on. Exactly like the unix "tr" command.
11138 This code also deals with multibyte characters properly.
11139
11140 Examples: >
11141 echo tr("hello there", "ht", "HT")
11142< returns "Hello THere" >
11143 echo tr("<blob>", "<>", "{}")
11144< returns "{blob}"
11145
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011146 Can also be used as a |method|: >
11147 GetText()->tr(from, to)
11148
Bram Moolenaar2245ae12020-05-31 22:20:36 +020011149trim({text} [, {mask} [, {dir}]]) *trim()*
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010011150 Return {text} as a String where any character in {mask} is
Bram Moolenaar2245ae12020-05-31 22:20:36 +020011151 removed from the beginning and/or end of {text}.
11152
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010011153 If {mask} is not given, {mask} is all characters up to 0x20,
11154 which includes Tab, space, NL and CR, plus the non-breaking
11155 space character 0xa0.
Bram Moolenaar2245ae12020-05-31 22:20:36 +020011156
11157 The optional {dir} argument specifies where to remove the
11158 characters:
11159 0 remove from the beginning and end of {text}
11160 1 remove only at the beginning of {text}
11161 2 remove only at the end of {text}
11162 When omitted both ends are trimmed.
11163
11164 This function deals with multibyte characters properly.
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010011165
11166 Examples: >
Bram Moolenaarab943432018-03-29 18:27:07 +020011167 echo trim(" some text ")
11168< returns "some text" >
11169 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010011170< returns "RESERVE_TAIL" >
Bram Moolenaarab943432018-03-29 18:27:07 +020011171 echo trim("rm<Xrm<>X>rrm", "rm<>")
Bram Moolenaar2245ae12020-05-31 22:20:36 +020011172< returns "Xrm<>X" (characters in the middle are not removed) >
11173 echo trim(" vim ", " ", 2)
11174< returns " vim"
Bram Moolenaar295ac5a2018-03-22 23:04:02 +010011175
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011176 Can also be used as a |method|: >
11177 GetText()->trim()
11178
Bram Moolenaar446cb832008-06-24 21:56:24 +000011179trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +000011180 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +000011181 equal to {expr} as a |Float| (truncate towards zero).
11182 {expr} must evaluate to a |Float| or a |Number|.
11183 Examples: >
11184 echo trunc(1.456)
11185< 1.0 >
11186 echo trunc(-5.456)
11187< -5.0 >
11188 echo trunc(4.0)
11189< 4.0
Bram Moolenaar93cf85f2019-08-17 21:36:28 +020011190
11191 Can also be used as a |method|: >
11192 Compute()->trunc()
11193<
Bram Moolenaar446cb832008-06-24 21:56:24 +000011194 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010011195
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011196 *type()*
Bram Moolenaardf48fb42016-07-22 21:50:18 +020011197type({expr}) The result is a Number representing the type of {expr}.
11198 Instead of using the number directly, it is better to use the
11199 v:t_ variable that has the value:
11200 Number: 0 |v:t_number|
11201 String: 1 |v:t_string|
11202 Funcref: 2 |v:t_func|
11203 List: 3 |v:t_list|
11204 Dictionary: 4 |v:t_dict|
11205 Float: 5 |v:t_float|
11206 Boolean: 6 |v:t_bool| (v:false and v:true)
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011207 None: 7 |v:t_none| (v:null and v:none)
11208 Job: 8 |v:t_job|
11209 Channel: 9 |v:t_channel|
11210 Blob: 10 |v:t_blob|
Bram Moolenaardf48fb42016-07-22 21:50:18 +020011211 For backward compatibility, this method can be used: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011212 :if type(myvar) == type(0)
11213 :if type(myvar) == type("")
11214 :if type(myvar) == type(function("tr"))
11215 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +000011216 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +000011217 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +010011218 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +010011219 :if type(myvar) == type(v:none)
Bram Moolenaardf48fb42016-07-22 21:50:18 +020011220< To check if the v:t_ variables exist use this: >
11221 :if exists('v:t_number')
Bram Moolenaar071d4272004-06-13 20:20:40 +000011222
Bram Moolenaarac92e252019-08-03 21:58:38 +020011223< Can also be used as a |method|: >
11224 mylist->type()
11225
Bram Moolenaara47e05f2021-01-12 21:49:00 +010011226
11227typename({expr}) *typename()*
11228 Return a string representation of the type of {expr}.
11229 Example: >
11230 echo typename([1, 2, 3])
11231 list<number>
11232
11233
Bram Moolenaara17d4c12010-05-30 18:30:36 +020011234undofile({name}) *undofile()*
11235 Return the name of the undo file that would be used for a file
11236 with name {name} when writing. This uses the 'undodir'
11237 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +020011238 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +020011239 {name} is always expanded to the full path, since that is what
11240 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +020011241 If {name} is empty undofile() returns an empty string, since a
11242 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +020011243 Useful in combination with |:wundo| and |:rundo|.
Bram Moolenaarb328cca2019-01-06 16:24:01 +010011244 When compiled without the |+persistent_undo| option this always
Bram Moolenaara17d4c12010-05-30 18:30:36 +020011245 returns an empty string.
11246
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011247 Can also be used as a |method|: >
11248 GetFilename()->undofile()
11249
Bram Moolenaara800b422010-06-27 01:15:55 +020011250undotree() *undotree()*
11251 Return the current state of the undo tree in a dictionary with
11252 the following items:
11253 "seq_last" The highest undo sequence number used.
11254 "seq_cur" The sequence number of the current position in
11255 the undo tree. This differs from "seq_last"
11256 when some changes were undone.
11257 "time_cur" Time last used for |:earlier| and related
11258 commands. Use |strftime()| to convert to
11259 something readable.
11260 "save_last" Number of the last file write. Zero when no
11261 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +020011262 "save_cur" Number of the current position in the undo
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010011263 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +020011264 "synced" Non-zero when the last undo block was synced.
11265 This happens when waiting from input from the
11266 user. See |undo-blocks|.
11267 "entries" A list of dictionaries with information about
11268 undo blocks.
11269
11270 The first item in the "entries" list is the oldest undo item.
Bram Moolenaare46a4402020-06-30 20:38:27 +020011271 Each List item is a |Dictionary| with these items:
Bram Moolenaara800b422010-06-27 01:15:55 +020011272 "seq" Undo sequence number. Same as what appears in
11273 |:undolist|.
11274 "time" Timestamp when the change happened. Use
11275 |strftime()| to convert to something readable.
11276 "newhead" Only appears in the item that is the last one
11277 that was added. This marks the last change
11278 and where further changes will be added.
11279 "curhead" Only appears in the item that is the last one
11280 that was undone. This marks the current
11281 position in the undo tree, the block that will
11282 be used by a redo command. When nothing was
11283 undone after the last change this item will
11284 not appear anywhere.
11285 "save" Only appears on the last block before a file
11286 write. The number is the write count. The
11287 first write has number 1, the last one the
11288 "save_last" mentioned above.
11289 "alt" Alternate entry. This is again a List of undo
11290 blocks. Each item may again have an "alt"
11291 item.
11292
Bram Moolenaar327aa022014-03-25 18:24:23 +010011293uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
11294 Remove second and succeeding copies of repeated adjacent
11295 {list} items in-place. Returns {list}. If you want a list
11296 to remain unmodified make a copy first: >
11297 :let newlist = uniq(copy(mylist))
11298< The default compare function uses the string representation of
11299 each item. For the use of {func} and {dict} see |sort()|.
11300
Bram Moolenaarac92e252019-08-03 21:58:38 +020011301 Can also be used as a |method|: >
11302 mylist->uniq()
11303
Bram Moolenaar677ee682005-01-27 14:41:15 +000011304values({dict}) *values()*
Bram Moolenaar58b85342016-08-14 19:54:54 +020011305 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +010011306 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaar677ee682005-01-27 14:41:15 +000011307
Bram Moolenaarac92e252019-08-03 21:58:38 +020011308 Can also be used as a |method|: >
11309 mydict->values()
Bram Moolenaar677ee682005-01-27 14:41:15 +000011310
Bram Moolenaar071d4272004-06-13 20:20:40 +000011311virtcol({expr}) *virtcol()*
11312 The result is a Number, which is the screen column of the file
11313 position given with {expr}. That is, the last screen position
11314 occupied by the character at that position, when the screen
11315 would be of unlimited width. When there is a <Tab> at the
11316 position, the returned Number will be the column at the end of
11317 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +020011318 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +000011319 For the byte position use |col()|.
11320 For the use of {expr} see |col()|.
11321 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +000011322 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +000011323 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +020011324 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011325 When Virtual editing is active in the current mode, a position
11326 beyond the end of the line can be returned. |'virtualedit'|
11327 The accepted positions are:
11328 . the cursor position
11329 $ the end of the cursor line (the result is the
11330 number of displayed characters in the cursor line
11331 plus one)
11332 'x position of mark x (if the mark is not set, 0 is
11333 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +010011334 v In Visual mode: the start of the Visual area (the
11335 cursor is the end). When not in Visual mode
11336 returns the cursor position. Differs from |'<| in
11337 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011338 Note that only marks in the current file can be used.
11339 Examples: >
11340 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
11341 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +000011342 virtcol("'t") with text " there", with 't at 'h', returns 6
Bram Moolenaar58b85342016-08-14 19:54:54 +020011343< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011344 A more advanced example that echoes the maximum length of
11345 all lines: >
11346 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
11347
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011348< Can also be used as a |method|: >
11349 GetPos()->virtcol()
Bram Moolenaar071d4272004-06-13 20:20:40 +000011350
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011351
11352visualmode([{expr}]) *visualmode()*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011353 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000011354 used in the current buffer. Initially it returns an empty
11355 string, but once Visual mode has been used, it returns "v",
11356 "V", or "<CTRL-V>" (a single CTRL-V character) for
11357 character-wise, line-wise, or block-wise Visual mode
11358 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011359 Example: >
11360 :exe "normal " . visualmode()
11361< This enters the same Visual mode as before. It is also useful
11362 in scripts if you wish to act differently depending on the
11363 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011364 If Visual mode is active, use |mode()| to get the Visual mode
11365 (e.g., in a |:vmap|).
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011366 If {expr} is supplied and it evaluates to a non-zero Number or
Bram Moolenaar05bb9532008-07-04 09:44:11 +000011367 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaare381d3d2016-07-07 14:50:41 +020011368 the old value is returned. See |non-zero-arg|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011369
Bram Moolenaar8738fc12013-02-20 17:59:11 +010011370wildmenumode() *wildmenumode()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +020011371 Returns |TRUE| when the wildmenu is active and |FALSE|
Bram Moolenaar8738fc12013-02-20 17:59:11 +010011372 otherwise. See 'wildmenu' and 'wildmode'.
11373 This can be used in mappings to handle the 'wildcharm' option
11374 gracefully. (Makes only sense with |mapmode-c| mappings).
11375
11376 For example to make <c-j> work like <down> in wildmode, use: >
11377 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
11378<
11379 (Note, this needs the 'wildcharm' option set appropriately).
11380
Bram Moolenaar868b7b62019-05-29 21:44:40 +020011381win_execute({id}, {command} [, {silent}]) *win_execute()*
11382 Like `execute()` but in the context of window {id}.
11383 The window will temporarily be made the current window,
Bram Moolenaarb4230122019-05-30 18:40:53 +020011384 without triggering autocommands. When executing {command}
11385 autocommands will be triggered, this may have unexpected side
11386 effects. Use |:noautocmd| if needed.
Bram Moolenaar868b7b62019-05-29 21:44:40 +020011387 Example: >
Bram Moolenaarb4230122019-05-30 18:40:53 +020011388 call win_execute(winid, 'set syntax=python')
11389< Doing the same with `setwinvar()` would not trigger
11390 autocommands and not actually show syntax highlighting.
Bram Moolenaarc423ad72021-01-13 20:38:03 +010011391
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020011392 *E994*
11393 Not all commands are allowed in popup windows.
Bram Moolenaarc423ad72021-01-13 20:38:03 +010011394 When window {id} does not exist then no error is given and
11395 an empty string is returned.
Bram Moolenaar8738fc12013-02-20 17:59:11 +010011396
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011397 Can also be used as a |method|, the base is passed as the
11398 second argument: >
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011399 GetCommand()->win_execute(winid)
11400
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010011401win_findbuf({bufnr}) *win_findbuf()*
Bram Moolenaar1b884a02020-12-10 21:11:27 +010011402 Returns a |List| with |window-ID|s for windows that contain
Bram Moolenaar7571d552016-08-18 22:54:46 +020011403 buffer {bufnr}. When there is none the list is empty.
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +010011404
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011405 Can also be used as a |method|: >
11406 GetBufnr()->win_findbuf()
11407
Bram Moolenaar86edef62016-03-13 18:07:30 +010011408win_getid([{win} [, {tab}]]) *win_getid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +020011409 Get the |window-ID| for the specified window.
Bram Moolenaar86edef62016-03-13 18:07:30 +010011410 When {win} is missing use the current window.
11411 With {win} this is the window number. The top window has
Bram Moolenaarba3ff532018-11-04 14:45:49 +010011412 number 1.
Bram Moolenaar86edef62016-03-13 18:07:30 +010011413 Without {tab} use the current tab, otherwise the tab with
11414 number {tab}. The first tab has number one.
11415 Return zero if the window cannot be found.
11416
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011417 Can also be used as a |method|: >
11418 GetWinnr()->win_getid()
11419
Bram Moolenaar00f3b4e2020-02-14 14:32:22 +010011420
11421win_gettype([{nr}]) *win_gettype()*
11422 Return the type of the window:
Bram Moolenaar40a019f2020-06-17 21:41:35 +020011423 "autocmd" autocommand window. Temporary window
Bram Moolenaar0fe937f2020-06-16 22:42:04 +020011424 used to execute autocommands.
Bram Moolenaar00f3b4e2020-02-14 14:32:22 +010011425 "popup" popup window |popup|
Bram Moolenaar0fe937f2020-06-16 22:42:04 +020011426 "preview" preview window |preview-window|
Bram Moolenaar00f3b4e2020-02-14 14:32:22 +010011427 "command" command-line window |cmdwin|
11428 (empty) normal window
11429 "unknown" window {nr} not found
11430
11431 When {nr} is omitted return the type of the current window.
11432 When {nr} is given return the type of this window by number or
11433 |window-ID|.
11434
11435 Also see the 'buftype' option. When running a terminal in a
11436 popup window then 'buftype' is "terminal" and win_gettype()
11437 returns "popup".
11438
11439
Bram Moolenaar86edef62016-03-13 18:07:30 +010011440win_gotoid({expr}) *win_gotoid()*
11441 Go to window with ID {expr}. This may also change the current
11442 tabpage.
Bram Moolenaar98a29d02021-01-18 19:55:44 +010011443 Return TRUE if successful, FALSE if the window cannot be found.
Bram Moolenaar86edef62016-03-13 18:07:30 +010011444
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011445 Can also be used as a |method|: >
11446 GetWinid()->win_gotoid()
11447
Bram Moolenaar03413f42016-04-12 21:07:15 +020011448win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +010011449 Return a list with the tab number and window number of window
11450 with ID {expr}: [tabnr, winnr].
11451 Return [0, 0] if the window cannot be found.
11452
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011453 Can also be used as a |method|: >
11454 GetWinid()->win_id2tabwin()
11455
Bram Moolenaar86edef62016-03-13 18:07:30 +010011456win_id2win({expr}) *win_id2win()*
11457 Return the window number of window with ID {expr}.
11458 Return 0 if the window cannot be found in the current tabpage.
11459
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011460 Can also be used as a |method|: >
11461 GetWinid()->win_id2win()
11462
Bram Moolenaar22044dc2017-12-02 15:43:37 +010011463win_screenpos({nr}) *win_screenpos()*
11464 Return the screen position of window {nr} as a list with two
11465 numbers: [row, col]. The first window always has position
Bram Moolenaar7132ddc2018-07-15 17:01:11 +020011466 [1, 1], unless there is a tabline, then it is [2, 1].
Bram Moolenaar1c6737b2020-09-07 22:18:52 +020011467 {nr} can be the window number or the |window-ID|. Use zero
11468 for the current window.
Bram Moolenaar22044dc2017-12-02 15:43:37 +010011469 Return [0, 0] if the window cannot be found in the current
11470 tabpage.
11471
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011472 Can also be used as a |method|: >
11473 GetWinid()->win_screenpos()
11474<
Bram Moolenaard20dcb32019-09-10 21:22:58 +020011475win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Bram Moolenaar73fef332020-06-21 22:12:03 +020011476 Move the window {nr} to a new split of the window {target}.
Bram Moolenaard20dcb32019-09-10 21:22:58 +020011477 This is similar to moving to {target}, creating a new window
11478 using |:split| but having the same contents as window {nr}, and
11479 then closing {nr}.
11480
11481 Both {nr} and {target} can be window numbers or |window-ID|s.
Bram Moolenaar29634562020-01-09 21:46:04 +010011482 Both must be in the current tab page.
Bram Moolenaard20dcb32019-09-10 21:22:58 +020011483
11484 Returns zero for success, non-zero for failure.
11485
Bram Moolenaare46a4402020-06-30 20:38:27 +020011486 {options} is a |Dictionary| with the following optional entries:
Bram Moolenaard20dcb32019-09-10 21:22:58 +020011487 "vertical" When TRUE, the split is created vertically,
11488 like with |:vsplit|.
11489 "rightbelow" When TRUE, the split is made below or to the
11490 right (if vertical). When FALSE, it is done
11491 above or to the left (if vertical). When not
11492 present, the values of 'splitbelow' and
11493 'splitright' are used.
11494
11495 Can also be used as a |method|: >
11496 GetWinid()->win_splitmove(target)
11497<
Bram Moolenaar4132eb52020-02-14 16:53:00 +010011498
Bram Moolenaar071d4272004-06-13 20:20:40 +000011499 *winbufnr()*
11500winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +020011501 associated with window {nr}. {nr} can be the window number or
Bram Moolenaar7571d552016-08-18 22:54:46 +020011502 the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +020011503 When {nr} is zero, the number of the buffer in the current
11504 window is returned.
11505 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011506 Example: >
11507 :echo "The file in the current window is " . bufname(winbufnr(0))
11508<
Bram Moolenaare49fbff2019-08-21 22:50:07 +020011509 Can also be used as a |method|: >
11510 FindWindow()->winbufnr()->bufname()
11511<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011512 *wincol()*
11513wincol() The result is a Number, which is the virtual column of the
11514 cursor in the window. This is counting screen cells from the
11515 left side of the window. The leftmost column is one.
11516
Bram Moolenaar0c1e3742019-12-27 13:49:24 +010011517 *windowsversion()*
11518windowsversion()
11519 The result is a String. For MS-Windows it indicates the OS
11520 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
11521 Windows XP is "5.1". For non-MS-Windows systems the result is
11522 an empty string.
11523
Bram Moolenaar071d4272004-06-13 20:20:40 +000011524winheight({nr}) *winheight()*
11525 The result is a Number, which is the height of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020011526 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011527 When {nr} is zero, the height of the current window is
11528 returned. When window {nr} doesn't exist, -1 is returned.
11529 An existing window always has a height of zero or more.
Bram Moolenaar37c64c72017-09-19 22:06:03 +020011530 This excludes any window toolbar line.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011531 Examples: >
11532 :echo "The current window has " . winheight(0) . " lines."
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011533
11534< Can also be used as a |method|: >
11535 GetWinid()->winheight()
Bram Moolenaar071d4272004-06-13 20:20:40 +000011536<
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +020011537winlayout([{tabnr}]) *winlayout()*
11538 The result is a nested List containing the layout of windows
11539 in a tabpage.
11540
11541 Without {tabnr} use the current tabpage, otherwise the tabpage
11542 with number {tabnr}. If the tabpage {tabnr} is not found,
11543 returns an empty list.
11544
11545 For a leaf window, it returns:
11546 ['leaf', {winid}]
11547 For horizontally split windows, which form a column, it
11548 returns:
11549 ['col', [{nested list of windows}]]
11550 For vertically split windows, which form a row, it returns:
11551 ['row', [{nested list of windows}]]
11552
11553 Example: >
11554 " Only one window in the tab page
11555 :echo winlayout()
11556 ['leaf', 1000]
11557 " Two horizontally split windows
11558 :echo winlayout()
11559 ['col', [['leaf', 1000], ['leaf', 1001]]]
Bram Moolenaarb17893a2020-03-14 08:19:51 +010011560 " The second tab page, with three horizontally split
11561 " windows, with two vertically split windows in the
11562 " middle window
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +020011563 :echo winlayout(2)
Bram Moolenaarb17893a2020-03-14 08:19:51 +010011564 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
11565 ['leaf', 1001]]], ['leaf', 1000]]]
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +020011566<
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011567 Can also be used as a |method|: >
11568 GetTabnr()->winlayout()
11569<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011570 *winline()*
11571winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar58b85342016-08-14 19:54:54 +020011572 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +000011573 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +000011574 If the cursor was moved the view on the file will be updated
11575 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011576
11577 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000011578winnr([{arg}]) The result is a Number, which is the number of the current
11579 window. The top window has number 1.
Bram Moolenaar560979e2020-02-04 22:53:05 +010011580 Returns zero for a popup window.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020011581
11582 The optional argument {arg} supports the following values:
11583 $ the number of the last window (the window
11584 count).
11585 # the number of the last accessed window (where
11586 |CTRL-W_p| goes to). If there is no previous
11587 window or it is in another tab page 0 is
11588 returned.
11589 {N}j the number of the Nth window below the
11590 current window (where |CTRL-W_j| goes to).
11591 {N}k the number of the Nth window above the current
11592 window (where |CTRL-W_k| goes to).
11593 {N}h the number of the Nth window left of the
11594 current window (where |CTRL-W_h| goes to).
11595 {N}l the number of the Nth window right of the
11596 current window (where |CTRL-W_l| goes to).
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000011597 The number can be used with |CTRL-W_w| and ":wincmd w"
11598 |:wincmd|.
Bram Moolenaar690afe12017-01-28 18:34:47 +010011599 Also see |tabpagewinnr()| and |win_getid()|.
Bram Moolenaar46ad2882019-04-08 20:01:47 +020011600 Examples: >
11601 let window_count = winnr('$')
11602 let prev_window = winnr('#')
11603 let wnum = winnr('3k')
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011604
11605< Can also be used as a |method|: >
11606 GetWinval()->winnr()
Bram Moolenaar46ad2882019-04-08 20:01:47 +020011607<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011608 *winrestcmd()*
11609winrestcmd() Returns a sequence of |:resize| commands that should restore
11610 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011611 are opened or closed and the current window and tab page is
11612 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011613 Example: >
11614 :let cmd = winrestcmd()
11615 :call MessWithWindowSizes()
11616 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011617<
11618 *winrestview()*
11619winrestview({dict})
11620 Uses the |Dictionary| returned by |winsaveview()| to restore
11621 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +020011622 Note: The {dict} does not have to contain all values, that are
11623 returned by |winsaveview()|. If values are missing, those
11624 settings won't be restored. So you can use: >
11625 :call winrestview({'curswant': 4})
11626<
11627 This will only set the curswant value (the column the cursor
11628 wants to move on vertical movements) of the cursor to column 5
11629 (yes, that is 5), while all other settings will remain the
11630 same. This is useful, if you set the cursor position manually.
11631
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011632 If you have changed the values the result is unpredictable.
11633 If the window size changed the result won't be the same.
11634
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011635 Can also be used as a |method|: >
11636 GetView()->winrestview()
11637<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011638 *winsaveview()*
11639winsaveview() Returns a |Dictionary| that contains information to restore
11640 the view of the current window. Use |winrestview()| to
11641 restore the view.
11642 This is useful if you have a mapping that jumps around in the
11643 buffer and you want to go back to the original view.
11644 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +000011645 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +020011646 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011647 The return value includes:
11648 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +020011649 col cursor column (Note: the first column
11650 zero, as opposed to what getpos()
11651 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011652 coladd cursor column offset for 'virtualedit'
11653 curswant column for vertical movement
11654 topline first line in the window
11655 topfill filler lines, only in diff mode
Bram Moolenaarcb80aa22020-10-26 21:12:46 +010011656 leftcol first column displayed; only used when
11657 'wrap' is off
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000011658 skipcol columns skipped
11659 Note that no option values are saved.
11660
Bram Moolenaar071d4272004-06-13 20:20:40 +000011661
11662winwidth({nr}) *winwidth()*
11663 The result is a Number, which is the width of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020011664 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011665 When {nr} is zero, the width of the current window is
11666 returned. When window {nr} doesn't exist, -1 is returned.
11667 An existing window always has a width of zero or more.
11668 Examples: >
11669 :echo "The current window has " . winwidth(0) . " columns."
11670 :if winwidth(0) <= 50
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010011671 : 50 wincmd |
Bram Moolenaar071d4272004-06-13 20:20:40 +000011672 :endif
Bram Moolenaarf8be4612017-06-23 20:52:40 +020011673< For getting the terminal or screen size, see the 'columns'
11674 option.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020011675
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011676 Can also be used as a |method|: >
11677 GetWinid()->winwidth()
11678
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020011679
Bram Moolenaared767a22016-01-03 22:49:16 +010011680wordcount() *wordcount()*
11681 The result is a dictionary of byte/chars/word statistics for
11682 the current buffer. This is the same info as provided by
11683 |g_CTRL-G|
11684 The return value includes:
11685 bytes Number of bytes in the buffer
11686 chars Number of chars in the buffer
11687 words Number of words in the buffer
11688 cursor_bytes Number of bytes before cursor position
11689 (not in Visual mode)
11690 cursor_chars Number of chars before cursor position
11691 (not in Visual mode)
11692 cursor_words Number of words before cursor position
11693 (not in Visual mode)
11694 visual_bytes Number of bytes visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020011695 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010011696 visual_chars Number of chars visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020011697 (only in Visual mode)
Bram Moolenaarc572da52017-08-27 16:52:01 +020011698 visual_words Number of words visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020011699 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010011700
11701
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000011702 *writefile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010011703writefile({object}, {fname} [, {flags}])
11704 When {object} is a |List| write it to file {fname}. Each list
11705 item is separated with a NL. Each list item must be a String
11706 or Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010011707 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000011708 not be a NL after the last list item. An empty item at the
11709 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010011710
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010011711 When {object} is a |Blob| write the bytes to file {fname}
11712 unmodified.
11713
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010011714 When {flags} contains "a" then append mode is used, lines are
Bram Moolenaar46fceaa2016-10-23 21:21:08 +020011715 appended to the file: >
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010011716 :call writefile(["foo"], "event.log", "a")
11717 :call writefile(["bar"], "event.log", "a")
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010011718<
11719 When {flags} contains "s" then fsync() is called after writing
11720 the file. This flushes the file to disk, if possible. This
11721 takes more time but avoids losing the file if the system
11722 crashes.
Bram Moolenaar74240d32017-12-10 15:26:15 +010011723 When {flags} does not contain "S" or "s" then fsync() is
11724 called if the 'fsync' option is set.
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010011725 When {flags} contains "S" then fsync() is not called, even
11726 when 'fsync' is set.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010011727
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010011728 All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000011729 Inserting CR characters needs to be done before passing {list}
11730 to writefile().
11731 An existing file is overwritten, if possible.
11732 When the write fails -1 is returned, otherwise 0. There is an
11733 error message if the file can't be created or when writing
11734 fails.
11735 Also see |readfile()|.
11736 To copy a file byte for byte: >
11737 :let fl = readfile("foo", "b")
11738 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +010011739
Bram Moolenaarf92e58c2019-09-08 21:51:41 +020011740< Can also be used as a |method|: >
11741 GetText()->writefile("thefile")
11742
Bram Moolenaard6e256c2011-12-14 15:32:50 +010011743
11744xor({expr}, {expr}) *xor()*
11745 Bitwise XOR on the two arguments. The arguments are converted
11746 to a number. A List, Dict or Float argument causes an error.
11747 Example: >
11748 :let bits = xor(bits, 0x80)
Bram Moolenaar2e693a82019-10-16 22:35:02 +020011749<
11750 Can also be used as a |method|: >
Bram Moolenaar073e4b92019-08-18 23:01:56 +020011751 :let bits = bits->xor(0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +010011752<
Bram Moolenaard6e256c2011-12-14 15:32:50 +010011753
Bram Moolenaar071d4272004-06-13 20:20:40 +000011754 *feature-list*
Bram Moolenaarade0d392020-01-21 22:33:58 +010011755There are three types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000117561. Features that are only supported when they have been enabled when Vim
11757 was compiled |+feature-list|. Example: >
11758 :if has("cindent")
117592. Features that are only supported when certain conditions have been met.
11760 Example: >
11761 :if has("gui_running")
11762< *has-patch*
Bram Moolenaar2f018892018-05-18 18:12:06 +0200117633. Beyond a certain version or at a certain version and including a specific
11764 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
11765 later, or it is version 7.4 and patch 248 was included. Example: >
Bram Moolenaarbcb98982014-05-01 14:08:19 +020011766 :if has("patch-7.4.248")
Bram Moolenaar2f018892018-05-18 18:12:06 +020011767< Note that it's possible for patch 248 to be omitted even though 249 is
11768 included. Only happens when cherry-picking patches.
11769 Note that this form only works for patch 7.4.237 and later, before that
11770 you need to check for the patch and the v:version. Example (checking
11771 version 6.2.148 or later): >
11772 :if v:version > 602 || (v:version == 602 && has("patch148"))
Bram Moolenaar071d4272004-06-13 20:20:40 +000011773
Bram Moolenaard823fa92016-08-12 16:29:27 +020011774Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
11775use: `if exists('+shellslash')`
11776
11777
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020011778acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011779all_builtin_terms Compiled with all builtin terminals enabled.
11780amiga Amiga version of Vim.
11781arabic Compiled with Arabic support |Arabic|.
11782arp Compiled with ARP support (Amiga).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011783autocmd Compiled with autocommand support. (always true)
Bram Moolenaar91f84f62018-07-29 15:07:52 +020011784autochdir Compiled with support for 'autochdir'
Bram Moolenaare42a6d22017-11-12 19:21:51 +010011785autoservername Automatically enable |clientserver|
Bram Moolenaar071d4272004-06-13 20:20:40 +000011786balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +000011787balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011788beos BeOS version of Vim.
11789browse Compiled with |:browse| support, and browse() will
11790 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +020011791browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011792bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar071d4272004-06-13 20:20:40 +000011793builtin_terms Compiled with some builtin terminals.
11794byte_offset Compiled with support for 'o' in 'statusline'
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +010011795channel Compiled with support for |channel| and |job|
Bram Moolenaar071d4272004-06-13 20:20:40 +000011796cindent Compiled with 'cindent' support.
11797clientserver Compiled with remote invocation support |clientserver|.
11798clipboard Compiled with 'clipboard' support.
Bram Moolenaar4999a7f2019-08-10 22:21:48 +020011799clipboard_working Compiled with 'clipboard' support and it can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011800cmdline_compl Compiled with |cmdline-completion| support.
11801cmdline_hist Compiled with |cmdline-history| support.
11802cmdline_info Compiled with 'showcmd' and 'ruler' support.
11803comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011804compatible Compiled to be very Vi compatible.
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +010011805conpty Platform where |ConPTY| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011806cryptv Compiled with encryption support |encryption|.
11807cscope Compiled with |cscope| support.
Bram Moolenaar314dd792019-02-03 15:27:20 +010011808cursorbind Compiled with |'cursorbind'| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011809debug Compiled with "DEBUG" defined.
11810dialog_con Compiled with console dialog support.
11811dialog_gui Compiled with GUI dialog support.
11812diff Compiled with |vimdiff| and 'diff' support.
11813digraphs Compiled with support for digraphs.
Bram Moolenaar58b85342016-08-14 19:54:54 +020011814directx Compiled with support for DirectX and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011815dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011816ebcdic Compiled on a machine with ebcdic character set.
11817emacs_tags Compiled with support for Emacs tags.
11818eval Compiled with expression evaluation support. Always
11819 true, of course!
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011820ex_extra |+ex_extra| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011821extra_search Compiled with support for |'incsearch'| and
11822 |'hlsearch'|
Bram Moolenaar4ceaa3a2019-12-03 22:49:09 +010011823farsi Support for Farsi was removed |farsi|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011824file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +000011825filterpipe When 'shelltemp' is off pipes are used for shell
11826 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000011827find_in_path Compiled with support for include file searches
11828 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011829float Compiled with support for |Float|.
Bram Moolenaar5666fcd2019-12-26 14:35:26 +010011830fname_case Case in file names matters (for Amiga and MS-Windows
11831 this is not present).
Bram Moolenaar071d4272004-06-13 20:20:40 +000011832folding Compiled with |folding| support.
11833footer Compiled with GUI footer support. |gui-footer|
11834fork Compiled to use fork()/exec() instead of system().
11835gettext Compiled with message translation |multi-lang|
11836gui Compiled with GUI enabled.
11837gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011838gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000011839gui_gtk Compiled with GTK+ GUI (any version).
11840gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +010011841gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaarb3f74062020-02-26 16:16:53 +010011842gui_haiku Compiled with Haiku GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011843gui_mac Compiled with Macintosh GUI.
11844gui_motif Compiled with Motif GUI.
11845gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011846gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011847gui_win32 Compiled with MS Windows Win32 GUI.
11848gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaarb3f74062020-02-26 16:16:53 +010011849haiku Haiku version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011850hangul_input Compiled with Hangul input support. |hangul|
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011851hpux HP-UX version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011852iconv Can use iconv() for conversion.
11853insert_expand Compiled with support for CTRL-X expansion commands in
Bram Moolenaare49fbff2019-08-21 22:50:07 +020011854 Insert mode. (always true)
Bram Moolenaard1caa942020-04-10 22:10:56 +020011855job Compiled with support for |channel| and |job|
Bram Moolenaar352f5542020-04-13 19:04:21 +020011856ipv6 Compiled with support for IPv6 networking in |channel|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011857jumplist Compiled with |jumplist| support.
11858keymap Compiled with 'keymap' support.
Bram Moolenaar437bafe2016-08-01 15:40:54 +020011859lambda Compiled with |lambda| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011860langmap Compiled with 'langmap' support.
11861libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +020011862linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
11863 'breakindent' support.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011864linux Linux version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011865lispindent Compiled with support for lisp indenting.
11866listcmds Compiled with commands for the buffer list |:files|
11867 and the argument list |arglist|.
11868localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +020011869lua Compiled with Lua interface |Lua|.
Bram Moolenaard0573012017-10-28 21:11:06 +020011870mac Any Macintosh version of Vim cf. osx
11871macunix Synonym for osxdarwin
Bram Moolenaar071d4272004-06-13 20:20:40 +000011872menu Compiled with support for |:menu|.
11873mksession Compiled with support for |:mksession|.
11874modify_fname Compiled with file name modifiers. |filename-modifiers|
Bram Moolenaara0d1fef2019-09-04 22:29:14 +020011875 (always true)
Bram Moolenaar3132cdd2020-11-05 20:41:49 +010011876mouse Compiled with support for mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011877mouse_dec Compiled with support for Dec terminal mouse.
11878mouse_gpm Compiled with support for gpm (Linux console mouse)
Bram Moolenaar4b8366b2019-05-04 17:34:34 +020011879mouse_gpm_enabled GPM mouse is working
Bram Moolenaar071d4272004-06-13 20:20:40 +000011880mouse_netterm Compiled with support for netterm mouse.
11881mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +000011882mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +020011883mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +010011884mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011885mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011886mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar4c92e752019-02-17 21:18:32 +010011887multi_byte Compiled with support for 'encoding' (always true)
Bram Moolenaar207f0092020-08-30 17:20:20 +020011888multi_byte_encoding 'encoding' is set to a multibyte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011889multi_byte_ime Compiled with support for IME input method.
11890multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000011891mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +020011892netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011893netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020011894num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011895ole Compiled with OLE automation support for Win32.
Bram Moolenaard0573012017-10-28 21:11:06 +020011896osx Compiled for macOS cf. mac
11897osxdarwin Compiled for macOS, with |mac-darwin-feature|
Bram Moolenaar91c49372016-05-08 09:50:29 +020011898packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011899path_extra Compiled with up/downwards search in 'path' and 'tags'
11900perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +020011901persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011902postscript Compiled with PostScript file printing.
11903printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +000011904profile Compiled with |:profile| support.
Bram Moolenaar84b242c2018-01-28 17:45:49 +010011905python Python 2.x interface available. |has-python|
11906python_compiled Compiled with Python 2.x interface. |has-python|
11907python_dynamic Python 2.x interface is dynamically loaded. |has-python|
11908python3 Python 3.x interface available. |has-python|
11909python3_compiled Compiled with Python 3.x interface. |has-python|
11910python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +010011911pythonx Python 2.x and/or 3.x interface available. |python_x|
Bram Moolenaar071d4272004-06-13 20:20:40 +000011912qnx QNX version of Vim.
11913quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +000011914reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011915rightleft Compiled with 'rightleft' support.
11916ruby Compiled with Ruby interface |ruby|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011917scrollbind Compiled with 'scrollbind' support. (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011918showcmd Compiled with 'showcmd' support.
11919signs Compiled with |:sign| support.
11920smartindent Compiled with 'smartindent' support.
Bram Moolenaar427f5b62019-06-09 13:43:51 +020011921sound Compiled with sound support, e.g. `sound_playevent()`
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011922spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +000011923startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011924statusline Compiled with support for 'statusline', 'rulerformat'
11925 and special formats of 'titlestring' and 'iconstring'.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011926sun SunOS version of Vim.
Bram Moolenaard09091d2019-01-17 16:07:22 +010011927sun_workshop Support for Sun |workshop| has been removed.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +000011928syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011929syntax_items There are active syntax highlighting items for the
11930 current buffer.
11931system Compiled to use system() instead of fork()/exec().
11932tag_binary Compiled with binary searching in tags files
11933 |tag-binary-search|.
Bram Moolenaar723dd942019-04-04 13:11:03 +020011934tag_old_static Support for old static tags was removed, see
Bram Moolenaar071d4272004-06-13 20:20:40 +000011935 |tag-old-static|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011936tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +020011937termguicolors Compiled with true color in terminal support.
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +020011938terminal Compiled with |terminal| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011939terminfo Compiled with terminfo instead of termcap.
11940termresponse Compiled with support for |t_RV| and |v:termresponse|.
11941textobjects Compiled with support for |text-objects|.
Bram Moolenaar98aefe72018-12-13 22:20:09 +010011942textprop Compiled with support for |text-properties|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011943tgetent Compiled with tgetent support, able to use a termcap
11944 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +010011945timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011946title Compiled with window title support |'title'|.
11947toolbar Compiled with support for |gui-toolbar|.
Bram Moolenaar2cab0e12016-11-24 15:09:07 +010011948ttyin input is a terminal (tty)
11949ttyout output is a terminal (tty)
Bram Moolenaar37c64c72017-09-19 22:06:03 +020011950unix Unix version of Vim. *+unix*
Bram Moolenaar3df01732017-02-17 22:47:16 +010011951unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
Bram Moolenaarac9fb182019-04-27 13:04:13 +020011952user_commands User-defined commands. (always true)
Bram Moolenaar4ceaa3a2019-12-03 22:49:09 +010011953vartabs Compiled with variable tabstop support |'vartabstop'|.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010011954vcon Win32: Virtual console support is working, can use
11955 'termguicolors'. Also see |+vtp|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011956vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011957 (always true)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011958vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010011959 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011960viminfo Compiled with viminfo support.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020011961vimscript-1 Compiled Vim script version 1 support
11962vimscript-2 Compiled Vim script version 2 support
Bram Moolenaar911ead12019-04-21 00:03:35 +020011963vimscript-3 Compiled Vim script version 3 support
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011964virtualedit Compiled with 'virtualedit' option. (always true)
Bram Moolenaar5b69c222019-01-11 14:50:06 +010011965visual Compiled with Visual mode. (always true)
11966visualextra Compiled with extra Visual mode commands. (always
11967 true) |blockwise-operators|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011968vms VMS version of Vim.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011969vreplace Compiled with |gR| and |gr| commands. (always true)
Bram Moolenaar98ef2332018-03-18 14:44:37 +010011970vtp Compiled for vcon support |+vtp| (check vcon to find
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +010011971 out if it works in the current console).
Bram Moolenaar071d4272004-06-13 20:20:40 +000011972wildignore Compiled with 'wildignore' option.
11973wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011974win16 old version for MS-Windows 3.1 (always false)
Bram Moolenaard58e9292011-02-09 17:07:58 +010011975win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
11976 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011977win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011978win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011979win95 Win32 version for MS-Windows 95/98/ME (always false)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010011980winaltkeys Compiled with 'winaltkeys' option.
11981windows Compiled with support for more than one window.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010011982 (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011983writebackup Compiled with 'writebackup' default on.
11984xfontset Compiled with X fontset support |xfontset|.
11985xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020011986xpm Compiled with pixmap support.
11987xpm_w32 Compiled with pixmap support for Win32. (Only for
11988 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +000011989xsmp Compiled with X session management support.
11990xsmp_interact Compiled with interactive X session management support.
11991xterm_clipboard Compiled with support for xterm clipboard.
11992xterm_save Compiled with support for saving and restoring the
11993 xterm screen.
11994x11 Compiled with X11 support.
11995
11996 *string-match*
11997Matching a pattern in a String
11998
11999A regexp pattern as explained at |pattern| is normally used to find a match in
12000the buffer lines. When a pattern is used to find a match in a String, almost
12001everything works in the same way. The difference is that a String is handled
12002like it is one line. When it contains a "\n" character, this is not seen as a
12003line break for the pattern. It can be matched with a "\n" in the pattern, or
12004with ".". Example: >
12005 :let a = "aaaa\nxxxx"
12006 :echo matchstr(a, "..\n..")
12007 aa
12008 xx
12009 :echo matchstr(a, "a.x")
12010 a
12011 x
12012
12013Don't forget that "^" will only match at the first character of the String and
12014"$" at the last character of the string. They don't match after or before a
12015"\n".
12016
12017==============================================================================
120185. Defining functions *user-functions*
12019
12020New functions can be defined. These can be called just like builtin
12021functions. The function executes a sequence of Ex commands. Normal mode
12022commands can be executed with the |:normal| command.
12023
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010012024This section is about the legacy functions. For the Vim9 functions, which
12025execute much faster, support type checking and more, see |vim9.txt|.
12026
Bram Moolenaar071d4272004-06-13 20:20:40 +000012027The function name must start with an uppercase letter, to avoid confusion with
12028builtin functions. To prevent from using the same name in different scripts
12029avoid obvious, short names. A good habit is to start the function name with
12030the name of the script, e.g., "HTMLcolor()".
12031
Bram Moolenaar92d640f2005-09-05 22:11:52 +000012032It's also possible to use curly braces, see |curly-braces-names|. And the
12033|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012034
12035 *local-function*
12036A function local to a script must start with "s:". A local script function
12037can only be called from within the script and from functions, user commands
12038and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +000012039function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +000012040instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +020012041There are only script-local functions, no buffer-local or window-local
12042functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012043
12044 *:fu* *:function* *E128* *E129* *E123*
12045:fu[nction] List all functions and their arguments.
12046
12047:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012048 {name} can also be a |Dictionary| entry that is a
12049 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012050 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +000012051
12052:fu[nction] /{pattern} List functions with a name matching {pattern}.
12053 Example that lists all functions ending with "File": >
12054 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000012055<
12056 *:function-verbose*
12057When 'verbose' is non-zero, listing a function will also display where it was
12058last defined. Example: >
12059
12060 :verbose function SetFileTypeSH
12061 function SetFileTypeSH(name)
12062 Last set from /usr/share/vim/vim-7.0/filetype.vim
12063<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +000012064See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000012065
Bram Moolenaarbcb98982014-05-01 14:08:19 +020012066 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020012067:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +010012068 Define a new function by the name {name}. The body of
12069 the function follows in the next lines, until the
12070 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010012071
Bram Moolenaar01164a62017-11-02 22:58:42 +010012072 The name must be made of alphanumeric characters and
12073 '_', and must start with a capital or "s:" (see
12074 above). Note that using "b:" or "g:" is not allowed.
12075 (since patch 7.4.260 E884 is given if the function
12076 name has a colon in the name, e.g. for "foo:bar()".
12077 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012078
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012079 {name} can also be a |Dictionary| entry that is a
12080 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012081 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +020012082< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012083 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +020012084 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012085 result is a |Funcref| to a numbered function. The
12086 function can only be used with a |Funcref| and will be
12087 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012088 *E127* *E122*
12089 When a function by this name already exists and [!] is
Bram Moolenaarded5f1b2018-11-10 17:33:29 +010012090 not used an error message is given. There is one
12091 exception: When sourcing a script again, a function
12092 that was previously defined in that script will be
12093 silently replaced.
12094 When [!] is used, an existing function is silently
12095 replaced. Unless it is currently being executed, that
12096 is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +020012097 NOTE: Use ! wisely. If used without care it can cause
12098 an existing function to be replaced unexpectedly,
12099 which is hard to debug.
Bram Moolenaar388a5d42020-05-26 21:20:45 +020012100 NOTE: In Vim9 script script-local functions cannot be
12101 deleted or redefined.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012102
12103 For the {arguments} see |function-argument|.
12104
Bram Moolenaar8d043172014-01-23 14:24:41 +010012105 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012106 When the [range] argument is added, the function is
12107 expected to take care of a range itself. The range is
12108 passed as "a:firstline" and "a:lastline". If [range]
12109 is excluded, ":{range}call" will call the function for
12110 each line in the range, with the cursor on the start
12111 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +010012112 The cursor is still moved to the first line of the
12113 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +010012114 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012115 When the [abort] argument is added, the function will
12116 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +010012117 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000012118 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +020012119 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000012120 local variable "self" will then be set to the
12121 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020012122 *:func-closure* *E932*
12123 When the [closure] argument is added, the function
12124 can access variables and arguments from the outer
12125 scope. This is usually called a closure. In this
12126 example Bar() uses "x" from the scope of Foo(). It
12127 remains referenced even after Foo() returns: >
12128 :function! Foo()
12129 : let x = 0
12130 : function! Bar() closure
12131 : let x += 1
12132 : return x
12133 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +020012134 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020012135 :endfunction
12136
12137 :let F = Foo()
12138 :echo F()
12139< 1 >
12140 :echo F()
12141< 2 >
12142 :echo F()
12143< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +000012144
Bram Moolenaar446cb832008-06-24 21:56:24 +000012145 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +000012146 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +000012147 will not be changed by the function. This also
12148 implies that the effect of |:nohlsearch| is undone
12149 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +000012150
Bram Moolenaarf8be4612017-06-23 20:52:40 +020012151 *:endf* *:endfunction* *E126* *E193* *W22*
Bram Moolenaar663bb232017-06-22 19:12:10 +020012152:endf[unction] [argument]
12153 The end of a function definition. Best is to put it
12154 on a line by its own, without [argument].
12155
12156 [argument] can be:
12157 | command command to execute next
12158 \n command command to execute next
12159 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +020012160 anything else ignored, warning given when
12161 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +020012162 The support for a following command was added in Vim
12163 8.0.0654, before that any argument was silently
12164 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012165
Bram Moolenaarf8be4612017-06-23 20:52:40 +020012166 To be able to define a function inside an `:execute`
12167 command, use line breaks instead of |:bar|: >
12168 :exe "func Foo()\necho 'foo'\nendfunc"
12169<
Bram Moolenaar437bafe2016-08-01 15:40:54 +020012170 *:delf* *:delfunction* *E130* *E131* *E933*
Bram Moolenaar663bb232017-06-22 19:12:10 +020012171:delf[unction][!] {name}
12172 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012173 {name} can also be a |Dictionary| entry that is a
12174 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012175 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +020012176< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012177 function is deleted if there are no more references to
12178 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +020012179 With the ! there is no error if the function does not
12180 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012181 *:retu* *:return* *E133*
12182:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
12183 evaluated and returned as the result of the function.
12184 If "[expr]" is not given, the number 0 is returned.
12185 When a function ends without an explicit ":return",
12186 the number 0 is returned.
12187 Note that there is no check for unreachable lines,
12188 thus there is no warning if commands follow ":return".
12189
12190 If the ":return" is used after a |:try| but before the
12191 matching |:finally| (if present), the commands
12192 following the ":finally" up to the matching |:endtry|
12193 are executed first. This process applies to all
12194 nested ":try"s inside the function. The function
12195 returns at the outermost ":endtry".
12196
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012197 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +020012198An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012199be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012200 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012201Up to 20 arguments can be given, separated by commas. After the named
12202arguments an argument "..." can be specified, which means that more arguments
12203may optionally be following. In the function the extra arguments can be used
12204as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012205can be 0). "a:000" is set to a |List| that contains these arguments. Note
12206that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012207 *E742*
12208The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +020012209However, if a composite type is used, such as |List| or |Dictionary| , you can
12210change their contents. Thus you can pass a |List| to a function and have the
12211function add an item to it. If you want to make sure the function cannot
12212change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012213
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012214It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +010012215still supply the () then.
12216
Bram Moolenaar98ef2332018-03-18 14:44:37 +010012217It is allowed to define another function inside a function body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012218
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012219 *optional-function-argument*
12220You can provide default values for positional named arguments. This makes
12221them optional for function calls. When a positional argument is not
12222specified at a call, the default expression is used to initialize it.
Bram Moolenaard1caa942020-04-10 22:10:56 +020012223This only works for functions declared with `:function` or `:def`, not for
12224lambda expressions |expr-lambda|.
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012225
12226Example: >
12227 function Something(key, value = 10)
Bram Moolenaar8aad88d2019-05-12 13:53:50 +020012228 echo a:key .. ": " .. a:value
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012229 endfunction
12230 call Something('empty') "empty: 10"
Bram Moolenaar8aad88d2019-05-12 13:53:50 +020012231 call Something('key', 20) "key: 20"
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012232
12233The argument default expressions are evaluated at the time of the function
12234call, not definition. Thus it is possible to use an expression which is
Bram Moolenaar68e65602019-05-26 21:33:31 +020012235invalid the moment the function is defined. The expressions are also only
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012236evaluated when arguments are not specified during a call.
Bram Moolenaar2547aa92020-07-26 17:00:44 +020012237 *none-function_argument*
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012238You can pass |v:none| to use the default expression. Note that this means you
12239cannot pass v:none as an ordinary value when an argument has a default
12240expression.
12241
12242Example: >
12243 function Something(a = 10, b = 20, c = 30)
12244 endfunction
12245 call Something(1, v:none, 3) " b = 20
12246<
12247 *E989*
12248Optional arguments with default expressions must occur after any mandatory
12249arguments. You can use "..." after all optional named arguments.
12250
12251It is possible for later argument defaults to refer to prior arguments,
12252but not the other way around. They must be prefixed with "a:", as with all
12253arguments.
12254
12255Example that works: >
12256 :function Okay(mandatory, optional = a:mandatory)
12257 :endfunction
12258Example that does NOT work: >
12259 :function NoGood(first = a:second, second = 10)
12260 :endfunction
12261<
Bram Moolenaard1caa942020-04-10 22:10:56 +020012262When not using "...", the number of arguments in a function call must be at
12263least equal to the number of mandatory named arguments. When using "...", the
12264number of arguments may be larger than the total of mandatory and optional
12265arguments.
Bram Moolenaar42ae78c2019-05-09 21:08:58 +020012266
Bram Moolenaar8f999f12005-01-25 22:12:55 +000012267 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +020012268Inside a function local variables can be used. These will disappear when the
12269function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +000012270
12271Example: >
12272 :function Table(title, ...)
12273 : echohl Title
12274 : echo a:title
12275 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +000012276 : echo a:0 . " items:"
12277 : for s in a:000
12278 : echon ' ' . s
12279 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +000012280 :endfunction
12281
12282This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +000012283 call Table("Table", "line1", "line2")
12284 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +000012285
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012286To return more than one value, return a |List|: >
12287 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012288 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012289 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +000012290 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012291 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +000012292 :endfunction
12293
12294This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012295 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012296 :if success == "ok"
12297 : echo div
12298 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012299<
Bram Moolenaar39f05632006-03-19 22:15:26 +000012300 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012301:[range]cal[l] {name}([arguments])
12302 Call a function. The name of the function and its arguments
Bram Moolenaar68e65602019-05-26 21:33:31 +020012303 are as specified with `:function`. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012304 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012305 Without a range and for functions that accept a range, the
12306 function is called once. When a range is given the cursor is
12307 positioned at the start of the first line before executing the
12308 function.
12309 When a range is given and the function doesn't handle it
12310 itself, the function is executed for each line in the range,
12311 with the cursor in the first column of that line. The cursor
12312 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +020012313 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +000012314 this works:
12315 *function-range-example* >
12316 :function Mynumber(arg)
12317 : echo line(".") . " " . a:arg
12318 :endfunction
12319 :1,5call Mynumber(getline("."))
12320<
12321 The "a:firstline" and "a:lastline" are defined anyway, they
12322 can be used to do something different at the start or end of
12323 the range.
12324
12325 Example of a function that handles the range itself: >
12326
12327 :function Cont() range
12328 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
12329 :endfunction
12330 :4,8call Cont()
12331<
12332 This function inserts the continuation character "\" in front
12333 of all the lines in the range, except the first one.
12334
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012335 When the function returns a composite value it can be further
12336 dereferenced, but the range will not be used then. Example: >
12337 :4,8call GetDict().method()
12338< Here GetDict() gets the range but method() does not.
12339
Bram Moolenaar071d4272004-06-13 20:20:40 +000012340 *E132*
12341The recursiveness of user functions is restricted with the |'maxfuncdepth'|
12342option.
12343
Bram Moolenaar25e42232019-08-04 15:04:10 +020012344It is also possible to use `:eval`. It does not support a range, but does
12345allow for method chaining, e.g.: >
12346 eval GetList()->Filter()->append('$')
12347
Bram Moolenaar088e8e32019-08-08 22:15:18 +020012348A function can also be called as part of evaluating an expression or when it
12349is used as a method: >
12350 let x = GetList()
12351 let y = GetList()->Filter()
12352
Bram Moolenaar7c626922005-02-07 22:01:03 +000012353
12354AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012355 *autoload-functions*
12356When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +000012357only when they are used. There are two methods: with an autocommand and with
12358the "autoload" directory in 'runtimepath'.
12359
12360
12361Using an autocommand ~
12362
Bram Moolenaar05159a02005-02-26 23:04:13 +000012363This is introduced in the user manual, section |41.14|.
12364
Bram Moolenaar7c626922005-02-07 22:01:03 +000012365The autocommand is useful if you have a plugin that is a long Vim script file.
Bram Moolenaar68e65602019-05-26 21:33:31 +020012366You can define the autocommand and quickly quit the script with `:finish`.
Bram Moolenaar58b85342016-08-14 19:54:54 +020012367That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar68e65602019-05-26 21:33:31 +020012368again, setting a variable to skip the `:finish` command.
Bram Moolenaar7c626922005-02-07 22:01:03 +000012369
12370Use the FuncUndefined autocommand event with a pattern that matches the
12371function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000012372
12373 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
12374
12375The file "~/vim/bufnetfuncs.vim" should then define functions that start with
12376"BufNet". Also see |FuncUndefined|.
12377
Bram Moolenaar7c626922005-02-07 22:01:03 +000012378
12379Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012380 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +000012381This is introduced in the user manual, section |41.15|.
12382
Bram Moolenaar7c626922005-02-07 22:01:03 +000012383Using a script in the "autoload" directory is simpler, but requires using
12384exactly the right file name. A function that can be autoloaded has a name
12385like this: >
12386
Bram Moolenaara7fc0102005-05-18 22:17:12 +000012387 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000012388
Bram Moolenaar65e0d772020-06-14 17:29:55 +020012389These functions are always global, in Vim9 script "g:" needs to be used: >
12390 :call g:filename#funcname()
12391
Bram Moolenaar7c626922005-02-07 22:01:03 +000012392When such a function is called, and it is not defined yet, Vim will search the
12393"autoload" directories in 'runtimepath' for a script file called
12394"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
12395then define the function like this: >
12396
Bram Moolenaara7fc0102005-05-18 22:17:12 +000012397 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000012398 echo "Done!"
12399 endfunction
12400
Bram Moolenaar60a795a2005-09-16 21:55:43 +000012401The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +000012402exactly, and the defined function must have the name exactly as it will be
Bram Moolenaar65e0d772020-06-14 17:29:55 +020012403called. In Vim9 script the "g:" prefix must be used: >
12404 function g:filename#funcname()
12405
12406or for a compiled function: >
12407 def g:filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000012408
Bram Moolenaara7fc0102005-05-18 22:17:12 +000012409It is possible to use subdirectories. Every # in the function name works like
12410a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +000012411
Bram Moolenaara7fc0102005-05-18 22:17:12 +000012412 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +000012413
12414Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
12415
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012416This also works when reading a variable that has not been set yet: >
12417
Bram Moolenaara7fc0102005-05-18 22:17:12 +000012418 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012419
Bram Moolenaara5792f52005-11-23 21:25:05 +000012420However, when the autoload script was already loaded it won't be loaded again
12421for an unknown variable.
12422
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012423When assigning a value to such a variable nothing special happens. This can
12424be used to pass settings to the autoload script before it's loaded: >
12425
Bram Moolenaara7fc0102005-05-18 22:17:12 +000012426 :let foo#bar#toggle = 1
12427 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012428
Bram Moolenaar4399ef42005-02-12 14:29:27 +000012429Note that when you make a mistake and call a function that is supposed to be
12430defined in an autoload script, but the script doesn't actually define the
Bram Moolenaarcb80aa22020-10-26 21:12:46 +010012431function, you will get an error message for the missing function. If you fix
12432the autoload script it won't be automatically loaded again. Either restart
12433Vim or manually source the script.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012434
12435Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +000012436other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000012437Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +000012438
Bram Moolenaar433f7c82006-03-21 21:29:36 +000012439Hint: If you distribute a bunch of scripts you can pack them together with the
12440|vimball| utility. Also read the user manual |distribute-script|.
12441
Bram Moolenaar071d4272004-06-13 20:20:40 +000012442==============================================================================
124436. Curly braces names *curly-braces-names*
12444
Bram Moolenaar84f72352012-03-11 15:57:40 +010012445In most places where you can use a variable, you can use a "curly braces name"
12446variable. This is a regular variable name with one or more expressions
12447wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000012448 my_{adjective}_variable
12449
12450When Vim encounters this, it evaluates the expression inside the braces, puts
12451that in place of the expression, and re-interprets the whole as a variable
12452name. So in the above example, if the variable "adjective" was set to
12453"noisy", then the reference would be to "my_noisy_variable", whereas if
12454"adjective" was set to "quiet", then it would be to "my_quiet_variable".
12455
12456One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +020012457value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +000012458 echo my_{&background}_message
12459
12460would output the contents of "my_dark_message" or "my_light_message" depending
12461on the current value of 'background'.
12462
12463You can use multiple brace pairs: >
12464 echo my_{adverb}_{adjective}_message
12465..or even nest them: >
12466 echo my_{ad{end_of_word}}_message
12467where "end_of_word" is either "verb" or "jective".
12468
12469However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000012470variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000012471 :let foo='a + b'
12472 :echo c{foo}d
12473.. since the result of expansion is "ca + bd", which is not a variable name.
12474
12475 *curly-braces-function-names*
12476You can call and define functions by an evaluated name in a similar way.
12477Example: >
12478 :let func_end='whizz'
12479 :call my_func_{func_end}(parameter)
12480
12481This would call the function "my_func_whizz(parameter)".
12482
Bram Moolenaar84f72352012-03-11 15:57:40 +010012483This does NOT work: >
12484 :let i = 3
12485 :let @{i} = '' " error
12486 :echo @{i} " error
12487
Bram Moolenaar071d4272004-06-13 20:20:40 +000012488==============================================================================
124897. Commands *expression-commands*
12490
Bram Moolenaar65e0d772020-06-14 17:29:55 +020012491Note: in Vim9 script `:let` is used for variable declaration, not assignment.
12492An assignment leaves out the `:let` command. |vim9-declaration|
12493
Bram Moolenaar071d4272004-06-13 20:20:40 +000012494:let {var-name} = {expr1} *:let* *E18*
12495 Set internal variable {var-name} to the result of the
12496 expression {expr1}. The variable will get the type
12497 from the {expr}. If {var-name} didn't exist yet, it
12498 is created.
12499
Bram Moolenaar13065c42005-01-08 16:08:21 +000012500:let {var-name}[{idx}] = {expr1} *E689*
12501 Set a list item to the result of the expression
12502 {expr1}. {var-name} must refer to a list and {idx}
12503 must be a valid index in that list. For nested list
12504 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +000012505 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020012506 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +000012507 can do that like this: >
12508 :let var = var[0:2] . 'X' . var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010012509< When {var-name} is a |Blob| then {idx} can be the
12510 length of the blob, in which case one byte is
12511 appended.
12512
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012513 *E711* *E719*
12514:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012515 Set a sequence of items in a |List| to the result of
12516 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000012517 correct number of items.
12518 {idx1} can be omitted, zero is used instead.
12519 {idx2} can be omitted, meaning the end of the list.
12520 When the selected range of items is partly past the
12521 end of the list, items will be added.
12522
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020012523 *:let+=* *:let-=* *:letstar=*
12524 *:let/=* *:let%=* *:let.=* *:let..=* *E734* *E985*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012525:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
12526:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +010012527:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
12528:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
12529:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012530:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020012531:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012532 These fail if {var} was not set yet and when the type
12533 of {var} and {expr1} don't fit the operator.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020012534 `.=` is not supported with Vim script version 2 and
12535 later, see |vimscript-version|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012536
12537
Bram Moolenaar071d4272004-06-13 20:20:40 +000012538:let ${env-name} = {expr1} *:let-environment* *:let-$*
12539 Set environment variable {env-name} to the result of
12540 the expression {expr1}. The type is always String.
Bram Moolenaar56c860c2019-08-17 20:09:31 +020012541
12542 On some systems making an environment variable empty
12543 causes it to be deleted. Many systems do not make a
12544 difference between an environment variable that is not
12545 set and an environment variable that is empty.
12546
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012547:let ${env-name} .= {expr1}
12548 Append {expr1} to the environment variable {env-name}.
12549 If the environment variable didn't exist yet this
12550 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +000012551
12552:let @{reg-name} = {expr1} *:let-register* *:let-@*
12553 Write the result of the expression {expr1} in register
12554 {reg-name}. {reg-name} must be a single letter, and
12555 must be the name of a writable register (see
12556 |registers|). "@@" can be used for the unnamed
12557 register, "@/" for the search pattern.
12558 If the result of {expr1} ends in a <CR> or <NL>, the
12559 register will be linewise, otherwise it will be set to
12560 characterwise.
12561 This can be used to clear the last search pattern: >
12562 :let @/ = ""
12563< This is different from searching for an empty string,
12564 that would match everywhere.
12565
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012566:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +020012567 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012568 register was empty it's like setting it to {expr1}.
12569
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012570:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012571 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +000012572 expression {expr1}. A String or Number value is
12573 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012574 For an option local to a window or buffer the effect
12575 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +000012576 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000012577 Example: >
12578 :let &path = &path . ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +010012579< This also works for terminal codes in the form t_xx.
12580 But only for alphanumerical names. Example: >
12581 :let &t_k1 = "\<Esc>[234;"
12582< When the code does not exist yet it will be created as
12583 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012584
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012585:let &{option-name} .= {expr1}
12586 For a string option: Append {expr1} to the value.
12587 Does not insert a comma like |:set+=|.
12588
12589:let &{option-name} += {expr1}
12590:let &{option-name} -= {expr1}
12591 For a number or boolean option: Add or subtract
12592 {expr1}.
12593
Bram Moolenaar071d4272004-06-13 20:20:40 +000012594:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012595:let &l:{option-name} .= {expr1}
12596:let &l:{option-name} += {expr1}
12597:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000012598 Like above, but only set the local value of an option
12599 (if there is one). Works like |:setlocal|.
12600
12601:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012602:let &g:{option-name} .= {expr1}
12603:let &g:{option-name} += {expr1}
12604:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000012605 Like above, but only set the global value of an option
12606 (if there is one). Works like |:setglobal|.
12607
Bram Moolenaar13065c42005-01-08 16:08:21 +000012608:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012609 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +000012610 the list is assigned to {name1}, the second item to
12611 {name2}, etc.
12612 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012613 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000012614 Each name can be one of the items of the ":let"
12615 command as mentioned above.
12616 Example: >
12617 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012618< Detail: {expr1} is evaluated first, then the
12619 assignments are done in sequence. This matters if
12620 {name2} depends on {name1}. Example: >
12621 :let x = [0, 1]
12622 :let i = 0
12623 :let [i, x[i]] = [1, 2]
12624 :echo x
12625< The result is [0, 2].
12626
12627:let [{name1}, {name2}, ...] .= {expr1}
12628:let [{name1}, {name2}, ...] += {expr1}
12629:let [{name1}, {name2}, ...] -= {expr1}
12630 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012631 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000012632
Bram Moolenaard1caa942020-04-10 22:10:56 +020012633:let [{name}, ..., ; {lastname}] = {expr1} *E452*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012634 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012635 items than there are names. A list of the remaining
12636 items is assigned to {lastname}. If there are no
12637 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000012638 Example: >
12639 :let [a, b; rest] = ["aval", "bval", 3, 4]
12640<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012641:let [{name}, ..., ; {lastname}] .= {expr1}
12642:let [{name}, ..., ; {lastname}] += {expr1}
12643:let [{name}, ..., ; {lastname}] -= {expr1}
12644 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012645 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +020012646
Bram Moolenaar24582002019-07-21 14:14:26 +020012647 *:let=<<* *:let-heredoc*
12648 *E990* *E991* *E172* *E221*
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012649:let {var-name} =<< [trim] {endmarker}
Bram Moolenaarf5842c52019-05-19 18:41:26 +020012650text...
12651text...
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012652{endmarker}
Bram Moolenaare46a4402020-06-30 20:38:27 +020012653 Set internal variable {var-name} to a |List|
12654 containing the lines of text bounded by the string
Bram Moolenaaraa970ab2020-08-02 16:10:39 +020012655 {endmarker}. The lines of text is used as a
12656 |literal-string|.
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012657 {endmarker} must not contain white space.
12658 {endmarker} cannot start with a lower case character.
12659 The last line should end only with the {endmarker}
12660 string without any other character. Watch out for
12661 white space after {endmarker}!
Bram Moolenaarf5842c52019-05-19 18:41:26 +020012662
Bram Moolenaare7eb9272019-06-24 00:58:07 +020012663 Without "trim" any white space characters in the lines
12664 of text are preserved. If "trim" is specified before
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012665 {endmarker}, then indentation is stripped so you can
12666 do: >
Bram Moolenaare7eb9272019-06-24 00:58:07 +020012667 let text =<< trim END
12668 if ok
12669 echo 'done'
12670 endif
12671 END
12672< Results in: ["if ok", " echo 'done'", "endif"]
12673 The marker must line up with "let" and the indentation
12674 of the first line is removed from all the text lines.
12675 Specifically: all the leading indentation exactly
12676 matching the leading indentation of the first
12677 non-empty text line is stripped from the input lines.
12678 All leading indentation exactly matching the leading
12679 indentation before `let` is stripped from the line
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012680 containing {endmarker}. Note that the difference
12681 between space and tab matters here.
Bram Moolenaarf5842c52019-05-19 18:41:26 +020012682
12683 If {var-name} didn't exist yet, it is created.
12684 Cannot be followed by another command, but can be
12685 followed by a comment.
12686
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012687 To avoid line continuation to be applied, consider
12688 adding 'C' to 'cpoptions': >
12689 set cpo+=C
12690 let var =<< END
12691 \ leading backslash
12692 END
12693 set cpo-=C
12694<
Bram Moolenaarf5842c52019-05-19 18:41:26 +020012695 Examples: >
12696 let var1 =<< END
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012697 Sample text 1
12698 Sample text 2
12699 Sample text 3
12700 END
Bram Moolenaarf5842c52019-05-19 18:41:26 +020012701
12702 let data =<< trim DATA
Bram Moolenaar2e693a82019-10-16 22:35:02 +020012703 1 2 3 4
12704 5 6 7 8
Bram Moolenaarf5842c52019-05-19 18:41:26 +020012705 DATA
12706<
Bram Moolenaar4a748032010-09-30 21:47:56 +020012707 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +020012708:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000012709 variable names may be given. Special names recognized
12710 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +000012711 g: global variables
12712 b: local buffer variables
12713 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +000012714 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +000012715 s: script-local variables
12716 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000012717 v: Vim variables.
Bram Moolenaar65e0d772020-06-14 17:29:55 +020012718 This does not work in Vim9 script. |vim9-declaration|
Bram Moolenaar071d4272004-06-13 20:20:40 +000012719
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000012720:let List the values of all variables. The type of the
12721 variable is indicated before the value:
12722 <nothing> String
12723 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000012724 * Funcref
Bram Moolenaar65e0d772020-06-14 17:29:55 +020012725 This does not work in Vim9 script. |vim9-declaration|
Bram Moolenaar071d4272004-06-13 20:20:40 +000012726
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012727:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012728 Remove the internal variable {name}. Several variable
12729 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012730 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012731 With [!] no error message is given for non-existing
12732 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012733 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000012734 :unlet list[3] " remove fourth item
12735 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012736< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000012737 :unlet dict['two']
12738 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +000012739< This is especially useful to clean up used global
12740 variables and script-local variables (these are not
12741 deleted when the script ends). Function-local
12742 variables are automatically deleted when the function
12743 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012744
Bram Moolenaar137374f2018-05-13 15:59:50 +020012745:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
12746 Remove environment variable {env-name}.
12747 Can mix {name} and ${env-name} in one :unlet command.
12748 No error message is given for a non-existing
12749 variable, also without !.
12750 If the system does not support deleting an environment
Bram Moolenaar9937a052019-06-15 15:45:06 +020012751 variable, it is made empty.
Bram Moolenaar137374f2018-05-13 15:59:50 +020012752
Bram Moolenaar1c196e72019-06-16 15:41:58 +020012753 *:cons* *:const*
Bram Moolenaar9937a052019-06-15 15:45:06 +020012754:cons[t] {var-name} = {expr1}
12755:cons[t] [{name1}, {name2}, ...] = {expr1}
Bram Moolenaar9937a052019-06-15 15:45:06 +020012756:cons[t] [{name}, ..., ; {lastname}] = {expr1}
12757:cons[t] {var-name} =<< [trim] {marker}
12758text...
12759text...
12760{marker}
12761 Similar to |:let|, but additionally lock the variable
12762 after setting the value. This is the same as locking
12763 the variable with |:lockvar| just after |:let|, thus: >
12764 :const x = 1
12765< is equivalent to: >
12766 :let x = 1
Bram Moolenaar021bda52020-08-17 21:07:22 +020012767 :lockvar! x
Bram Moolenaara187c432020-09-16 21:08:28 +020012768< NOTE: in Vim9 script `:const` works differently, see
12769 |vim9-const|
12770 This is useful if you want to make sure the variable
Bram Moolenaar021bda52020-08-17 21:07:22 +020012771 is not modified. If the value is a List or Dictionary
12772 literal then the items also cannot be changed: >
12773 const ll = [1, 2, 3]
12774 let ll[1] = 5 " Error!
12775< Nested references are not locked: >
12776 let lvar = ['a']
12777 const lconst = [0, lvar]
12778 let lconst[0] = 2 " Error!
12779 let lconst[1][0] = 'b' " OK
12780< *E995*
Bram Moolenaar9b283522019-06-17 22:19:33 +020012781 |:const| does not allow to for changing a variable: >
Bram Moolenaar9937a052019-06-15 15:45:06 +020012782 :let x = 1
12783 :const x = 2 " Error!
Bram Moolenaar1c196e72019-06-16 15:41:58 +020012784< *E996*
12785 Note that environment variables, option values and
12786 register values cannot be used here, since they cannot
12787 be locked.
12788
Bram Moolenaar85850f32019-07-19 22:05:51 +020012789:cons[t]
12790:cons[t] {var-name}
12791 If no argument is given or only {var-name} is given,
12792 the behavior is the same as |:let|.
12793
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012794:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
12795 Lock the internal variable {name}. Locking means that
12796 it can no longer be changed (until it is unlocked).
12797 A locked variable can be deleted: >
12798 :lockvar v
12799 :let v = 'asdf' " fails!
12800 :unlet v
Bram Moolenaare7877fe2017-02-20 22:35:33 +010012801< *E741* *E940*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012802 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +010012803 error message: "E741: Value is locked: {name}".
12804 If you try to lock or unlock a built-in variable you
12805 get an error message: "E940: Cannot lock or unlock
12806 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012807
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012808 [depth] is relevant when locking a |List| or
12809 |Dictionary|. It specifies how deep the locking goes:
Bram Moolenaara187c432020-09-16 21:08:28 +020012810 0 Lock the variable {name} but not its
12811 value.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012812 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012813 cannot add or remove items, but can
12814 still change their values.
12815 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012816 the items. If an item is a |List| or
12817 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012818 items, but can still change the
12819 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012820 3 Like 2 but for the |List| /
12821 |Dictionary| in the |List| /
12822 |Dictionary|, one level deeper.
12823 The default [depth] is 2, thus when {name} is a |List|
12824 or |Dictionary| the values cannot be changed.
Bram Moolenaara187c432020-09-16 21:08:28 +020012825
12826 Example with [depth] 0: >
12827 let mylist = [1, 2, 3]
12828 lockvar 0 mylist
12829 let mylist[0] = 77 " OK
12830 call add(mylist, 4] " OK
12831 let mylist = [7, 8, 9] " Error!
12832< *E743*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012833 For unlimited depth use [!] and omit [depth].
12834 However, there is a maximum depth of 100 to catch
12835 loops.
12836
Bram Moolenaar32466aa2006-02-24 23:53:04 +000012837 Note that when two variables refer to the same |List|
12838 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +000012839 locked when used through the other variable.
12840 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000012841 :let l = [0, 1, 2, 3]
12842 :let cl = l
12843 :lockvar l
12844 :let cl[1] = 99 " won't work!
12845< You may want to make a copy of a list to avoid this.
12846 See |deepcopy()|.
12847
12848
12849:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
12850 Unlock the internal variable {name}. Does the
12851 opposite of |:lockvar|.
12852
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020012853:if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012854:en[dif] Execute the commands until the next matching ":else"
12855 or ":endif" if {expr1} evaluates to non-zero.
12856
12857 From Vim version 4.5 until 5.0, every Ex command in
12858 between the ":if" and ":endif" is ignored. These two
12859 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +010012860 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +000012861 that any ":else" or ":elseif" was ignored, the "else"
12862 part was not executed either.
12863
12864 You can use this to remain compatible with older
12865 versions: >
12866 :if version >= 500
12867 : version-5-specific-commands
12868 :endif
12869< The commands still need to be parsed to find the
12870 "endif". Sometimes an older Vim has a problem with a
12871 new command. For example, ":silent" is recognized as
12872 a ":substitute" command. In that case ":execute" can
12873 avoid problems: >
12874 :if version >= 600
12875 : execute "silent 1,$delete"
12876 :endif
12877<
12878 NOTE: The ":append" and ":insert" commands don't work
12879 properly in between ":if" and ":endif".
12880
12881 *:else* *:el* *E581* *E583*
12882:el[se] Execute the commands until the next matching ":else"
12883 or ":endif" if they previously were not being
12884 executed.
12885
12886 *:elseif* *:elsei* *E582* *E584*
12887:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
12888 is no extra ":endif".
12889
12890:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000012891 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012892:endw[hile] Repeat the commands between ":while" and ":endwhile",
12893 as long as {expr1} evaluates to non-zero.
12894 When an error is detected from a command inside the
12895 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +000012896 Example: >
12897 :let lnum = 1
12898 :while lnum <= line("$")
12899 :call FixLine(lnum)
12900 :let lnum = lnum + 1
12901 :endwhile
12902<
Bram Moolenaar071d4272004-06-13 20:20:40 +000012903 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +000012904 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012905
Bram Moolenaar5e66b422019-01-24 21:58:10 +010012906:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +000012907:endfo[r] *:endfo* *:endfor*
12908 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar5e66b422019-01-24 21:58:10 +010012909 each item in {object}. {object} can be a |List| or
12910 a |Blob|. Variable {var} is set to the value of each
12911 item. When an error is detected for a command inside
12912 the loop, execution continues after the "endfor".
12913 Changing {object} inside the loop affects what items
12914 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +000012915 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +010012916<
12917 When {object} is a |List| and not making a copy, Vim
12918 stores a reference to the next item in the |List|
12919 before executing the commands with the current item.
12920 Thus the current item can be removed without effect.
12921 Removing any later item means it will not be found.
12922 Thus the following example works (an inefficient way
12923 to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010012924 for item in mylist
12925 call remove(mylist, 0)
12926 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +010012927< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000012928 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +000012929
Bram Moolenaar5e66b422019-01-24 21:58:10 +010012930 When {object} is a |Blob|, Vim always makes a copy to
12931 iterate over. Unlike with |List|, modifying the
12932 |Blob| does not affect the iteration.
12933
Bram Moolenaar12805862005-01-05 22:16:17 +000012934:for [{var1}, {var2}, ...] in {listlist}
12935:endfo[r]
12936 Like ":for" above, but each item in {listlist} must be
12937 a list, of which each item is assigned to {var1},
12938 {var2}, etc. Example: >
12939 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
12940 :echo getline(lnum)[col]
12941 :endfor
12942<
Bram Moolenaar071d4272004-06-13 20:20:40 +000012943 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +000012944:con[tinue] When used inside a ":while" or ":for" loop, jumps back
12945 to the start of the loop.
12946 If it is used after a |:try| inside the loop but
12947 before the matching |:finally| (if present), the
12948 commands following the ":finally" up to the matching
12949 |:endtry| are executed first. This process applies to
12950 all nested ":try"s inside the loop. The outermost
12951 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012952
12953 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +000012954:brea[k] When used inside a ":while" or ":for" loop, skips to
12955 the command after the matching ":endwhile" or
12956 ":endfor".
12957 If it is used after a |:try| inside the loop but
12958 before the matching |:finally| (if present), the
12959 commands following the ":finally" up to the matching
12960 |:endtry| are executed first. This process applies to
12961 all nested ":try"s inside the loop. The outermost
12962 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012963
12964:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
12965:endt[ry] Change the error handling for the commands between
12966 ":try" and ":endtry" including everything being
12967 executed across ":source" commands, function calls,
12968 or autocommand invocations.
12969
12970 When an error or interrupt is detected and there is
12971 a |:finally| command following, execution continues
12972 after the ":finally". Otherwise, or when the
12973 ":endtry" is reached thereafter, the next
12974 (dynamically) surrounding ":try" is checked for
12975 a corresponding ":finally" etc. Then the script
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +010012976 processing is terminated. Whether a function
12977 definition has an "abort" argument does not matter.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012978 Example: >
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +010012979 try | call Unknown() | finally | echomsg "cleanup" | endtry
12980 echomsg "not reached"
Bram Moolenaar071d4272004-06-13 20:20:40 +000012981<
12982 Moreover, an error or interrupt (dynamically) inside
12983 ":try" and ":endtry" is converted to an exception. It
12984 can be caught as if it were thrown by a |:throw|
12985 command (see |:catch|). In this case, the script
12986 processing is not terminated.
12987
12988 The value "Vim:Interrupt" is used for an interrupt
12989 exception. An error in a Vim command is converted
12990 to a value of the form "Vim({command}):{errmsg}",
12991 other errors are converted to a value of the form
12992 "Vim:{errmsg}". {command} is the full command name,
12993 and {errmsg} is the message that is displayed if the
12994 error exception is not caught, always beginning with
12995 the error number.
12996 Examples: >
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +010012997 try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
12998 try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
Bram Moolenaar071d4272004-06-13 20:20:40 +000012999<
13000 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010013001:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +000013002 |:finally|, or |:endtry| that belongs to the same
13003 |:try| as the ":catch" are executed when an exception
13004 matching {pattern} is being thrown and has not yet
13005 been caught by a previous ":catch". Otherwise, these
13006 commands are skipped.
13007 When {pattern} is omitted all errors are caught.
13008 Examples: >
Bram Moolenaar647e24b2019-03-17 16:39:46 +010013009 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
13010 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
13011 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
13012 :catch /^Vim(write):/ " catch all errors in :write
13013 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
13014 :catch /my-exception/ " catch user exception
13015 :catch /.*/ " catch everything
13016 :catch " same as /.*/
Bram Moolenaar071d4272004-06-13 20:20:40 +000013017<
13018 Another character can be used instead of / around the
13019 {pattern}, so long as it does not have a special
13020 meaning (e.g., '|' or '"') and doesn't occur inside
13021 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020013022 Information about the exception is available in
13023 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013024 NOTE: It is not reliable to ":catch" the TEXT of
13025 an error message because it may vary in different
13026 locales.
13027
13028 *:fina* *:finally* *E606* *E607*
13029:fina[lly] The following commands until the matching |:endtry|
13030 are executed whenever the part between the matching
13031 |:try| and the ":finally" is left: either by falling
13032 through to the ":finally" or by a |:continue|,
13033 |:break|, |:finish|, or |:return|, or by an error or
13034 interrupt or exception (see |:throw|).
13035
13036 *:th* *:throw* *E608*
13037:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
13038 If the ":throw" is used after a |:try| but before the
13039 first corresponding |:catch|, commands are skipped
13040 until the first ":catch" matching {expr1} is reached.
13041 If there is no such ":catch" or if the ":throw" is
13042 used after a ":catch" but before the |:finally|, the
13043 commands following the ":finally" (if present) up to
13044 the matching |:endtry| are executed. If the ":throw"
13045 is after the ":finally", commands up to the ":endtry"
13046 are skipped. At the ":endtry", this process applies
13047 again for the next dynamically surrounding ":try"
13048 (which may be found in a calling function or sourcing
13049 script), until a matching ":catch" has been found.
13050 If the exception is not caught, the command processing
13051 is terminated.
13052 Example: >
13053 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +010013054< Note that "catch" may need to be on a separate line
13055 for when an error causes the parsing to skip the whole
13056 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013057
13058 *:ec* *:echo*
13059:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
13060 first {expr1} starts on a new line.
13061 Also see |:comment|.
13062 Use "\n" to start a new line. Use "\r" to move the
13063 cursor to the first column.
13064 Uses the highlighting set by the |:echohl| command.
13065 Cannot be followed by a comment.
13066 Example: >
13067 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013068< *:echo-redraw*
13069 A later redraw may make the message disappear again.
13070 And since Vim mostly postpones redrawing until it's
13071 finished with a sequence of commands this happens
13072 quite often. To avoid that a command from before the
13073 ":echo" causes a redraw afterwards (redraws are often
13074 postponed until you type something), force a redraw
13075 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000013076 :new | redraw | echo "there is a new window"
13077<
13078 *:echon*
13079:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
13080 |:comment|.
13081 Uses the highlighting set by the |:echohl| command.
13082 Cannot be followed by a comment.
13083 Example: >
13084 :echon "the value of 'shell' is " &shell
13085<
13086 Note the difference between using ":echo", which is a
13087 Vim command, and ":!echo", which is an external shell
13088 command: >
13089 :!echo % --> filename
13090< The arguments of ":!" are expanded, see |:_%|. >
13091 :!echo "%" --> filename or "filename"
13092< Like the previous example. Whether you see the double
13093 quotes or not depends on your 'shell'. >
13094 :echo % --> nothing
13095< The '%' is an illegal character in an expression. >
13096 :echo "%" --> %
13097< This just echoes the '%' character. >
13098 :echo expand("%") --> filename
13099< This calls the expand() function to expand the '%'.
13100
13101 *:echoh* *:echohl*
13102:echoh[l] {name} Use the highlight group {name} for the following
13103 |:echo|, |:echon| and |:echomsg| commands. Also used
13104 for the |input()| prompt. Example: >
13105 :echohl WarningMsg | echo "Don't panic!" | echohl None
13106< Don't forget to set the group back to "None",
13107 otherwise all following echo's will be highlighted.
13108
13109 *:echom* *:echomsg*
13110:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
13111 message in the |message-history|.
13112 Spaces are placed between the arguments as with the
13113 |:echo| command. But unprintable characters are
13114 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013115 The parsing works slightly different from |:echo|,
13116 more like |:execute|. All the expressions are first
13117 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010013118 If expressions does not evaluate to a Number or
13119 String, string() is used to turn it into a string.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013120 Uses the highlighting set by the |:echohl| command.
13121 Example: >
13122 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +000013123< See |:echo-redraw| to avoid the message disappearing
13124 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013125 *:echoe* *:echoerr*
13126:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
13127 message in the |message-history|. When used in a
13128 script or function the line number will be added.
13129 Spaces are placed between the arguments as with the
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010013130 |:echomsg| command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +000013131 the message is raised as an error exception instead
13132 (see |try-echoerr|).
13133 Example: >
13134 :echoerr "This script just failed!"
13135< If you just want a highlighted message use |:echohl|.
13136 And to get a beep: >
13137 :exe "normal \<Esc>"
13138<
Bram Moolenaar09c6f262019-11-17 15:55:14 +010013139 *:eval*
13140:eval {expr} Evaluate {expr} and discard the result. Example: >
13141 :eval Getlist()->Filter()->append('$')
13142
13143< The expression is supposed to have a side effect,
13144 since the resulting value is not used. In the example
13145 the `append()` call appends the List with text to the
13146 buffer. This is similar to `:call` but works with any
13147 expression.
13148
13149 The command can be shortened to `:ev` or `:eva`, but
13150 these are hard to recognize and therefore not to be
13151 used.
13152
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +010013153 The command cannot be followed by "|" and another
13154 command, since "|" is seen as part of the expression.
13155
Bram Moolenaar09c6f262019-11-17 15:55:14 +010013156
Bram Moolenaar071d4272004-06-13 20:20:40 +000013157 *:exe* *:execute*
13158:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +020013159 of {expr1} as an Ex command.
13160 Multiple arguments are concatenated, with a space in
Bram Moolenaar7e6a5152021-01-02 16:39:53 +010013161 between. To avoid the extra space use the ".."
Bram Moolenaar00a927d2010-05-14 23:24:24 +020013162 operator to concatenate strings into one argument.
13163 {expr1} is used as the processed command, command line
13164 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013165 Cannot be followed by a comment.
13166 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +020013167 :execute "buffer" nextbuf
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +010013168 :execute "normal" count .. "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +000013169<
13170 ":execute" can be used to append a command to commands
13171 that don't accept a '|'. Example: >
13172 :execute '!ls' | echo "theend"
13173
13174< ":execute" is also a nice way to avoid having to type
13175 control characters in a Vim script for a ":normal"
13176 command: >
13177 :execute "normal ixxx\<Esc>"
13178< This has an <Esc> character, see |expr-string|.
13179
Bram Moolenaar446cb832008-06-24 21:56:24 +000013180 Be careful to correctly escape special characters in
13181 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +000013182 for Vim commands, |shellescape()| for |:!| commands.
13183 Examples: >
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +010013184 :execute "e " .. fnameescape(filename)
13185 :execute "!ls " .. shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +000013186<
Bram Moolenaar071d4272004-06-13 20:20:40 +000013187 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010013188 starting or ending "if", "while" and "for" does not
13189 always work, because when commands are skipped the
13190 ":execute" is not evaluated and Vim loses track of
13191 where blocks start and end. Also "break" and
13192 "continue" should not be inside ":execute".
13193 This example does not work, because the ":execute" is
13194 not evaluated and Vim does not see the "while", and
13195 gives an error for finding an ":endwhile": >
13196 :if 0
13197 : execute 'while i > 5'
13198 : echo "test"
13199 : endwhile
13200 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +000013201<
13202 It is allowed to have a "while" or "if" command
13203 completely in the executed string: >
13204 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
13205<
13206
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010013207 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +000013208 ":execute", ":echo" and ":echon" cannot be followed by
13209 a comment directly, because they see the '"' as the
13210 start of a string. But, you can use '|' followed by a
13211 comment. Example: >
13212 :echo "foo" | "this is a comment
13213
13214==============================================================================
132158. Exception handling *exception-handling*
13216
13217The Vim script language comprises an exception handling feature. This section
13218explains how it can be used in a Vim script.
13219
13220Exceptions may be raised by Vim on an error or on interrupt, see
13221|catch-errors| and |catch-interrupt|. You can also explicitly throw an
13222exception by using the ":throw" command, see |throw-catch|.
13223
13224
13225TRY CONDITIONALS *try-conditionals*
13226
13227Exceptions can be caught or can cause cleanup code to be executed. You can
13228use a try conditional to specify catch clauses (that catch exceptions) and/or
13229a finally clause (to be executed for cleanup).
13230 A try conditional begins with a |:try| command and ends at the matching
13231|:endtry| command. In between, you can use a |:catch| command to start
13232a catch clause, or a |:finally| command to start a finally clause. There may
13233be none or multiple catch clauses, but there is at most one finally clause,
13234which must not be followed by any catch clauses. The lines before the catch
13235clauses and the finally clause is called a try block. >
13236
13237 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +000013238 : ...
13239 : ... TRY BLOCK
13240 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000013241 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000013242 : ...
13243 : ... CATCH CLAUSE
13244 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000013245 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000013246 : ...
13247 : ... CATCH CLAUSE
13248 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000013249 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +000013250 : ...
13251 : ... FINALLY CLAUSE
13252 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000013253 :endtry
13254
13255The try conditional allows to watch code for exceptions and to take the
13256appropriate actions. Exceptions from the try block may be caught. Exceptions
13257from the try block and also the catch clauses may cause cleanup actions.
13258 When no exception is thrown during execution of the try block, the control
13259is transferred to the finally clause, if present. After its execution, the
13260script continues with the line following the ":endtry".
13261 When an exception occurs during execution of the try block, the remaining
13262lines in the try block are skipped. The exception is matched against the
13263patterns specified as arguments to the ":catch" commands. The catch clause
13264after the first matching ":catch" is taken, other catch clauses are not
13265executed. The catch clause ends when the next ":catch", ":finally", or
13266":endtry" command is reached - whatever is first. Then, the finally clause
13267(if present) is executed. When the ":endtry" is reached, the script execution
13268continues in the following line as usual.
13269 When an exception that does not match any of the patterns specified by the
13270":catch" commands is thrown in the try block, the exception is not caught by
13271that try conditional and none of the catch clauses is executed. Only the
13272finally clause, if present, is taken. The exception pends during execution of
13273the finally clause. It is resumed at the ":endtry", so that commands after
13274the ":endtry" are not executed and the exception might be caught elsewhere,
13275see |try-nesting|.
13276 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +020013277remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +000013278not matched against the patterns in any of the ":catch" commands of the same
13279try conditional and none of its catch clauses is taken. If there is, however,
13280a finally clause, it is executed, and the exception pends during its
13281execution. The commands following the ":endtry" are not executed. The new
13282exception might, however, be caught elsewhere, see |try-nesting|.
13283 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +020013284thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000013285clause has been taken because of an exception from the try block or one of the
13286catch clauses, the original (pending) exception is discarded. The commands
13287following the ":endtry" are not executed, and the exception from the finally
13288clause is propagated and can be caught elsewhere, see |try-nesting|.
13289
13290The finally clause is also executed, when a ":break" or ":continue" for
13291a ":while" loop enclosing the complete try conditional is executed from the
13292try block or a catch clause. Or when a ":return" or ":finish" is executed
13293from the try block or a catch clause of a try conditional in a function or
13294sourced script, respectively. The ":break", ":continue", ":return", or
13295":finish" pends during execution of the finally clause and is resumed when the
13296":endtry" is reached. It is, however, discarded when an exception is thrown
13297from the finally clause.
13298 When a ":break" or ":continue" for a ":while" loop enclosing the complete
13299try conditional or when a ":return" or ":finish" is encountered in the finally
13300clause, the rest of the finally clause is skipped, and the ":break",
13301":continue", ":return" or ":finish" is executed as usual. If the finally
13302clause has been taken because of an exception or an earlier ":break",
13303":continue", ":return", or ":finish" from the try block or a catch clause,
13304this pending exception or command is discarded.
13305
13306For examples see |throw-catch| and |try-finally|.
13307
13308
13309NESTING OF TRY CONDITIONALS *try-nesting*
13310
13311Try conditionals can be nested arbitrarily. That is, a complete try
13312conditional can be put into the try block, a catch clause, or the finally
13313clause of another try conditional. If the inner try conditional does not
13314catch an exception thrown in its try block or throws a new exception from one
13315of its catch clauses or its finally clause, the outer try conditional is
13316checked according to the rules above. If the inner try conditional is in the
13317try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +020013318otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +000013319nesting, whether the inner try conditional is directly contained in the outer
13320one, or whether the outer one sources a script or calls a function containing
13321the inner try conditional.
13322
13323When none of the active try conditionals catches an exception, just their
13324finally clauses are executed. Thereafter, the script processing terminates.
13325An error message is displayed in case of an uncaught exception explicitly
13326thrown by a ":throw" command. For uncaught error and interrupt exceptions
13327implicitly raised by Vim, the error message(s) or interrupt message are shown
13328as usual.
13329
13330For examples see |throw-catch|.
13331
13332
13333EXAMINING EXCEPTION HANDLING CODE *except-examine*
13334
13335Exception handling code can get tricky. If you are in doubt what happens, set
13336'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
13337script file. Then you see when an exception is thrown, discarded, caught, or
13338finished. When using a verbosity level of at least 14, things pending in
13339a finally clause are also shown. This information is also given in debug mode
13340(see |debug-scripts|).
13341
13342
13343THROWING AND CATCHING EXCEPTIONS *throw-catch*
13344
13345You can throw any number or string as an exception. Use the |:throw| command
13346and pass the value to be thrown as argument: >
13347 :throw 4711
13348 :throw "string"
13349< *throw-expression*
13350You can also specify an expression argument. The expression is then evaluated
13351first, and the result is thrown: >
13352 :throw 4705 + strlen("string")
13353 :throw strpart("strings", 0, 6)
13354
13355An exception might be thrown during evaluation of the argument of the ":throw"
13356command. Unless it is caught there, the expression evaluation is abandoned.
13357The ":throw" command then does not throw a new exception.
13358 Example: >
13359
13360 :function! Foo(arg)
13361 : try
13362 : throw a:arg
13363 : catch /foo/
13364 : endtry
13365 : return 1
13366 :endfunction
13367 :
13368 :function! Bar()
13369 : echo "in Bar"
13370 : return 4710
13371 :endfunction
13372 :
13373 :throw Foo("arrgh") + Bar()
13374
13375This throws "arrgh", and "in Bar" is not displayed since Bar() is not
13376executed. >
13377 :throw Foo("foo") + Bar()
13378however displays "in Bar" and throws 4711.
13379
13380Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +020013381abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000013382exception is then propagated to the caller of the command.
13383 Example: >
13384
13385 :if Foo("arrgh")
13386 : echo "then"
13387 :else
13388 : echo "else"
13389 :endif
13390
13391Here neither of "then" or "else" is displayed.
13392
13393 *catch-order*
13394Exceptions can be caught by a try conditional with one or more |:catch|
13395commands, see |try-conditionals|. The values to be caught by each ":catch"
13396command can be specified as a pattern argument. The subsequent catch clause
13397gets executed when a matching exception is caught.
13398 Example: >
13399
13400 :function! Foo(value)
13401 : try
13402 : throw a:value
13403 : catch /^\d\+$/
13404 : echo "Number thrown"
13405 : catch /.*/
13406 : echo "String thrown"
13407 : endtry
13408 :endfunction
13409 :
13410 :call Foo(0x1267)
13411 :call Foo('string')
13412
13413The first call to Foo() displays "Number thrown", the second "String thrown".
13414An exception is matched against the ":catch" commands in the order they are
13415specified. Only the first match counts. So you should place the more
13416specific ":catch" first. The following order does not make sense: >
13417
13418 : catch /.*/
13419 : echo "String thrown"
13420 : catch /^\d\+$/
13421 : echo "Number thrown"
13422
13423The first ":catch" here matches always, so that the second catch clause is
13424never taken.
13425
13426 *throw-variables*
13427If you catch an exception by a general pattern, you may access the exact value
13428in the variable |v:exception|: >
13429
13430 : catch /^\d\+$/
13431 : echo "Number thrown. Value is" v:exception
13432
13433You may also be interested where an exception was thrown. This is stored in
13434|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
13435exception most recently caught as long it is not finished.
13436 Example: >
13437
13438 :function! Caught()
13439 : if v:exception != ""
13440 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
13441 : else
13442 : echo 'Nothing caught'
13443 : endif
13444 :endfunction
13445 :
13446 :function! Foo()
13447 : try
13448 : try
13449 : try
13450 : throw 4711
13451 : finally
13452 : call Caught()
13453 : endtry
13454 : catch /.*/
13455 : call Caught()
13456 : throw "oops"
13457 : endtry
13458 : catch /.*/
13459 : call Caught()
13460 : finally
13461 : call Caught()
13462 : endtry
13463 :endfunction
13464 :
13465 :call Foo()
13466
13467This displays >
13468
13469 Nothing caught
13470 Caught "4711" in function Foo, line 4
13471 Caught "oops" in function Foo, line 10
13472 Nothing caught
13473
13474A practical example: The following command ":LineNumber" displays the line
13475number in the script or function where it has been used: >
13476
13477 :function! LineNumber()
13478 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
13479 :endfunction
13480 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
13481<
13482 *try-nested*
13483An exception that is not caught by a try conditional can be caught by
13484a surrounding try conditional: >
13485
13486 :try
13487 : try
13488 : throw "foo"
13489 : catch /foobar/
13490 : echo "foobar"
13491 : finally
13492 : echo "inner finally"
13493 : endtry
13494 :catch /foo/
13495 : echo "foo"
13496 :endtry
13497
13498The inner try conditional does not catch the exception, just its finally
13499clause is executed. The exception is then caught by the outer try
13500conditional. The example displays "inner finally" and then "foo".
13501
13502 *throw-from-catch*
13503You can catch an exception and throw a new one to be caught elsewhere from the
13504catch clause: >
13505
13506 :function! Foo()
13507 : throw "foo"
13508 :endfunction
13509 :
13510 :function! Bar()
13511 : try
13512 : call Foo()
13513 : catch /foo/
13514 : echo "Caught foo, throw bar"
13515 : throw "bar"
13516 : endtry
13517 :endfunction
13518 :
13519 :try
13520 : call Bar()
13521 :catch /.*/
13522 : echo "Caught" v:exception
13523 :endtry
13524
13525This displays "Caught foo, throw bar" and then "Caught bar".
13526
13527 *rethrow*
13528There is no real rethrow in the Vim script language, but you may throw
13529"v:exception" instead: >
13530
13531 :function! Bar()
13532 : try
13533 : call Foo()
13534 : catch /.*/
13535 : echo "Rethrow" v:exception
13536 : throw v:exception
13537 : endtry
13538 :endfunction
13539< *try-echoerr*
13540Note that this method cannot be used to "rethrow" Vim error or interrupt
13541exceptions, because it is not possible to fake Vim internal exceptions.
13542Trying so causes an error exception. You should throw your own exception
13543denoting the situation. If you want to cause a Vim error exception containing
13544the original error exception value, you can use the |:echoerr| command: >
13545
13546 :try
13547 : try
13548 : asdf
13549 : catch /.*/
13550 : echoerr v:exception
13551 : endtry
13552 :catch /.*/
13553 : echo v:exception
13554 :endtry
13555
13556This code displays
13557
Bram Moolenaar446cb832008-06-24 21:56:24 +000013558 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000013559
13560
13561CLEANUP CODE *try-finally*
13562
13563Scripts often change global settings and restore them at their end. If the
13564user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +020013565an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +000013566a script when an error occurs or you explicitly throw an exception without
13567catching it. You can solve these problems by using a try conditional with
13568a finally clause for restoring the settings. Its execution is guaranteed on
13569normal control flow, on error, on an explicit ":throw", and on interrupt.
13570(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +020013571to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000013572clause has been executed.)
13573Example: >
13574
13575 :try
13576 : let s:saved_ts = &ts
13577 : set ts=17
13578 :
13579 : " Do the hard work here.
13580 :
13581 :finally
13582 : let &ts = s:saved_ts
13583 : unlet s:saved_ts
13584 :endtry
13585
13586This method should be used locally whenever a function or part of a script
13587changes global settings which need to be restored on failure or normal exit of
13588that function or script part.
13589
13590 *break-finally*
13591Cleanup code works also when the try block or a catch clause is left by
13592a ":continue", ":break", ":return", or ":finish".
13593 Example: >
13594
13595 :let first = 1
13596 :while 1
13597 : try
13598 : if first
13599 : echo "first"
13600 : let first = 0
13601 : continue
13602 : else
13603 : throw "second"
13604 : endif
13605 : catch /.*/
13606 : echo v:exception
13607 : break
13608 : finally
13609 : echo "cleanup"
13610 : endtry
13611 : echo "still in while"
13612 :endwhile
13613 :echo "end"
13614
13615This displays "first", "cleanup", "second", "cleanup", and "end". >
13616
13617 :function! Foo()
13618 : try
13619 : return 4711
13620 : finally
13621 : echo "cleanup\n"
13622 : endtry
13623 : echo "Foo still active"
13624 :endfunction
13625 :
13626 :echo Foo() "returned by Foo"
13627
13628This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +020013629extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +000013630return value.)
13631
13632 *except-from-finally*
13633Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
13634a finally clause is possible, but not recommended since it abandons the
13635cleanup actions for the try conditional. But, of course, interrupt and error
13636exceptions might get raised from a finally clause.
13637 Example where an error in the finally clause stops an interrupt from
13638working correctly: >
13639
13640 :try
13641 : try
13642 : echo "Press CTRL-C for interrupt"
13643 : while 1
13644 : endwhile
13645 : finally
13646 : unlet novar
13647 : endtry
13648 :catch /novar/
13649 :endtry
13650 :echo "Script still running"
13651 :sleep 1
13652
13653If you need to put commands that could fail into a finally clause, you should
13654think about catching or ignoring the errors in these commands, see
13655|catch-errors| and |ignore-errors|.
13656
13657
13658CATCHING ERRORS *catch-errors*
13659
13660If you want to catch specific errors, you just have to put the code to be
13661watched in a try block and add a catch clause for the error message. The
13662presence of the try conditional causes all errors to be converted to an
13663exception. No message is displayed and |v:errmsg| is not set then. To find
13664the right pattern for the ":catch" command, you have to know how the format of
13665the error exception is.
13666 Error exceptions have the following format: >
13667
13668 Vim({cmdname}):{errmsg}
13669or >
13670 Vim:{errmsg}
13671
13672{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +020013673the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +000013674when the error occurs outside try conditionals. It always begins with
13675a capital "E", followed by a two or three-digit error number, a colon, and
13676a space.
13677
13678Examples:
13679
13680The command >
13681 :unlet novar
13682normally produces the error message >
13683 E108: No such variable: "novar"
13684which is converted inside try conditionals to an exception >
13685 Vim(unlet):E108: No such variable: "novar"
13686
13687The command >
13688 :dwim
13689normally produces the error message >
13690 E492: Not an editor command: dwim
13691which is converted inside try conditionals to an exception >
13692 Vim:E492: Not an editor command: dwim
13693
13694You can catch all ":unlet" errors by a >
13695 :catch /^Vim(unlet):/
13696or all errors for misspelled command names by a >
13697 :catch /^Vim:E492:/
13698
13699Some error messages may be produced by different commands: >
13700 :function nofunc
13701and >
13702 :delfunction nofunc
13703both produce the error message >
13704 E128: Function name must start with a capital: nofunc
13705which is converted inside try conditionals to an exception >
13706 Vim(function):E128: Function name must start with a capital: nofunc
13707or >
13708 Vim(delfunction):E128: Function name must start with a capital: nofunc
13709respectively. You can catch the error by its number independently on the
13710command that caused it if you use the following pattern: >
13711 :catch /^Vim(\a\+):E128:/
13712
13713Some commands like >
13714 :let x = novar
13715produce multiple error messages, here: >
13716 E121: Undefined variable: novar
13717 E15: Invalid expression: novar
13718Only the first is used for the exception value, since it is the most specific
13719one (see |except-several-errors|). So you can catch it by >
13720 :catch /^Vim(\a\+):E121:/
13721
13722You can catch all errors related to the name "nofunc" by >
13723 :catch /\<nofunc\>/
13724
13725You can catch all Vim errors in the ":write" and ":read" commands by >
13726 :catch /^Vim(\(write\|read\)):E\d\+:/
13727
13728You can catch all Vim errors by the pattern >
13729 :catch /^Vim\((\a\+)\)\=:E\d\+:/
13730<
13731 *catch-text*
13732NOTE: You should never catch the error message text itself: >
13733 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +010013734only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +000013735a different language by the |:language| command. It is however helpful to
13736cite the message text in a comment: >
13737 :catch /^Vim(\a\+):E108:/ " No such variable
13738
13739
13740IGNORING ERRORS *ignore-errors*
13741
13742You can ignore errors in a specific Vim command by catching them locally: >
13743
13744 :try
13745 : write
13746 :catch
13747 :endtry
13748
13749But you are strongly recommended NOT to use this simple form, since it could
13750catch more than you want. With the ":write" command, some autocommands could
13751be executed and cause errors not related to writing, for instance: >
13752
13753 :au BufWritePre * unlet novar
13754
13755There could even be such errors you are not responsible for as a script
13756writer: a user of your script might have defined such autocommands. You would
13757then hide the error from the user.
13758 It is much better to use >
13759
13760 :try
13761 : write
13762 :catch /^Vim(write):/
13763 :endtry
13764
13765which only catches real write errors. So catch only what you'd like to ignore
13766intentionally.
13767
13768For a single command that does not cause execution of autocommands, you could
13769even suppress the conversion of errors to exceptions by the ":silent!"
13770command: >
13771 :silent! nunmap k
13772This works also when a try conditional is active.
13773
13774
13775CATCHING INTERRUPTS *catch-interrupt*
13776
13777When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +020013778the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000013779script is not terminated, then.
13780 Example: >
13781
13782 :function! TASK1()
13783 : sleep 10
13784 :endfunction
13785
13786 :function! TASK2()
13787 : sleep 20
13788 :endfunction
13789
13790 :while 1
13791 : let command = input("Type a command: ")
13792 : try
13793 : if command == ""
13794 : continue
13795 : elseif command == "END"
13796 : break
13797 : elseif command == "TASK1"
13798 : call TASK1()
13799 : elseif command == "TASK2"
13800 : call TASK2()
13801 : else
13802 : echo "\nIllegal command:" command
13803 : continue
13804 : endif
13805 : catch /^Vim:Interrupt$/
13806 : echo "\nCommand interrupted"
13807 : " Caught the interrupt. Continue with next prompt.
13808 : endtry
13809 :endwhile
13810
13811You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +020013812a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +000013813
13814For testing what happens when CTRL-C would be pressed on a specific line in
13815your script, use the debug mode and execute the |>quit| or |>interrupt|
13816command on that line. See |debug-scripts|.
13817
13818
13819CATCHING ALL *catch-all*
13820
13821The commands >
13822
13823 :catch /.*/
13824 :catch //
13825 :catch
13826
13827catch everything, error exceptions, interrupt exceptions and exceptions
13828explicitly thrown by the |:throw| command. This is useful at the top level of
13829a script in order to catch unexpected things.
13830 Example: >
13831
13832 :try
13833 :
13834 : " do the hard work here
13835 :
13836 :catch /MyException/
13837 :
13838 : " handle known problem
13839 :
13840 :catch /^Vim:Interrupt$/
13841 : echo "Script interrupted"
13842 :catch /.*/
13843 : echo "Internal error (" . v:exception . ")"
13844 : echo " - occurred at " . v:throwpoint
13845 :endtry
13846 :" end of script
13847
13848Note: Catching all might catch more things than you want. Thus, you are
13849strongly encouraged to catch only for problems that you can really handle by
13850specifying a pattern argument to the ":catch".
13851 Example: Catching all could make it nearly impossible to interrupt a script
13852by pressing CTRL-C: >
13853
13854 :while 1
13855 : try
13856 : sleep 1
13857 : catch
13858 : endtry
13859 :endwhile
13860
13861
13862EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
13863
13864Exceptions may be used during execution of autocommands. Example: >
13865
13866 :autocmd User x try
13867 :autocmd User x throw "Oops!"
13868 :autocmd User x catch
13869 :autocmd User x echo v:exception
13870 :autocmd User x endtry
13871 :autocmd User x throw "Arrgh!"
13872 :autocmd User x echo "Should not be displayed"
13873 :
13874 :try
13875 : doautocmd User x
13876 :catch
13877 : echo v:exception
13878 :endtry
13879
13880This displays "Oops!" and "Arrgh!".
13881
13882 *except-autocmd-Pre*
13883For some commands, autocommands get executed before the main action of the
13884command takes place. If an exception is thrown and not caught in the sequence
13885of autocommands, the sequence and the command that caused its execution are
13886abandoned and the exception is propagated to the caller of the command.
13887 Example: >
13888
13889 :autocmd BufWritePre * throw "FAIL"
13890 :autocmd BufWritePre * echo "Should not be displayed"
13891 :
13892 :try
13893 : write
13894 :catch
13895 : echo "Caught:" v:exception "from" v:throwpoint
13896 :endtry
13897
13898Here, the ":write" command does not write the file currently being edited (as
13899you can see by checking 'modified'), since the exception from the BufWritePre
13900autocommand abandons the ":write". The exception is then caught and the
13901script displays: >
13902
13903 Caught: FAIL from BufWrite Auto commands for "*"
13904<
13905 *except-autocmd-Post*
13906For some commands, autocommands get executed after the main action of the
13907command has taken place. If this main action fails and the command is inside
13908an active try conditional, the autocommands are skipped and an error exception
13909is thrown that can be caught by the caller of the command.
13910 Example: >
13911
13912 :autocmd BufWritePost * echo "File successfully written!"
13913 :
13914 :try
13915 : write /i/m/p/o/s/s/i/b/l/e
13916 :catch
13917 : echo v:exception
13918 :endtry
13919
13920This just displays: >
13921
13922 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
13923
13924If you really need to execute the autocommands even when the main action
13925fails, trigger the event from the catch clause.
13926 Example: >
13927
13928 :autocmd BufWritePre * set noreadonly
13929 :autocmd BufWritePost * set readonly
13930 :
13931 :try
13932 : write /i/m/p/o/s/s/i/b/l/e
13933 :catch
13934 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
13935 :endtry
13936<
13937You can also use ":silent!": >
13938
13939 :let x = "ok"
13940 :let v:errmsg = ""
13941 :autocmd BufWritePost * if v:errmsg != ""
13942 :autocmd BufWritePost * let x = "after fail"
13943 :autocmd BufWritePost * endif
13944 :try
13945 : silent! write /i/m/p/o/s/s/i/b/l/e
13946 :catch
13947 :endtry
13948 :echo x
13949
13950This displays "after fail".
13951
13952If the main action of the command does not fail, exceptions from the
13953autocommands will be catchable by the caller of the command: >
13954
13955 :autocmd BufWritePost * throw ":-("
13956 :autocmd BufWritePost * echo "Should not be displayed"
13957 :
13958 :try
13959 : write
13960 :catch
13961 : echo v:exception
13962 :endtry
13963<
13964 *except-autocmd-Cmd*
13965For some commands, the normal action can be replaced by a sequence of
13966autocommands. Exceptions from that sequence will be catchable by the caller
13967of the command.
13968 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +020013969had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +000013970some way. >
13971
13972 :if !exists("cnt")
13973 : let cnt = 0
13974 :
13975 : autocmd BufWriteCmd * if &modified
13976 : autocmd BufWriteCmd * let cnt = cnt + 1
13977 : autocmd BufWriteCmd * if cnt % 3 == 2
13978 : autocmd BufWriteCmd * throw "BufWriteCmdError"
13979 : autocmd BufWriteCmd * endif
13980 : autocmd BufWriteCmd * write | set nomodified
13981 : autocmd BufWriteCmd * if cnt % 3 == 0
13982 : autocmd BufWriteCmd * throw "BufWriteCmdError"
13983 : autocmd BufWriteCmd * endif
13984 : autocmd BufWriteCmd * echo "File successfully written!"
13985 : autocmd BufWriteCmd * endif
13986 :endif
13987 :
13988 :try
13989 : write
13990 :catch /^BufWriteCmdError$/
13991 : if &modified
13992 : echo "Error on writing (file contents not changed)"
13993 : else
13994 : echo "Error after writing"
13995 : endif
13996 :catch /^Vim(write):/
13997 : echo "Error on writing"
13998 :endtry
13999
14000When this script is sourced several times after making changes, it displays
14001first >
14002 File successfully written!
14003then >
14004 Error on writing (file contents not changed)
14005then >
14006 Error after writing
14007etc.
14008
14009 *except-autocmd-ill*
14010You cannot spread a try conditional over autocommands for different events.
14011The following code is ill-formed: >
14012
14013 :autocmd BufWritePre * try
14014 :
14015 :autocmd BufWritePost * catch
14016 :autocmd BufWritePost * echo v:exception
14017 :autocmd BufWritePost * endtry
14018 :
14019 :write
14020
14021
14022EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
14023
14024Some programming languages allow to use hierarchies of exception classes or to
14025pass additional information with the object of an exception class. You can do
14026similar things in Vim.
14027 In order to throw an exception from a hierarchy, just throw the complete
14028class name with the components separated by a colon, for instance throw the
14029string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
14030 When you want to pass additional information with your exception class, add
14031it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
14032for an error when writing "myfile".
14033 With the appropriate patterns in the ":catch" command, you can catch for
14034base classes or derived classes of your hierarchy. Additional information in
14035parentheses can be cut out from |v:exception| with the ":substitute" command.
14036 Example: >
14037
14038 :function! CheckRange(a, func)
14039 : if a:a < 0
14040 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
14041 : endif
14042 :endfunction
14043 :
14044 :function! Add(a, b)
14045 : call CheckRange(a:a, "Add")
14046 : call CheckRange(a:b, "Add")
14047 : let c = a:a + a:b
14048 : if c < 0
14049 : throw "EXCEPT:MATHERR:OVERFLOW"
14050 : endif
14051 : return c
14052 :endfunction
14053 :
14054 :function! Div(a, b)
14055 : call CheckRange(a:a, "Div")
14056 : call CheckRange(a:b, "Div")
14057 : if (a:b == 0)
14058 : throw "EXCEPT:MATHERR:ZERODIV"
14059 : endif
14060 : return a:a / a:b
14061 :endfunction
14062 :
14063 :function! Write(file)
14064 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +000014065 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +000014066 : catch /^Vim(write):/
14067 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
14068 : endtry
14069 :endfunction
14070 :
14071 :try
14072 :
14073 : " something with arithmetics and I/O
14074 :
14075 :catch /^EXCEPT:MATHERR:RANGE/
14076 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
14077 : echo "Range error in" function
14078 :
14079 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
14080 : echo "Math error"
14081 :
14082 :catch /^EXCEPT:IO/
14083 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
14084 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
14085 : if file !~ '^/'
14086 : let file = dir . "/" . file
14087 : endif
14088 : echo 'I/O error for "' . file . '"'
14089 :
14090 :catch /^EXCEPT/
14091 : echo "Unspecified error"
14092 :
14093 :endtry
14094
14095The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
14096a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
14097exceptions with the "Vim" prefix; they are reserved for Vim.
14098 Vim error exceptions are parameterized with the name of the command that
14099failed, if known. See |catch-errors|.
14100
14101
14102PECULIARITIES
14103 *except-compat*
14104The exception handling concept requires that the command sequence causing the
14105exception is aborted immediately and control is transferred to finally clauses
14106and/or a catch clause.
14107
14108In the Vim script language there are cases where scripts and functions
14109continue after an error: in functions without the "abort" flag or in a command
14110after ":silent!", control flow goes to the following line, and outside
14111functions, control flow goes to the line following the outermost ":endwhile"
14112or ":endif". On the other hand, errors should be catchable as exceptions
14113(thus, requiring the immediate abortion).
14114
14115This problem has been solved by converting errors to exceptions and using
14116immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +020014117conditional is active. This is no restriction since an (error) exception can
14118be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +000014119termination without catching the error, just use a try conditional without
14120catch clause. (You can cause cleanup code being executed before termination
14121by specifying a finally clause.)
14122
14123When no try conditional is active, the usual abortion and continuation
14124behavior is used instead of immediate abortion. This ensures compatibility of
14125scripts written for Vim 6.1 and earlier.
14126
14127However, when sourcing an existing script that does not use exception handling
14128commands (or when calling one of its functions) from inside an active try
14129conditional of a new script, you might change the control flow of the existing
14130script on error. You get the immediate abortion on error and can catch the
14131error in the new script. If however the sourced script suppresses error
14132messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +020014133|v:errmsg| if appropriate), its execution path is not changed. The error is
14134not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +000014135where this happens is for scripts that don't care about errors and produce
14136error messages. You probably won't want to use such code from your new
14137scripts.
14138
14139 *except-syntax-err*
14140Syntax errors in the exception handling commands are never caught by any of
14141the ":catch" commands of the try conditional they belong to. Its finally
14142clauses, however, is executed.
14143 Example: >
14144
14145 :try
14146 : try
14147 : throw 4711
14148 : catch /\(/
14149 : echo "in catch with syntax error"
14150 : catch
14151 : echo "inner catch-all"
14152 : finally
14153 : echo "inner finally"
14154 : endtry
14155 :catch
14156 : echo 'outer catch-all caught "' . v:exception . '"'
14157 : finally
14158 : echo "outer finally"
14159 :endtry
14160
14161This displays: >
14162 inner finally
14163 outer catch-all caught "Vim(catch):E54: Unmatched \("
14164 outer finally
14165The original exception is discarded and an error exception is raised, instead.
14166
14167 *except-single-line*
14168The ":try", ":catch", ":finally", and ":endtry" commands can be put on
14169a single line, but then syntax errors may make it difficult to recognize the
14170"catch" line, thus you better avoid this.
14171 Example: >
14172 :try | unlet! foo # | catch | endtry
14173raises an error exception for the trailing characters after the ":unlet!"
14174argument, but does not see the ":catch" and ":endtry" commands, so that the
14175error exception is discarded and the "E488: Trailing characters" message gets
14176displayed.
14177
14178 *except-several-errors*
14179When several errors appear in a single command, the first error message is
14180usually the most specific one and therefor converted to the error exception.
14181 Example: >
14182 echo novar
14183causes >
14184 E121: Undefined variable: novar
14185 E15: Invalid expression: novar
14186The value of the error exception inside try conditionals is: >
14187 Vim(echo):E121: Undefined variable: novar
14188< *except-syntax-error*
14189But when a syntax error is detected after a normal error in the same command,
14190the syntax error is used for the exception being thrown.
14191 Example: >
14192 unlet novar #
14193causes >
14194 E108: No such variable: "novar"
14195 E488: Trailing characters
14196The value of the error exception inside try conditionals is: >
14197 Vim(unlet):E488: Trailing characters
14198This is done because the syntax error might change the execution path in a way
14199not intended by the user. Example: >
14200 try
14201 try | unlet novar # | catch | echo v:exception | endtry
14202 catch /.*/
14203 echo "outer catch:" v:exception
14204 endtry
14205This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
14206a "E600: Missing :endtry" error message is given, see |except-single-line|.
14207
14208==============================================================================
142099. Examples *eval-examples*
14210
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014211Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000014212>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010014213 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014214 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +000014215 : let n = a:nr
14216 : let r = ""
14217 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014218 : let r = '01'[n % 2] . r
14219 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +000014220 : endwhile
14221 : return r
14222 :endfunc
14223
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014224 :" The function String2Bin() converts each character in a string to a
14225 :" binary string, separated with dashes.
14226 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +000014227 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014228 : for ix in range(strlen(a:str))
14229 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
14230 : endfor
14231 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +000014232 :endfunc
14233
14234Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014235 :echo Nr2Bin(32)
14236result: "100000" >
14237 :echo String2Bin("32")
14238result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +000014239
14240
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014241Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000014242
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014243This example sorts lines with a specific compare function. >
14244
14245 :func SortBuffer()
14246 : let lines = getline(1, '$')
14247 : call sort(lines, function("Strcmp"))
14248 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +000014249 :endfunction
14250
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014251As a one-liner: >
14252 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +000014253
Bram Moolenaar071d4272004-06-13 20:20:40 +000014254
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014255scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000014256 *sscanf*
14257There is no sscanf() function in Vim. If you need to extract parts from a
14258line, you can use matchstr() and substitute() to do it. This example shows
14259how to get the file name, line number and column number out of a line like
14260"foobar.txt, 123, 45". >
14261 :" Set up the match bit
14262 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
14263 :"get the part matching the whole expression
14264 :let l = matchstr(line, mx)
14265 :"get each item out of the match
14266 :let file = substitute(l, mx, '\1', '')
14267 :let lnum = substitute(l, mx, '\2', '')
14268 :let col = substitute(l, mx, '\3', '')
14269
14270The input is in the variable "line", the results in the variables "file",
14271"lnum" and "col". (idea from Michael Geddes)
14272
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014273
14274getting the scriptnames in a Dictionary ~
14275 *scriptnames-dictionary*
14276The |:scriptnames| command can be used to get a list of all script files that
14277have been sourced. There is no equivalent function or variable for this
14278(because it's rarely needed). In case you need to manipulate the list this
14279code can be used: >
14280 " Get the output of ":scriptnames" in the scriptnames_output variable.
14281 let scriptnames_output = ''
14282 redir => scriptnames_output
14283 silent scriptnames
14284 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010014285
Bram Moolenaar446cb832008-06-24 21:56:24 +000014286 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014287 " "scripts" dictionary.
14288 let scripts = {}
14289 for line in split(scriptnames_output, "\n")
14290 " Only do non-blank lines.
14291 if line =~ '\S'
14292 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +000014293 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014294 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +000014295 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014296 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +000014297 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014298 endif
14299 endfor
14300 unlet scriptnames_output
14301
Bram Moolenaar071d4272004-06-13 20:20:40 +000014302==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001430310. Vim script versions *vimscript-version* *vimscript-versions*
Bram Moolenaar911ead12019-04-21 00:03:35 +020014304 *scriptversion*
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014305Over time many features have been added to Vim script. This includes Ex
14306commands, functions, variable types, etc. Each individual feature can be
14307checked with the |has()| and |exists()| functions.
14308
14309Sometimes old syntax of functionality gets in the way of making Vim better.
14310When support is taken away this will break older Vim scripts. To make this
14311explicit the |:scriptversion| command can be used. When a Vim script is not
14312compatible with older versions of Vim this will give an explicit error,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020014313instead of failing in mysterious ways.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014314
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020014315 *scriptversion-1* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014316 :scriptversion 1
14317< This is the original Vim script, same as not using a |:scriptversion|
14318 command. Can be used to go back to old syntax for a range of lines.
14319 Test for support with: >
14320 has('vimscript-1')
14321
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020014322< *scriptversion-2* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014323 :scriptversion 2
Bram Moolenaar68e65602019-05-26 21:33:31 +020014324< String concatenation with "." is not supported, use ".." instead.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014325 This avoids the ambiguity using "." for Dict member access and
14326 floating point numbers. Now ".5" means the number 0.5.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +020014327
14328 *scriptversion-3* >
Bram Moolenaar911ead12019-04-21 00:03:35 +020014329 :scriptversion 3
14330< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't
14331 work as |v:version| anymore, it can be used as a normal variable.
14332 Same for some obvious names as "count" and others.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014333
Bram Moolenaar911ead12019-04-21 00:03:35 +020014334 Test for support with: >
14335 has('vimscript-3')
Bram Moolenaar60a8de22019-09-15 14:33:22 +020014336<
14337 *scriptversion-4* >
14338 :scriptversion 4
Bram Moolenaarc17e66c2020-06-02 21:38:22 +020014339< Numbers with a leading zero are not recognized as octal. "0o" or "0O"
14340 is still recognized as octal. With the
Bram Moolenaar60a8de22019-09-15 14:33:22 +020014341 previous version you get: >
Bram Moolenaarc17e66c2020-06-02 21:38:22 +020014342 echo 017 " displays 15 (octal)
14343 echo 0o17 " displays 15 (octal)
14344 echo 018 " displays 18 (decimal)
Bram Moolenaar60a8de22019-09-15 14:33:22 +020014345< with script version 4: >
Bram Moolenaarc17e66c2020-06-02 21:38:22 +020014346 echo 017 " displays 17 (decimal)
14347 echo 0o17 " displays 15 (octal)
14348 echo 018 " displays 18 (decimal)
Bram Moolenaar60a8de22019-09-15 14:33:22 +020014349< Also, it is possible to use single quotes inside numbers to make them
14350 easier to read: >
14351 echo 1'000'000
14352< The quotes must be surrounded by digits.
14353
14354 Test for support with: >
14355 has('vimscript-4')
Bram Moolenaar558ca4a2019-04-04 18:15:38 +020014356
14357==============================================================================
1435811. No +eval feature *no-eval-feature*
Bram Moolenaar071d4272004-06-13 20:20:40 +000014359
14360When the |+eval| feature was disabled at compile time, none of the expression
14361evaluation commands are available. To prevent this from causing Vim scripts
14362to generate all kinds of errors, the ":if" and ":endif" commands are still
14363recognized, though the argument of the ":if" and everything between the ":if"
14364and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
14365only if the commands are at the start of the line. The ":else" command is not
14366recognized.
14367
14368Example of how to avoid executing commands when the |+eval| feature is
14369missing: >
14370
14371 :if 1
14372 : echo "Expression evaluation is compiled in"
14373 :else
14374 : echo "You will _never_ see this message"
14375 :endif
14376
Bram Moolenaar773a97c2019-06-06 20:39:55 +020014377To execute a command only when the |+eval| feature is disabled can be done in
14378two ways. The simplest is to exit the script (or Vim) prematurely: >
14379 if 1
14380 echo "commands executed with +eval"
14381 finish
14382 endif
14383 args " command executed without +eval
14384
14385If you do not want to abort loading the script you can use a trick, as this
14386example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +020014387
14388 silent! while 0
14389 set history=111
14390 silent! endwhile
14391
14392When the |+eval| feature is available the command is skipped because of the
14393"while 0". Without the |+eval| feature the "while 0" is an error, which is
14394silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020014395
Bram Moolenaar071d4272004-06-13 20:20:40 +000014396==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001439712. The sandbox *eval-sandbox* *sandbox* *E48*
Bram Moolenaar071d4272004-06-13 20:20:40 +000014398
Bram Moolenaar368373e2010-07-19 20:46:22 +020014399The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
14400'foldtext' options may be evaluated in a sandbox. This means that you are
14401protected from these expressions having nasty side effects. This gives some
14402safety for when these options are set from a modeline. It is also used when
14403the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000014404The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000014405
14406These items are not allowed in the sandbox:
14407 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +020014408 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000014409 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000014410 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000014411 - executing a shell command
14412 - reading or writing a file
14413 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000014414 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000014415This is not guaranteed 100% secure, but it should block most attacks.
14416
14417 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000014418:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000014419 option that may have been set from a modeline, e.g.
14420 'foldexpr'.
14421
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000014422 *sandbox-option*
14423A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000014424have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000014425restrictive, thus this only happens when the option was set from an insecure
14426location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000014427- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000014428- while executing in the sandbox
14429- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +020014430- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000014431
14432Note that when in the sandbox and saving an option value and restoring it, the
14433option will still be marked as it was set in the sandbox.
14434
14435==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02001443613. Textlock *textlock*
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000014437
14438In a few situations it is not allowed to change the text in the buffer, jump
14439to another window and some other things that might confuse or break what Vim
14440is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +020014441actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000014442happen any moment the mouse cursor is resting at some position.
14443
14444This is not allowed when the textlock is active:
14445 - changing the buffer text
14446 - jumping to another buffer or window
14447 - editing another file
14448 - closing a window or quitting Vim
14449 - etc.
14450
Bram Moolenaar071d4272004-06-13 20:20:40 +000014451
Bram Moolenaar91f84f62018-07-29 15:07:52 +020014452 vim:tw=78:ts=8:noet:ft=help:norl: