updated for version 7.0034

runtime/doc/eval.txt

@@ -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
@@ -13,6 +13,10 @@ done, the features in this document are not available.  See |+eval| and the
 last chapter below.
 
 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|
@@ -29,7 +33,9 @@ last chapter below.
 ==============================================================================
 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 ~
+								*E706*
-								*Funcref*
+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
+Note that a Funcref cannot be used with |:call|, because its argument is not
-expression.
+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 ~
+1.3 List ~
-								*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
+
+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*
+A negative index is counted from the end.  Index -1 refers to the last item in
-Indexes are zero-based, thus the first item has index zero.  A negative index
+the List, -2 to the last but one item, etc. >
-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.
 
@@ -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

runtime/doc/motion.txt

@@ -1,4 +1,4 @@
-*motion.txt*    For Vim version 7.0aa.  Last change: 2004 Dec 29
+*motion.txt*    For Vim version 7.0aa.  Last change: 2005 Jan 08
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -938,7 +938,9 @@ These commands are not marks themselves, but jump to a mark:
 <
 			Note that ":keepjumps" must be used for every command.
 			When invoking a function the commands in that function
-			can still change the jumplist.
+			can still change the jumplist.  Also, for 
+			":keepjumps exe 'command '" the "command" won't keep
+			jumps.  Instead use: ":exe 'keepjumps command'"
 
 ==============================================================================
 8. Jumps					*jump-motions*

runtime/doc/tags

@@ -3572,8 +3572,34 @@ E679	syntax.txt	/*E679*
 E68	pattern.txt	/*E68*
 E680	autocmd.txt	/*E680*
 E681	quickfix.txt	/*E681*
+E682	quickfix.txt	/*E682*
+E683	quickfix.txt	/*E683*
+E684	eval.txt	/*E684*
+E685	message.txt	/*E685*
+E686	eval.txt	/*E686*
+E687	eval.txt	/*E687*
+E688	eval.txt	/*E688*
+E689	eval.txt	/*E689*
 E69	pattern.txt	/*E69*
+E690	eval.txt	/*E690*
+E691	eval.txt	/*E691*
+E692	eval.txt	/*E692*
+E693	eval.txt	/*E693*
+E694	eval.txt	/*E694*
+E695	eval.txt	/*E695*
+E696	eval.txt	/*E696*
+E697	eval.txt	/*E697*
+E698	eval.txt	/*E698*
+E699	eval.txt	/*E699*
 E70	pattern.txt	/*E70*
+E700	eval.txt	/*E700*
+E701	eval.txt	/*E701*
+E702	eval.txt	/*E702*
+E703	eval.txt	/*E703*
+E704	eval.txt	/*E704*
+E705	eval.txt	/*E705*
+E706	eval.txt	/*E706*
+E707	eval.txt	/*E707*
 E71	pattern.txt	/*E71*
 E72	message.txt	/*E72*
 E73	tagsrch.txt	/*E73*
@@ -4522,6 +4548,7 @@ eiffel.vim	syntax.txt	/*eiffel.vim*
 emacs-keys	tips.txt	/*emacs-keys*
 emacs-tags	tagsrch.txt	/*emacs-tags*
 emacs_tags	tagsrch.txt	/*emacs_tags*
+empty()	eval.txt	/*empty()*
 encoding-names	mbyte.txt	/*encoding-names*
 encoding-table	mbyte.txt	/*encoding-table*
 encoding-values	mbyte.txt	/*encoding-values*
@@ -5310,6 +5337,7 @@ linewise-register	change.txt	/*linewise-register*
 linewise-visual	visual.txt	/*linewise-visual*
 lispindent()	eval.txt	/*lispindent()*
 list-index	eval.txt	/*list-index*
+list-modification	eval.txt	/*list-modification*
 list-repeat	windows.txt	/*list-repeat*
 lite-syntax	syntax.txt	/*lite-syntax*
 lite.vim	syntax.txt	/*lite.vim*
@@ -5432,6 +5460,7 @@ moo-syntax	syntax.txt	/*moo-syntax*
 moo.vim	syntax.txt	/*moo.vim*
 more-compatible	version5.txt	/*more-compatible*
 more-prompt	message.txt	/*more-prompt*
+more-variables	eval.txt	/*more-variables*
 motion.txt	motion.txt	/*motion.txt*
 mouse-mode-table	term.txt	/*mouse-mode-table*
 mouse-overview	term.txt	/*mouse-overview*

src/version.h

@@ -36,5 +36,5 @@
 #define VIM_VERSION_NODOT	"vim70aa"
 #define VIM_VERSION_SHORT	"7.0aa"
 #define VIM_VERSION_MEDIUM	"7.0aa ALPHA"
-#define VIM_VERSION_LONG	"VIM - Vi IMproved 7.0aa ALPHA (2004 Jan 7)"
+#define VIM_VERSION_LONG	"VIM - Vi IMproved 7.0aa ALPHA (2004 Jan 8)"
-#define VIM_VERSION_LONG_DATE	"VIM - Vi IMproved 7.0aa ALPHA (2004 Jan 7, compiled "
+#define VIM_VERSION_LONG_DATE	"VIM - Vi IMproved 7.0aa ALPHA (2004 Jan 8, compiled "