annotate runtime/doc/usr_40.txt @ 18415:52eb1bbf7690

Added tag v8.1.2201 for changeset 6b8508ea90d798b96e29aaa21d6f8021c43128a7
author Bram Moolenaar <Bram@vim.org>
date Wed, 23 Oct 2019 21:45:04 +0200
parents 5c5908e81e93
children af69c9335223
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13963
1174611ad715 Vim 8.1 release
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
1 *usr_40.txt* For Vim version 8.1. Last change: 2013 Aug 05
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
3 VIM USER MANUAL - by Bram Moolenaar
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
5 Make new commands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
6
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
8 Vim is an extensible editor. You can take a sequence of commands you use
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
9 often and turn it into a new command. Or redefine an existing command.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
10 Autocommands make it possible to execute commands automatically.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
11
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
12 |40.1| Key mapping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
13 |40.2| Defining command-line commands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
14 |40.3| Autocommands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
15
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
16 Next chapter: |usr_41.txt| Write a Vim script
800
d8f905020502 updated for version 7.0b
vimboss
parents: 237
diff changeset
17 Previous chapter: |usr_32.txt| The undo tree
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
18 Table of contents: |usr_toc.txt|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
19
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
20 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
21 *40.1* Key mapping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
22
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
23 A simple mapping was explained in section |05.3|. The principle is that one
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
24 sequence of key strokes is translated into another sequence of key strokes.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
25 This is a simple, yet powerful mechanism.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
26 The simplest form is that one key is mapped to a sequence of keys. Since
2207
b17bbfa96fa0 Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
27 the function keys, except <F1>, have no predefined meaning in Vim, these are
b17bbfa96fa0 Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
28 good choices to map. Example: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
29
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
30 :map <F2> GoDate: <Esc>:read !date<CR>kJ
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
31
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
32 This shows how three modes are used. After going to the last line with "G",
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
33 the "o" command opens a new line and starts Insert mode. The text "Date: " is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
34 inserted and <Esc> takes you out of insert mode.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
35 Notice the use of special keys inside <>. This is called angle bracket
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
36 notation. You type these as separate characters, not by pressing the key
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
37 itself. This makes the mappings better readable and you can copy and paste
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
38 the text without problems.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
39 The ":" character takes Vim to the command line. The ":read !date" command
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
40 reads the output from the "date" command and appends it below the current
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
41 line. The <CR> is required to execute the ":read" command.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
42 At this point of execution the text looks like this:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
43
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
44 Date: ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
45 Fri Jun 15 12:54:34 CEST 2001 ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
46
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
47 Now "kJ" moves the cursor up and joins the lines together.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
48 To decide which key or keys you use for mapping, see |map-which-keys|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
49
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
50
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
51 MAPPING AND MODES
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
52
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
53 The ":map" command defines remapping for keys in Normal mode. You can also
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
54 define mappings for other modes. For example, ":imap" applies to Insert mode.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
55 You can use it to insert a date below the cursor: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
56
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
57 :imap <F2> <CR>Date: <Esc>:read !date<CR>kJ
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
58
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
59 It looks a lot like the mapping for <F2> in Normal mode, only the start is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
60 different. The <F2> mapping for Normal mode is still there. Thus you can map
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
61 the same key differently for each mode.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
62 Notice that, although this mapping starts in Insert mode, it ends in Normal
42
c75153d791d0 updated for version 7.0026
vimboss
parents: 7
diff changeset
63 mode. If you want it to continue in Insert mode, append an "a" to the
c75153d791d0 updated for version 7.0026
vimboss
parents: 7
diff changeset
64 mapping.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
65
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
66 Here is an overview of map commands and in which mode they work:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
67
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
68 :map Normal, Visual and Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
69 :vmap Visual
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
70 :nmap Normal
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
71 :omap Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
72 :map! Insert and Command-line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
73 :imap Insert
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
74 :cmap Command-line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
75
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
76 Operator-pending mode is when you typed an operator character, such as "d" or
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
77 "y", and you are expected to type the motion command or a text object. Thus
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
78 when you type "dw", the "w" is entered in operator-pending mode.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
79
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
80 Suppose that you want to define <F7> so that the command d<F7> deletes a C
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
81 program block (text enclosed in curly braces, {}). Similarly y<F7> would yank
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
82 the program block into the unnamed register. Therefore, what you need to do
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
83 is to define <F7> to select the current program block. You can do this with
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
84 the following command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
85
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
86 :omap <F7> a{
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
87
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
88 This causes <F7> to perform a select block "a{" in operator-pending mode, just
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
89 like you typed it. This mapping is useful if typing a { on your keyboard is a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
90 bit difficult.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
91
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
92
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
93 LISTING MAPPINGS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
94
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
95 To see the currently defined mappings, use ":map" without arguments. Or one
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
96 of the variants that include the mode in which they work. The output could
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
97 look like this:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
98
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
99 _g :call MyGrep(1)<CR> ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
100 v <F2> :s/^/> /<CR>:noh<CR>`` ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
101 n <F2> :.,$s/^/> /<CR>:noh<CR>`` ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
102 <xHome> <Home>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
103 <xEnd> <End>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
104
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
105
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
106 The first column of the list shows in which mode the mapping is effective.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
107 This is "n" for Normal mode, "i" for Insert mode, etc. A blank is used for a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
108 mapping defined with ":map", thus effective in both Normal and Visual mode.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
109 One useful purpose of listing the mapping is to check if special keys in <>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
110 form have been recognized (this only works when color is supported). For
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
111 example, when <Esc> is displayed in color, it stands for the escape character.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
112 When it has the same color as the other text, it is five characters.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
113
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
114
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
115 REMAPPING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
116
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
117 The result of a mapping is inspected for other mappings in it. For example,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
118 the mappings for <F2> above could be shortened to: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
119
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
120 :map <F2> G<F3>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
121 :imap <F2> <Esc><F3>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
122 :map <F3> oDate: <Esc>:read !date<CR>kJ
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
123
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
124 For Normal mode <F2> is mapped to go to the last line, and then behave like
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
125 <F3> was pressed. In Insert mode <F2> stops Insert mode with <Esc> and then
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
126 also uses <F3>. Then <F3> is mapped to do the actual work.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
127
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
128 Suppose you hardly ever use Ex mode, and want to use the "Q" command to format
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
129 text (this was so in old versions of Vim). This mapping will do it: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
130
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
131 :map Q gq
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
132
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
133 But, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
134 that you can still go to Ex mode: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
135
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
136 :map gQ Q
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
137
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
138 What happens now is that when you type "gQ" it is mapped to "Q". So far so
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
139 good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
140 you don't get to Ex mode at all.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
141 To avoid keys to be mapped again, use the ":noremap" command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
142
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
143 :noremap gQ Q
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
144
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
145 Now Vim knows that the "Q" is not to be inspected for mappings that apply to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
146 it. There is a similar command for every mode:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
147
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
148 :noremap Normal, Visual and Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
149 :vnoremap Visual
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
150 :nnoremap Normal
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
151 :onoremap Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
152 :noremap! Insert and Command-line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
153 :inoremap Insert
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
154 :cnoremap Command-line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
155
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
156
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
157 RECURSIVE MAPPING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
158
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
159 When a mapping triggers itself, it will run forever. This can be used to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
160 repeat an action an unlimited number of times.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
161 For example, you have a list of files that contain a version number in the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
162 first line. You edit these files with "vim *.txt". You are now editing the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
163 first file. Define this mapping: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
164
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
165 :map ,, :s/5.1/5.2/<CR>:wnext<CR>,,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
166
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
167 Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
168 in the first line. Then it does a ":wnext" to write the file and edit the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
169 next one. The mapping ends in ",,". This triggers the same mapping again,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
170 thus doing the substitution, etc.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
171 This continues until there is an error. In this case it could be a file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
172 where the substitute command doesn't find a match for "5.1". You can then
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
173 make a change to insert "5.1" and continue by typing ",," again. Or the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
174 ":wnext" fails, because you are in the last file in the list.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
175 When a mapping runs into an error halfway, the rest of the mapping is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
176 discarded. CTRL-C interrupts the mapping (CTRL-Break on MS-Windows).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
177
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
178
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
179 DELETE A MAPPING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
180
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
181 To remove a mapping use the ":unmap" command. Again, the mode the unmapping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
182 applies to depends on the command used:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
183
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
184 :unmap Normal, Visual and Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
185 :vunmap Visual
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
186 :nunmap Normal
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
187 :ounmap Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
188 :unmap! Insert and Command-line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
189 :iunmap Insert
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
190 :cunmap Command-line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
191
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
192 There is a trick to define a mapping that works in Normal and Operator-pending
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
193 mode, but not in Visual mode. First define it for all three modes, then
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
194 delete it for Visual mode: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
195
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
196 :map <C-A> /---><CR>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
197 :vunmap <C-A>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
198
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
199 Notice that the five characters "<C-A>" stand for the single key CTRL-A.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
200
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
201 To remove all mappings use the |:mapclear| command. You can guess the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
202 variations for different modes by now. Be careful with this command, it can't
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
203 be undone.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
204
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
205
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
206 SPECIAL CHARACTERS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
207
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
208 The ":map" command can be followed by another command. A | character
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
209 separates the two commands. This also means that a | character can't be used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
210 inside a map command. To include one, use <Bar> (five characters). Example:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
211 >
5690
40f18a1c1592 updated for version 7.4.191
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
212 :map <F8> :write <Bar> !checkin %:S<CR>
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
213
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
214 The same problem applies to the ":unmap" command, with the addition that you
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
215 have to watch out for trailing white space. These two commands are different:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
216 >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
217 :unmap a | unmap b
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
218 :unmap a| unmap b
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
219
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
220 The first command tries to unmap "a ", with a trailing space.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
221
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
222 When using a space inside a mapping, use <Space> (seven characters): >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
223
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
224 :map <Space> W
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
225
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
226 This makes the spacebar move a blank-separated word forward.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
227
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
228 It is not possible to put a comment directly after a mapping, because the "
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
229 character is considered to be part of the mapping. You can use |", this
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
230 starts a new, empty command with a comment. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
231
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
232 :map <Space> W| " Use spacebar to move forward a word
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
233
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
234
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
235 MAPPINGS AND ABBREVIATIONS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
236
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
237 Abbreviations are a lot like Insert mode mappings. The arguments are handled
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
238 in the same way. The main difference is the way they are triggered. An
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
239 abbreviation is triggered by typing a non-word character after the word. A
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
240 mapping is triggered when typing the last character.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
241 Another difference is that the characters you type for an abbreviation are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
242 inserted in the text while you type them. When the abbreviation is triggered
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
243 these characters are deleted and replaced by what the abbreviation produces.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
244 When typing the characters for a mapping, nothing is inserted until you type
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
245 the last character that triggers it. If the 'showcmd' option is set, the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
246 typed characters are displayed in the last line of the Vim window.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
247 An exception is when a mapping is ambiguous. Suppose you have done two
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
248 mappings: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
249
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
250 :imap aa foo
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
251 :imap aaa bar
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
252
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
253 Now, when you type "aa", Vim doesn't know if it should apply the first or the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
254 second mapping. It waits for another character to be typed. If it is an "a",
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
255 the second mapping is applied and results in "bar". If it is a space, for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
256 example, the first mapping is applied, resulting in "foo", and then the space
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
257 is inserted.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
258
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
259
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
260 ADDITIONALLY...
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
261
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
262 The <script> keyword can be used to make a mapping local to a script. See
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
263 |:map-<script>|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
264
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
265 The <buffer> keyword can be used to make a mapping local to a specific buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
266 See |:map-<buffer>|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
267
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
268 The <unique> keyword can be used to make defining a new mapping fail when it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
269 already exists. Otherwise a new mapping simply overwrites the old one. See
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
270 |:map-<unique>|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
271
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
272 To make a key do nothing, map it to <Nop> (five characters). This will make
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
273 the <F7> key do nothing at all: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
274
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
275 :map <F7> <Nop>| map! <F7> <Nop>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
276
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
277 There must be no space after <Nop>.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
278
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
279 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
280 *40.2* Defining command-line commands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
281
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
282 The Vim editor enables you to define your own commands. You execute these
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
283 commands just like any other Command-line mode command.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
284 To define a command, use the ":command" command, as follows: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
285
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
286 :command DeleteFirst 1delete
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
287
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
288 Now when you execute the command ":DeleteFirst" Vim executes ":1delete", which
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
289 deletes the first line.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
290
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
291 Note:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
292 User-defined commands must start with a capital letter. You cannot
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
293 use ":X", ":Next" and ":Print". The underscore cannot be used! You
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
294 can use digits, but this is discouraged.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
295
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
296 To list the user-defined commands, execute the following command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
297
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
298 :command
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
299
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
300 Just like with the builtin commands, the user defined commands can be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
301 abbreviated. You need to type just enough to distinguish the command from
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
302 another. Command line completion can be used to get the full name.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
303
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
304
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
305 NUMBER OF ARGUMENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
306
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
307 User-defined commands can take a series of arguments. The number of arguments
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
308 must be specified by the -nargs option. For instance, the example
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
309 :DeleteFirst command takes no arguments, so you could have defined it as
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
310 follows: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
311
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
312 :command -nargs=0 DeleteFirst 1delete
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
313
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
314 However, because zero arguments is the default, you do not need to add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
315 "-nargs=0". The other values of -nargs are as follows:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
316
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
317 -nargs=0 No arguments
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
318 -nargs=1 One argument
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
319 -nargs=* Any number of arguments
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
320 -nargs=? Zero or one argument
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
321 -nargs=+ One or more arguments
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
322
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
323
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
324 USING THE ARGUMENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
325
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
326 Inside the command definition, the arguments are represented by the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
327 <args> keyword. For example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
328
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
329 :command -nargs=+ Say :echo "<args>"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
330
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
331 Now when you type >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
332
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
333 :Say Hello World
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
334
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
335 Vim echoes "Hello World". However, if you add a double quote, it won't work.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
336 For example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
337
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
338 :Say he said "hello"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
339
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
340 To get special characters turned into a string, properly escaped to use as an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
341 expression, use "<q-args>": >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
342
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
343 :command -nargs=+ Say :echo <q-args>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
344
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
345 Now the above ":Say" command will result in this to be executed: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
346
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
347 :echo "he said \"hello\""
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
348
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
349 The <f-args> keyword contains the same information as the <args> keyword,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
350 except in a format suitable for use as function call arguments. For example:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
351 >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
352 :command -nargs=* DoIt :call AFunction(<f-args>)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
353 :DoIt a b c
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
354
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
355 Executes the following command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
356
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
357 :call AFunction("a", "b", "c")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
358
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
359
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
360 LINE RANGE
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
361
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
362 Some commands take a range as their argument. To tell Vim that you are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
363 defining such a command, you need to specify a -range option. The values for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
364 this option are as follows:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
365
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
366 -range Range is allowed; default is the current line.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
367 -range=% Range is allowed; default is the whole file.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
368 -range={count} Range is allowed; the last number in it is used as a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
369 single number whose default is {count}.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
370
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
371 When a range is specified, the keywords <line1> and <line2> get the values of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
372 the first and last line in the range. For example, the following command
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
373 defines the SaveIt command, which writes out the specified range to the file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
374 "save_file": >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
375
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
376 :command -range=% SaveIt :<line1>,<line2>write! save_file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
377
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
378
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
379 OTHER OPTIONS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
380
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
381 Some of the other options and keywords are as follows:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
382
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
383 -count={number} The command can take a count whose default is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
384 {number}. The resulting count can be used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
385 through the <count> keyword.
237
73354c21f1e4 updated for version 7.0066
vimboss
parents: 42
diff changeset
386 -bang You can use a !. If present, using <bang> will
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
387 result in a !.
237
73354c21f1e4 updated for version 7.0066
vimboss
parents: 42
diff changeset
388 -register You can specify a register. (The default is
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
389 the unnamed register.)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
390 The register specification is available as
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
391 <reg> (a.k.a. <register>).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
392 -complete={type} Type of command-line completion used. See
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
393 |:command-completion| for the list of possible
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
394 values.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
395 -bar The command can be followed by | and another
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
396 command, or " and a comment.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
397 -buffer The command is only available for the current
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
398 buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
399
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
400 Finally, you have the <lt> keyword. It stands for the character <. Use this
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
401 to escape the special meaning of the <> items mentioned.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
402
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
403
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
404 REDEFINING AND DELETING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
405
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
406 To redefine the same command use the ! argument: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
407
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
408 :command -nargs=+ Say :echo "<args>"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
409 :command! -nargs=+ Say :echo <q-args>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
410
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
411 To delete a user command use ":delcommand". It takes a single argument, which
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
412 is the name of the command. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
413
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
414 :delcommand SaveIt
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
415
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
416 To delete all the user commands: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
417
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
418 :comclear
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
419
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
420 Careful, this can't be undone!
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
421
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
422 More details about all this in the reference manual: |user-commands|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
423
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
424 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
425 *40.3* Autocommands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
426
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
427 An autocommand is a command that is executed automatically in response to some
237
73354c21f1e4 updated for version 7.0066
vimboss
parents: 42
diff changeset
428 event, such as a file being read or written or a buffer change. Through the
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
429 use of autocommands you can train Vim to edit compressed files, for example.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
430 That is used in the |gzip| plugin.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
431 Autocommands are very powerful. Use them with care and they will help you
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
432 avoid typing many commands. Use them carelessly and they will cause a lot of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
433 trouble.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
434
237
73354c21f1e4 updated for version 7.0066
vimboss
parents: 42
diff changeset
435 Suppose you want to replace a datestamp on the end of a file every time it is
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
436 written. First you define a function: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
437
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
438 :function DateInsert()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
439 : $delete
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
440 : read !date
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
441 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
442
5294
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
443 You want this function to be called each time, just before a buffer is written
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
444 to a file. This will make that happen: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
445
5294
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
446 :autocmd BufWritePre * call DateInsert()
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
447
5294
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
448 "BufWritePre" is the event for which this autocommand is triggered: Just
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
449 before (pre) writing a buffer to a file. The "*" is a pattern to match with
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
450 the file name. In this case it matches all files.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
451 With this command enabled, when you do a ":write", Vim checks for any
5294
359743c1f59a release version 7.4
Bram Moolenaar <bram@vim.org>
parents: 5247
diff changeset
452 matching BufWritePre autocommands and executes them, and then it
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
453 performs the ":write".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
454 The general form of the :autocmd command is as follows: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
455
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
456 :autocmd [group] {events} {file_pattern} [nested] {command}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
457
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
458 The [group] name is optional. It is used in managing and calling the commands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
459 (more on this later). The {events} parameter is a list of events (comma
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
460 separated) that trigger the command.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
461 {file_pattern} is a filename, usually with wildcards. For example, using
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
462 "*.txt" makes the autocommand be used for all files whose name end in ".txt".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
463 The optional [nested] flag allows for nesting of autocommands (see below), and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
464 finally, {command} is the command to be executed.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
465
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
466
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
467 EVENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
468
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
469 One of the most useful events is BufReadPost. It is triggered after a new
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
470 file is being edited. It is commonly used to set option values. For example,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
471 you know that "*.gsm" files are GNU assembly language. To get the syntax file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
472 right, define this autocommand: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
473
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
474 :autocmd BufReadPost *.gsm set filetype=asm
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
475
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
476 If Vim is able to detect the type of file, it will set the 'filetype' option
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
477 for you. This triggers the Filetype event. Use this to do something when a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
478 certain type of file is edited. For example, to load a list of abbreviations
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
479 for text files: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
480
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
481 :autocmd Filetype text source ~/.vim/abbrevs.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
482
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
483 When starting to edit a new file, you could make Vim insert a skeleton: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
484
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
485 :autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.c
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
486
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
487 See |autocmd-events| for a complete list of events.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
488
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
489
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
490 PATTERNS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
491
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
492 The {file_pattern} argument can actually be a comma-separated list of file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
493 patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
494 The usual file wildcards can be used. Here is a summary of the most often
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
495 used ones:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
496
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
497 * Match any character any number of times
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
498 ? Match any character once
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
499 [abc] Match the character a, b or c
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
500 . Matches a dot
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
501 a{b,c} Matches "ab" and "ac"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
502
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
503 When the pattern includes a slash (/) Vim will compare directory names.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
504 Without the slash only the last part of a file name is used. For example,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
505 "*.txt" matches "/home/biep/readme.txt". The pattern "/home/biep/*" would
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
506 also match it. But "home/foo/*.txt" wouldn't.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
507 When including a slash, Vim matches the pattern against both the full path
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
508 of the file ("/home/biep/readme.txt") and the relative path (e.g.,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
509 "biep/readme.txt").
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
510
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
511 Note:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
512 When working on a system that uses a backslash as file separator, such
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
513 as MS-Windows, you still use forward slashes in autocommands. This
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
514 makes it easier to write the pattern, since a backslash has a special
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
515 meaning. It also makes the autocommands portable.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
516
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
517
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
518 DELETING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
519
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
520 To delete an autocommand, use the same command as what it was defined with,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
521 but leave out the {command} at the end and use a !. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
522
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
523 :autocmd! FileWritePre *
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
524
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
525 This will delete all autocommands for the "FileWritePre" event that use the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
526 "*" pattern.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
527
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
528
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
529 LISTING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
530
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
531 To list all the currently defined autocommands, use this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
532
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
533 :autocmd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
534
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
535 The list can be very long, especially when filetype detection is used. To
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
536 list only part of the commands, specify the group, event and/or pattern. For
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
537 example, to list all BufNewFile autocommands: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
538
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
539 :autocmd BufNewFile
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
540
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
541 To list all autocommands for the pattern "*.c": >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
542
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
543 :autocmd * *.c
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
544
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
545 Using "*" for the event will list all the events. To list all autocommands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
546 for the cprograms group: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
547
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
548 :autocmd cprograms
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
549
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
550
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
551 GROUPS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
552
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
553 The {group} item, used when defining an autocommand, groups related autocommands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
554 together. This can be used to delete all the autocommands in a certain group,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
555 for example.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
556 When defining several autocommands for a certain group, use the ":augroup"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
557 command. For example, let's define autocommands for C programs: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
558
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
559 :augroup cprograms
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
560 : autocmd BufReadPost *.c,*.h :set sw=4 sts=4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
561 : autocmd BufReadPost *.cpp :set sw=3 sts=3
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
562 :augroup END
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
563
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
564 This will do the same as: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
565
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
566 :autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
567 :autocmd cprograms BufReadPost *.cpp :set sw=3 sts=3
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
568
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
569 To delete all autocommands in the "cprograms" group: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
570
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
571 :autocmd! cprograms
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
572
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
573
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
574 NESTING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
575
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
576 Generally, commands executed as the result of an autocommand event will not
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
577 trigger any new events. If you read a file in response to a FileChangedShell
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
578 event, it will not trigger the autocommands that would set the syntax, for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
579 example. To make the events triggered, add the "nested" argument: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
580
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
581 :autocmd FileChangedShell * nested edit
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
582
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
583
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
584 EXECUTING AUTOCOMMANDS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
585
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
586 It is possible to trigger an autocommand by pretending an event has occurred.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
587 This is useful to have one autocommand trigger another one. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
588
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
589 :autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
590
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
591 This defines an autocommand that is triggered when a new file has been edited.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
592 The file name must end in ".new". The ":execute" command uses expression
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
593 evaluation to form a new command and execute it. When editing the file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
594 "tryout.c.new" the executed command will be: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
595
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
596 :doautocmd BufReadPost tryout.c
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
597
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
598 The expand() function takes the "<afile>" argument, which stands for the file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
599 name the autocommand was executed for, and takes the root of the file name
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
600 with ":r".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
601
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
602 ":doautocmd" executes on the current buffer. The ":doautoall" command works
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
603 like "doautocmd" except it executes on all the buffers.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
604
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
605
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
606 USING NORMAL MODE COMMANDS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
607
1125
96cd8222a819 updated for version 7.1a
vimboss
parents: 874
diff changeset
608 The commands executed by an autocommand are Command-line commands. If you
96cd8222a819 updated for version 7.1a
vimboss
parents: 874
diff changeset
609 want to use a Normal mode command, the ":normal" command can be used.
96cd8222a819 updated for version 7.1a
vimboss
parents: 874
diff changeset
610 Example: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
611
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
612 :autocmd BufReadPost *.log normal G
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
613
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
614 This will make the cursor jump to the last line of *.log files when you start
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
615 to edit it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
616 Using the ":normal" command is a bit tricky. First of all, make sure its
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
617 argument is a complete command, including all the arguments. When you use "i"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
618 to go to Insert mode, there must also be a <Esc> to leave Insert mode again.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
619 If you use a "/" to start a search pattern, there must be a <CR> to execute
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
620 it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
621 The ":normal" command uses all the text after it as commands. Thus there
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
622 can be no | and another command following. To work around this, put the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
623 ":normal" command inside an ":execute" command. This also makes it possible
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
624 to pass unprintable characters in a convenient way. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
625
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
626 :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" |
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
627 \ 1read !date
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
628
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
629 This also shows the use of a backslash to break a long command into more
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
630 lines. This can be used in Vim scripts (not at the command line).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
631
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
632 When you want the autocommand do something complicated, which involves jumping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
633 around in the file and then returning to the original position, you may want
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
634 to restore the view on the file. See |restore-position| for an example.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
635
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
636
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
637 IGNORING EVENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
638
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
639 At times, you will not want to trigger an autocommand. The 'eventignore'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
640 option contains a list of events that will be totally ignored. For example,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
641 the following causes events for entering and leaving a window to be ignored: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
642
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
643 :set eventignore=WinEnter,WinLeave
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
644
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
645 To ignore all events, use the following command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
646
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
647 :set eventignore=all
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
648
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
649 To set it back to the normal behavior, make 'eventignore' empty: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
650
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
651 :set eventignore=
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
652
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
653 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
654
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
655 Next chapter: |usr_41.txt| Write a Vim script
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
656
14519
5c5908e81e93 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
657 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: