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