diff options
author | Bram Moolenaar <Bram@vim.org> | 2008-06-24 21:56:24 +0000 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2008-06-24 21:56:24 +0000 |
commit | 446cb837a017fc1c1b144cb5c2a35cb90abfbbcf (patch) | |
tree | 6c1fe56f2db8d4adbeee792b181b0659c4d1f216 /runtime/doc | |
parent | 3577c6fafb77da5419cd1001dac56f204d480bdc (diff) |
updated for version 7.2a
Diffstat (limited to 'runtime/doc')
40 files changed, 2970 insertions, 1474 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 978686a3aa..80032e038a 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1,4 +1,4 @@ -*autocmd.txt* For Vim version 7.1. Last change: 2007 Mar 27 +*autocmd.txt* For Vim version 7.2a. Last change: 2008 Jun 24 VIM REFERENCE MANUAL by Bram Moolenaar @@ -104,7 +104,7 @@ local to the script and use mappings local to the script. When the event is triggered and the command executed, it will run in the context of the script it was defined in. This matters if |<SID>| is used in a command. -When executing the commands, the messages from one command overwrites a +When executing the commands, the message from one command overwrites a previous message. This is different from when executing the commands manually. Mostly the screen will not scroll up, thus there is no hit-enter prompt. When one command outputs two messages this can happen anyway. @@ -334,7 +334,7 @@ BufDelete Before deleting a buffer from the buffer list. list is renamed. NOTE: When this autocommand is executed, the current buffer "%" may be different from the - buffer being deleted "<afile>". + buffer being deleted "<afile>" and "<abuf>". *BufEnter* BufEnter After entering a buffer. Useful for setting options for a file type. Also executed when @@ -400,10 +400,15 @@ BufUnload Before unloading a buffer. This is when the *BufWinEnter* BufWinEnter After a buffer is displayed in a window. This can be when the buffer is loaded (after - processing the modelines), when a hidden + processing the modelines) or when a hidden buffer is displayed in a window (and is no - longer hidden) or a buffer already visible in - a window is also displayed in another window. + longer hidden). + Does not happen for |:split| without + arguments, since you keep editing the same + buffer, or ":split" with a file that's already + open in a window. But it does happen for + a ":split" with the name of the current + buffer, since it reloads that buffer. *BufWinLeave* BufWinLeave Before a buffer is removed from a window. Not when it's still visible in another window. @@ -677,7 +682,7 @@ QuickFixCmdPre Before a quickfix command is run (|:make|, *QuickFixCmdPost* QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix command is run, before jumping to the first - location. + location. See |QuickFixCmdPost-example|. *RemoteReply* RemoteReply When a reply from a Vim that functions as server was received |server2client()|. The @@ -848,7 +853,7 @@ This autocommand will for example be executed for "/tmp/doc/xx.txt" and The file name that the pattern is matched against is after expanding -wildcards. Thus is you issue this command: > +wildcards. Thus if you issue this command: > :e $ROOTDIR/main.$EXT The argument is first expanded to: > /usr/root/main.py @@ -927,7 +932,7 @@ simply use the special string instead of the pattern. Examples: > " current buffer :au! * <buffer=33> " remove buffer-local autocommands for " buffer #33 - :dobuf :au! CursorHold <buffer> " remove autocmd for given event for all + :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all " buffers :au * <buffer> " list buffer-local autocommands for " current buffer @@ -1031,8 +1036,9 @@ option will not cause any commands to be executed. undefined group name, Vim gives you an error message. After applying the autocommands the modelines are - processed, so that their overrule the settings from - autocommands, like what happens when editing a file. + processed, so that their settings overrule the + settings from autocommands, like what happens when + editing a file. *:doautoa* *:doautoall* :doautoa[ll] [group] {event} [fname] diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index c1eed2c0a4..24cf3fe9c0 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1,4 +1,4 @@ -*change.txt* For Vim version 7.1. Last change: 2007 Jan 07 +*change.txt* For Vim version 7.2a. Last change: 2008 Jun 22 VIM REFERENCE MANUAL by Bram Moolenaar @@ -229,16 +229,18 @@ key restores the original text (if there was any). (See section "Insert and Replace mode" |mode-ins-repl|). *cw* *cW* -Special case: "cw" and "cW" work the same as "ce" and "cE" if the cursor is -on a non-blank. This is because Vim interprets "cw" as change-word, and a -word does not include the following white space. {Vi: "cw" when on a blank -followed by other blanks changes only the first blank; this is probably a -bug, because "dw" deletes all the blanks; use the 'w' flag in 'cpoptions' to -make it work like Vi anyway} +Special case: When the cursor is in a word, "cw" and "cW" do not include the +white space after a word, they only change up to the end of the word. This is +because Vim interprets "cw" as change-word, and a word does not include the +following white space. +{Vi: "cw" when on a blank followed by other blanks changes only the first +blank; this is probably a bug, because "dw" deletes all the blanks; use the +'w' flag in 'cpoptions' to make it work like Vi anyway} If you prefer "cw" to include the space after a word, use this mapping: > :map cw dwi -< +Or use "caw" (see |aw|). + *:c* *:ch* *:change* :{range}c[hange][!] Replace lines of text with some different text. Type a line containing only "." to stop replacing. @@ -345,6 +347,10 @@ g?{motion} Rot13 encode {motion} text. {not in Vi} g?g? *g?g?* *g??* g?? Rot13 encode current line. {not in Vi}. +To turn one line into title caps, make every first letter of a word +uppercase: > + :s/\v<(.)(\w*)/\u\1\L\2/g + Adding and subtracting ~ *CTRL-A* @@ -474,7 +480,7 @@ For example: > A filter is a program that accepts text at standard input, changes it in some way, and sends it to standard output. You can use the commands below to send -some text through a filter, so that it is replace by the filter output. +some text through a filter, so that it is replaced by the filter output. Examples of filters are "sort", which sorts lines alphabetically, and "indent", which formats C program files (you need a version of indent that works like a filter; not all versions do). The 'shell' option specifies the @@ -661,9 +667,9 @@ The flags that you can use for the substitute commands: {not in Vi} Note that there is no flag to change the "magicness" of the pattern. A -different command is used instead. The reason is that the flags can only be -found by skipping the pattern, and in order to skip the pattern the -"magicness" must be known. Catch 22! +different command is used instead, or you can use |/\v| and friends. The +reason is that the flags can only be found by skipping the pattern, and in +order to skip the pattern the "magicness" must be known. Catch 22! If the {pattern} for the substitute command is empty, the command uses the pattern from the last substitute or ":global" command. With the [r] flag, the @@ -686,7 +692,9 @@ can use any other single-byte character, but not an alphanumeric character, pattern or replacement string. Example: > :s+/+//+ -For the definition of a pattern, see |pattern|. +For the definition of a pattern, see |pattern|. In Visual block mode, use +|/\%V| in the pattern to have the substitute work in the block only. +Otherwise it works on whole lines anyway. *sub-replace-special* *:s\=* When the {string} starts with "\=" it is evaluated as an expression, see @@ -1128,7 +1136,10 @@ nothing is returned. {not in Vi} Contains the most recent search-pattern. This is used for "n" and 'hlsearch'. It is writable with ":let", you can change it to have 'hlsearch' highlight other matches without actually searching. You can't yank or delete into this -register. {not in Vi} +register. The search direction is available in |v:searchforward|. +Note that the valued is restored when returning from a function +|function-search-undo|. +{not in Vi} *@/* You can write to a register with a ":let" command |:let-@|. Example: > @@ -1253,9 +1264,11 @@ an external command, like "par" (e.g.: "!}par" to format until the end of the paragraph) or set 'formatprg' to "par". *format-comments* -Vim can format comments in a special way. Vim recognizes a comment by a -specific string at the start of the line (ignoring white space). Three types -of comments can be used: +An overview of comment formatting is in section |30.6| of the user manual. + +Vim can automatically insert and format comments in a special way. Vim +recognizes a comment by a specific string at the start of the line (ignoring +white space). Three types of comments can be used: - A comment string that repeats at the start of each line. An example is the type of comment used in shell scripts, starting with "#". @@ -1263,7 +1276,7 @@ of comments can be used: lines. An example is this list with dashes. - Three-piece comments that have a start string, an end string, and optional lines in between. The strings for the start, middle and end are different. - An example is the C-style comment: + An example is the C style comment: /* * this is a C comment */ @@ -1289,23 +1302,24 @@ type of comment string. A part consists of: e End of a three-piece comment - l Left adjust middle with start or end (default). Only recognized when - used together with 's' or 'e'. + l Left align. Used together with 's' or 'e', the leftmost character of + start or end will line up with the leftmost character from the middle. + This is the default and can be omitted. See below for more details. - r Right adjust middle with start or end. Only recognized when used - together with 's' or 'e'. + r Right align. Same as above but rightmost instead of leftmost. See + below for more details. - O Don't use this one for the "O" command. + O Don't consider this comment for the "O" command. x Allows three-piece comments to be ended by just typing the last - character of the end-comment string as the first character on a new - line, when the middle-comment string has already been inserted - automatically. See below for more details. + character of the end-comment string as the first action on a new + line when the middle-comment string has been inserted automatically. + See below for more details. {digits} - When together with 's' or 'e': add extra indent for the middle part. - This can be used to left-align the middle part with the start or end - and then add an offset. + When together with 's' or 'e': add {digit} amount of offset to an + automatically inserted middle or end comment leader. The offset begins + from a left alignment. See below for more details. -{digits} Like {digits} but reduce the indent. This only works when there is @@ -1334,12 +1348,42 @@ have a middle string because otherwise Vim can't recognize the middle lines. Notice the use of the "x" flag in the above three-piece comment definition. When you hit Return in a C-comment, Vim will insert the middle comment leader -for the new line, e.g. " * ". To close this comment you just have to type "/" +for the new line: " * ". To close this comment you just have to type "/" before typing anything else on the new line. This will replace the -middle-comment leader with the end-comment leader, leaving just " */". There -is no need to hit BackSpace first. - -Examples: > +middle-comment leader with the end-comment leader and apply any specified +alignment, leaving just " */". There is no need to hit BackSpace first. + + +Here is an example of alignment flags at work to make a comment stand out +(kind of looks like a 1 too). Consider comment string > + sr:/***,m:**,ex2:******/ + + /*** + **<--right aligned from "r" flag + ** +offset 2 spaces from the "2" flag--->** + ******/ +In this case, the first comment was typed, then return was pressed 4 times, +then "/" was pressed to end the comment. + +Here are some finer points of three part comments. There are three times when +alignment and offset flags are taken into consideration: opening a new line +after a start-comment, opening a new line before an end-comment, and +automatically ending a three-piece comment. The end alignment flag has a +backwards perspective; the result is that the same alignment flag used with +"s" and "e" will result in the same indent for the starting and ending pieces. +Only one alignment per comment part is meant to be used, but an offset number +will override the "r" and "l" flag. + +Enabling 'cindent' will override the alignment flags in many cases. +Reindenting using a different method like |gq| or |=| will not consult +alignment flags either. The same behaviour can be defined in those other +formatting options. One consideration is that 'cindent' has additional options +for context based indenting of comments but cannot replicate many three piece +indent alignments. However, 'indentexpr' is has the ability to work better +with three piece comments. + +Other examples: > "b:*" Includes lines starting with "*", but not if the "*" is followed by a non-blank. This avoids a pointer dereference like "*str" to be recognized as a comment. @@ -1350,17 +1394,6 @@ By default, "b:#" is included. This means that a line that starts with "#include" is not recognized as a comment line. But a line that starts with "# define" is recognized. This is a compromise. -Often the alignment can be changed from right alignment to a left alignment -with an additional space. For example, for Javadoc comments, this can be -used (insert a backslash before the space when using ":set"): > - s1:/*,mb:*,ex:*/ -Note that an offset is included with start, so that the middle part is left -aligned with the start and then an offset of one character added. This makes -it possible to left align the start and middle for this construction: > - /** - * comment - */ - {not available when compiled without the |+comments| feature} *fo-table* @@ -1391,7 +1424,7 @@ a Automatic formatting of paragraphs. Every time text is inserted or n When formatting text, recognize numbered lists. This actually uses the 'formatlistpat' option, thus any kind of list can be used. The indent of the text after the number is used for the next line. The - default is to find a number, optionally be followed by '.', ':', ')', + default is to find a number, optionally followed by '.', ':', ')', ']' or '}'. Note that 'autoindent' must be set too. Doesn't work well together with "2". Example: > @@ -1555,9 +1588,10 @@ found here: |sort()|. :sort /.*\%10v/ < To sort on the first number in the line, no matter what is in front of it: > - :sort /.*\ze\d/ - -< With [r] sorting is done on the matching {pattern} + :sort /.\{-}\ze\d/ +< (Explanation: ".\{-}" matches any text, "\ze" sets the + end of the match and \d matches a digit.) + With [r] sorting is done on the matching {pattern} instead of skipping past it as described above. For example, to sort on only the first three letters of each line: > diff --git a/runtime/doc/debug.txt b/runtime/doc/debug.txt index ffc178dcc2..0e83ec7151 100644 --- a/runtime/doc/debug.txt +++ b/runtime/doc/debug.txt @@ -1,4 +1,4 @@ -*debug.txt* For Vim version 7.1. Last change: 2006 May 01 +*debug.txt* For Vim version 7.2a. Last change: 2006 May 01 VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 10870f76f2..1adef600c6 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -1,4 +1,4 @@ -*diff.txt* For Vim version 7.1. Last change: 2006 Oct 02 +*diff.txt* For Vim version 7.2a. Last change: 2006 Oct 02 VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 126b98b92d..349df2f251 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,7 +1,7 @@ -*eval.txt* For Vim version 7.1. Last change: 2008 May 28 +*eval.txt* For Vim version 7.2a. Last change: 2008 Jun 24 - VIM REFERENCE MANUAL by Bram Moolenaar + VIM REFERENCE MANUAL by Bram Moolenaar Expression evaluation *expression* *expr* *E15* *eval* @@ -9,7 +9,7 @@ Expression evaluation *expression* *expr* *E15* *eval* Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|. 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 +done, the features in this document are not available. See |+eval| and |no-eval-feature|. 1. Variables |variables| @@ -37,13 +37,17 @@ done, the features in this document are not available. See |+eval| and 1.1 Variable types ~ *E712* -There are five types of variables: +There are six types of variables: -Number A 32 bit signed number. +Number A 32 bit signed number. |expr-number| *Number* Examples: -123 0x10 0177 +Float A floating point number. |floating-point-format| *Float* + {only when compiled with the |+float| feature} + Examples: 123.456 1.15e-6 -1.1e3 + String A NUL terminated string of 8-bit unsigned characters (bytes). - Examples: "ab\txx\"--" 'x-z''a,c' + |expr-string| Examples: "ab\txx\"--" 'x-z''a,c' Funcref A reference to a function |Funcref|. Example: function("strlen") @@ -92,18 +96,26 @@ use strlen(): > < *E745* *E728* *E703* *E729* *E730* *E731* List, Dictionary and Funcref types are not automatically converted. - *E706* + *E805* *E806* *E808* +When mixing Number and Float the Number is converted to Float. Otherwise +there is no automatic conversion of Float. You can use str2float() for String +to Float, printf() for Float to String and float2nr() for Float to Number. + + *E706* *sticky-type-checking* 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. Consider this sequence of commands: > +equivalent though, as well are Float and Number. Consider this sequence of +commands: > :let l = "string" :let l = 44 " changes type from String to Number - :let l = [1, 2, 3] " error! + :let l = [1, 2, 3] " error! l is still a Number + :let l = 4.4 " changes type from Number to Float + :let l = "string" " error! 1.2 Function references ~ *Funcref* *E695* *E718* -A Funcref variable is obtained with the |function()| function. It can be used +A Funcref variable is obtained with the |function()| function. It can be used in an expression in the place of a function name, before the parenthesis around the arguments, to invoke the function it refers to. Example: > @@ -137,7 +149,7 @@ arguments: > 1.3 Lists ~ *List* *Lists* *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 +can be accessed by their index number. Items can be added and removed at any position in the sequence. @@ -148,7 +160,7 @@ Examples: > :let mylist = [1, two, 3, "four"] :let emptylist = [] -An item can be any expression. Using a List for an item creates a +An item can be any expression. Using a List for an item creates a List of Lists: > :let nestlist = [[11, 12], [21, 22], [31, 32]] @@ -207,7 +219,7 @@ length minus one is used: > :echo mylist[2:8] " result: [2, 3] NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for -using a single letter variable before the ":". Insert a space when needed: +using a single letter variable before the ":". Insert a space when needed: mylist[s : e]. @@ -258,13 +270,13 @@ variables. Example: > < 0 Thus comparing Lists is more strict than comparing numbers and strings. You -can compare simple values this way too by putting them in a string: > +can compare simple values this way too by putting them in a list: > :let a = 5 :let b = "5" - echo a == b + :echo a == b < 1 > - echo [a] == [b] + :echo [a] == [b] < 0 @@ -339,7 +351,7 @@ the loop. If all you want to do is modify each item in the list then the |map()| function will be a simpler method than a for loop. -Just like the |:let| command, |:for| also accepts a list of variables. This +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) @@ -396,10 +408,10 @@ only appear once. Examples: > < *E713* *E716* *E717* A key is always a String. You can use a Number, it will be converted to a String automatically. Thus the String '4' and the number 4 will find the same -entry. Note that the String '04' and the Number 04 are different, since the +entry. Note that the String '04' and the Number 04 are different, since the Number will be converted to the String '4'. -A value can be any expression. Using a Dictionary for a value creates a +A value can be any expression. Using a Dictionary for a value creates a nested Dictionary: > :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}} @@ -426,7 +438,7 @@ key lookup can be repeated: > Dictionary to List conversion ~ -You may want to loop over the entries in a dictionary. For this you need to +You may want to loop over the entries in a dictionary. For this you need to turn the Dictionary into a List and pass it to |:for|. Most often you want to loop over the keys, using the |keys()| function: > @@ -443,7 +455,7 @@ To loop over the values use the |values()| function: > :endfor If you want both the key and the value use the |items()| function. It returns -a List in which each item is a List with two items, the key and the value: > +a List in which each item is a List with two items, the key and the value: > :for [key, value] in items(mydict) : echo key . ': ' . value :endfor @@ -493,7 +505,7 @@ This removes all entries from "dict" with a value not matching 'x'. Dictionary function ~ *Dictionary-function* *self* *E725* When a function is defined with the "dict" attribute it can be used in a -special way with a dictionary. Example: > +special way with a dictionary. Example: > :function Mylen() dict : return len(self.data) :endfunction @@ -517,7 +529,7 @@ assigned to a Dictionary in this way: > :echo mydict.len() The function will then get a number and the value of dict.len is a |Funcref| -that references this function. The function can only be used through a +that references this function. The function can only be used through a |Funcref|. It will automatically be deleted when there is no |Funcref| remaining that refers to it. @@ -699,7 +711,7 @@ expr5 {cmp} expr5 Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1 if it evaluates to true. - *expr-==* *expr-!=* *expr->* *expr->=* + *expr-==* *expr-!=* *expr->* *expr->=* *expr-<* *expr-<=* *expr-=~* *expr-!~* *expr-==#* *expr-!=#* *expr->#* *expr->=#* *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#* @@ -738,21 +750,21 @@ 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 +referring to the same |List| instance. A copy of a |List| is different from the original |List|. When using "is" without a |List| it is equivalent to using "equal", using "isnot" equivalent to using "not equal". Except that a -different type means the values are different. "4 == '4'" is true, "4 is '4'" +different type means the values are different. "4 == '4'" is true, "4 is '4'" is false. When comparing a String with a Number, the String is converted to a Number, -and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE, +and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE, because 'x' converted to a Number is zero. When comparing two Strings, this is done with strcmp() or stricmp(). This results in the mathematical difference (comparing byte values), not necessarily the alphabetical difference in the local language. -When using the operators with a trailing '#", or the short version and +When using the operators with a trailing '#', or the short version and 'ignorecase' is off, the comparing is done with strcmp(): case matters. When using the operators with a trailing '?', or the short version and @@ -792,11 +804,30 @@ Note the difference between "+" and ".": "123" + "456" = 579 "123" . "456" = "123456" -When the righthand side of '/' is zero, the result is 0x7fffffff. +Since '.' has the same precedence as '+' and '-', you need to read: > + 1 . 90 + 90.0 +As: > + (1 . 90) + 90.0 +That works, since the String "190" is automatically converted to the Number +190, which can be added to the Float 90.0. However: > + 1 . 90 * 90.0 +Should be read as: > + 1 . (90 * 90.0) +Since '.' has lower precedence than '*'. This does NOT work, since this +attempts to concatenate a Float and a String. + +When dividing a Number by zero the result depends on the value: + 0 / 0 = -0x80000000 (like NaN for Float) + >0 / 0 = 0x7fffffff (like positive infinity) + <0 / 0 = -0x7fffffff (like negative infinity) + (before Vim 7.2 it was always 0x7fffffff) + When the righthand side of '%' is zero, the result is 0. None of these work for |Funcref|s. +. and % do not work for Float. *E804* + expr7 *expr7* ----- @@ -810,7 +841,7 @@ For '+' the number is unchanged. A String will be converted to a Number first. -These three can be repeated and mixed. Examples: +These three can be repeated and mixed. Examples: !-1 == 0 !!8 == 1 --9 == 9 @@ -835,7 +866,7 @@ compatibility). Use [-1:] to get the last byte. If expr8 is a |List| then it results the item at index expr1. See |list-index| for possible index values. If the index is out of range this results in an -error. Example: > +error. Example: > :let item = mylist[-1] " get last item Generally, if a |List| index is equal to or higher than the length of the @@ -866,7 +897,7 @@ Examples: > :let s = s[:-3] " remove last two bytes If expr8 is a |List| this results in a new |List| with the items indicated by -the indexes expr1a and expr1b. This works like with a String, as explained +the indexes expr1a and expr1b. This works like with a String, as explained just above, except that indexes out of range cause an error. Examples: > :let l = mylist[:3] " first four items :let l = mylist[4:4] " List with one item @@ -909,6 +940,53 @@ number number constant *expr-number* Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0). + *floating-point-format* +Floating point numbers can be written in two forms: + + [-+]{N}.{M} + [-+]{N}.{M}e[-+]{exp} + +{N} and {M} are numbers. Both {N} and {M} must be present and can only +contain digits. +[-+] means there is an optional plus or minus sign. +{exp} is the exponent, power of 10. +Only a decimal point is accepted, not a comma. No matter what the current +locale is. +{on |