diff options
author | Bram Moolenaar <Bram@vim.org> | 2005-01-08 16:08:21 +0000 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2005-01-08 16:08:21 +0000 |
commit | 13065c4e70f9e227e50513e8ffa4a3e79005babf (patch) | |
tree | 25056331af509228b9c14c9092ce68b32d5410b4 /runtime/doc | |
parent | cf3630f2d0d908f637f1d577a0cfd720987d35f0 (diff) |
updated for version 7.0034
Diffstat (limited to 'runtime/doc')
-rw-r--r-- | runtime/doc/eval.txt | 271 | ||||
-rw-r--r-- | runtime/doc/motion.txt | 6 | ||||
-rw-r--r-- | runtime/doc/tags | 29 |
3 files changed, 263 insertions, 43 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index f729bfcf7e..5eccc448d1 100644 --- a/runtime/doc/eval.txt +++ b/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 @@ -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. + + *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. @@ -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 diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index d7f6cbc40c..bee238e5e0 100644 --- a/runtime/doc/motion.txt +++ b/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* diff --git a/runtime/doc/tags b/runtime/doc/tags index 23d0dc0777..286d9f3b1a 100644 --- a/runtime/doc/tags +++ b/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* |