1 *if_tcl.txt* For Vim version 5.8. Last change: 2000 Jun 04
4 VIM REFERENCE MANUAL by Ingo Wilken
7 The Tcl Interface to Vim *tcl* *Tcl* *TCL*
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|
18 {Vi does not have any of these commands}
20 The Tcl interface only works when Vim was compiled with the |+tcl| feature.
22 WARNING: There are probably still some bugs. Please send bug reports,
23 comments, ideas etc to <Ingo.Wilken@informatik.uni-oldenburg.de>
25 ==============================================================================
26 1. Commands *tcl-ex-commands*
29 :tc[l] {cmd} Execute Tcl command {cmd}. {not in Vi}
32 :[range]tcld[o] {cmd} Execute Tcl command {cmd} for each line in [range]
33 with the variable "line" being set to the text of each
34 line in turn, and "lnum" to the line number. Setting
35 "line" will change the text, but note that it is not
36 possible to add or delete lines using this command.
37 If {cmd} returns an error, the command is interrupted.
38 The default for [range] is the whole file: "1,$".
39 See |tcl-var-line| and |tcl-var-lnum|. {not in Vi}
42 :tclf[ile] {file} Execute the Tcl script in {file}. This is the same as
43 ":tcl source {file}", but allows file name completion.
47 Note that Tcl objects (like variables) persist from one command to the next,
48 just as in the Tcl shell.
50 ==============================================================================
51 2. Tcl commands *tcl-commands*
53 Tcl code gets all of its access to vim via commands in the "::vim" namespace.
54 The following commands are implemented:
56 > ::vim::beep # Guess.
57 > ::vim::buffer {n} # Create Tcl command for one buffer.
58 > ::vim::buffer list # Create Tcl commands for all buffers.
59 > ::vim::command [-quiet] {cmd} # Execute an ex command.
60 > ::vim::expr {expr} # Use Vim's expression evaluator.
61 > ::vim::option {opt} # Get vim option.
62 > ::vim::option {opt} {val} # Set vim option.
63 > ::vim::window list # Create Tcl commands for all windows.
66 ::vim::beep *tcl-beep*
67 Honk. Does not return a result.
69 ::vim::buffer {n} *tcl-buffer*
70 ::vim::buffer exists {n}
72 Provides access to vim buffers. With an integer argument, creates a
73 buffer command (see |tcl-buffer-cmds|) for the buffer with that
74 number, and returns its name as the result. Invalid buffer numbers
75 result in a standard Tcl error. To test for valid buffer numbers,
76 vim's internal functions can be used:
77 > set nbufs [::vim::expr bufnr("$")]
78 > set isvalid [::vim::expr "bufexists($n)"]
79 The "list" option creates a buffer command for each valid buffer, and
80 returns a list of the command names as the result.
82 > set bufs [::vim::buffer list]
83 > foreach b $bufs { $b append end "The End!" }
84 The "exists" option checks if a buffer with the given number exists.
86 > if { [::vim::buffer exists $n] } { ::vim::command ":e #$n" }
87 This command might be replaced by a variable in future versions.
88 See also |tcl-var-current| for the current buffer.
90 ::vim::command {cmd} *tcl-command*
91 ::vim::command -quiet {cmd}
92 Execute the vim (ex-mode) command {cmd}. Any ex command that affects
93 a buffer or window uses the current buffer/current window. Does not
94 return a result other than a standard Tcl error code. After this
95 command is completed, the "::vim::current" variable is updated.
96 The "-quiet" flag suppresses any error messages from vim.
98 > ::vim::command "set ts=8"
99 > ::vim::command "%s/foo/bar/g"
100 To execute normal-mode commands, use "normal" (see |:normal|):
102 > ::vim::command "normal $cmd"
103 See also |tcl-window-command| and |tcl-buffer-command|.
105 ::vim::expr {expr} *tcl-expr*
106 Evaluates the expression {expr} using vim's internal expression
107 evaluator (see |expression|). Any expression that queries a buffer
108 or window property uses the current buffer/current window. Returns
109 the result as a string.
111 > set perl_available [::vim::expr has("perl")]
112 See also |tcl-window-expr| and |tcl-buffer-expr|.
114 ::vim::option {opt} *tcl-option*
115 ::vim::option {opt} {value}
116 Without second argument, queries the value of a vim option. With this
117 argument, sets the vim option to {value}, and returns the previous
118 value as the result. Any options that are marked as 'local to buffer'
119 or 'local to window' affect the current buffer/current window. For
120 boolean options, {value} should be "0" or "1", or any of the keywords
121 "on", "off" or "toggle". See |option-summary| for a list of options.
124 See also |tcl-window-option| and |tcl-buffer-option|.
126 ::vim::window {option} *tcl-window*
127 Provides access to vim windows. Currently only the "list" option is
128 implemented. This creates a window command (see |tcl-window-cmds|) for
129 each window, and returns a list of the command names as the result.
131 > set wins [::vim::window list]
132 > foreach w $wins { $w height 4 }
133 This command might be replaced by a variable in future versions.
134 See also |tcl-var-current| for the current window.
136 ==============================================================================
137 3. Tcl variables *tcl-variables*
139 The ::vim namespace contains a few variables. These are created when the Tcl
140 interpreter is called from vim and set to current values.
142 > ::vim::current # array containing "current" objects
143 > ::vim::lbase # number of first line
144 > ::vim::range # array containing current range numbers
145 > line # current line as a string (:tcldo only)
146 > lnum # current line number (:tcldo only)
149 ::vim::current *tcl-var-current*
150 This is an array providing access to various "current" objects
151 available in vim. The contents of this array are updated after
152 "::vim::command" is called, as this might change vim's current
153 settings (e.g., by deleting the current buffer).
154 The "buffer" element contains the name of the buffer command for the
155 current buffer. This can be used directly to invoke buffer commands
156 (see |tcl-buffer-cmds|). This element is read-only.
158 > $::vim::current(buffer) insert begin "Hello world"
159 The "window" element contains the name of the window command for the
160 current window. This can be used directly to invoke window commands
161 (see |tcl-window-cmds|). This element is read-only.
163 > $::vim::current(window) height 10
165 ::vim::lbase *tcl-var-lbase*
166 This variable controls how Tcl treats line numbers. If it is set to
167 '1', then lines and columns start at 1. This way, line numbers from
168 Tcl commands and vim expressions are compatible. If this variable is
169 set to '0', then line numbers and columns start at 0 in Tcl. This is
170 useful if you want to treat a buffer as a Tcl list or a line as a Tcl
171 string and use standard Tcl commands that return an index ("lsort" or
172 "string first", for example). The default value is '1'. Currently,
173 any non-zero values is treated as '1', but your scripts should not
174 rely on this. See also |tcl-linenumbers|.
176 ::vim::range *tcl-var-range*
177 This is an array with three elements, "start", "begin" end "end". It
178 contains the line numbers of the start and end row of the current
179 range. "begin" is the same as "start". This variable is read-only.
184 These global variables are only available if the ":tcldo" ex command
185 is being executed. They contain the text and line number of the
186 current line. When the Tcl command invoked by ":tcldo" is completed,
187 the current line is set to the contents of the "line" variable, unless
188 the variable was unset by the Tcl command. The "lnum" variable is
189 read-only. These variables are not in the "::vim" namespace so they
190 can be used in ":tcldo" without much typing (this might be changed in
191 future versions). See also |tcl-linenumbers|.
193 ==============================================================================
194 4. Tcl window commands *tcl-window-cmds*
196 Window commands represent vim windows. They are created by several commands:
197 ::vim::window list |tcl-window|
198 "windows" option of a buffer command |tcl-buffer-windows|
199 The ::vim::current(window) variable contains the name of the window command
200 for the current window. A window command is automatically deleted when the
201 corresponding vim window is closed.
203 Lets assume the name of the window command is stored in the Tcl variable "win",
204 i.e. "$win" calls the command. The following options are available:
206 > $win buffer # Create Tcl command for window's buffer.
207 > $win command {cmd} # Execute ex command in windows context.
208 > $win cursor # Get current cursor position.
209 > $win cursor {var} # Set cursor position from array variable.
210 > $win cursor {row} {col} # Set cursor position.
211 > $win delcmd {cmd} # Call Tcl command when window is closed.
212 > $win expr {expr} # Evaluate vim expression in windows context.
213 > $win height # Report the window's height.
214 > $win height {n} # Set the window's height.
215 > $win option {opt} [val] # Get/Set vim option in windows context.
219 $win buffer *tcl-window-buffer*
220 Creates a Tcl command for the window's buffer, and returns its name as
221 the result. The name should be stored in a variable:
222 > set buf [$win buffer]
223 $buf is now a valid Tcl command. See |tcl-buffer-cmds| for the
226 $win cursor *tcl-window-cursor*
228 $win cursor {row} {col}
229 Without argument, reports the current cursor position as a string.
230 This can be converted to a Tcl array variable:
231 > array set here [$win cursor]
232 "here(row)" and "here(column)" now contain the cursor position.
233 With a single argument, the argument is interpreted as the name of a
234 Tcl array variable, which must contain two elements "row" and "column".
235 These are used to set the cursor to the new position:
236 > $win cursor here ;# not $here !
237 With two arguments, sets the cursor to the specified row and colum:
238 > $win cursor $here(row) $here(column)
239 Invalid positions result in a standard Tcl error, which can be caught
240 with "catch". The row and column values depend on the "::vim::lbase"
241 variable. See |tcl-var-lbase|.
243 $win delcmd {cmd} *tcl-window-delcmd*
244 Registers the Tcl command {cmd} as a deletion callback for the window.
245 This command is executed (in the global scope) just before the window
246 is closed. Complex commands should be build with "list":
247 > $win delcmd [list puts vimerr "window deleted"]
248 See also |tcl-buffer-delcmd|.
250 $win height *tcl-window-height*
252 Without argument, reports the window's current height. With an
253 argument, tries to set the window's height to {n}, then reports the
254 new height (which might be different from {n}).
256 $win command [-quiet] {cmd} *tcl-window-command*
257 $win expr {expr} *tcl-window-expr*
258 $win option {opt} [val] *tcl-window-option*
259 These are similar to "::vim::command" etc., except that everything is
260 done in the context of the window represented by $win, instead of the
261 current window. For example, setting an option that is marked 'local
262 to window' affects the window $win. Anything that affects or queries
263 a buffer uses the buffer displayed in this window (i.e. the buffer
264 that is represented by "$win buffer"). See |tcl-command|, |tcl-expr|
265 and |tcl-option| for more information.
267 > $win option number on
269 ==============================================================================
270 5. Tcl buffer commands *tcl-buffer-cmds*
272 Buffer commands represent vim buffers. They are created by several commands:
273 ::vim::buffer {N} |tcl-buffer|
274 ::vim::buffer list |tcl-buffer|
275 "buffer" option of a window command |tcl-window-buffer|
276 The ::vim::current(buffer) variable contains the name of the buffer command
277 for the current buffer. A buffer command is automatically deleted when the
278 corresponding vim buffer is destroyed. Whenever the buffer's contents are
279 changed, all marks in the buffer are automatically adjusted. Any changes to
280 the buffer's contents made by Tcl commands can be undone with the "undo" vim
281 command (see |undo|).
283 Lets assume the name of the buffer command is stored in the Tcl variable "buf",
284 i.e. "$buf" calls the command. The following options are available:
286 > $buf append {n} {str} # Append a line to buffer, after line {n}.
287 > $buf command {cmd} # Execute ex command in buffers context.
288 > $buf count # Report number of lines in buffer.
289 > $buf delcmd {cmd} # Call Tcl command when buffer is deleted.
290 > $buf delete {n} # Delete a single line.
291 > $buf delete {n} {m} # Delete several lines.
292 > $buf expr {expr} # Evaluate vim expression in buffers context.
293 > $buf get {n} # Get a single line as a string.
294 > $buf get {n} {m} # Get several lines as a list.
295 > $buf insert {n} {str} # Insert a line in buffer, as line {n}.
296 > $buf last # Report line number of last line in buffer.
297 > $buf mark {mark} # Report position of buffer mark.
298 > $buf name # Report name of file in buffer.
299 > $buf number # Report number of this buffer.
300 > $buf option {opt} [val] # Get/Set vim option in buffers context.
301 > $buf set {n} {text} # Replace a single line.
302 > $buf set {n} {m} {list} # Replace several lines.
303 > $buf windows # Create Tcl commands for buffer's windows.
306 Most buffer commands take line numbers as arguments. How Tcl treats these
307 numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|). Instead
308 of line numbers, several keywords can be also used: "top", "start", "begin",
309 "first", "bottom", "end" and "last".
312 $buf append {n} {str} *tcl-buffer-append*
313 $buf insert {n} {str} *tcl-buffer-insert*
314 Add a line to the buffer. With the "insert" option, the string
315 becomes the new line {n}, with "append" it is inserted after line {n}.
317 > $buf insert top "This is the beginning."
318 > $buf append end "This is the end."
319 To add a list of lines to the buffer, use a loop:
320 > foreach line $list { $buf append $num $line ; incr num }
322 $buf count *tcl-buffer-count*
323 Reports the total number of lines in the buffer.
325 $buf delcmd {cmd} *tcl-buffer-delcmd*
326 Registers the Tcl command {cmd} as a deletion callback for the buffer.
327 This command is executed (in the global scope) just before the buffer
328 is deleted. Complex commands should be build with "list":
329 > $buf delcmd [list puts vimerr "buffer [$buf number] gone"]
330 See also |tcl-window-delcmd|.
332 $buf delete {n} *tcl-buffer-delete*
334 Deletes line {n} or lines {n} through {m} from the buffer.
335 This example deletes everything except the last line:
336 > $buf delete first [expr [$buf last] - 1]
338 $buf get {n} *tcl-buffer-get*
340 Gets one or more lines from the buffer. For a single line, the result
341 is a string; for several lines, a list of strings.
343 > set topline [$buf get top]
345 $buf last *tcl-buffer-last*
346 Reports the line number of the last line. This value depends on the
347 "::vim::lbase" variable. See |tcl-var-lbase|.
349 $buf mark {mark} *tcl-buffer-mark*
350 Reports the position of the named mark as a string, similar to the
351 cursor position of the "cursor" option of a window command (see
352 |tcl-window-cursor|). This can be converted to a Tcl array variable:
353 > array set mpos [$buf mark "a"]
354 "mpos(column)" and "mpos(row)" now contain the position of the mark.
355 If the mark is not set, a standard Tcl error results.
358 Reports the name of the file in the buffer. For a buffer without a
359 file, this is an empty string.
362 Reports the number of this buffer. See |:buffers|.
363 This example deletes a buffer from vim:
364 > ::vim::command "bdelete [$buf number]"
366 $buf set {n} {string} *tcl-buffer-set*
367 $buf set {n} {m} {list}
368 Replace one or several lines in the buffer. If the list contains more
369 elements than there are lines to replace, they are inserted into the
370 buffer. If the list contains fewer elements, any unreplaced line is
371 deleted from the buffer.
373 $buf windows *tcl-buffer-windows*
374 Creates a window command for each window that displays this buffer, and
375 returns a list of the command names as the result.
377 > set winlist [$buf windows]
378 > foreach win $winlist { $win height 4 }
379 See |tcl-window-cmds| for the available options.
381 $buf command [-quiet] {cmd} *tcl-buffer-command*
382 $buf expr {exr} *tcl-buffer-expr*
383 $buf option {opt} [val] *tcl-buffer-option*
384 These are similar to "::vim::command" etc., except that everything is
385 done in the context of the buffer represented by $buf, instead of the
386 current buffer. For example, setting an option that is marked 'local
387 to buffer' affects the buffer $buf. Anything that affects or queries
388 a window uses the first window in vim's window list that displays this
389 buffer (i.e. the first entry in the list returned by "$buf windows").
390 See |tcl-command|, |tcl-expr| and |tcl-option| for more information.
392 > if { [$buf option modified] } { $buf command "w" }
394 ==============================================================================
395 6. Miscellaneous; Output from Tcl *tcl-misc* *tcl-output*
397 The standard Tcl commands "exit" and "catch" are replaced by custom versions.
398 "exit" terminates the current Tcl script and returns to vim, which deletes the
399 Tcl interpreter. Another call to ":tcl" then creates a new Tcl interpreter.
400 "exit" does NOT terminate vim! "catch" works as before, except that it does
401 not prevent script termination from "exit". An exit code != 0 causes the ex
402 command that invoked the Tcl script to return an error.
404 Two new I/O streams are available in Tcl, "vimout" and "vimerr". All output
405 directed to them is displayed in the vim message area, as information messages
406 and error messages, respectively. The standard Tcl output streams stdout and
407 stderr are mapped to vimout and vimerr, so that a normal "puts" command can be
408 used to display messages in vim.
410 ==============================================================================
411 7. Known bugs & problems *tcl-bugs*
413 Calling one of the Tcl ex commands from inside Tcl (via "::vim::command") may
414 have unexpected side effects. The command creates a new interpreter, which
415 has the same abilities as the standard interpreter - making "::vim::command"
416 available in a safe child interpreter therefore makes the child unsafe. (It
417 would be trivial to block nested :tcl* calls or ensure that such calls from a
418 safe interpreter create only new safe interpreters, but quite pointless -
419 depending on vim's configuration, "::vim::command" may execute arbitrary code
420 in any number of other scripting languages.) A call to "exit" within this new
421 interpreter does not affect the old interpreter; it only terminates the new
422 interpreter, then script processing continues normally in the old interpreter.
424 Input from stdin is currently not supported.
426 ==============================================================================
427 8. Examples: *tcl-examples*
429 Here are a few small (and maybe useful) Tcl scripts.
431 This script sorts the lines of the entire buffer (assume it contains a list
432 of names or something similar):
433 set buf $::vim::current(buffer)
434 set lines [$buf get top bottom]
435 set lines [lsort -dictionary $lines]
436 $buf set top bottom $lines
438 This script reverses the lines in the buffer. Note the use of "::vim::lbase"
439 and "$buf last" to work with any line number setting.
440 set buf $::vim::current(buffer)
452 This script adds a consecutive number to each line in the current range:
453 set buf $::vim::current(buffer)
454 set i $::vim::range(start)
456 while { $i <= $::vim::range(end) } {
457 set line [$buf get $i]
458 $buf set $i "$n\t$line"
462 The same can also be done quickly with two ex commands, using ":tcldo":
464 :[range]tcldo set line "$n\t$line" ; incr n
466 This procedure runs an ex command on each buffer (idea stolen from Ron Aaron):
467 proc eachbuf { cmd } {
468 foreach b [::vim::buffer list] {
473 :tcl eachbuf %s/foo/bar/g
474 Be careful with Tcl's string and backslash substitution, tough. If in doubt,
475 surround the ex command with curly braces.
478 If you want to add some Tcl procedures permanently to vim, just place them in
479 a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your
480 startup file (usually "~/.vimrc" on Unix):
485 ==============================================================================