vim: runtime/doc/repeat.txt comparison

comparison runtime/doc/repeat.txt @ 7:3fc0f57ecb91 v7.0001

updated for version 7.0001

author	vimboss
date	Sun, 13 Jun 2004 20:20:40 +0000
parents
children	4e2284e71352

comparison

equal deleted inserted replaced

-:c2daee826b8f
+:3fc0f57ecb91
+*repeat.txt*    For Vim version 7.0aa.  Last change: 2004 Apr 02
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+Repeating commands, Vim scripts and debugging			*repeating*
+Chapter 26 of the user manual introduces repeating |usr_26.txt|.
+1. Single repeats	|single-repeat|
+2. Multiple repeats	|multi-repeat|
+3. Complex repeats	|complex-repeat|
+4. Using Vim scripts	|using-scripts|
+5. Debugging scripts	|debug-scripts|
+==============================================================================
+1. Single repeats					*single-repeat*
+							*.*
+.			Repeat last change, with count replaced with [count].
+			Also repeat a yank command, when the 'y' flag is
+			included in 'cpoptions'.
+Simple changes can be repeated with the "." command.  Without a count, the
+count of the last change is used.  If you enter a count, it will replace the
+last one.  If the last change included a specification of a numbered register,
+the register number will be incremented.  See |redo-register| for an example
+how to use this.  Note that when repeating a command that used a Visual
+selection, the same SIZE of area is used, see |visual-repeat|.
+							*@:*
+@:			Repeat last command-line [count] times.
+			{not available when compiled without the
+			|+cmdline_hist| feature}
+==============================================================================
+2. Multiple repeats					*multi-repeat*
+						*:g* *:global* *E147* *E148*
+:[range]g[lobal]/{pattern}/[cmd]
+			Execute the Ex command [cmd] (default ":p") on the
+			lines within [range] where {pattern} matches.
+:[range]g[lobal]!/{pattern}/[cmd]
+			Execute the Ex command [cmd] (default ":p") on the
+			lines within [range] where {pattern} does NOT match.
+							*:v* *:vglobal*
+:[range]v[global]/{pattern}/[cmd]
+			Same as :g!.
+The global commands work by first scanning through the [range] lines and
+marking each line where a match occurs (for a multi-line pattern, only the
+start of the match matters).
+In a second scan the [cmd] is executed for each marked line with its line
+number prepended.  For ":v" and ":g!" the command is executed for each not
+marked line.  If a line is deleted its mark disappears.
+The default for [range] is the whole buffer (1,$).  Use "CTRL-C" to interrupt
+the command.  If an error message is given for a line, the command for that
+line is aborted and the global command continues with the next marked or
+unmarked line.
+To repeat a non-Ex command, you can use the ":normal" command: >
+	:g/pat/normal {commands}
+Make sure that {commands} ends with a whole command, otherwise Vim will wait
+for you to type the rest of the command for each match.  The screen will not
+have been updated, so you don't know what you are doing.  See |:normal|.
+The undo/redo command will undo/redo the whole global command at once.
+The previous context mark will only be set once (with "''" you go back to
+where the cursor was before the global command).
+The global command sets both the last used search pattern and the last used
+substitute pattern (this is vi compatible).  This makes it easy to globally
+replace a string:
+	:g/pat/s//PAT/g
+This replaces all occurrences of "pat" with "PAT".  The same can be done with:
+	:%s/pat/PAT/g
+Which is two characters shorter!
+==============================================================================
+3. Complex repeats					*complex-repeat*
+							*q* *recording*
+q{0-9a-zA-Z"}		Record typed characters into register {0-9a-zA-Z"}
+			(uppercase to append).  The 'q' command is disabled
+			while executing a register, and it doesn't work inside
+			a mapping.  {Vi: no recording}
+q			Stops recording.  (Implementation note: The 'q' that
+			stops recording is not stored in the register, unless
+			it was the result of a mapping)  {Vi: no recording}
+							*@*
+@{0-9a-z".=*}		Execute the contents of register {0-9a-z".=*} [count]
+			times.  Note that register '%' (name of the current
+			file) and '#' (name of the alternate file) cannot be
+			used.  For "@=" you are prompted to enter an
+			expression.  The result of the expression is then
+			executed.  See also |@:|.  {Vi: only named registers}
+							*@@*
+@@			Repeat the previous @{0-9a-z":*} [count] times.
+:[addr]*{0-9a-z".=}						*:@* *:star*
+:[addr]@{0-9a-z".=*}	Execute the contents of register {0-9a-z".=*} as an Ex
+			command.  First set cursor at line [addr] (default is
+			current line).  When the last line in the register does
+			not have a <CR> it will be added automatically when
+			the 'e' flag is present in 'cpoptions'.
+			Note that the ":*" command is only recognized when the
+			'*' flag is present in 'cpoptions'.  This is NOT the
+			default when 'nocompatible' is used.
+			For ":@=" the last used expression is used.  The
+			result of evaluating the expression is executed as an
+			Ex command.
+			Mappings are not recognized in these commands.
+			{Vi: only in some versions} Future: Will execute the
+			register for each line in the address range.
+							*:@:*
+:[addr]@:		Repeat last command-line.  First set cursor at line
+			[addr] (default is current line).  {not in Vi}
+							*:@@*
+:[addr]@@		Repeat the previous :@{0-9a-z"}.  First set cursor at
+			line [addr] (default is current line).  {Vi: only in
+			some versions}
+==============================================================================
+4. Using Vim scripts					*using-scripts*
+For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
+					*:so* *:source* *load-vim-script*
+:so[urce] {file}	Read Ex commands from {file}.  These are commands that
+			start with a ":".
+:so[urce]! {file}	Read Vim commands from {file}.  These are commands
+			that are executed from Normal mode, like you type
+			them.
+			When used after |:global|, |:argdo|, |:windo|,
+			|:bufdo|, in a loop or when another command follows
+			the display won't be updated while executing the
+			commands.
+			{not in Vi}
+							*:ru* *:runtime*
+:ru[ntime][!] {file} ..
+			Read Ex commands from {file} in each directory given
+			by 'runtimepath'.  There is no error for non-existing
+			files.  Example: >
+				:runtime syntax/c.vim
+<			There can be multiple {file} arguments, separated by
+			spaces.  Each {file} is searched for in the first
+			directory from 'runtimepath', then in the second
+			directory, etc.  Use a backslash to include a space
+			inside {file} (although it's better not to use spaces
+			in file names, it causes trouble).
+			When [!] is included, all found files are sourced.
+			When it is not included only the first found file is
+			sourced.
+			When {file} contains wildcards it is expanded to all
+			matching files.  Example: >
+				:runtime! plugin/*.vim
+<			This is what Vim uses to load the plugin files when
+			starting up. This similar command: >
+				:runtime plugin/*.vim
+<			would source the first file only.
+			When 'verbose' is one or higher, there is a message
+			when no file could be found.
+			When 'verbose' is two or higher, there is a message
+			about each searched file.
+			{not in Vi}
+:scripte[ncoding] [encoding]		*:scripte* *:scriptencoding* *E167*
+			Specify the character encoding used in the script.
+			The following lines will be converted from [encoding]
+			to the value of the 'encoding' option, if they are
+			different.  Examples: >
+				scriptencoding iso-8859-5
+				scriptencoding cp932
+<
+			When [encoding] is empty, no conversion is done.  This
+			can be used to restrict conversion to a sequence of
+			lines: >
+				scriptencoding euc-jp
+				... lines to be converted ...
+				scriptencoding
+				... not converted ...
+<			When conversion isn't supported by the system, there
+			is no error message and no conversion is done.
+			Don't use "ucs-2" or "ucs-4", scripts cannot be in
+			these encodings (they would contain NUL bytes).
+			When a sourced script starts with a BOM (Byte Order
+			Mark) in utf-8 format Vim will recognized it, no need
+			to use ":scriptencoding utf-8" then.
+			When compiled without the |+multi_byte| feature this
+			command is ignored.
+			{not in Vi}
+						*:scrip* *:scriptnames*
+:scrip[tnames]		List all sourced script names, in the order they were
+			first sourced.  The number is used for the script ID
+			|<SID>|.
+			{not in Vi} {not available when compiled without the
+			|+eval| feature}
+						*:fini* *:finish* *E168*
+:fini[sh]		Stop sourcing a script.  Can only be used in a Vim
+			script file.  This is a quick way to skip the rest of
+			the file.  If it is used after a |:try| but before the
+			matching |:finally| (if present), the commands
+			following the ":finally" up to the matching |:endtry|
+			are executed first.  This process applies to all
+			nested ":try"s in the script.  The outermost ":endtry"
+			then stops sourcing the script.  {not in Vi}
+All commands and command sequences can be repeated by putting them in a named
+register and then executing it.  There are two ways to get the commands in the
+register:
+- Use the record command "q".  You type the commands once, and while they are
+being executed they are stored in a register.  Easy, because you can see
+what you are doing.  If you make a mistake, "p"ut the register into the
+file, edit the command sequence, and then delete it into the register
+again.  You can continue recording by appending to the register (use an
+uppercase letter).
+- Delete or yank the command sequence into the register.
+Often used command sequences can be put under a function key with the ':map'
+command.
+An alternative is to put the commands in a file, and execute them with the
+':source!' command.  Useful for long command sequences.  Can be combined with
+the ':map' command to put complicated commands under a function key.
+The ':source' command reads Ex commands from a file line by line.  You will
+have to type any needed keyboard input.  The ':source!' command reads from a
+script file character by character, interpreting each character as if you
+typed it.
+Example: When you give the ":!ls" command you get the |hit-enter| prompt.  If
+you ':source' a file with the line "!ls" in it, you will have to type the
+<Enter> yourself.  But if you ':source!' a file with the line ":!ls" in it,
+the next characters from that file are read until a <CR> is found.  You will
+not have to type <CR> yourself, unless ":!ls" was the last line in the file.
+It is possible to put ':source[!]' commands in the script file, so you can
+make a top-down hierarchy of script files.  The ':source' command can be
+nested as deep as the number of files that can be opened at one time (about
+15).  The ':source!' command can be nested up to 15 levels deep.
+You can use the "<sfile>" string (literally, this is not a special key) inside
+of the sourced file, in places where a file name is expected.  It will be
+replaced by the file name of the sourced file.  For example, if you have a
+"other.vimrc" file in the same directory as your ".vimrc" file, you can source
+it from your ".vimrc" file with this command: >
+	:source <sfile>:h/other.vimrc
+In script files terminal-dependent key codes are represented by
+terminal-independent two character codes.  This means that they can be used
+in the same way on different kinds of terminals.  The first character of a
+key code is 0x80 or 128, shown on the screen as "~@".  The second one can be
+found in the list |key-notation|.  Any of these codes can also be entered
+with CTRL-V followed by the three digit decimal code.  This does NOT work for
+the <t_xx> termcap codes, these can only be used in mappings.
+							*:source_crnl* *W15*
+MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have
+<CR><NL> <EOL>s.  These always work.  If you are using a file with <NL> <EOL>s
+(for example, a file made on Unix), this will be recognized if 'fileformats'
+is not empty and the first line does not end in a <CR>.  This fails if the
+first line has something like ":map <F1> :help^M", where "^M" is a <CR>.  If
+the first line ends in a <CR>, but following ones don't, you will get an error
+message, because the <CR> from the first lines will be lost.
+Macintosh: Files that are read with ":source" normally have <CR> <EOL>s.
+These always work.  If you are using a file with <NL> <EOL>s (for example, a
+file made on Unix), this will be recognized if 'fileformats' is not empty and
+the first line does not end in a <CR>.  Be careful not to use a file with <NL>
+linebreaks which has a <CR> in first line.
+On other systems, Vim expects ":source"ed files to end in a <NL>.  These
+always work.  If you are using a file with <CR><NL> <EOL>s (for example, a
+file made on MS-DOS), all lines will have a trailing <CR>.  This may cause
+problems for some commands (e.g., mappings).  There is no automatic <EOL>
+detection, because it's common to start with a line that defines a mapping
+that ends in a <CR>, which will confuse the automaton.
+							*line-continuation*
+Long lines in a ":source"d Ex command script file can be split by inserting
+a line continuation symbol "\" (backslash) at the start of the next line.
+There can be white space before the backslash, which is ignored.
+Example: the lines >
+	:set comments=sr:/*,mb:*,el:*/,
+		     \://,
+		     \b:#,
+		     \:%,
+		     \n:>,
+		     \fb:-
+are interpreted as if they were given in one line:
+	:set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
+All leading whitespace characters in the line before a backslash are ignored.
+Note however that trailing whitespace in the line before it cannot be
+inserted freely; it depends on the position where a command is split up
+whether additional whitespace is allowed or not.
+There is a problem with the ":append" and ":insert" commands: >
+:1append
+\asdf
+.
+The backslash is seen as a line-continuation symbol, thus this results in the
+command: >
+:1appendasdf
+.
+To avoid this, add the 'C' flag to the 'cpoptions' option: >
+:set cpo+=C
+:1append
+\asdf
+.
+:set cpo-=C
+Note that when the commands are inside a function, you need to add the 'C'
+flag when defining the function, it is not relevant when executing it. >
+:set cpo+=C
+:function Foo()
+:1append
+\asdf
+.
+:endfunction
+:set cpo-=C
+Rationale:
+	Most programs work with a trailing backslash to indicate line
+	continuation.  Using this in Vim would cause incompatibility with Vi.
+	For example for this Vi mapping: >
+		:map xx  asdf\
+<	Therefore the unusual leading backslash is used.
+==============================================================================
+5. Debugging scripts					*debug-scripts*
+Besides the obvious messages that you can add to your scripts to find out what
+they are doing, Vim offers a debug mode.  This allows you to step through a
+sourced file or user function and set breakpoints.
+NOTE: The debugging mode is far from perfect.  Debugging will have side
+effects on how Vim works.  You cannot use it to debug everything.  For
+example, the display is messed up by the debugging messages.
+{Vi does not have a debug mode}
+An alternative to debug mode is setting the 'verbose' option.  With a bigger
+number it will give more verbose messages about what Vim is doing.
+STARTING DEBUG MODE						*debug-mode*
+To enter debugging mode use one of these methods:
+1. Start Vim with the |-D| argument: >
+	vim -D file.txt
+<  Debugging will start as soon as the first vimrc file is sourced.  This is
+useful to find out what is happening when Vim is starting up.  A side
+effect is that Vim will switch the terminal mode before initialisations
+have finished, with unpredictable results.
+For a GUI-only version (Windows, Macintosh) the debugging will start as
+soon as the GUI window has been opened.  To make this happen early, add a
+":gui" command in the vimrc file.
+								*:debug*
+2. Run a command with ":debug" prepended.  Debugging will only be done while
+this command executes.  Useful for debugging a specific script or user
+function.  And for scripts and functions used by autocommands.  Example: >
+	:debug edit test.txt.gz
+3. Set a breakpoint in a sourced file or user function.  You could do this in
+the command line: >
+	vim -c "breakadd file */explorer.vim" .
+<  This will run Vim and stop in the first line of the "explorer.vim" script.
+Breakpoints can also be set while in debugging mode.
+In debugging mode every executed command is displayed before it is executed.
+Comment lines, empty lines and lines that are not executed are skipped.  When
+a line contains two commands, separated by "|", each command will be displayed
+separately.
+DEBUG MODE
+Once in debugging mode, the usual Ex commands can be used.  For example, to
+inspect the value of a variable: >
+	echo idx
+When inside a user function, this will print the value of the local variable
+"idx".  Prepend "g:" to get the value of a global variable: >
+	echo g:idx
+All commands are executed in the context of the current function or script.
+You can also set options, for example setting or resetting 'verbose' will show
+what happens, but you might want to set it just before executing the lines you
+are interested in: >
+	:set verbose=20
+Commands that require updating the screen should be avoided, because their
+effect won't be noticed until after leaving debug mode.  For example: >
+	:help
+won't be very helpful.
+There is a separate command-line history for debug mode.
+The line number for a function line is relative to the start of the function.
+If you have trouble figuring out where you are, edit the file that defines
+the function in another Vim, search for the start of the function and do
+"99j".  Replace "99" with the line number.
+Additionally, these commands can be used:
+							*>cont*
+	cont		Continue execution until the next breakpoint is hit.
+							*>quit*
+	quit		Abort execution.  This is like using CTRL-C, some
+			things might still be executed, doesn't abort
+			everything.  Still stops at the next breakpoint.
+							*>next*
+	next		Execute the command and come back to debug mode when
+			it's finished.  This steps over user function calls
+			and sourced files.
+							*>step*
+	step		Execute the command and come back to debug mode for
+			the next command.  This steps into called user
+			functions and sourced files.
+							*>interrupt*
+	interrupt	This is like using CTRL-C, but unlike ">quit" comes
+			back to debug mode for the next command that is
+			executed.  Useful for testing |:finally| and |:catch|
+			on interrupt exceptions.
+							*>finish*
+	finish		Finish the current script or user function and come
+			back to debug mode for the command after the one that
+			sourced or called it.
+About the additional commands in debug mode:
+- There is no command-line completion for them, you get the completion for the
+normal Ex commands only.
+- You can shorten them, up to a single character: "c", "n", "s" and "f".
+- Hitting <CR> will repeat the previous one.  When doing another command, this
+is reset (because it's not clear what you want to repeat).
+- When you want to use the Ex command with the same name, prepend a colon:
+":cont", ":next", ":finish" (or shorter).
+DEFINING BREAKPOINTS
+							*:breaka* *:breakadd*
+:breaka[dd] func [lnum] {name}
+		Set a breakpoint in a function.  Example: >
+			:breakadd func Explore
+<		Doesn't check for a valid function name, thus the breakpoint
+		can be set before the function is defined.
+:breaka[dd] file [lnum] {name}
+		Set a breakpoint in a sourced file.  Example: >
+			:breakadd file 43 .vimrc
+The [lnum] is the line number of the breakpoint.  Vim will stop at or after
+this line.  When omitted line 1 is used.
+{name} is a pattern that is matched with the file or function name.  The
+pattern is like what is used for autocommands.  There must be a full match (as
+if the pattern starts with "^" and ends in "$").  A "*" matches any sequence
+of characters.  'ignorecase' is not used, but "\c" can be used in the pattern
+to ignore case |/\c|.  Don't include the () for the function name!
+The match for sourced scripts is done against the full file name.  Examples: >
+	breakadd file explorer
+won't match, the path is missing. >
+	breakadd file *explorer.vim
+matches ".../plugin/explorer.vim" and ".../plugin/iexplorer.vim". >
+	breakadd file */explorer.vim
+matches ".../plugin/explorer.vim" only.
+The match for functions is done against the name as it's shown in the output
+of ":function".  For local functions this means that something like "<SNR>99_"
+is prepended.
+DELETING BREAKPOINTS
+						*:breakd* *:breakdel* *E161*
+:breakd[el] {nr}
+		Delete breakpoint {nr}.  Use |:breaklist| to see the number of
+		each breakpoint.
+:breakd[el] func [lnum] {name}
+		Delete a breakpoint in a function.
+:breakd[el] file [lnum] {name}
+		Delete a breakpoint in a sourced file.
+When [lnum] is omitted, the first breakpoint in the function or file is
+deleted.
+The {name} must be exactly the same as what was typed for the ":breakadd"
+command.  "explorer", "*explorer.vim" and "*explorer*" are different.
+LISTING BREAKPOINTS
+							*:breakl* *:breaklist*
+:breakl[ist]
+		List all breakpoints.
+OBSCURE
+						*:debugg* *:debuggreedy*
+:debugg[reedy]
+		Read debug mode commands from the normal input stream, instead
+		of getting them directly from the user.  Only useful for test
+		scripts.  Example: >
+		  echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
+:0debugg[reedy]
+		Undo ":debuggreedy": get debug mode commands directly from the
+		user, don't use typeahead for debug commands.
+vim:tw=78:ts=8:ft=help:norl:

Mercurial > vim

comparison runtime/doc/repeat.txt @ 7:3fc0f57ecb91 v7.0001