share/vim/vim58/doc/repeat.txt

   1 *repeat.txt*    For Vim version 5.8.  Last change: 2000 Apr 14
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 Repeating commands                                      *repeating*
   8
   9 1. Single repeats       |single-repeat|
  10 2. Multiple repeats     |multi-repeat|
  11 3. Complex repeats      |complex-repeat|
  12
  13 ==============================================================================
  14 1. Single repeats                                       *single-repeat*
  15
  16                                                         *.*
  17 .                       Repeat last change, with count replaced with [count].
  18                         Also repeat a yank command, when the 'y' flag is
  19                         included in 'cpoptions'.
  20
  21 Simple changes can be repeated with the "." command.  Without a count, the
  22 count of the last change is used.  If you enter a count, it will replace the
  23 last one.  If the last change included a specification of a numbered register,
  24 the register number will be incremented.  See |undo-redo| for an example how
  25 to use this.  Note that when repeating a command that used a Visual selection,
  26 the same SIZE of area is used, see |visual-repeat|.
  27
  28                                                         *@:*
  29 @:                      Repeat last command-line [count] times.
  30
  31
  32 ==============================================================================
  33 2. Multiple repeats                                     *multi-repeat*
  34
  35                                                         *:g* *:global*
  36 :[range]g[lobal]/{pattern}/[cmd]
  37                         Execute the Ex command [cmd] (default ":p") on the
  38                         lines within [range] where {pattern} matches.
  39
  40 :[range]g[lobal]!/{pattern}/[cmd]
  41                         Execute the Ex command [cmd] (default ":p") on the
  42                         lines within [range] where {pattern} does NOT match.
  43
  44                                                         *:v* *:vglobal*
  45 :[range]v[global]/{pattern}/[cmd]
  46                         Same as :g!.
  47
  48 The global commands work by first scanning through the [range] lines and
  49 marking each line where a match occurs.  In a second scan the [cmd] is
  50 executed for each marked line with its line number prepended.  If a line is
  51 changed or deleted its mark disappears.  The default for [range] is the whole
  52 buffer (1,$).  Use "CTRL-C" to interrupt the command.  If an error message is
  53 given for a line, the command for that line is aborted and the global command
  54 continues with the next matching line.
  55
  56 To repeat a non-Ex command, you can use the ":normal" command:
  57         :g/pat/normal {commands}
  58 Make sure that {commands} ends with a whole command, otherwise Vim will wait
  59 for you to type the rest of the command for each match.  The screen will not
  60 have been updated, so you don't know what you are doing.  See |:normal|.
  61
  62 The undo/redo command will undo/redo the whole global command at once.
  63 The previous context mark will only be set once (with "''" you go back to
  64 where the cursor was before the global command).
  65
  66 The global command sets both the last used search pattern and the last used
  67 substitute pattern (this is vi compatible).  This makes it easy to globally
  68 replace a string:
  69         :g/pat/s//PAT/g
  70 This replaces all occurrences of "pat" with "PAT".  The same can be done with:
  71         :%s/pat/PAT/g
  72 Which is two characters shorter!
  73
  74 ==============================================================================
  75 3. Complex repeats                                      *complex-repeat*
  76
  77                                                         *q* *recording*
  78 q{0-9a-zA-Z"}           Record typed characters into register {0-9a-zA-Z"}
  79                         (uppercase to append).  The 'q' command is disabled
  80                         while executing a register, and it doesn't work inside
  81                         a mapping.  {Vi: no recording}
  82
  83 q                       Stops recording.  (Implementation note: The 'q' that
  84                         stops recording is not stored in the register, unless
  85                         it was the result of a mapping)  {Vi: no recording}
  86
  87                                                         *@*
  88 @{0-9a-z".=*}           Execute the contents of register {0-9a-z".=*} [count]
  89                         times.  Note that register '%' (name of the current
  90                         file) and '#' (name of the alternate file) cannot be
  91                         used.  For "@=" you are prompted to enter an
  92                         expression.  The result of the expression is then
  93                         executed.  See also |@:|.  {Vi: only named registers}
  94
  95                                                         *@@*
  96 @@                      Repeat the previous @{0-9a-z":*} [count] times.
  97
  98 :[addr]*{0-9a-z".=}                                             *:@* *:star*
  99 :[addr]@{0-9a-z".=*}    Execute the contents of register {0-9a-z".=*} as an Ex
 100                         command.  First set cursor at line [addr] (default is
 101                         current line).  When the last line in the register does
 102                         not have a <CR> it will be added automatically when
 103                         the 'e' flag is present in 'cpoptions'.
 104                         Note that the ":*" command is only recognized when the
 105                         '*' flag is present in 'cpoptions'.  This is NOT the
 106                         default when 'nocompatible' is used.
 107                         For ":@=" the last used expression is used.  The
 108                         result of evaluating the expression is executed as an
 109                         Ex command.
 110                         Mappings are not recognized in these commands.
 111                         {Vi: only in some versions} Future: Will execute the
 112                         register for each line in the address range.
 113
 114                                                         *:@:*
 115 :[addr]@:               Repeat last command-line.  First set cursor at line
 116                         [addr] (default is current line).  {not in Vi}
 117
 118                                                         *:@@*
 119 :[addr]@@               Repeat the previous :@{0-9a-z"}.  First set cursor at
 120                         line [addr] (default is current line).  {Vi: only in
 121                         some versions}
 122
 123                                         *:so* *:source* *load-vim-script*
 124 :so[urce] {file}        Read Ex commands from {file}.
 125
 126 :so[urce]! {file}       Read Vim commands from {file}.  {not in Vi}
 127
 128 All commands and command sequences can be repeated by putting them in a named
 129 register and then executing it.  There are two ways to get the commands in the
 130 register:
 131 - Use the record command "q".  You type the commands once, and while they are
 132   being executed they are stored in a register.  Easy, because you can see
 133   what you are doing.  If you make a mistake, "p"ut the register into the
 134   file, edit the command sequence, and then delete it into the register
 135   again.  You can continue recording by appending to the register (use an
 136   uppercase letter).
 137 - Delete or yank the command sequence into the register.
 138
 139 Often used command sequences can be put under a function key with the ':map'
 140 command.
 141
 142 An alternative is to put the commands in a file, and execute them with the
 143 ':source!' command.  Useful for long command sequences.  Can be combined with
 144 the ':map' command to put complicated commands under a function key.
 145
 146 The ':source' command reads Ex commands from a file line by line.  You will
 147 have to type any needed keyboard input.  The ':source!' command reads from a
 148 script file character by character, interpreting each character as if you
 149 typed it.
 150
 151 Example: When you give the ":!ls" command you get the |hit-return| prompt.  If
 152 you ':source' a file with the line "!ls" in it, you will have to type the
 153 return yourself.  But if you ':source!' a file with the line ":!ls" in it, the
 154 next characters from that file are read until a <CR> is found.  You will not
 155 have to type <CR> yourself, unless ":!ls" was the last line in the file.
 156
 157 It is possible to put ':source[!]' commands in the script file, so you can
 158 make a top-down hierarchy of script files.  The ':source' command can be
 159 nested as deep as the number of files that can be opened at one time (about
 160 15).  The ':source!' command can be nested up to 15 levels deep.
 161
 162 You can use the "<sfile>" string (literally, this is not a special key) inside
 163 of the sourced file, in places where a file name is expected.  It will be
 164 replaced by the file name of the sourced file.  For example, if you have a
 165 "other.vimrc" file in the same directory as your ".vimrc" file, you can source
 166 it from your ".vimrc" file with this command:
 167 >       :source <sfile>:h/other.vimrc
 168
 169 In script files terminal-dependent key codes are represented by
 170 terminal-independent two character codes.  This means that they can be used
 171 in the same way on different kinds of terminals.  The first character of a
 172 key code is 0x80 or 128, shown on the screen as "~@".  The second one can be
 173 found in the list |key-notation|.  Any of these codes can also be entered
 174 with CTRL-V followed by the three digit decimal code.  This does NOT work for
 175 the <t_xx> termcap codes, these can only be used in mappings.
 176
 177                                                         *:source_crnl*
 178 MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have
 179 <CR><NL> <EOL>s.  These always work.  If you are using a file with <NL> <EOL>s
 180 (for example, a file made on Unix), this will be recognized if 'fileformats'
 181 is not empty and the first line does not end in a <CR>.  This fails if the
 182 first line has something like ":map <F1> :help^M", where "^M" is a <CR>.  If
 183 the first line ends in a <CR>, but following ones don't, you will get an error
 184 message, because the <CR> from the first lines will be lost.
 185
 186 On other systems, Vim expects ":source"ed files to end in a <NL>.  These
 187 always work.  If you are using a file with <CR><NL> <EOL>s (for example, a
 188 file made on MS-DOS), all lines will have a trailing <CR>.  This may cause
 189 problems for some commands (e.g., mappings).  There is no automatic <EOL>
 190 detection, because it's common to start with a line that defines a mapping
 191 that ends in a <CR>, which will confuse the automaton.
 192
 193                                                         *line-continuation*
 194 Long lines in a ":source"d Ex command script file can be split by inserting
 195 a line continuation symbol "\" (backslash) at the start of the next line.
 196 There can be white space before the backslash, which is ignored.
 197
 198 Example: the lines
 199 >       set comments=sr:/*,mb:*,el:*/,
 200 >                    \://,
 201 >                    \b:#,
 202 >                    \:%,
 203 >                    \n:>,
 204 >                    \fb:-
 205 are interpreted as if they were given in one line:
 206 >       set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
 207
 208 All leading whitespace characters in the line before a backslash are ignored.
 209 Note however that trailing whitespace in the line before it cannot be
 210 inserted freely; it depends on the position where a command is split up
 211 whether additional whitespace is allowed or not.
 212
 213 There is a problem with the ":append" and ":insert" commands:
 214 >   1append
 215 >   \asdf
 216 >   .
 217 The backslash is seen as a line-continuation symbol, thus this results in the
 218 command:
 219 >   1appendasdf
 220 >   .
 221 To avoid this, add the 'C' flag to the 'cpoptions' option:
 222 >   set cpo+=C
 223 >   1append
 224 >   \asdf
 225 >   .
 226 >   set cpo-=C
 227
 228 Rationale: Most programs work with a trailing backslash to indicate line
 229 continuation.  Using this in Vim would cause incompatibility with Vi.  For
 230 example for this Vi mapping:
 231 >       map xx  asdf\
 232 Therefore the unusual leading backslash is used.
 233
 234  vim:tw=78:ts=8:sw=8: