vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 85:fc244e0a6e7e

updated for version 7.0034

author	vimboss
date	Sat, 08 Jan 2005 16:08:21 +0000
parents	366d9947baf2
children	014ba200db86

comparison

equal deleted inserted replaced

-:60834e43d187
+:fc244e0a6e7e
-*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
 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|
+1.  Variables			|variables|
-2.  Expression syntax	|expression-syntax|
+1.1 Variable types
-3.  Internal variable	|internal-variables|
+1.2 Function reference		|Funcref|
-4.  Builtin Functions	|functions|
+1.3 List				|List|
-5.  Defining functions	|user-functions|
+1.4 More about variables		|more-variables|
-6.  Curly braces names	|curly-braces-names|
+2.  Expression syntax		|expression-syntax|
-7.  Commands		|expression-commands|
+3.  Internal variable		|internal-variables|
-8.  Exception handling	|exception-handling|
+4.  Builtin Functions		|functions|
-9.  Examples		|eval-examples|
+5.  Defining functions		|user-functions|
-10. No +eval feature	|no-eval-feature|
+6.  Curly braces names		|curly-braces-names|
-11. The sandbox		|eval-sandbox|
+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)
 Funcref		a reference to a function |Funcref|
 List		an ordered sequence of items |List|
 	:if "foo"
 "foo" is converted to 0, which means FALSE.  To test for a non-empty string,
 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()
+<
-Note that this doesn't work with |:call|, because its argument is not an
+							*E704* *E705* *E707*
-expression.
+A Funcref variable must start with a capital, "s:", "w:" or "b:".  You cannot
-The name of the referenced function can be obtained with |string()|.  A
+have both a Funcref variable and a function with the same name.
-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.
-Lists ~
-								*List*
+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)
+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: >
+Examples: >
-	:let mylist = [1, 'two', 3, "four"]
+	: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: >
+nested List: >
-	:let mylist = [[11, 12], [21, 22], [31, 32]]
+	: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
-<
-								*list-index*
+When the item is a list again this can be repeated: >
-Indexes are zero-based, thus the first item has index zero.  A negative index
+	:let item = nestlist[0][1]	" get the first list, second item: 12
-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 shortlist = [2:2]		" List with one item: [3]
-	:let otherlist = [:]		" make a copy
+	: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.
 When the '!' flag is included in the 'viminfo' option, global variables that
 start with an uppercase letter, and don't contain a lowercase letter, are
 Examples:
 "abc" ==# "Abc"	  evaluates to 0
 "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.
 When using "is" or "isnot" with a List this checks if the expressions are
 referring to the same List instance.  A copy of a List is different from the
 deepcopy( {expr})		any	make a full copy of {expr}
 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
 exists( {expr})			Number	TRUE if {expr} exists
 expand( {expr})			String	expand special keywords in {expr}
 		List. Examples: >
 			:let alist = add([1, 2, 3], item)
 			: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()*
 		When {expr} is a List: Append each item of the list as a text
 		line below line {lnum} in the current buffer.
 			echo strpart(s, 0, byteidx(s, 1))
 <		If there are less than {nr} characters -1 is returned.
 		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.
 		a:firstline and a:lastline are set to the cursor line.
 		Returns the return value of the called function.
 		the cursor will be positioned at the last character in the
 		line.
 		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
 		that the original List can be changed without changing the
 		copy, and vise versa.  When an item is a List, a copy for it
 		line, "'m" mark m, etc.
 		{col} is 1 for the leftmost column, {lnum} is 1 for the first
 		line.
 		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: >
 			:echo escape('c:\program files\vim', ' \')
 		|remote_foreground()| instead.
 		{only in the Win32, Athena, Motif and GTK GUI versions and the
 		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.
 get({list}, {idx} [, {default}])			*get*
 		The result is a Number, which is non-zero when a directory
 		with the name {directory} exists.  If {directory} doesn't
 		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()|.
 		When {expr} is a List the number of items in the List is
 		returned.
 		removed when "dir" is a symbolic link within the same
 		directory.  In order to resolve all the involved symbolic
 		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))
 <		Uses the string representation of each item to sort on.
 		When {func} is given and it is one then case is ignored.
 			{expr} type	result ~
 			String		identical
 			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
 		{expr} in bytes.  If you want to count the number of
 		multi-byte characters use something like this: >
 			Set internal variable {var-name} to the result of the
 			expression {expr1}.  The variable will get the type
 			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.
 :let @{reg-name} = {expr1}			*:let-register* *:let-@*
 :let &g:{option-name} = {expr1}
 			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.
 			The number of names must match the number of items in
 			the List.
 				:endwhile
 <
 			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
 			value of each item.
 			When an error is detected for a command inside the

Mercurial > vim

comparison runtime/doc/eval.txt @ 85:fc244e0a6e7e