codekingpro/portable-devtools

1*if_tcl.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Ingo Wilken5 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{only available when Vim was compiled with the |+tcl| feature}20 21							*E280*22WARNING: There are probably still some bugs.  Please send bug reports,23comments, ideas etc to <Ingo.Wilken@informatik.uni-oldenburg.de>24 25==============================================================================261. Commands				*tcl-ex-commands* *E571* *E572*27 28							*:tcl*29:[range]tcl {cmd}	Execute Tcl command {cmd}.  A simple check if `:tcl`30			is working: >31				:tcl puts "Hello"32 33:[range]tcl << [trim] [{endmarker}]34{script}35{endmarker}36			Execute Tcl script {script}.37			Note: This command doesn't work when the Tcl feature38			wasn't compiled in.  To avoid errors, see39			|script-here|.40 41If [endmarker] is omitted from after the "<<", a dot '.' must be used after42{script}, like for the |:append| and |:insert| commands.  Refer to43|:let-heredoc| for more information.44 45This form of the |:tcl| command is mainly useful for including tcl code in Vim46scripts.47 48Example: >49	function! DefineDate()50	    tcl << EOF51	    proc date {} {52		return [clock format [clock seconds]]53	    }54	EOF55	endfunction56<57To see what version of Tcl you have: >58	:tcl puts [info patchlevel]59<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 each64			line in turn, and "lnum" to the line number.  Setting65			"line" will change the text, but note that it is not66			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,$".69			See |tcl-var-line| and |tcl-var-lnum|.70 71							*:tclfile* *:tclf*72:[range]tclf[ile] {file}73			Execute the Tcl script in {file}.  This is the same as74			":tcl source {file}", but allows file name completion.75 76 77Note that Tcl objects (like variables) persist from one command to the next,78just as in the Tcl shell.79 80Executing Tcl commands is not possible in the |sandbox|.81 82==============================================================================832. Tcl commands						*tcl-commands*84 85Tcl code gets all of its access to vim via commands in the "::vim" namespace.86The following commands are implemented: >87 88	::vim::beep			# Guess.89	::vim::buffer {n}		# Create Tcl command for one buffer.90	::vim::buffer list		# Create Tcl commands for all buffers.91	::vim::command [-quiet] {cmd}	# Execute an Ex command.92	::vim::expr {expr}		# Use Vim's expression evaluator.93	::vim::option {opt}		# Get vim option.94	::vim::option {opt} {val}	# Set vim option.95	::vim::window list		# Create Tcl commands for all windows.96 97Commands:98	::vim::beep					*tcl-beep*99	Honk.  Does not return a result.100 101	::vim::buffer {n}				*tcl-buffer*102	::vim::buffer exists {n}103	::vim::buffer list104	Provides access to vim buffers.  With an integer argument, creates a105	buffer command (see |tcl-buffer-cmds|) for the buffer with that106	number, and returns its name as the result.  Invalid buffer numbers107	result in a standard Tcl error.  To test for valid buffer numbers,108	vim's internal functions can be used: >109		set nbufs [::vim::expr bufnr("$")]110		set isvalid [::vim::expr "bufexists($n)"]111<	The "list" option creates a buffer command for each valid buffer, and112	returns a list of the command names as the result.113	Example: >114		set bufs [::vim::buffer list]115		foreach b $bufs { $b append end "The End!" }116<	The "exists" option checks if a buffer with the given number exists.117	Example: >118		if { [::vim::buffer exists $n] } { ::vim::command ":e #$n" }119<	This command might be replaced by a variable in future versions.120	See also |tcl-var-current| for the current buffer.121 122	::vim::command {cmd}				*tcl-command*123	::vim::command -quiet {cmd}124	Execute the vim (ex-mode) command {cmd}.  Any Ex command that affects125	a buffer or window uses the current buffer/current window.  Does not126	return a result other than a standard Tcl error code.  After this127	command is completed, the "::vim::current" variable is updated.128	The "-quiet" flag suppresses any error messages from vim.129	Examples: >130		::vim::command "set ts=8"131		::vim::command "%s/foo/bar/g"132<	To execute normal-mode commands, use "normal" (see |:normal|): >133		set cmd "jj"134		::vim::command "normal $cmd"135<	See also |tcl-window-command| and |tcl-buffer-command|.136 137	::vim::expr {expr}				*tcl-expr*138	Evaluates the expression {expr} using vim's internal expression139	evaluator (see |expression|).   Any expression that queries a buffer140	or window property uses the current buffer/current window.  Returns141	the result as a string.  A |List| is turned into a string by joining142	the items and inserting line breaks.143	Examples: >144		set perl_available [::vim::expr has("perl")]145<	See also |tcl-window-expr| and |tcl-buffer-expr|.146 147	::vim::option {opt}				*tcl-option*148	::vim::option {opt} {value}149	Without second argument, queries the value of a vim option.  With this150	argument, sets the vim option to {value}, and returns the previous151	value as the result.  Any options that are marked as 'local to buffer'152	or 'local to window' affect the current buffer/current window.  The153	global value is not changed, use the ":set" command for that.  For154	boolean options, {value} should be "0" or "1", or any of the keywords155	"on", "off" or "toggle".  See |option-summary| for a list of options.156	Example: >157		::vim::option ts 8158<	See also |tcl-window-option| and |tcl-buffer-option|.159 160	::vim::window {option}				*tcl-window*161	Provides access to vim windows.  Currently only the "list" option is162	implemented.  This creates a window command (see |tcl-window-cmds|) for163	each window, and returns a list of the command names as the result.164	Example: >165		set wins [::vim::window list]166		foreach w $wins { $w height 4 }167<	This command might be replaced by a variable in future versions.168	See also |tcl-var-current| for the current window.169 170==============================================================================1713. Tcl variables					*tcl-variables*172 173The ::vim namespace contains a few variables.  These are created when the Tcl174interpreter is called from vim and set to current values. >175 176	::vim::current		# array containing "current" objects177	::vim::lbase		# number of first line178	::vim::range		# array containing current range numbers179	line			# current line as a string (:tcldo only)180	lnum			# current line number (:tcldo only)181 182Variables:183	::vim::current					*tcl-var-current*184	This is an array providing access to various "current" objects185	available in vim.  The contents of this array are updated after186	"::vim::command" is called, as this might change vim's current187	settings (e.g., by deleting the current buffer).188	The "buffer" element contains the name of the buffer command for the189	current buffer.  This can be used directly to invoke buffer commands190	(see |tcl-buffer-cmds|).  This element is read-only.191	Example: >192		$::vim::current(buffer) insert begin "Hello world"193<	The "window" element contains the name of the window command for the194	current window.  This can be used directly to invoke window commands195	(see |tcl-window-cmds|).  This element is read-only.196	Example: >197		$::vim::current(window) height 10198<199	::vim::lbase					*tcl-var-lbase*200	This variable controls how Tcl treats line numbers.  If it is set to201	'1', then lines and columns start at 1.  This way, line numbers from202	Tcl commands and vim expressions are compatible.  If this variable is203	set to '0', then line numbers and columns start at 0 in Tcl.  This is204	useful if you want to treat a buffer as a Tcl list or a line as a Tcl205	string and use standard Tcl commands that return an index ("lsort" or206	"string first", for example).  The default value is '1'.  Currently,207	any non-zero values is treated as '1', but your scripts should not208	rely on this.  See also |tcl-linenumbers|.209 210	::vim::range					*tcl-var-range*211	This is an array with three elements, "start", "begin" and "end".  It212	contains the line numbers of the start and end row of the current213	range.  "begin" is the same as "start".  This variable is read-only.214	See |tcl-examples|.215 216	line						*tcl-var-line*217	lnum						*tcl-var-lnum*218	These global variables are only available if the ":tcldo" Ex command219	is being executed.  They contain the text and line number of the220	current line.  When the Tcl command invoked by ":tcldo" is completed,221	the current line is set to the contents of the "line" variable, unless222	the variable was unset by the Tcl command.  The "lnum" variable is223	read-only.  These variables are not in the "::vim" namespace so they224	can be used in ":tcldo" without much typing (this might be changed in225	future versions).  See also |tcl-linenumbers|.226 227==============================================================================2284. Tcl window commands					*tcl-window-cmds*229 230Window commands represent vim windows.  They are created by several commands:231	::vim::window list			|tcl-window|232	"windows" option of a buffer command	|tcl-buffer-windows|233The ::vim::current(window) variable contains the name of the window command234for the current window.  A window command is automatically deleted when the235corresponding vim window is closed.236 237Let's assume the name of the window command is stored in the Tcl variable238"win", i.e. "$win" calls the command.  The following options are available: >239 240	$win buffer		# Create Tcl command for window's buffer.241	$win command {cmd}	# Execute Ex command in windows context.242	$win cursor		# Get current cursor position.243	$win cursor {var}	# Set cursor position from array variable.244	$win cursor {row} {col}	# Set cursor position.245	$win delcmd {cmd}	# Call Tcl command when window is closed.246	$win expr {expr}	# Evaluate vim expression in windows context.247	$win height		# Report the window's height.248	$win height {n}		# Set the window's height.249	$win option {opt} [val]	# Get/Set vim option in windows context.250 251Options:252	$win buffer					*tcl-window-buffer*253	Creates a Tcl command for the window's buffer, and returns its name as254	the result.  The name should be stored in a variable: >255		set buf [$win buffer]256<	$buf is now a valid Tcl command.  See |tcl-buffer-cmds| for the257	available options.258 259	$win cursor					*tcl-window-cursor*260	$win cursor {var}261	$win cursor {row} {col}262	Without argument, reports the current cursor position as a string.263	This can be converted to a Tcl array variable: >264		array set here [$win cursor]265<	"here(row)" and "here(column)" now contain the cursor position.266	With a single argument, the argument is interpreted as the name of a267	Tcl array variable, which must contain two elements "row" and268	"column".269	These are used to set the cursor to the new position: >270		$win cursor here	;# not $here !271<	With two arguments, sets the cursor to the specified row and column: >272		$win cursor $here(row) $here(column)273<	Invalid positions result in a standard Tcl error, which can be caught274	with "catch".  The row and column values depend on the "::vim::lbase"275	variable.  See |tcl-var-lbase|.276 277	$win delcmd {cmd}				*tcl-window-delcmd*278	Registers the Tcl command {cmd} as a deletion callback for the window.279	This command is executed (in the global scope) just before the window280	is closed.  Complex commands should be built with "list": >281		$win delcmd [list puts vimerr "window deleted"]282<	See also |tcl-buffer-delcmd|.283 284	$win height					*tcl-window-height*285	$win height {n}286	Without argument, reports the window's current height.  With an287	argument, tries to set the window's height to {n}, then reports the288	new height (which might be different from {n}).289 290	$win command [-quiet] {cmd}			*tcl-window-command*291	$win expr {expr}				*tcl-window-expr*292	$win option {opt} [val]				*tcl-window-option*293	These are similar to "::vim::command" etc., except that everything is294	done in the context of the window represented by $win, instead of the295	current window.  For example, setting an option that is marked 'local296	to window' affects the window $win.  Anything that affects or queries297	a buffer uses the buffer displayed in this window (i.e. the buffer298	that is represented by "$win buffer").  See |tcl-command|, |tcl-expr|299	and |tcl-option| for more information.300	Example: >301		$win option number on302 303==============================================================================3045. Tcl buffer commands					*tcl-buffer-cmds*305 306Buffer commands represent vim buffers.  They are created by several commands:307	::vim::buffer {N}			|tcl-buffer|308	::vim::buffer list			|tcl-buffer|309	"buffer" option of a window command	|tcl-window-buffer|310The ::vim::current(buffer) variable contains the name of the buffer command311for the current buffer.  A buffer command is automatically deleted when the312corresponding vim buffer is destroyed.  Whenever the buffer's contents are313changed, all marks in the buffer are automatically adjusted.  Any changes to314the buffer's contents made by Tcl commands can be undone with the "undo" vim315command (see |undo|).316 317Let's assume the name of the buffer command is stored in the Tcl variable318"buf", i.e. "$buf" calls the command.  The following options are available: >319 320	$buf append {n} {str}	# Append a line to buffer, after line {n}.321	$buf command {cmd}	# Execute Ex command in buffers context.322	$buf count		# Report number of lines in buffer.323	$buf delcmd {cmd}	# Call Tcl command when buffer is deleted.324	$buf delete {n}		# Delete a single line.325	$buf delete {n} {m}	# Delete several lines.326	$buf expr {expr}	# Evaluate vim expression in buffers context.327	$buf get {n}		# Get a single line as a string.328	$buf get {n} {m}	# Get several lines as a list.329	$buf insert {n} {str}	# Insert a line in buffer, as line {n}.330	$buf last		# Report line number of last line in buffer.331	$buf mark {mark}	# Report position of buffer mark.332	$buf name		# Report name of file in buffer.333	$buf number		# Report number of this buffer.334	$buf option {opt} [val]	# Get/Set vim option in buffers context.335	$buf set {n} {text}	# Replace a single line.336	$buf set {n} {m} {list}	# Replace several lines.337	$buf windows		# Create Tcl commands for buffer's windows.338<339							*tcl-linenumbers*340Most buffer commands take line numbers as arguments.  How Tcl treats these341numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|).  Instead342of line numbers, several keywords can be also used: "top", "start", "begin",343"first", "bottom", "end" and "last".344 345Options:346	$buf append {n} {str}				*tcl-buffer-append*347	$buf insert {n} {str}				*tcl-buffer-insert*348	Add a line to the buffer.  With the "insert" option, the string349	becomes the new line {n}, with "append" it is inserted after line {n}.350	Example: >351		$buf insert top "This is the beginning."352		$buf append end "This is the end."353<	To add a list of lines to the buffer, use a loop: >354		foreach line $list { $buf append $num $line ; incr num }355<356	$buf count					*tcl-buffer-count*357	Reports the total number of lines in the buffer.358 359	$buf delcmd {cmd}				*tcl-buffer-delcmd*360	Registers the Tcl command {cmd} as a deletion callback for the buffer.361	This command is executed (in the global scope) just before the buffer362	is deleted.  Complex commands should be built with "list": >363		$buf delcmd [list puts vimerr "buffer [$buf number] gone"]364<	See also |tcl-window-delcmd|.365 366	$buf delete {n}					*tcl-buffer-delete*367	$buf delete {n} {m}368	Deletes line {n} or lines {n} through {m} from the buffer.369	This example deletes everything except the last line: >370		$buf delete first [expr [$buf last] - 1]371<372	$buf get {n}					*tcl-buffer-get*373	$buf get {n} {m}374	Gets one or more lines from the buffer.  For a single line, the result375	is a string; for several lines, a list of strings.376	Example: >377		set topline [$buf get top]378<379	$buf last					*tcl-buffer-last*380	Reports the line number of the last line.  This value depends on the381	"::vim::lbase" variable.  See |tcl-var-lbase|.382 383	$buf mark {mark}				*tcl-buffer-mark*384	Reports the position of the named mark as a string, similar to the385	cursor position of the "cursor" option of a window command (see386	|tcl-window-cursor|).  This can be converted to a Tcl array variable: >387		array set mpos [$buf mark "a"]388<	"mpos(column)" and "mpos(row)" now contain the position of the mark.389	If the mark is not set, a standard Tcl error results.390 391	$buf name392	Reports the name of the file in the buffer.  For a buffer without a393	file, this is an empty string.394 395	$buf number396	Reports the number of this buffer.  See |:buffers|.397	This example deletes a buffer from vim: >398		::vim::command "bdelete [$buf number]"399<400	$buf set {n} {string}				*tcl-buffer-set*401	$buf set {n} {m} {list}402	Replace one or several lines in the buffer.  If the list contains more403	elements than there are lines to replace, they are inserted into the404	buffer.  If the list contains fewer elements, any unreplaced line is405	deleted from the buffer.406 407	$buf windows					*tcl-buffer-windows*408	Creates a window command for each window that displays this buffer,409	and returns a list of the command names as the result.410	Example: >411		set winlist [$buf windows]412		foreach win $winlist { $win height 4 }413<	See |tcl-window-cmds| for the available options.414 415	$buf command [-quiet] {cmd}			*tcl-buffer-command*416	$buf expr {expr}				*tcl-buffer-expr*417	$buf option {opt} [val]				*tcl-buffer-option*418	These are similar to "::vim::command" etc., except that everything is419	done in the context of the buffer represented by $buf, instead of the420	current buffer.  For example, setting an option that is marked 'local421	to buffer' affects the buffer $buf.  Anything that affects or queries422	a window uses the first window in vim's window list that displays this423	buffer (i.e. the first entry in the list returned by "$buf windows").424	See |tcl-command|, |tcl-expr| and |tcl-option| for more information.425	Example: >426		if { [$buf option modified] } { $buf command "w" }427 428==============================================================================4296. Miscellaneous; Output from Tcl		*tcl-misc* *tcl-output*430 431The standard Tcl commands "exit" and "catch" are replaced by custom versions.432"exit" terminates the current Tcl script and returns to vim, which deletes the433Tcl interpreter.  Another call to ":tcl" then creates a new Tcl interpreter.434"exit" does NOT terminate vim!  "catch" works as before, except that it does435not prevent script termination from "exit".  An exit code != 0 causes the ex436command that invoked the Tcl script to return an error.437 438Two new I/O streams are available in Tcl, "vimout" and "vimerr".  All output439directed to them is displayed in the vim message area, as information messages440and error messages, respectively.  The standard Tcl output streams stdout and441stderr are mapped to vimout and vimerr, so that a normal "puts" command can be442used to display messages in vim.443 444==============================================================================4457. Known bugs & problems				*tcl-bugs*446 447Calling one of the Tcl Ex commands from inside Tcl (via "::vim::command") may448have unexpected side effects.  The command creates a new interpreter, which449has the same abilities as the standard interpreter - making "::vim::command"450available in a safe child interpreter therefore makes the child unsafe.  (It451would be trivial to block nested :tcl* calls or ensure that such calls from a452safe interpreter create only new safe interpreters, but quite pointless -453depending on vim's configuration, "::vim::command" may execute arbitrary code454in any number of other scripting languages.)  A call to "exit" within this new455interpreter does not affect the old interpreter; it only terminates the new456interpreter, then script processing continues normally in the old interpreter.457 458Input from stdin is currently not supported.459 460==============================================================================4618. Examples:						*tcl-examples*462 463Here are a few small (and maybe useful) Tcl scripts.464 465This script sorts the lines of the entire buffer (assume it contains a list466of names or something similar): >467	set buf $::vim::current(buffer)468	set lines [$buf get top bottom]469	set lines [lsort -dictionary $lines]470	$buf set top bottom $lines471 472This script reverses the lines in the buffer.  Note the use of "::vim::lbase"473and "$buf last" to work with any line number setting: >474	set buf $::vim::current(buffer)475	set t $::vim::lbase476	set b [$buf last]477	while { $t < $b } {478		set tl [$buf get $t]479		set bl [$buf get $b]480		$buf set $t $bl481		$buf set $b $tl482		incr t483		incr b -1484	}485 486This script adds a consecutive number to each line in the current range: >487	set buf $::vim::current(buffer)488	set i $::vim::range(start)489	set n 1490	while { $i <= $::vim::range(end) } {491		set line [$buf get $i]492		$buf set $i "$n\t$line"493		incr i ; incr n494	}495 496The same can also be done quickly with two Ex commands, using ":tcldo": >497	:tcl set n 1498	:[range]tcldo set line "$n\t$line" ; incr n499 500This procedure runs an Ex command on each buffer (idea stolen from Ron Aaron): >501	proc eachbuf { cmd } {502		foreach b [::vim::buffer list] {503			$b command $cmd504		}505	}506Use it like this: >507	:tcl eachbuf %s/foo/bar/g508Be careful with Tcl's string and backslash substitution, tough.  If in doubt,509surround the Ex command with curly braces.510 511 512If you want to add some Tcl procedures permanently to vim, just place them in513a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your514startup file (usually "~/.vimrc" on Unix): >515	if has("tcl")516		tclfile ~/.vimrc.tcl517	endif518 519==============================================================================5209. Dynamic loading					*tcl-dynamic*521 522On MS-Windows and Unix the Tcl library can be loaded dynamically.  The523|:version| output then includes |+tcl/dyn|.524 525This means that Vim will search for the Tcl DLL or shared library file only526when needed.  When you don't use the Tcl interface you don't need it, thus you527can use Vim without this file.528 529 530MS-Windows ~531 532To use the Tcl interface the Tcl DLL must be in your search path.  In a533console window type "path" to see what directories are used.  The 'tcldll'534option can be also used to specify the Tcl DLL.535 536The name of the DLL must match the Tcl version Vim was compiled with.537Currently the name is "tcl86.dll".  That is for Tcl 8.6.  To know for sure538edit "gvim.exe" and search for "tcl\d*.dll\c".539 540 541Unix ~542 543The 'tcldll' option can be used to specify the Tcl shared library file instead544of DYNAMIC_TCL_DLL file what was specified at compile time.  The version of545the shared library must match the Tcl version Vim was compiled with.546 547==============================================================================548 vim:tw=78:ts=8:noet:ft=help:norl:549