-*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
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)
use strlen(): >
:if strlen("foo")
+List and Funcref types are not automatically converted.
+
+ *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!
-Function references ~
- *Funcref*
+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 a Funcref cannot be used with |:call|, because its argument is not
+an expression.
-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:".
+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
+
+
+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.
-More about variables ~
+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.
"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.
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
: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()*
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.
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
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: >
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.
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()|.
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))
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
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.
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.
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
projects / vim / commitdiff