Mercurial > vim
annotate runtime/doc/repeat.txt @ 2207:b17bbfa96fa0 vim73
Add the settabvar() and gettabvar() functions.
Various runtime file updates.
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Sat, 22 May 2010 15:37:44 +0200 |
| parents | 7c8c7c95a865 |
| children | 7e1bd501306d |
| rev | line source |
|---|---|
|
2154
7c8c7c95a865
First step in the Vim 7.3 branch. Changed version numbers.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
1 *repeat.txt* For Vim version 7.3a. Last change: 2009 Nov 04 |
| 7 | 2 |
| 3 | |
| 4 VIM REFERENCE MANUAL by Bram Moolenaar | |
| 5 | |
| 6 | |
| 7 Repeating commands, Vim scripts and debugging *repeating* | |
| 8 | |
| 9 Chapter 26 of the user manual introduces repeating |usr_26.txt|. | |
| 10 | |
| 11 1. Single repeats |single-repeat| | |
| 12 2. Multiple repeats |multi-repeat| | |
| 13 3. Complex repeats |complex-repeat| | |
| 14 4. Using Vim scripts |using-scripts| | |
| 15 5. Debugging scripts |debug-scripts| | |
| 170 | 16 6. Profiling |profiling| |
| 7 | 17 |
| 18 ============================================================================== | |
| 19 1. Single repeats *single-repeat* | |
| 20 | |
| 21 *.* | |
| 22 . Repeat last change, with count replaced with [count]. | |
| 23 Also repeat a yank command, when the 'y' flag is | |
| 22 | 24 included in 'cpoptions'. Does not repeat a |
| 25 command-line command. | |
| 7 | 26 |
| 27 Simple changes can be repeated with the "." command. Without a count, the | |
| 28 count of the last change is used. If you enter a count, it will replace the | |
| 29 last one. If the last change included a specification of a numbered register, | |
| 30 the register number will be incremented. See |redo-register| for an example | |
| 31 how to use this. Note that when repeating a command that used a Visual | |
| 32 selection, the same SIZE of area is used, see |visual-repeat|. | |
| 33 | |
| 34 *@:* | |
| 35 @: Repeat last command-line [count] times. | |
| 36 {not available when compiled without the | |
| 37 |+cmdline_hist| feature} | |
| 38 | |
| 39 | |
| 40 ============================================================================== | |
| 41 2. Multiple repeats *multi-repeat* | |
| 42 | |
| 43 *:g* *:global* *E147* *E148* | |
| 44 :[range]g[lobal]/{pattern}/[cmd] | |
| 45 Execute the Ex command [cmd] (default ":p") on the | |
| 46 lines within [range] where {pattern} matches. | |
| 47 | |
| 48 :[range]g[lobal]!/{pattern}/[cmd] | |
| 49 Execute the Ex command [cmd] (default ":p") on the | |
| 50 lines within [range] where {pattern} does NOT match. | |
| 51 | |
| 52 *:v* *:vglobal* | |
| 53 :[range]v[global]/{pattern}/[cmd] | |
| 54 Same as :g!. | |
| 55 | |
| 1125 | 56 Instead of the '/' which surrounds the {pattern}, you can use any other |
| 57 single byte character, but not an alphanumeric character, '\', '"' or '|'. | |
| 58 This is useful if you want to include a '/' in the search pattern or | |
| 59 replacement string. | |
| 60 | |
| 61 For the definition of a pattern, see |pattern|. | |
| 62 | |
| 7 | 63 The global commands work by first scanning through the [range] lines and |
| 64 marking each line where a match occurs (for a multi-line pattern, only the | |
| 65 start of the match matters). | |
| 66 In a second scan the [cmd] is executed for each marked line with its line | |
| 67 number prepended. For ":v" and ":g!" the command is executed for each not | |
| 68 marked line. If a line is deleted its mark disappears. | |
| 69 The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt | |
| 70 the command. If an error message is given for a line, the command for that | |
| 71 line is aborted and the global command continues with the next marked or | |
| 72 unmarked line. | |
| 73 | |
| 74 To repeat a non-Ex command, you can use the ":normal" command: > | |
| 75 :g/pat/normal {commands} | |
| 76 Make sure that {commands} ends with a whole command, otherwise Vim will wait | |
| 77 for you to type the rest of the command for each match. The screen will not | |
| 78 have been updated, so you don't know what you are doing. See |:normal|. | |
| 79 | |
| 80 The undo/redo command will undo/redo the whole global command at once. | |
| 81 The previous context mark will only be set once (with "''" you go back to | |
| 82 where the cursor was before the global command). | |
| 83 | |
| 84 The global command sets both the last used search pattern and the last used | |
| 85 substitute pattern (this is vi compatible). This makes it easy to globally | |
| 86 replace a string: | |
| 87 :g/pat/s//PAT/g | |
| 88 This replaces all occurrences of "pat" with "PAT". The same can be done with: | |
| 89 :%s/pat/PAT/g | |
| 90 Which is two characters shorter! | |
| 91 | |
| 1623 | 92 When using "global" in Ex mode, a special case is using ":visual" as a |
| 93 command. This will move to a matching line, go to Normal mode to let you | |
| 94 execute commands there until you use |Q| to return to Ex mode. This will be | |
| 95 repeated for each matching line. While doing this you cannot use ":global". | |
| 96 To abort this type CTRL-C twice. | |
| 168 | 97 |
| 7 | 98 ============================================================================== |
| 99 3. Complex repeats *complex-repeat* | |
| 100 | |
| 101 *q* *recording* | |
| 102 q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} | |
| 103 (uppercase to append). The 'q' command is disabled | |
| 104 while executing a register, and it doesn't work inside | |
| 105 a mapping. {Vi: no recording} | |
| 106 | |
| 107 q Stops recording. (Implementation note: The 'q' that | |
| 108 stops recording is not stored in the register, unless | |
| 109 it was the result of a mapping) {Vi: no recording} | |
| 110 | |
| 111 *@* | |
| 112 @{0-9a-z".=*} Execute the contents of register {0-9a-z".=*} [count] | |
| 113 times. Note that register '%' (name of the current | |
| 114 file) and '#' (name of the alternate file) cannot be | |
| 115 used. For "@=" you are prompted to enter an | |
| 116 expression. The result of the expression is then | |
| 117 executed. See also |@:|. {Vi: only named registers} | |
| 118 | |
| 168 | 119 *@@* *E748* |
| 7 | 120 @@ Repeat the previous @{0-9a-z":*} [count] times. |
| 121 | |
| 122 :[addr]*{0-9a-z".=} *:@* *:star* | |
| 123 :[addr]@{0-9a-z".=*} Execute the contents of register {0-9a-z".=*} as an Ex | |
| 124 command. First set cursor at line [addr] (default is | |
| 125 current line). When the last line in the register does | |
| 126 not have a <CR> it will be added automatically when | |
| 127 the 'e' flag is present in 'cpoptions'. | |
| 128 Note that the ":*" command is only recognized when the | |
| 129 '*' flag is present in 'cpoptions'. This is NOT the | |
| 130 default when 'nocompatible' is used. | |
| 131 For ":@=" the last used expression is used. The | |
| 132 result of evaluating the expression is executed as an | |
| 133 Ex command. | |
| 134 Mappings are not recognized in these commands. | |
| 135 {Vi: only in some versions} Future: Will execute the | |
| 136 register for each line in the address range. | |
| 137 | |
| 138 *:@:* | |
| 139 :[addr]@: Repeat last command-line. First set cursor at line | |
| 140 [addr] (default is current line). {not in Vi} | |
| 141 | |
| 142 *:@@* | |
| 143 :[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at | |
| 144 line [addr] (default is current line). {Vi: only in | |
| 145 some versions} | |
| 146 | |
| 147 ============================================================================== | |
| 148 4. Using Vim scripts *using-scripts* | |
| 149 | |
| 150 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. | |
| 151 | |
| 152 *:so* *:source* *load-vim-script* | |
| 153 :so[urce] {file} Read Ex commands from {file}. These are commands that | |
| 154 start with a ":". | |
| 716 | 155 Triggers the |SourcePre| autocommand. |
| 7 | 156 |
| 157 :so[urce]! {file} Read Vim commands from {file}. These are commands | |
| 158 that are executed from Normal mode, like you type | |
| 159 them. | |
| 160 When used after |:global|, |:argdo|, |:windo|, | |
| 161 |:bufdo|, in a loop or when another command follows | |
| 162 the display won't be updated while executing the | |
| 163 commands. | |
| 164 {not in Vi} | |
| 165 | |
| 166 *:ru* *:runtime* | |
| 167 :ru[ntime][!] {file} .. | |
| 168 Read Ex commands from {file} in each directory given | |
| 169 by 'runtimepath'. There is no error for non-existing | |
| 170 files. Example: > | |
| 171 :runtime syntax/c.vim | |
| 172 | |
| 173 < There can be multiple {file} arguments, separated by | |
| 174 spaces. Each {file} is searched for in the first | |
| 175 directory from 'runtimepath', then in the second | |
| 176 directory, etc. Use a backslash to include a space | |
| 177 inside {file} (although it's better not to use spaces | |
| 178 in file names, it causes trouble). | |
| 179 | |
| 180 When [!] is included, all found files are sourced. | |
| 181 When it is not included only the first found file is | |
| 182 sourced. | |
| 183 | |
| 184 When {file} contains wildcards it is expanded to all | |
| 185 matching files. Example: > | |
| 186 :runtime! plugin/*.vim | |
| 187 < This is what Vim uses to load the plugin files when | |
| 237 | 188 starting up. This similar command: > |
| 7 | 189 :runtime plugin/*.vim |
| 190 < would source the first file only. | |
| 191 | |
| 192 When 'verbose' is one or higher, there is a message | |
| 193 when no file could be found. | |
| 194 When 'verbose' is two or higher, there is a message | |
| 195 about each searched file. | |
| 196 {not in Vi} | |
| 197 | |
| 198 :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167* | |
| 199 Specify the character encoding used in the script. | |
| 200 The following lines will be converted from [encoding] | |
| 201 to the value of the 'encoding' option, if they are | |
| 202 different. Examples: > | |
| 203 scriptencoding iso-8859-5 | |
| 204 scriptencoding cp932 | |
| 205 < | |
| 206 When [encoding] is empty, no conversion is done. This | |
| 207 can be used to restrict conversion to a sequence of | |
| 208 lines: > | |
| 209 scriptencoding euc-jp | |
| 210 ... lines to be converted ... | |
| 211 scriptencoding | |
| 212 ... not converted ... | |
| 213 | |
| 214 < When conversion isn't supported by the system, there | |
| 215 is no error message and no conversion is done. | |
| 216 | |
| 217 Don't use "ucs-2" or "ucs-4", scripts cannot be in | |
| 218 these encodings (they would contain NUL bytes). | |
| 219 When a sourced script starts with a BOM (Byte Order | |
|
2207
b17bbfa96fa0
Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
220 Mark) in utf-8 format Vim will recognize it, no need |
| 7 | 221 to use ":scriptencoding utf-8" then. |
| 222 | |
| 223 When compiled without the |+multi_byte| feature this | |
| 224 command is ignored. | |
| 225 {not in Vi} | |
| 226 | |
| 227 *:scrip* *:scriptnames* | |
| 228 :scrip[tnames] List all sourced script names, in the order they were | |
| 229 first sourced. The number is used for the script ID | |
| 230 |<SID>|. | |
| 231 {not in Vi} {not available when compiled without the | |
| 232 |+eval| feature} | |
| 233 | |
| 234 *:fini* *:finish* *E168* | |
| 235 :fini[sh] Stop sourcing a script. Can only be used in a Vim | |
| 236 script file. This is a quick way to skip the rest of | |
| 237 the file. If it is used after a |:try| but before the | |
| 238 matching |:finally| (if present), the commands | |
| 239 following the ":finally" up to the matching |:endtry| | |
| 240 are executed first. This process applies to all | |
| 241 nested ":try"s in the script. The outermost ":endtry" | |
| 242 then stops sourcing the script. {not in Vi} | |
| 243 | |
| 244 All commands and command sequences can be repeated by putting them in a named | |
| 245 register and then executing it. There are two ways to get the commands in the | |
| 246 register: | |
| 247 - Use the record command "q". You type the commands once, and while they are | |
| 248 being executed they are stored in a register. Easy, because you can see | |
| 249 what you are doing. If you make a mistake, "p"ut the register into the | |
| 250 file, edit the command sequence, and then delete it into the register | |
| 251 again. You can continue recording by appending to the register (use an | |
| 252 uppercase letter). | |
| 253 - Delete or yank the command sequence into the register. | |
| 254 | |
| 255 Often used command sequences can be put under a function key with the ':map' | |
| 256 command. | |
| 257 | |
| 258 An alternative is to put the commands in a file, and execute them with the | |
| 259 ':source!' command. Useful for long command sequences. Can be combined with | |
| 260 the ':map' command to put complicated commands under a function key. | |
| 261 | |
| 262 The ':source' command reads Ex commands from a file line by line. You will | |
| 263 have to type any needed keyboard input. The ':source!' command reads from a | |
| 264 script file character by character, interpreting each character as if you | |
| 265 typed it. | |
| 266 | |
| 267 Example: When you give the ":!ls" command you get the |hit-enter| prompt. If | |
| 268 you ':source' a file with the line "!ls" in it, you will have to type the | |
| 269 <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it, | |
| 270 the next characters from that file are read until a <CR> is found. You will | |
| 271 not have to type <CR> yourself, unless ":!ls" was the last line in the file. | |
| 272 | |
| 273 It is possible to put ':source[!]' commands in the script file, so you can | |
| 274 make a top-down hierarchy of script files. The ':source' command can be | |
| 275 nested as deep as the number of files that can be opened at one time (about | |
| 276 15). The ':source!' command can be nested up to 15 levels deep. | |
| 277 | |
| 278 You can use the "<sfile>" string (literally, this is not a special key) inside | |
| 279 of the sourced file, in places where a file name is expected. It will be | |
| 280 replaced by the file name of the sourced file. For example, if you have a | |
| 281 "other.vimrc" file in the same directory as your ".vimrc" file, you can source | |
| 282 it from your ".vimrc" file with this command: > | |
| 283 :source <sfile>:h/other.vimrc | |
| 284 | |
| 285 In script files terminal-dependent key codes are represented by | |
| 286 terminal-independent two character codes. This means that they can be used | |
| 287 in the same way on different kinds of terminals. The first character of a | |
| 288 key code is 0x80 or 128, shown on the screen as "~@". The second one can be | |
| 289 found in the list |key-notation|. Any of these codes can also be entered | |
| 290 with CTRL-V followed by the three digit decimal code. This does NOT work for | |
| 291 the <t_xx> termcap codes, these can only be used in mappings. | |
| 292 | |
| 293 *:source_crnl* *W15* | |
| 294 MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have | |
| 295 <CR><NL> <EOL>s. These always work. If you are using a file with <NL> <EOL>s | |
| 296 (for example, a file made on Unix), this will be recognized if 'fileformats' | |
| 297 is not empty and the first line does not end in a <CR>. This fails if the | |
| 298 first line has something like ":map <F1> :help^M", where "^M" is a <CR>. If | |
| 299 the first line ends in a <CR>, but following ones don't, you will get an error | |
| 300 message, because the <CR> from the first lines will be lost. | |
| 301 | |
| 333 | 302 Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. |
| 7 | 303 These always work. If you are using a file with <NL> <EOL>s (for example, a |
| 304 file made on Unix), this will be recognized if 'fileformats' is not empty and | |
| 305 the first line does not end in a <CR>. Be careful not to use a file with <NL> | |
| 306 linebreaks which has a <CR> in first line. | |
| 307 | |
| 308 On other systems, Vim expects ":source"ed files to end in a <NL>. These | |
| 309 always work. If you are using a file with <CR><NL> <EOL>s (for example, a | |
| 310 file made on MS-DOS), all lines will have a trailing <CR>. This may cause | |
| 311 problems for some commands (e.g., mappings). There is no automatic <EOL> | |
| 312 detection, because it's common to start with a line that defines a mapping | |
| 313 that ends in a <CR>, which will confuse the automaton. | |
| 314 | |
| 315 *line-continuation* | |
| 316 Long lines in a ":source"d Ex command script file can be split by inserting | |
| 317 a line continuation symbol "\" (backslash) at the start of the next line. | |
| 318 There can be white space before the backslash, which is ignored. | |
| 319 | |
| 320 Example: the lines > | |
| 321 :set comments=sr:/*,mb:*,el:*/, | |
| 322 \://, | |
| 323 \b:#, | |
| 324 \:%, | |
| 325 \n:>, | |
| 326 \fb:- | |
| 327 are interpreted as if they were given in one line: | |
| 328 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:- | |
| 329 | |
| 330 All leading whitespace characters in the line before a backslash are ignored. | |
| 331 Note however that trailing whitespace in the line before it cannot be | |
| 332 inserted freely; it depends on the position where a command is split up | |
| 333 whether additional whitespace is allowed or not. | |
| 334 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
335 When a space is required it's best to put it right after the backslash. A |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
336 space at the end of a line is hard to see and may be accidentally deleted. > |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
337 :syn match Comment |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
338 \ "very long regexp" |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
339 \ keepend |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
340 |
| 7 | 341 There is a problem with the ":append" and ":insert" commands: > |
| 342 :1append | |
| 343 \asdf | |
| 344 . | |
| 345 The backslash is seen as a line-continuation symbol, thus this results in the | |
| 346 command: > | |
| 347 :1appendasdf | |
| 348 . | |
| 349 To avoid this, add the 'C' flag to the 'cpoptions' option: > | |
| 350 :set cpo+=C | |
| 351 :1append | |
| 352 \asdf | |
| 353 . | |
| 354 :set cpo-=C | |
| 355 | |
| 356 Note that when the commands are inside a function, you need to add the 'C' | |
| 357 flag when defining the function, it is not relevant when executing it. > | |
| 358 :set cpo+=C | |
| 359 :function Foo() | |
| 360 :1append | |
| 361 \asdf | |
| 362 . | |
| 363 :endfunction | |
| 364 :set cpo-=C | |
| 365 | |
| 366 Rationale: | |
| 367 Most programs work with a trailing backslash to indicate line | |
| 368 continuation. Using this in Vim would cause incompatibility with Vi. | |
| 369 For example for this Vi mapping: > | |
| 370 :map xx asdf\ | |
| 371 < Therefore the unusual leading backslash is used. | |
| 372 | |
| 373 ============================================================================== | |
| 374 5. Debugging scripts *debug-scripts* | |
| 375 | |
| 376 Besides the obvious messages that you can add to your scripts to find out what | |
| 377 they are doing, Vim offers a debug mode. This allows you to step through a | |
| 378 sourced file or user function and set breakpoints. | |
| 379 | |
| 380 NOTE: The debugging mode is far from perfect. Debugging will have side | |
| 381 effects on how Vim works. You cannot use it to debug everything. For | |
| 382 example, the display is messed up by the debugging messages. | |
| 383 {Vi does not have a debug mode} | |
| 384 | |
| 385 An alternative to debug mode is setting the 'verbose' option. With a bigger | |
| 386 number it will give more verbose messages about what Vim is doing. | |
| 387 | |
| 388 | |
| 389 STARTING DEBUG MODE *debug-mode* | |
| 390 | |
| 391 To enter debugging mode use one of these methods: | |
| 392 1. Start Vim with the |-D| argument: > | |
| 393 vim -D file.txt | |
| 394 < Debugging will start as soon as the first vimrc file is sourced. This is | |
| 395 useful to find out what is happening when Vim is starting up. A side | |
| 396 effect is that Vim will switch the terminal mode before initialisations | |
| 397 have finished, with unpredictable results. | |
| 398 For a GUI-only version (Windows, Macintosh) the debugging will start as | |
| 399 soon as the GUI window has been opened. To make this happen early, add a | |
| 400 ":gui" command in the vimrc file. | |
| 401 *:debug* | |
| 402 2. Run a command with ":debug" prepended. Debugging will only be done while | |
| 403 this command executes. Useful for debugging a specific script or user | |
| 404 function. And for scripts and functions used by autocommands. Example: > | |
| 405 :debug edit test.txt.gz | |
| 406 | |
| 407 3. Set a breakpoint in a sourced file or user function. You could do this in | |
| 408 the command line: > | |
| 409 vim -c "breakadd file */explorer.vim" . | |
| 410 < This will run Vim and stop in the first line of the "explorer.vim" script. | |
| 411 Breakpoints can also be set while in debugging mode. | |
| 412 | |
| 413 In debugging mode every executed command is displayed before it is executed. | |
| 414 Comment lines, empty lines and lines that are not executed are skipped. When | |
| 415 a line contains two commands, separated by "|", each command will be displayed | |
| 416 separately. | |
| 417 | |
| 418 | |
| 419 DEBUG MODE | |
| 420 | |
| 421 Once in debugging mode, the usual Ex commands can be used. For example, to | |
| 422 inspect the value of a variable: > | |
| 423 echo idx | |
| 424 When inside a user function, this will print the value of the local variable | |
| 425 "idx". Prepend "g:" to get the value of a global variable: > | |
| 426 echo g:idx | |
| 427 All commands are executed in the context of the current function or script. | |
| 428 You can also set options, for example setting or resetting 'verbose' will show | |
| 429 what happens, but you might want to set it just before executing the lines you | |
| 430 are interested in: > | |
| 431 :set verbose=20 | |
| 432 | |
| 433 Commands that require updating the screen should be avoided, because their | |
| 434 effect won't be noticed until after leaving debug mode. For example: > | |
| 435 :help | |
| 436 won't be very helpful. | |
| 437 | |
| 438 There is a separate command-line history for debug mode. | |
| 439 | |
| 440 The line number for a function line is relative to the start of the function. | |
| 441 If you have trouble figuring out where you are, edit the file that defines | |
| 442 the function in another Vim, search for the start of the function and do | |
| 443 "99j". Replace "99" with the line number. | |
| 444 | |
| 445 Additionally, these commands can be used: | |
| 446 *>cont* | |
| 447 cont Continue execution until the next breakpoint is hit. | |
| 448 *>quit* | |
| 449 quit Abort execution. This is like using CTRL-C, some | |
| 450 things might still be executed, doesn't abort | |
| 451 everything. Still stops at the next breakpoint. | |
| 452 *>next* | |
| 453 next Execute the command and come back to debug mode when | |
| 454 it's finished. This steps over user function calls | |
| 455 and sourced files. | |
| 456 *>step* | |
| 457 step Execute the command and come back to debug mode for | |
| 458 the next command. This steps into called user | |
| 459 functions and sourced files. | |
| 460 *>interrupt* | |
| 461 interrupt This is like using CTRL-C, but unlike ">quit" comes | |
| 462 back to debug mode for the next command that is | |
| 463 executed. Useful for testing |:finally| and |:catch| | |
| 464 on interrupt exceptions. | |
| 465 *>finish* | |
| 466 finish Finish the current script or user function and come | |
| 467 back to debug mode for the command after the one that | |
| 468 sourced or called it. | |
| 469 | |
| 470 About the additional commands in debug mode: | |
| 471 - There is no command-line completion for them, you get the completion for the | |
| 472 normal Ex commands only. | |
| 473 - You can shorten them, up to a single character: "c", "n", "s" and "f". | |
| 474 - Hitting <CR> will repeat the previous one. When doing another command, this | |
| 475 is reset (because it's not clear what you want to repeat). | |
| 476 - When you want to use the Ex command with the same name, prepend a colon: | |
| 477 ":cont", ":next", ":finish" (or shorter). | |
| 478 | |
| 479 | |
| 480 DEFINING BREAKPOINTS | |
| 481 *:breaka* *:breakadd* | |
| 482 :breaka[dd] func [lnum] {name} | |
| 483 Set a breakpoint in a function. Example: > | |
| 484 :breakadd func Explore | |
| 485 < Doesn't check for a valid function name, thus the breakpoint | |
| 486 can be set before the function is defined. | |
| 487 | |
| 488 :breaka[dd] file [lnum] {name} | |
| 489 Set a breakpoint in a sourced file. Example: > | |
| 490 :breakadd file 43 .vimrc | |
| 491 | |
| 10 | 492 :breaka[dd] here |
| 493 Set a breakpoint in the current line of the current file. | |
| 494 Like doing: > | |
| 495 :breakadd file <cursor-line> <current-file> | |
| 496 < Note that this only works for commands that are executed when | |
| 497 sourcing the file, not for a function defined in that file. | |
| 498 | |
| 7 | 499 The [lnum] is the line number of the breakpoint. Vim will stop at or after |
| 500 this line. When omitted line 1 is used. | |
| 501 | |
| 170 | 502 *:debug-name* |
| 7 | 503 {name} is a pattern that is matched with the file or function name. The |
| 504 pattern is like what is used for autocommands. There must be a full match (as | |
| 505 if the pattern starts with "^" and ends in "$"). A "*" matches any sequence | |
| 506 of characters. 'ignorecase' is not used, but "\c" can be used in the pattern | |
| 507 to ignore case |/\c|. Don't include the () for the function name! | |
| 508 | |
| 11 | 509 The match for sourced scripts is done against the full file name. If no path |
| 510 is specified the current directory is used. Examples: > | |
| 511 breakadd file explorer.vim | |
| 512 matches "explorer.vim" in the current directory. > | |
| 7 | 513 breakadd file *explorer.vim |
| 11 | 514 matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. > |
| 7 | 515 breakadd file */explorer.vim |
| 11 | 516 matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory. |
| 7 | 517 |
| 518 The match for functions is done against the name as it's shown in the output | |
| 519 of ":function". For local functions this means that something like "<SNR>99_" | |
| 520 is prepended. | |
| 521 | |
| 148 | 522 Note that functions are first loaded and later executed. When they are loaded |
| 523 the "file" breakpoints are checked, when they are executed the "func" | |
| 524 breakpoints. | |
| 525 | |
| 7 | 526 |
| 527 DELETING BREAKPOINTS | |
| 528 *:breakd* *:breakdel* *E161* | |
| 529 :breakd[el] {nr} | |
| 530 Delete breakpoint {nr}. Use |:breaklist| to see the number of | |
| 531 each breakpoint. | |
| 532 | |
| 359 | 533 :breakd[el] * |
| 534 Delete all breakpoints. | |
| 535 | |
| 7 | 536 :breakd[el] func [lnum] {name} |
| 537 Delete a breakpoint in a function. | |
| 538 | |
| 539 :breakd[el] file [lnum] {name} | |
| 540 Delete a breakpoint in a sourced file. | |
| 541 | |
| 10 | 542 :breakd[el] here |
| 543 Delete a breakpoint at the current line of the current file. | |
| 544 | |
| 7 | 545 When [lnum] is omitted, the first breakpoint in the function or file is |
| 546 deleted. | |
| 547 The {name} must be exactly the same as what was typed for the ":breakadd" | |
| 548 command. "explorer", "*explorer.vim" and "*explorer*" are different. | |
| 549 | |
| 550 | |
| 551 LISTING BREAKPOINTS | |
| 552 *:breakl* *:breaklist* | |
| 553 :breakl[ist] | |
| 554 List all breakpoints. | |
| 555 | |
| 556 | |
| 557 OBSCURE | |
| 558 | |
| 559 *:debugg* *:debuggreedy* | |
| 560 :debugg[reedy] | |
| 561 Read debug mode commands from the normal input stream, instead | |
| 562 of getting them directly from the user. Only useful for test | |
| 563 scripts. Example: > | |
| 564 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim | |
| 565 | |
| 566 :0debugg[reedy] | |
| 567 Undo ":debuggreedy": get debug mode commands directly from the | |
| 568 user, don't use typeahead for debug commands. | |
| 569 | |
| 170 | 570 ============================================================================== |
| 571 6. Profiling *profile* *profiling* | |
| 572 | |
| 573 Profiling means that Vim measures the time that is spend on executing | |
| 574 functions and/or scripts. The |+profile| feature is required for this. | |
| 575 It is only included when Vim was compiled with "huge" features. | |
| 576 {Vi does not have profiling} | |
| 577 | |
| 794 | 578 You can also use the |reltime()| function to measure time. This only requires |
| 579 the |+reltime| feature, which is present more often. | |
| 580 | |
| 170 | 581 :prof[ile] start {fname} *:prof* *:profile* *E750* |
| 582 Start profiling, write the output in {fname} upon exit. | |
| 790 | 583 If {fname} already exists it will be silently overwritten. |
| 170 | 584 The variable |v:profiling| is set to one. |
| 585 | |
| 790 | 586 :prof[ile] pause |
| 587 Don't profile until the following ":profile continue". Can be | |
| 588 used when doing something that should not be counted (e.g., an | |
| 589 external command). Does not nest. | |
| 590 | |
| 591 :prof[ile] continue | |
| 592 Continue profiling after ":profile pause". | |
| 593 | |
| 170 | 594 :prof[ile] func {pattern} |
| 595 Profile function that matches the pattern {pattern}. | |
| 596 See |:debug-name| for how {pattern} is used. | |
| 597 | |
| 598 :prof[ile][!] file {pattern} | |
| 599 Profile script file that matches the pattern {pattern}. | |
| 600 See |:debug-name| for how {pattern} is used. | |
| 601 This only profiles the script itself, not the functions | |
| 602 defined in it. | |
| 603 When the [!] is added then all functions defined in the script | |
| 177 | 604 will also be profiled. But only if the script is loaded after |
| 605 this command. | |
| 170 | 606 |
| 607 | |
| 364 | 608 :profd[el] ... *:profd* *:profdel* |
| 609 Stop profiling for the arguments specified. See |:breakdel| | |
| 610 for the arguments. | |
| 611 | |
| 612 | |
| 170 | 613 You must always start with a ":profile start fname" command. The resulting |
| 614 file is written when Vim exits. Here is an example of the output, with line | |
| 615 numbers prepended for the explanation: | |
| 616 | |
| 617 1 FUNCTION Test2() ~ | |
| 618 2 Called 1 time ~ | |
| 619 3 Total time: 0.155251 ~ | |
| 620 4 Self time: 0.002006 ~ | |
| 621 5 ~ | |
| 622 6 count total (s) self (s) ~ | |
| 856 | 623 7 9 0.000096 for i in range(8) ~ |
| 624 8 8 0.153655 0.000410 call Test3() ~ | |
| 625 9 8 0.000070 endfor ~ | |
| 626 10 " Ask a question ~ | |
| 627 11 1 0.001341 echo input("give me an answer: ") ~ | |
| 170 | 628 |
| 629 The header (lines 1-4) gives the time for the whole function. The "Total" | |
| 630 time is the time passed while the function was executing. The "Self" time is | |
| 631 the "Total" time reduced by time spent in: | |
| 632 - other user defined functions | |
| 633 - sourced scripts | |
| 634 - executed autocommands | |
| 635 - external (shell) commands | |
| 636 | |
| 637 Lines 7-11 show the time spent in each executed line. Lines that are not | |
| 638 executed do not count. Thus a comment line is never counted. | |
| 639 | |
| 640 The Count column shows how many times a line was executed. Note that the | |
| 641 "for" command in line 7 is executed one more time as the following lines. | |
| 642 That is because the line is also executed to detect the end of the loop. | |
| 643 | |
| 644 The time Vim spends waiting for user input isn't counted at all. Thus how | |
| 645 long you take to respond to the input() prompt is irrelevant. | |
| 646 | |
| 647 Profiling should give a good indication of where time is spent, but keep in | |
| 648 mind there are various things that may clobber the results: | |
| 649 | |
| 650 - The accuracy of the time measured depends on the gettimeofday() system | |
| 651 function. It may only be as accurate as 1/100 second, even though the times | |
| 652 are displayed in micro seconds. | |
| 653 | |
| 654 - Real elapsed time is measured, if other processes are busy they may cause | |
| 655 delays at unpredictable moments. You may want to run the profiling several | |
| 656 times and use the lowest results. | |
| 657 | |
| 658 - If you have several commands in one line you only get one time. Split the | |
| 659 line to see the time for the individual commands. | |
| 660 | |
| 661 - The time of the lines added up is mostly less than the time of the whole | |
| 662 function. There is some overhead in between. | |
| 663 | |
| 664 - Functions that are deleted before Vim exits will not produce profiling | |
| 665 information. You can check the |v:profiling| variable if needed: > | |
| 856 | 666 :if !v:profiling |
| 170 | 667 : delfunc MyFunc |
| 668 :endif | |
| 669 < | |
| 177 | 670 - Profiling may give weird results on multi-processor systems, when sleep |
| 671 mode kicks in or the processor frequency is reduced to save power. | |
| 170 | 672 |
| 1125 | 673 - The "self" time is wrong when a function is used recursively. |
| 674 | |
| 675 | |
| 7 | 676 vim:tw=78:ts=8:ft=help:norl: |