|
|
|
|
@ -1,4 +1,4 @@
|
|
|
|
|
*eval.txt* For Vim version 7.0aa. Last change: 2005 Jan 07
|
|
|
|
|
*eval.txt* For Vim version 7.0aa. Last change: 2005 Jan 08
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
|
|
@ -12,24 +12,30 @@ Note: Expression evaluation can be disabled at compile time. If this has been
|
|
|
|
|
done, the features in this document are not available. See |+eval| and the
|
|
|
|
|
last chapter below.
|
|
|
|
|
|
|
|
|
|
1. Variables |variables|
|
|
|
|
|
2. Expression syntax |expression-syntax|
|
|
|
|
|
3. Internal variable |internal-variables|
|
|
|
|
|
4. Builtin Functions |functions|
|
|
|
|
|
5. Defining functions |user-functions|
|
|
|
|
|
6. Curly braces names |curly-braces-names|
|
|
|
|
|
7. Commands |expression-commands|
|
|
|
|
|
8. Exception handling |exception-handling|
|
|
|
|
|
9. Examples |eval-examples|
|
|
|
|
|
10. No +eval feature |no-eval-feature|
|
|
|
|
|
11. The sandbox |eval-sandbox|
|
|
|
|
|
1. Variables |variables|
|
|
|
|
|
1.1 Variable types
|
|
|
|
|
1.2 Function reference |Funcref|
|
|
|
|
|
1.3 List |List|
|
|
|
|
|
1.4 More about variables |more-variables|
|
|
|
|
|
2. Expression syntax |expression-syntax|
|
|
|
|
|
3. Internal variable |internal-variables|
|
|
|
|
|
4. Builtin Functions |functions|
|
|
|
|
|
5. Defining functions |user-functions|
|
|
|
|
|
6. Curly braces names |curly-braces-names|
|
|
|
|
|
7. Commands |expression-commands|
|
|
|
|
|
8. Exception handling |exception-handling|
|
|
|
|
|
9. Examples |eval-examples|
|
|
|
|
|
10. No +eval feature |no-eval-feature|
|
|
|
|
|
11. The sandbox |eval-sandbox|
|
|
|
|
|
|
|
|
|
|
{Vi does not have any of these commands}
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
|
|
|
1. Variables *variables*
|
|
|
|
|
|
|
|
|
|
There are three types of variables:
|
|
|
|
|
1.1 Variable types ~
|
|
|
|
|
|
|
|
|
|
There are four types of variables:
|
|
|
|
|
|
|
|
|
|
Number a 32 bit signed number
|
|
|
|
|
String a NUL terminated string of 8-bit unsigned characters (bytes)
|
|
|
|
|
@ -67,63 +73,226 @@ Note that in the command >
|
|
|
|
|
use strlen(): >
|
|
|
|
|
:if strlen("foo")
|
|
|
|
|
|
|
|
|
|
List and Funcref types are not automatically converted.
|
|
|
|
|
|
|
|
|
|
Function references ~
|
|
|
|
|
*Funcref*
|
|
|
|
|
*E706*
|
|
|
|
|
You will get an error if you try to change the type of a variable. You need
|
|
|
|
|
to |:unlet| it first to avoid this error. String and Number are considered
|
|
|
|
|
equivalent though. >
|
|
|
|
|
:let l = "string"
|
|
|
|
|
:let l = 44
|
|
|
|
|
:let l = [1, 2, 3] " error!
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1.2 Function reference ~
|
|
|
|
|
*Funcref* *E695* *E703*
|
|
|
|
|
A Funcref variable is obtained with the |function()| function. It can be used
|
|
|
|
|
in an expression to invoke the function it refers to by using it in the place
|
|
|
|
|
of a function name, before the parenthesis around the arguments. Example: >
|
|
|
|
|
|
|
|
|
|
:let Fn = function("MyFunc")
|
|
|
|
|
:echo Fn()
|
|
|
|
|
<
|
|
|
|
|
*E704* *E705* *E707*
|
|
|
|
|
A Funcref variable must start with a capital, "s:", "w:" or "b:". You cannot
|
|
|
|
|
have both a Funcref variable and a function with the same name.
|
|
|
|
|
|
|
|
|
|
Note that this doesn't work with |:call|, because its argument is not an
|
|
|
|
|
expression.
|
|
|
|
|
The name of the referenced function can be obtained with |string()|. A
|
|
|
|
|
Funcref variable must start with a capital, "s:", "w:" or "b:".
|
|
|
|
|
Note that a Funcref cannot be used with |:call|, because its argument is not
|
|
|
|
|
an expression.
|
|
|
|
|
|
|
|
|
|
The name of the referenced function can be obtained with |string()|. >
|
|
|
|
|
:echo "The function is " . string(Myfunc)
|
|
|
|
|
|
|
|
|
|
You can use |call()| to invoke a Funcref and use a list variable for the
|
|
|
|
|
arguments: >
|
|
|
|
|
:let r = call(Myfunc, mylist)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Lists ~
|
|
|
|
|
*List*
|
|
|
|
|
1.3 List ~
|
|
|
|
|
*List* *E686*
|
|
|
|
|
A List is an ordered sequence of items. An item can be of any type. Items
|
|
|
|
|
can be accessed by their index number. Items can be added and removed at any
|
|
|
|
|
position in the sequence.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
List creation ~
|
|
|
|
|
*E696* *E697*
|
|
|
|
|
A List is created with a comma separated list of items in square brackets.
|
|
|
|
|
Example: >
|
|
|
|
|
:let mylist = [1, 'two', 3, "four"]
|
|
|
|
|
Examples: >
|
|
|
|
|
:let mylist = [1, two, 3, "four"]
|
|
|
|
|
:let emptylist = []
|
|
|
|
|
|
|
|
|
|
An item can be any expression. Using a List for an item creates a
|
|
|
|
|
two-dimensional List: >
|
|
|
|
|
:let mylist = [[11, 12], [21, 22], [31, 32]]
|
|
|
|
|
nested List: >
|
|
|
|
|
:let nestlist = [[11, 12], [21, 22], [31, 32]]
|
|
|
|
|
|
|
|
|
|
An extra comma after the last item is ignored.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
List index ~
|
|
|
|
|
*list-index* *E684*
|
|
|
|
|
An item in the List can be accessed by putting the index in square brackets
|
|
|
|
|
after the List: >
|
|
|
|
|
after the List. Indexes are zero-based, thus the first item has index zero. >
|
|
|
|
|
:let item = mylist[0] " get the first item: 1
|
|
|
|
|
:let item = mylist[2] " get the third item: 3
|
|
|
|
|
|
|
|
|
|
When the item is a list again this can be repeated: >
|
|
|
|
|
:let item = nestlist[0][1] " get the first list, second item: 12
|
|
|
|
|
<
|
|
|
|
|
*list-index*
|
|
|
|
|
Indexes are zero-based, thus the first item has index zero. A negative index
|
|
|
|
|
is counted from the end. Index -1 refers to the last item in the List, -2 to
|
|
|
|
|
the last but one item, etc. >
|
|
|
|
|
A negative index is counted from the end. Index -1 refers to the last item in
|
|
|
|
|
the List, -2 to the last but one item, etc. >
|
|
|
|
|
:let last = mylist[-1] " get the last item: "four"
|
|
|
|
|
|
|
|
|
|
To avoid an error for an invalid index use the |get()| function. When an item
|
|
|
|
|
is not available it returns zero, unless you specify a default value: >
|
|
|
|
|
:echo get(mylist, idx)
|
|
|
|
|
:echo get(mylist, idx, "NONE")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
List concatenation ~
|
|
|
|
|
|
|
|
|
|
Two lists can be concatenated with the "+" operator: >
|
|
|
|
|
:let longlist = mylist + [5, 6]
|
|
|
|
|
|
|
|
|
|
To prepend or append an item turn the item into a list by putting [] around
|
|
|
|
|
it. To change a list in-place see |list-modification| below.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sublist ~
|
|
|
|
|
|
|
|
|
|
A part of the List can be obtained by specifying the first and last index,
|
|
|
|
|
separated by a colon in square brackets: >
|
|
|
|
|
:let smalllist = mylist[2:-1] " get List [3, "four"]
|
|
|
|
|
:let shortlist = mylist[2:-1] " get List [3, "four"]
|
|
|
|
|
|
|
|
|
|
Omitting the first index is similar to zero. Omitting the last index is
|
|
|
|
|
similar to -1. The difference is that there is no error if the items are not
|
|
|
|
|
available. >
|
|
|
|
|
:let endlist = [2:] " from item 2 to the end: [3, "four"]
|
|
|
|
|
:let shortlist = [1:1] " List with one item: ['two']
|
|
|
|
|
:let otherlist = [:] " make a copy
|
|
|
|
|
:let shortlist = [2:2] " List with one item: [3]
|
|
|
|
|
:let otherlist = [:] " make a copy of the List
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
More about variables ~
|
|
|
|
|
List identity ~
|
|
|
|
|
|
|
|
|
|
When variable "aa" is a list and you assign it to another variable "bb", both
|
|
|
|
|
variables refer to the same list. Thus changing the list "aa" will also
|
|
|
|
|
change "bb": >
|
|
|
|
|
:let aa = [1, 2, 3]
|
|
|
|
|
:let bb = aa
|
|
|
|
|
:call add(aa, 4)
|
|
|
|
|
:echo bb
|
|
|
|
|
[1, 2, 3, 4]
|
|
|
|
|
|
|
|
|
|
Making a copy of a list is done with the |copy()| function. Using [:] also
|
|
|
|
|
works, as explained above. This creates a shallow copy of the list: Changing
|
|
|
|
|
a list in the list will also change the copied list: >
|
|
|
|
|
:let aa = [[1, 'a'], 2, 3]
|
|
|
|
|
:let bb = copy(aa)
|
|
|
|
|
:let aa = aa + [4]
|
|
|
|
|
:let aa[0][1] = 'aaa'
|
|
|
|
|
:echo aa
|
|
|
|
|
[[1, aaa], 2, 3, 4]
|
|
|
|
|
:echo bb
|
|
|
|
|
[[1, aaa], 2, 3]
|
|
|
|
|
|
|
|
|
|
To make a completely independent list use |deepcopy()|. This also copies the
|
|
|
|
|
values in the list, recursively.
|
|
|
|
|
|
|
|
|
|
The operator "is" can be used to check if two variables refer to the same
|
|
|
|
|
list. "isnot" does the opposite. In contrast "==" compares if two lists have
|
|
|
|
|
the same value.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
List unpack ~
|
|
|
|
|
|
|
|
|
|
To unpack the items in a list to individual variables, put the variables in
|
|
|
|
|
square brackets, like list items: >
|
|
|
|
|
:let [var1, var2] = mylist
|
|
|
|
|
|
|
|
|
|
When the number of variables does not match the number of items in the list
|
|
|
|
|
this produces an error. To handle any extra items from the list append ";"
|
|
|
|
|
and a variable name: >
|
|
|
|
|
:let [var1, var2; rest] = mylist
|
|
|
|
|
|
|
|
|
|
This works like: >
|
|
|
|
|
:let var1 = mylist[0]
|
|
|
|
|
:let var2 = mylist[1]
|
|
|
|
|
:let rest = mjlist[2:]
|
|
|
|
|
|
|
|
|
|
Except that there is no error if there are only two items. "rest" will be an
|
|
|
|
|
empty list then.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
List modification ~
|
|
|
|
|
*list-modification*
|
|
|
|
|
To change a specific item of a list use |:let|: >
|
|
|
|
|
:let list[4] = "four"
|
|
|
|
|
:let listlist[0][3] = item
|
|
|
|
|
|
|
|
|
|
Adding and removing items from a list is done with functions. Here are a few
|
|
|
|
|
examples: >
|
|
|
|
|
:call insert(list, 'a') " prepend item 'a'
|
|
|
|
|
:call insert(list, 'a', 3) " insert item 'a' before list[3]
|
|
|
|
|
:call add(list, "new") " append String item
|
|
|
|
|
:call add(list, [1, 2]) " append List as one new item
|
|
|
|
|
:call extend(list, [1, 2]) " extend the list with two more items
|
|
|
|
|
:let i = remove(list, 3) " remove item 3
|
|
|
|
|
:let l = remove(list, 3, -1) " remove items 3 to last item
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For loop ~
|
|
|
|
|
|
|
|
|
|
The |:for| loop executes commands for each item in a list. Example: >
|
|
|
|
|
:for i in mylist
|
|
|
|
|
: call Doit(i)
|
|
|
|
|
:endfor
|
|
|
|
|
|
|
|
|
|
This works like: >
|
|
|
|
|
:let index = 0
|
|
|
|
|
:while index < len(mylist)
|
|
|
|
|
: let i = mylist[index]
|
|
|
|
|
: :call Doit(i)
|
|
|
|
|
: let index = index + 1
|
|
|
|
|
:endwhile
|
|
|
|
|
|
|
|
|
|
Note that all items in the list should be of the same type, otherwise this
|
|
|
|
|
results in an error. To avoid this |:unlet| the variable at the end of the
|
|
|
|
|
loop.
|
|
|
|
|
|
|
|
|
|
Just like the |:let| command, |:for| also accepts a list of variables. This
|
|
|
|
|
requires the argument to be a list of lists. >
|
|
|
|
|
:for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
|
|
|
|
|
: call Doit(lnum, col)
|
|
|
|
|
:endfor
|
|
|
|
|
|
|
|
|
|
This works like a |:let| command is done for each list item. Again, the types
|
|
|
|
|
must remain the same to avoid an error.
|
|
|
|
|
|
|
|
|
|
It is also possible to put remaining items in a list: >
|
|
|
|
|
:for [i, j; rest] in listlist
|
|
|
|
|
: call Doit(i, j)
|
|
|
|
|
: if !empty(rest)
|
|
|
|
|
: echo "remainder: " . string(rest)
|
|
|
|
|
: endif
|
|
|
|
|
:endfor
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
List functions ~
|
|
|
|
|
|
|
|
|
|
Functions that are useful with a List: >
|
|
|
|
|
:let r = call(funcname, list) " invoke a function with argument list
|
|
|
|
|
:if empty(list) " check if list is empty
|
|
|
|
|
:let l = len(list) " number of items in a list
|
|
|
|
|
:let xs = count(list, 'x') " count occurrences of a value
|
|
|
|
|
:let i = index(list, 'x') " find a value
|
|
|
|
|
:let lines = getline(1, 10) " get ten text lines from buffer
|
|
|
|
|
:call append('$', lines) " append text lines in buffer
|
|
|
|
|
:let list = str2list("a b c") " create list from items in a string
|
|
|
|
|
:let s = string() " String representation of a list
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1.4 More about variables ~
|
|
|
|
|
*more-variables*
|
|
|
|
|
If you need to know the type of a variable or expression, use the |type()|
|
|
|
|
|
function.
|
|
|
|
|
|
|
|
|
|
@ -303,10 +472,12 @@ Examples:
|
|
|
|
|
"abc" ==? "Abc" evaluates to 1
|
|
|
|
|
"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
|
|
|
|
|
|
|
|
|
|
*E691* *E692*
|
|
|
|
|
A List can only be compared with a List and only "equal", "not equal" and "is"
|
|
|
|
|
can be used. This compares the values of the list, recursively. Ignoring
|
|
|
|
|
case means case is ignored when comparing item values.
|
|
|
|
|
|
|
|
|
|
*E693* *E694*
|
|
|
|
|
A Funcref can only be compared with a Funcref and only "equal" and "not equal"
|
|
|
|
|
can be used. Case is never ignored.
|
|
|
|
|
|
|
|
|
|
@ -966,6 +1137,7 @@ delete( {fname}) Number delete file {fname}
|
|
|
|
|
did_filetype() Number TRUE if FileType autocommand event used
|
|
|
|
|
diff_filler( {lnum}) Number diff filler lines about {lnum}
|
|
|
|
|
diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
|
|
|
|
|
empty( {expr}) Number TRUE if {expr} is empty
|
|
|
|
|
escape( {string}, {chars}) String escape {chars} in {string} with '\'
|
|
|
|
|
eventhandler( ) Number TRUE if inside an event handler
|
|
|
|
|
executable( {expr}) Number 1 if executable {expr} exists
|
|
|
|
|
@ -1106,6 +1278,7 @@ add({list}, {expr}) *add()*
|
|
|
|
|
:call add(mylist, "woodstock")
|
|
|
|
|
< Note that when {expr} is a List it is appended as a single
|
|
|
|
|
item. Use |extend()| to concatenate Lists.
|
|
|
|
|
Use |insert()| to add an item at another position.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
append({lnum}, {expr}) *append()*
|
|
|
|
|
@ -1273,7 +1446,7 @@ byteidx({expr}, {nr}) *byteidx()*
|
|
|
|
|
If there are exactly {nr} characters the length of the string
|
|
|
|
|
is returned.
|
|
|
|
|
|
|
|
|
|
call({func}, {arglist}) *call()*
|
|
|
|
|
call({func}, {arglist}) *call()* *E699*
|
|
|
|
|
Call function {func} with the items in List {arglist} as
|
|
|
|
|
arguments.
|
|
|
|
|
{func} can either be a Funcref or the name of a function.
|
|
|
|
|
@ -1437,7 +1610,7 @@ cursor({lnum}, {col}) *cursor()*
|
|
|
|
|
If {col} is zero, the cursor will stay in the current column.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
deepcopy({expr}) *deepcopy()*
|
|
|
|
|
deepcopy({expr}) *deepcopy()* *E698*
|
|
|
|
|
Make a copy of {expr}. For Numbers and Strings this isn't
|
|
|
|
|
different from using {expr} directly.
|
|
|
|
|
When {expr} is a List a full copy is created. This means
|
|
|
|
|
@ -1484,6 +1657,13 @@ diff_hlID({lnum}, {col}) *diff_hlID()*
|
|
|
|
|
The highlight ID can be used with |synIDattr()| to obtain
|
|
|
|
|
syntax information about the highlighting.
|
|
|
|
|
|
|
|
|
|
empty({expr}) *empty()*
|
|
|
|
|
Return the Number 1 if {expr} is empty, zero otherwise.
|
|
|
|
|
A List is empty when it does not have any items.
|
|
|
|
|
A Number is empty when its value is zero.
|
|
|
|
|
For a long List this is much faster then comparing the length
|
|
|
|
|
with zero.
|
|
|
|
|
|
|
|
|
|
escape({string}, {chars}) *escape()*
|
|
|
|
|
Escape the characters in {chars} that occur in {string} with a
|
|
|
|
|
backslash. Example: >
|
|
|
|
|
@ -1754,7 +1934,7 @@ foreground() Move the Vim window to the foreground. Useful when sent from
|
|
|
|
|
Win32 console version}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
function({name}) *function()*
|
|
|
|
|
function({name}) *function()* *E700*
|
|
|
|
|
Return a Funcref variable that refers to function {name}.
|
|
|
|
|
{name} can be a user defined function or an internal function.
|
|
|
|
|
|
|
|
|
|
@ -2260,7 +2440,7 @@ isdirectory({directory}) *isdirectory()*
|
|
|
|
|
exist, or isn't a directory, the result is FALSE. {directory}
|
|
|
|
|
is any expression, which is used as a String.
|
|
|
|
|
|
|
|
|
|
*len()*
|
|
|
|
|
*len()* *E701*
|
|
|
|
|
len({expr}) The result is a Number, which is the length of the argument.
|
|
|
|
|
When {expr} is a String or a Number the length in bytes is
|
|
|
|
|
used, as with |strlen()|.
|
|
|
|
|
@ -2858,7 +3038,7 @@ simplify({filename}) *simplify()*
|
|
|
|
|
links before simplifying the path name, use |resolve()|.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
sort({list} [, {func}]) *sort()*
|
|
|
|
|
sort({list} [, {func}]) *sort()* *E702*
|
|
|
|
|
Sort the items in {list} in-place. Returns {list}. If you
|
|
|
|
|
want a list to remain unmodified make a copy first: >
|
|
|
|
|
:let sortedlist = sort(copy(mylist))
|
|
|
|
|
@ -2922,6 +3102,8 @@ string({expr}) Return {expr} converted to a String.
|
|
|
|
|
Number decimal representation
|
|
|
|
|
Funcref name of the function
|
|
|
|
|
List "[item, item]" form
|
|
|
|
|
Note that string values are not in quotes, thus the result
|
|
|
|
|
can't be parsed back to a List.
|
|
|
|
|
|
|
|
|
|
*strlen()*
|
|
|
|
|
strlen({expr}) The result is a Number, which is the length of the String
|
|
|
|
|
@ -3652,6 +3834,13 @@ This would call the function "my_func_whizz(parameter)".
|
|
|
|
|
from the {expr}. If {var-name} didn't exist yet, it
|
|
|
|
|
is created.
|
|
|
|
|
|
|
|
|
|
:let {var-name}[{idx}] = {expr1} *E689*
|
|
|
|
|
Set a list item to the result of the expression
|
|
|
|
|
{expr1}. {var-name} must refer to a list and {idx}
|
|
|
|
|
must be a valid index in that list. For nested list
|
|
|
|
|
the index can be repeated.
|
|
|
|
|
This cannot be used to add an item to a list.
|
|
|
|
|
|
|
|
|
|
:let ${env-name} = {expr1} *:let-environment* *:let-$*
|
|
|
|
|
Set environment variable {env-name} to the result of
|
|
|
|
|
the expression {expr1}. The type is always String.
|
|
|
|
|
@ -3688,7 +3877,7 @@ This would call the function "my_func_whizz(parameter)".
|
|
|
|
|
Like above, but only set the global value of an option
|
|
|
|
|
(if there is one). Works like |:setglobal|.
|
|
|
|
|
|
|
|
|
|
:let [{name1}, {name2}, ...] = {expr1} *:let-unpack*
|
|
|
|
|
:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
|
|
|
|
|
{expr1} must evaluate to a List. The first item in
|
|
|
|
|
the list is assigned to {name1}, the second item to
|
|
|
|
|
{name2}, etc.
|
|
|
|
|
@ -3777,7 +3966,7 @@ This would call the function "my_func_whizz(parameter)".
|
|
|
|
|
NOTE: The ":append" and ":insert" commands don't work
|
|
|
|
|
properly inside a :while" and ":for" loop.
|
|
|
|
|
|
|
|
|
|
:for {var} in {list} *:for*
|
|
|
|
|
:for {var} in {list} *:for* *E690*
|
|
|
|
|
:endfo[r] *:endfo* *:endfor*
|
|
|
|
|
Repeat the commands between ":for" and ":endfor" for
|
|
|
|
|
each item in {list}. variable {var} is set to the
|
|
|
|
|
|
Bram Moolenaar