|
799
|
1 *if_tcl.txt* For Vim version 7.0b. Last change: 2006 Mar 06
|
|
7
|
2
|
|
|
3
|
|
|
4 VIM REFERENCE MANUAL by Ingo Wilken
|
|
|
5
|
|
|
6
|
|
|
7 The Tcl Interface to Vim *tcl* *Tcl* *TCL*
|
|
|
8
|
|
|
9 1. Commands |tcl-ex-commands|
|
|
|
10 2. Tcl commands |tcl-commands|
|
|
|
11 3. Tcl variables |tcl-variables|
|
|
|
12 4. Tcl window commands |tcl-window-cmds|
|
|
|
13 5. Tcl buffer commands |tcl-buffer-cmds|
|
|
|
14 6. Miscellaneous; Output from Tcl |tcl-misc| |tcl-output|
|
|
|
15 7. Known bugs & problems |tcl-bugs|
|
|
|
16 8. Examples |tcl-examples|
|
|
557
|
17 9. Dynamic loading |tcl-dynamic|
|
|
7
|
18
|
|
|
19 {Vi does not have any of these commands} *E280* *E281*
|
|
|
20
|
|
|
21 The Tcl interface only works when Vim was compiled with the |+tcl| feature.
|
|
|
22
|
|
|
23 WARNING: There are probably still some bugs. Please send bug reports,
|
|
|
24 comments, ideas etc to <Ingo.Wilken@informatik.uni-oldenburg.de>
|
|
|
25
|
|
|
26 ==============================================================================
|
|
|
27 1. Commands *tcl-ex-commands* *E571* *E572*
|
|
|
28
|
|
|
29 *:tcl* *:tc*
|
|
|
30 :tc[l] {cmd} Execute Tcl command {cmd}.
|
|
|
31
|
|
|
32 :[range]tc[l] << {endmarker}
|
|
|
33 {script}
|
|
|
34 {endmarker}
|
|
|
35 Execute Tcl script {script}.
|
|
|
36 Note: This command doesn't work when the Tcl feature
|
|
|
37 wasn't compiled in. To avoid errors, see
|
|
|
38 |script-here|.
|
|
|
39
|
|
236
|
40 {endmarker} must NOT be preceded by any white space. If {endmarker} is
|
|
7
|
41 omitted from after the "<<", a dot '.' must be used after {script}, like for
|
|
|
42 the |:append| and |:insert| commands.
|
|
|
43 This form of the |:tcl| command is mainly useful for including tcl code in Vim
|
|
|
44 scripts.
|
|
|
45
|
|
|
46 Example: >
|
|
|
47 function! DefineDate()
|
|
|
48 tcl << EOF
|
|
|
49 proc date {} {
|
|
|
50 return [clock format [clock seconds]]
|
|
|
51 }
|
|
|
52 EOF
|
|
|
53 endfunction
|
|
|
54 <
|
|
|
55
|
|
|
56 *:tcldo* *:tcld*
|
|
|
57 :[range]tcld[o] {cmd} Execute Tcl command {cmd} for each line in [range]
|
|
|
58 with the variable "line" being set to the text of each
|
|
|
59 line in turn, and "lnum" to the line number. Setting
|
|
|
60 "line" will change the text, but note that it is not
|
|
|
61 possible to add or delete lines using this command.
|
|
|
62 If {cmd} returns an error, the command is interrupted.
|
|
|
63 The default for [range] is the whole file: "1,$".
|
|
|
64 See |tcl-var-line| and |tcl-var-lnum|. {not in Vi}
|
|
|
65
|
|
|
66 *:tclfile* *:tclf*
|
|
|
67 :tclf[ile] {file} Execute the Tcl script in {file}. This is the same as
|
|
|
68 ":tcl source {file}", but allows file name completion.
|
|
|
69 {not in Vi}
|
|
|
70
|
|
|
71
|
|
|
72 Note that Tcl objects (like variables) persist from one command to the next,
|
|
|
73 just as in the Tcl shell.
|
|
|
74
|
|
|
75 Executing Tcl commands is not possible in the |sandbox|.
|
|
|
76
|
|
|
77 ==============================================================================
|
|
|
78 2. Tcl commands *tcl-commands*
|
|
|
79
|
|
|
80 Tcl code gets all of its access to vim via commands in the "::vim" namespace.
|
|
|
81 The following commands are implemented: >
|
|
|
82
|
|
|
83 ::vim::beep # Guess.
|
|
|
84 ::vim::buffer {n} # Create Tcl command for one buffer.
|
|
|
85 ::vim::buffer list # Create Tcl commands for all buffers.
|
|
|
86 ::vim::command [-quiet] {cmd} # Execute an ex command.
|
|
|
87 ::vim::expr {expr} # Use Vim's expression evaluator.
|
|
|
88 ::vim::option {opt} # Get vim option.
|
|
|
89 ::vim::option {opt} {val} # Set vim option.
|
|
|
90 ::vim::window list # Create Tcl commands for all windows.
|
|
|
91
|
|
|
92 Commands:
|
|
|
93 ::vim::beep *tcl-beep*
|
|
|
94 Honk. Does not return a result.
|
|
|
95
|
|
|
96 ::vim::buffer {n} *tcl-buffer*
|
|
|
97 ::vim::buffer exists {n}
|
|
|
98 ::vim::buffer list
|
|
|
99 Provides access to vim buffers. With an integer argument, creates a
|
|
|
100 buffer command (see |tcl-buffer-cmds|) for the buffer with that
|
|
|
101 number, and returns its name as the result. Invalid buffer numbers
|
|
|
102 result in a standard Tcl error. To test for valid buffer numbers,
|
|
|
103 vim's internal functions can be used: >
|
|
|
104 set nbufs [::vim::expr bufnr("$")]
|
|
|
105 set isvalid [::vim::expr "bufexists($n)"]
|
|
|
106 < The "list" option creates a buffer command for each valid buffer, and
|
|
|
107 returns a list of the command names as the result.
|
|
|
108 Example: >
|
|
|
109 set bufs [::vim::buffer list]
|
|
|
110 foreach b $bufs { $b append end "The End!" }
|
|
|
111 < The "exists" option checks if a buffer with the given number exists.
|
|
|
112 Example: >
|
|
|
113 if { [::vim::buffer exists $n] } { ::vim::command ":e #$n" }
|
|
|
114 < This command might be replaced by a variable in future versions.
|
|
|
115 See also |tcl-var-current| for the current buffer.
|
|
|
116
|
|
|
117 ::vim::command {cmd} *tcl-command*
|
|
|
118 ::vim::command -quiet {cmd}
|
|
|
119 Execute the vim (ex-mode) command {cmd}. Any ex command that affects
|
|
|
120 a buffer or window uses the current buffer/current window. Does not
|
|
|
121 return a result other than a standard Tcl error code. After this
|
|
|
122 command is completed, the "::vim::current" variable is updated.
|
|
|
123 The "-quiet" flag suppresses any error messages from vim.
|
|
|
124 Examples: >
|
|
|
125 ::vim::command "set ts=8"
|
|
|
126 ::vim::command "%s/foo/bar/g"
|
|
|
127 < To execute normal-mode commands, use "normal" (see |:normal|): >
|
|
|
128 set cmd "jj"
|
|
|
129 ::vim::command "normal $cmd"
|
|
|
130 < See also |tcl-window-command| and |tcl-buffer-command|.
|
|
|
131
|
|
|
132 ::vim::expr {expr} *tcl-expr*
|
|
|
133 Evaluates the expression {expr} using vim's internal expression
|
|
|
134 evaluator (see |expression|). Any expression that queries a buffer
|
|
|
135 or window property uses the current buffer/current window. Returns
|
|
714
|
136 the result as a string. A |List| is turned into a string by joining
|
|
|
137 the items and inserting line breaks.
|
|
7
|
138 Examples: >
|
|
|
139 set perl_available [::vim::expr has("perl")]
|
|
|
140 < See also |tcl-window-expr| and |tcl-buffer-expr|.
|
|
|
141
|
|
|
142 ::vim::option {opt} *tcl-option*
|
|
|
143 ::vim::option {opt} {value}
|
|
|
144 Without second argument, queries the value of a vim option. With this
|
|
|
145 argument, sets the vim option to {value}, and returns the previous
|
|
|
146 value as the result. Any options that are marked as 'local to buffer'
|
|
|
147 or 'local to window' affect the current buffer/current window. The
|
|
|
148 global value is not changed, use the ":set" command for that. For
|
|
|
149 boolean options, {value} should be "0" or "1", or any of the keywords
|
|
|
150 "on", "off" or "toggle". See |option-summary| for a list of options.
|
|
|
151 Example: >
|
|
|
152 ::vim::option ts 8
|
|
|
153 < See also |tcl-window-option| and |tcl-buffer-option|.
|
|
|
154
|
|
|
155 ::vim::window {option} *tcl-window*
|
|
|
156 Provides access to vim windows. Currently only the "list" option is
|
|
236
|
157 implemented. This creates a window command (see |tcl-window-cmds|) for
|
|
7
|
158 each window, and returns a list of the command names as the result.
|
|
|
159 Example: >
|
|
|
160 set wins [::vim::window list]
|
|
|
161 foreach w $wins { $w height 4 }
|
|
|
162 < This command might be replaced by a variable in future versions.
|
|
|
163 See also |tcl-var-current| for the current window.
|
|
|
164
|
|
|
165 ==============================================================================
|
|
|
166 3. Tcl variables *tcl-variables*
|
|
|
167
|
|
|
168 The ::vim namespace contains a few variables. These are created when the Tcl
|
|
|
169 interpreter is called from vim and set to current values. >
|
|
|
170
|
|
|
171 ::vim::current # array containing "current" objects
|
|
|
172 ::vim::lbase # number of first line
|
|
|
173 ::vim::range # array containing current range numbers
|
|
|
174 line # current line as a string (:tcldo only)
|
|
|
175 lnum # current line number (:tcldo only)
|
|
|
176
|
|
|
177 Variables:
|
|
|
178 ::vim::current *tcl-var-current*
|
|
|
179 This is an array providing access to various "current" objects
|
|
|
180 available in vim. The contents of this array are updated after
|
|
|
181 "::vim::command" is called, as this might change vim's current
|
|
|
182 settings (e.g., by deleting the current buffer).
|
|
|
183 The "buffer" element contains the name of the buffer command for the
|
|
|
184 current buffer. This can be used directly to invoke buffer commands
|
|
|
185 (see |tcl-buffer-cmds|). This element is read-only.
|
|
|
186 Example: >
|
|
|
187 $::vim::current(buffer) insert begin "Hello world"
|
|
|
188 < The "window" element contains the name of the window command for the
|
|
|
189 current window. This can be used directly to invoke window commands
|
|
|
190 (see |tcl-window-cmds|). This element is read-only.
|
|
|
191 Example: >
|
|
|
192 $::vim::current(window) height 10
|
|
|
193 <
|
|
|
194 ::vim::lbase *tcl-var-lbase*
|
|
|
195 This variable controls how Tcl treats line numbers. If it is set to
|
|
|
196 '1', then lines and columns start at 1. This way, line numbers from
|
|
|
197 Tcl commands and vim expressions are compatible. If this variable is
|
|
|
198 set to '0', then line numbers and columns start at 0 in Tcl. This is
|
|
|
199 useful if you want to treat a buffer as a Tcl list or a line as a Tcl
|
|
|
200 string and use standard Tcl commands that return an index ("lsort" or
|
|
|
201 "string first", for example). The default value is '1'. Currently,
|
|
|
202 any non-zero values is treated as '1', but your scripts should not
|
|
|
203 rely on this. See also |tcl-linenumbers|.
|
|
|
204
|
|
|
205 ::vim::range *tcl-var-range*
|
|
|
206 This is an array with three elements, "start", "begin" and "end". It
|
|
|
207 contains the line numbers of the start and end row of the current
|
|
|
208 range. "begin" is the same as "start". This variable is read-only.
|
|
|
209 See |tcl-examples|.
|
|
|
210
|
|
|
211 line *tcl-var-line*
|
|
|
212 lnum *tcl-var-lnum*
|
|
|
213 These global variables are only available if the ":tcldo" ex command
|
|
|
214 is being executed. They contain the text and line number of the
|
|
|
215 current line. When the Tcl command invoked by ":tcldo" is completed,
|
|
|
216 the current line is set to the contents of the "line" variable, unless
|
|
|
217 the variable was unset by the Tcl command. The "lnum" variable is
|
|
|
218 read-only. These variables are not in the "::vim" namespace so they
|
|
|
219 can be used in ":tcldo" without much typing (this might be changed in
|
|
|
220 future versions). See also |tcl-linenumbers|.
|
|
|
221
|
|
|
222 ==============================================================================
|
|
|
223 4. Tcl window commands *tcl-window-cmds*
|
|
|
224
|
|
|
225 Window commands represent vim windows. They are created by several commands:
|
|
|
226 ::vim::window list |tcl-window|
|
|
|
227 "windows" option of a buffer command |tcl-buffer-windows|
|
|
|
228 The ::vim::current(window) variable contains the name of the window command
|
|
|
229 for the current window. A window command is automatically deleted when the
|
|
|
230 corresponding vim window is closed.
|
|
|
231
|
|
236
|
232 Let's assume the name of the window command is stored in the Tcl variable "win",
|
|
7
|
233 i.e. "$win" calls the command. The following options are available: >
|
|
|
234
|
|
|
235 $win buffer # Create Tcl command for window's buffer.
|
|
|
236 $win command {cmd} # Execute ex command in windows context.
|
|
|
237 $win cursor # Get current cursor position.
|
|
|
238 $win cursor {var} # Set cursor position from array variable.
|
|
|
239 $win cursor {row} {col} # Set cursor position.
|
|
|
240 $win delcmd {cmd} # Call Tcl command when window is closed.
|
|
|
241 $win expr {expr} # Evaluate vim expression in windows context.
|
|
|
242 $win height # Report the window's height.
|
|
|
243 $win height {n} # Set the window's height.
|
|
|
244 $win option {opt} [val] # Get/Set vim option in windows context.
|
|
|
245
|
|
|
246 Options:
|
|
|
247 $win buffer *tcl-window-buffer*
|
|
|
248 Creates a Tcl command for the window's buffer, and returns its name as
|
|
|
249 the result. The name should be stored in a variable: >
|
|
|
250 set buf [$win buffer]
|
|
|
251 < $buf is now a valid Tcl command. See |tcl-buffer-cmds| for the
|
|
|
252 available options.
|
|
|
253
|
|
|
254 $win cursor *tcl-window-cursor*
|
|
|
255 $win cursor {var}
|
|
|
256 $win cursor {row} {col}
|
|
|
257 Without argument, reports the current cursor position as a string.
|
|
|
258 This can be converted to a Tcl array variable: >
|
|
|
259 array set here [$win cursor]
|
|
|
260 < "here(row)" and "here(column)" now contain the cursor position.
|
|
|
261 With a single argument, the argument is interpreted as the name of a
|
|
|
262 Tcl array variable, which must contain two elements "row" and "column".
|
|
|
263 These are used to set the cursor to the new position: >
|
|
|
264 $win cursor here ;# not $here !
|
|
|
265 < With two arguments, sets the cursor to the specified row and column: >
|
|
|
266 $win cursor $here(row) $here(column)
|
|
|
267 < Invalid positions result in a standard Tcl error, which can be caught
|
|
|
268 with "catch". The row and column values depend on the "::vim::lbase"
|
|
|
269 variable. See |tcl-var-lbase|.
|
|
|
270
|
|
|
271 $win delcmd {cmd} *tcl-window-delcmd*
|
|
|
272 Registers the Tcl command {cmd} as a deletion callback for the window.
|
|
|
273 This command is executed (in the global scope) just before the window
|
|
|
274 is closed. Complex commands should be build with "list": >
|
|
|
275 $win delcmd [list puts vimerr "window deleted"]
|
|
|
276 < See also |tcl-buffer-delcmd|.
|
|
|
277
|
|
|
278 $win height *tcl-window-height*
|
|
|
279 $win height {n}
|
|
|
280 Without argument, reports the window's current height. With an
|
|
|
281 argument, tries to set the window's height to {n}, then reports the
|
|
|
282 new height (which might be different from {n}).
|
|
|
283
|
|
|
284 $win command [-quiet] {cmd} *tcl-window-command*
|
|
|
285 $win expr {expr} *tcl-window-expr*
|
|
|
286 $win option {opt} [val] *tcl-window-option*
|
|
|
287 These are similar to "::vim::command" etc., except that everything is
|
|
|
288 done in the context of the window represented by $win, instead of the
|
|
|
289 current window. For example, setting an option that is marked 'local
|
|
|
290 to window' affects the window $win. Anything that affects or queries
|
|
|
291 a buffer uses the buffer displayed in this window (i.e. the buffer
|
|
|
292 that is represented by "$win buffer"). See |tcl-command|, |tcl-expr|
|
|
|
293 and |tcl-option| for more information.
|
|
|
294 Example: >
|
|
|
295 $win option number on
|
|
|
296
|
|
|
297 ==============================================================================
|
|
|
298 5. Tcl buffer commands *tcl-buffer-cmds*
|
|
|
299
|
|
|
300 Buffer commands represent vim buffers. They are created by several commands:
|
|
|
301 ::vim::buffer {N} |tcl-buffer|
|
|
|
302 ::vim::buffer list |tcl-buffer|
|
|
|
303 "buffer" option of a window command |tcl-window-buffer|
|
|
|
304 The ::vim::current(buffer) variable contains the name of the buffer command
|
|
|
305 for the current buffer. A buffer command is automatically deleted when the
|
|
|
306 corresponding vim buffer is destroyed. Whenever the buffer's contents are
|
|
|
307 changed, all marks in the buffer are automatically adjusted. Any changes to
|
|
|
308 the buffer's contents made by Tcl commands can be undone with the "undo" vim
|
|
|
309 command (see |undo|).
|
|
|
310
|
|
236
|
311 Let's assume the name of the buffer command is stored in the Tcl variable "buf",
|
|
7
|
312 i.e. "$buf" calls the command. The following options are available: >
|
|
|
313
|
|
|
314 $buf append {n} {str} # Append a line to buffer, after line {n}.
|
|
|
315 $buf command {cmd} # Execute ex command in buffers context.
|
|
|
316 $buf count # Report number of lines in buffer.
|
|
|
317 $buf delcmd {cmd} # Call Tcl command when buffer is deleted.
|
|
|
318 $buf delete {n} # Delete a single line.
|
|
|
319 $buf delete {n} {m} # Delete several lines.
|
|
|
320 $buf expr {expr} # Evaluate vim expression in buffers context.
|
|
|
321 $buf get {n} # Get a single line as a string.
|
|
|
322 $buf get {n} {m} # Get several lines as a list.
|
|
|
323 $buf insert {n} {str} # Insert a line in buffer, as line {n}.
|
|
|
324 $buf last # Report line number of last line in buffer.
|
|
|
325 $buf mark {mark} # Report position of buffer mark.
|
|
|
326 $buf name # Report name of file in buffer.
|
|
|
327 $buf number # Report number of this buffer.
|
|
|
328 $buf option {opt} [val] # Get/Set vim option in buffers context.
|
|
|
329 $buf set {n} {text} # Replace a single line.
|
|
|
330 $buf set {n} {m} {list} # Replace several lines.
|
|
|
331 $buf windows # Create Tcl commands for buffer's windows.
|
|
|
332 <
|
|
|
333 *tcl-linenumbers*
|
|
|
334 Most buffer commands take line numbers as arguments. How Tcl treats these
|
|
|
335 numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|). Instead
|
|
|
336 of line numbers, several keywords can be also used: "top", "start", "begin",
|
|
|
337 "first", "bottom", "end" and "last".
|
|
|
338
|
|
|
339 Options:
|
|
|
340 $buf append {n} {str} *tcl-buffer-append*
|
|
|
341 $buf insert {n} {str} *tcl-buffer-insert*
|
|
|
342 Add a line to the buffer. With the "insert" option, the string
|
|
|
343 becomes the new line {n}, with "append" it is inserted after line {n}.
|
|
|
344 Example: >
|
|
|
345 $buf insert top "This is the beginning."
|
|
|
346 $buf append end "This is the end."
|
|
|
347 < To add a list of lines to the buffer, use a loop: >
|
|
|
348 foreach line $list { $buf append $num $line ; incr num }
|
|
|
349 <
|
|
|
350 $buf count *tcl-buffer-count*
|
|
|
351 Reports the total number of lines in the buffer.
|
|
|
352
|
|
|
353 $buf delcmd {cmd} *tcl-buffer-delcmd*
|
|
|
354 Registers the Tcl command {cmd} as a deletion callback for the buffer.
|
|
|
355 This command is executed (in the global scope) just before the buffer
|
|
|
356 is deleted. Complex commands should be build with "list": >
|
|
|
357 $buf delcmd [list puts vimerr "buffer [$buf number] gone"]
|
|
|
358 < See also |tcl-window-delcmd|.
|
|
|
359
|
|
|
360 $buf delete {n} *tcl-buffer-delete*
|
|
|
361 $buf delete {n} {m}
|
|
|
362 Deletes line {n} or lines {n} through {m} from the buffer.
|
|
|
363 This example deletes everything except the last line: >
|
|
|
364 $buf delete first [expr [$buf last] - 1]
|
|
|
365 <
|
|
|
366 $buf get {n} *tcl-buffer-get*
|
|
|
367 $buf get {n} {m}
|
|
|
368 Gets one or more lines from the buffer. For a single line, the result
|
|
|
369 is a string; for several lines, a list of strings.
|
|
|
370 Example: >
|
|
|
371 set topline [$buf get top]
|
|
|
372 <
|
|
|
373 $buf last *tcl-buffer-last*
|
|
|
374 Reports the line number of the last line. This value depends on the
|
|
|
375 "::vim::lbase" variable. See |tcl-var-lbase|.
|
|
|
376
|
|
|
377 $buf mark {mark} *tcl-buffer-mark*
|
|
|
378 Reports the position of the named mark as a string, similar to the
|
|
|
379 cursor position of the "cursor" option of a window command (see
|
|
|
380 |tcl-window-cursor|). This can be converted to a Tcl array variable: >
|
|
|
381 array set mpos [$buf mark "a"]
|
|
|
382 < "mpos(column)" and "mpos(row)" now contain the position of the mark.
|
|
|
383 If the mark is not set, a standard Tcl error results.
|
|
|
384
|
|
|
385 $buf name
|
|
|
386 Reports the name of the file in the buffer. For a buffer without a
|
|
|
387 file, this is an empty string.
|
|
|
388
|
|
|
389 $buf number
|
|
|
390 Reports the number of this buffer. See |:buffers|.
|
|
|
391 This example deletes a buffer from vim: >
|
|
|
392 ::vim::command "bdelete [$buf number]"
|
|
|
393 <
|
|
|
394 $buf set {n} {string} *tcl-buffer-set*
|
|
|
395 $buf set {n} {m} {list}
|
|
|
396 Replace one or several lines in the buffer. If the list contains more
|
|
|
397 elements than there are lines to replace, they are inserted into the
|
|
|
398 buffer. If the list contains fewer elements, any unreplaced line is
|
|
|
399 deleted from the buffer.
|
|
|
400
|
|
|
401 $buf windows *tcl-buffer-windows*
|
|
|
402 Creates a window command for each window that displays this buffer, and
|
|
|
403 returns a list of the command names as the result.
|
|
|
404 Example: >
|
|
|
405 set winlist [$buf windows]
|
|
|
406 foreach win $winlist { $win height 4 }
|
|
|
407 < See |tcl-window-cmds| for the available options.
|
|
|
408
|
|
|
409 $buf command [-quiet] {cmd} *tcl-buffer-command*
|
|
|
410 $buf expr {exr} *tcl-buffer-expr*
|
|
|
411 $buf option {opt} [val] *tcl-buffer-option*
|
|
|
412 These are similar to "::vim::command" etc., except that everything is
|
|
|
413 done in the context of the buffer represented by $buf, instead of the
|
|
|
414 current buffer. For example, setting an option that is marked 'local
|
|
|
415 to buffer' affects the buffer $buf. Anything that affects or queries
|
|
|
416 a window uses the first window in vim's window list that displays this
|
|
|
417 buffer (i.e. the first entry in the list returned by "$buf windows").
|
|
|
418 See |tcl-command|, |tcl-expr| and |tcl-option| for more information.
|
|
|
419 Example: >
|
|
|
420 if { [$buf option modified] } { $buf command "w" }
|
|
|
421
|
|
|
422 ==============================================================================
|
|
|
423 6. Miscellaneous; Output from Tcl *tcl-misc* *tcl-output*
|
|
|
424
|
|
|
425 The standard Tcl commands "exit" and "catch" are replaced by custom versions.
|
|
|
426 "exit" terminates the current Tcl script and returns to vim, which deletes the
|
|
|
427 Tcl interpreter. Another call to ":tcl" then creates a new Tcl interpreter.
|
|
|
428 "exit" does NOT terminate vim! "catch" works as before, except that it does
|
|
|
429 not prevent script termination from "exit". An exit code != 0 causes the ex
|
|
|
430 command that invoked the Tcl script to return an error.
|
|
|
431
|
|
|
432 Two new I/O streams are available in Tcl, "vimout" and "vimerr". All output
|
|
|
433 directed to them is displayed in the vim message area, as information messages
|
|
|
434 and error messages, respectively. The standard Tcl output streams stdout and
|
|
|
435 stderr are mapped to vimout and vimerr, so that a normal "puts" command can be
|
|
|
436 used to display messages in vim.
|
|
|
437
|
|
|
438 ==============================================================================
|
|
|
439 7. Known bugs & problems *tcl-bugs*
|
|
|
440
|
|
|
441 Calling one of the Tcl ex commands from inside Tcl (via "::vim::command") may
|
|
|
442 have unexpected side effects. The command creates a new interpreter, which
|
|
|
443 has the same abilities as the standard interpreter - making "::vim::command"
|
|
|
444 available in a safe child interpreter therefore makes the child unsafe. (It
|
|
|
445 would be trivial to block nested :tcl* calls or ensure that such calls from a
|
|
|
446 safe interpreter create only new safe interpreters, but quite pointless -
|
|
|
447 depending on vim's configuration, "::vim::command" may execute arbitrary code
|
|
|
448 in any number of other scripting languages.) A call to "exit" within this new
|
|
|
449 interpreter does not affect the old interpreter; it only terminates the new
|
|
|
450 interpreter, then script processing continues normally in the old interpreter.
|
|
|
451
|
|
|
452 Input from stdin is currently not supported.
|
|
|
453
|
|
|
454 ==============================================================================
|
|
|
455 8. Examples: *tcl-examples*
|
|
|
456
|
|
|
457 Here are a few small (and maybe useful) Tcl scripts.
|
|
|
458
|
|
|
459 This script sorts the lines of the entire buffer (assume it contains a list
|
|
|
460 of names or something similar):
|
|
|
461 set buf $::vim::current(buffer)
|
|
|
462 set lines [$buf get top bottom]
|
|
|
463 set lines [lsort -dictionary $lines]
|
|
|
464 $buf set top bottom $lines
|
|
|
465
|
|
|
466 This script reverses the lines in the buffer. Note the use of "::vim::lbase"
|
|
|
467 and "$buf last" to work with any line number setting.
|
|
|
468 set buf $::vim::current(buffer)
|
|
|
469 set t $::vim::lbase
|
|
|
470 set b [$buf last]
|
|
|
471 while { $t < $b } {
|
|
|
472 set tl [$buf get $t]
|
|
|
473 set bl [$buf get $b]
|
|
|
474 $buf set $t $bl
|
|
|
475 $buf set $b $tl
|
|
|
476 incr t
|
|
|
477 incr b -1
|
|
|
478 }
|
|
|
479
|
|
|
480 This script adds a consecutive number to each line in the current range:
|
|
|
481 set buf $::vim::current(buffer)
|
|
|
482 set i $::vim::range(start)
|
|
|
483 set n 1
|
|
|
484 while { $i <= $::vim::range(end) } {
|
|
|
485 set line [$buf get $i]
|
|
|
486 $buf set $i "$n\t$line"
|
|
|
487 incr i ; incr n
|
|
|
488 }
|
|
|
489
|
|
|
490 The same can also be done quickly with two ex commands, using ":tcldo":
|
|
|
491 :tcl set n 1
|
|
|
492 :[range]tcldo set line "$n\t$line" ; incr n
|
|
|
493
|
|
|
494 This procedure runs an ex command on each buffer (idea stolen from Ron Aaron):
|
|
|
495 proc eachbuf { cmd } {
|
|
|
496 foreach b [::vim::buffer list] {
|
|
|
497 $b command $cmd
|
|
|
498 }
|
|
|
499 }
|
|
|
500 Use it like this:
|
|
|
501 :tcl eachbuf %s/foo/bar/g
|
|
236
|
502 Be careful with Tcl's string and backslash substitution, tough. If in doubt,
|
|
7
|
503 surround the ex command with curly braces.
|
|
|
504
|
|
|
505
|
|
|
506 If you want to add some Tcl procedures permanently to vim, just place them in
|
|
|
507 a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your
|
|
|
508 startup file (usually "~/.vimrc" on Unix):
|
|
|
509 if has("tcl")
|
|
|
510 tclfile ~/.vimrc.tcl
|
|
|
511 endif
|
|
|
512
|
|
|
513 ==============================================================================
|
|
557
|
514 9. Dynamic loading *tcl-dynamic*
|
|
|
515
|
|
|
516 On MS-Windows the Tcl library can be loaded dynamically. The |:version|
|
|
|
517 output then includes |+tcl/dyn|.
|
|
|
518
|
|
|
519 This means that Vim will search for the Tcl DLL file only when needed. When
|
|
|
520 you don't use the Tcl interface you don't need it, thus you can use Vim
|
|
|
521 without this DLL file.
|
|
|
522
|
|
|
523 To use the Tcl interface the Tcl DLL must be in your search path. In a
|
|
|
524 console window type "path" to see what directories are used.
|
|
|
525
|
|
|
526 The name of the DLL must match the Tcl version Vim was compiled with.
|
|
|
527 Currently the name is "tcl83.dll". That is for Tcl 8.3. To know for sure
|
|
|
528 edit "gvim.exe" and search for "tcl\d*.dll\c".
|
|
|
529
|
|
|
530 ==============================================================================
|
|
7
|
531 vim:tw=78:ts=8:ft=help:norl:
|
