1*if_tcl.txt* For Vim version 7.3. Last change: 2008 Aug 16 2 3 4 VIM REFERENCE MANUAL by Ingo Wilken 5 6 7The Tcl Interface to Vim *tcl* *Tcl* *TCL* 8 91. Commands |tcl-ex-commands| 102. Tcl commands |tcl-commands| 113. Tcl variables |tcl-variables| 124. Tcl window commands |tcl-window-cmds| 135. Tcl buffer commands |tcl-buffer-cmds| 146. Miscellaneous; Output from Tcl |tcl-misc| |tcl-output| 157. Known bugs & problems |tcl-bugs| 168. Examples |tcl-examples| 179. Dynamic loading |tcl-dynamic| 18 19{Vi does not have any of these commands} *E280* *E281* 20 21The Tcl interface only works when Vim was compiled with the |+tcl| feature. 22 23WARNING: There are probably still some bugs. Please send bug reports, 24comments, ideas etc to <Ingo.Wilken@informatik.uni-oldenburg.de> 25 26============================================================================== 271. 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 40{endmarker} must NOT be preceded by any white space. If {endmarker} is 41omitted from after the "<<", a dot '.' must be used after {script}, like for 42the |:append| and |:insert| commands. 43This form of the |:tcl| command is mainly useful for including tcl code in Vim 44scripts. 45 46Example: > 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 72Note that Tcl objects (like variables) persist from one command to the next, 73just as in the Tcl shell. 74 75Executing Tcl commands is not possible in the |sandbox|. 76 77============================================================================== 782. Tcl commands *tcl-commands* 79 80Tcl code gets all of its access to vim via commands in the "::vim" namespace. 81The 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 92Commands: 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 136 the result as a string. A |List| is turned into a string by joining 137 the items and inserting line breaks. 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 157 implemented. This creates a window command (see |tcl-window-cmds|) for 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============================================================================== 1663. Tcl variables *tcl-variables* 167 168The ::vim namespace contains a few variables. These are created when the Tcl 169interpreter 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 177Variables: 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============================================================================== 2234. Tcl window commands *tcl-window-cmds* 224 225Window 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| 228The ::vim::current(window) variable contains the name of the window command 229for the current window. A window command is automatically deleted when the 230corresponding vim window is closed. 231 232Let's assume the name of the window command is stored in the Tcl variable "win", 233i.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 246Options: 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============================================================================== 2985. Tcl buffer commands *tcl-buffer-cmds* 299 300Buffer 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| 304The ::vim::current(buffer) variable contains the name of the buffer command 305for the current buffer. A buffer command is automatically deleted when the 306corresponding vim buffer is destroyed. Whenever the buffer's contents are 307changed, all marks in the buffer are automatically adjusted. Any changes to 308the buffer's contents made by Tcl commands can be undone with the "undo" vim 309command (see |undo|). 310 311Let's assume the name of the buffer command is stored in the Tcl variable "buf", 312i.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* 334Most buffer commands take line numbers as arguments. How Tcl treats these 335numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|). Instead 336of line numbers, several keywords can be also used: "top", "start", "begin", 337"first", "bottom", "end" and "last". 338 339Options: 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 {expr} *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============================================================================== 4236. Miscellaneous; Output from Tcl *tcl-misc* *tcl-output* 424 425The 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 427Tcl 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 429not prevent script termination from "exit". An exit code != 0 causes the ex 430command that invoked the Tcl script to return an error. 431 432Two new I/O streams are available in Tcl, "vimout" and "vimerr". All output 433directed to them is displayed in the vim message area, as information messages 434and error messages, respectively. The standard Tcl output streams stdout and 435stderr are mapped to vimout and vimerr, so that a normal "puts" command can be 436used to display messages in vim. 437 438============================================================================== 4397. Known bugs & problems *tcl-bugs* 440 441Calling one of the Tcl Ex commands from inside Tcl (via "::vim::command") may 442have unexpected side effects. The command creates a new interpreter, which 443has the same abilities as the standard interpreter - making "::vim::command" 444available in a safe child interpreter therefore makes the child unsafe. (It 445would be trivial to block nested :tcl* calls or ensure that such calls from a 446safe interpreter create only new safe interpreters, but quite pointless - 447depending on vim's configuration, "::vim::command" may execute arbitrary code 448in any number of other scripting languages.) A call to "exit" within this new 449interpreter does not affect the old interpreter; it only terminates the new 450interpreter, then script processing continues normally in the old interpreter. 451 452Input from stdin is currently not supported. 453 454============================================================================== 4558. Examples: *tcl-examples* 456 457Here are a few small (and maybe useful) Tcl scripts. 458 459This script sorts the lines of the entire buffer (assume it contains a list 460of 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 466This script reverses the lines in the buffer. Note the use of "::vim::lbase" 467and "$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 480This 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 490The 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 494This 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 } 500Use it like this: 501 :tcl eachbuf %s/foo/bar/g 502Be careful with Tcl's string and backslash substitution, tough. If in doubt, 503surround the Ex command with curly braces. 504 505 506If you want to add some Tcl procedures permanently to vim, just place them in 507a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your 508startup file (usually "~/.vimrc" on Unix): 509 if has("tcl") 510 tclfile ~/.vimrc.tcl 511 endif 512 513============================================================================== 5149. Dynamic loading *tcl-dynamic* 515 516On MS-Windows the Tcl library can be loaded dynamically. The |:version| 517output then includes |+tcl/dyn|. 518 519This means that Vim will search for the Tcl DLL file only when needed. When 520you don't use the Tcl interface you don't need it, thus you can use Vim 521without this DLL file. 522 523To use the Tcl interface the Tcl DLL must be in your search path. In a 524console window type "path" to see what directories are used. 525 526The name of the DLL must match the Tcl version Vim was compiled with. 527Currently the name is "tcl83.dll". That is for Tcl 8.3. To know for sure 528edit "gvim.exe" and search for "tcl\d*.dll\c". 529 530============================================================================== 531 vim:tw=78:ts=8:ft=help:norl: 532