if_tcl.txt

MSYS在windows下模拟了一个类unix的终端

*if_tcl.txt*    For Vim version 5.8.  Last change: 2000 Jun 04


		  VIM REFERENCE MANUAL    by Ingo Wilken


The Tcl Interface to Vim				*tcl* *Tcl* *TCL*

1. Commands				|tcl-ex-commands|
2. Tcl commands				|tcl-commands|
3. Tcl variables			|tcl-variables|
4. Tcl window commands			|tcl-window-cmds|
5. Tcl buffer commands			|tcl-buffer-cmds|
6. Miscellaneous; Output from Tcl	|tcl-misc| |tcl-output|
7. Known bugs & problems		|tcl-bugs|
8. Examples				|tcl-examples|

{Vi does not have any of these commands}

The Tcl interface only works when Vim was compiled with the |+tcl| feature.

WARNING: There are probably still some bugs.  Please send bug reports,
comments, ideas etc to <[e-mail]>

==============================================================================
1. Commands						*tcl-ex-commands*

							*:tcl* *:tc*
:tc[l] {cmd}		Execute Tcl command {cmd}. {not in Vi}

							*:tcldo* *:tcld*
:[range]tcld[o] {cmd}	Execute Tcl command {cmd} for each line in [range]
			with the variable "line" being set to the text of each
			line in turn, and "lnum" to the line number.  Setting
			"line" will change the text, but note that it is not
			possible to add or delete lines using this command.
			If {cmd} returns an error, the command is interrupted.
			The default for [range] is the whole file: "1,$".
			See |tcl-var-line| and |tcl-var-lnum|.  {not in Vi}

							*:tclfile* *:tclf*
:tclf[ile] {file}	Execute the Tcl script in {file}.  This is the same as
			":tcl source {file}", but allows file name completion.
			{not in Vi}


Note that Tcl objects (like variables) persist from one command to the next,
just as in the Tcl shell.

==============================================================================
2. Tcl commands						*tcl-commands*

Tcl code gets all of its access to vim via commands in the "::vim" namespace.
The following commands are implemented:

>	::vim::beep			# Guess.
>	::vim::buffer {n}		# Create Tcl command for one buffer.
>	::vim::buffer list		# Create Tcl commands for all buffers.
>	::vim::command [-quiet] {cmd}	# Execute an ex command.
>	::vim::expr {expr}		# Use Vim's expression evaluator.
>	::vim::option {opt}		# Get vim option.
>	::vim::option {opt} {val}	# Set vim option.
>	::vim::window list		# Create Tcl commands for all windows.

Commands:
	::vim::beep					*tcl-beep*
	Honk.  Does not return a result.

	::vim::buffer {n}				*tcl-buffer*
	::vim::buffer exists {n}
	::vim::buffer list
	Provides access to vim buffers.  With an integer argument, creates a
	buffer command (see |tcl-buffer-cmds|) for the buffer with that
	number, and returns its name as the result.  Invalid buffer numbers
	result in a standard Tcl error.  To test for valid buffer numbers,
	vim's internal functions can be used:
>		set nbufs [::vim::expr bufnr("$")]
>		set isvalid [::vim::expr "bufexists($n)"]
	The "list" option creates a buffer command for each valid buffer, and
	returns a list of the command names as the result.
	Example:
>		set bufs [::vim::buffer list]
>		foreach b $bufs { $b append end "The End!" }
	The "exists" option checks if a buffer with the given number exists.
	Example:
>		if { [::vim::buffer exists $n] } { ::vim::command ":e #$n" }
	This command might be replaced by a variable in future versions.
	See also |tcl-var-current| for the current buffer.

	::vim::command {cmd}				*tcl-command*
	::vim::command -quiet {cmd}
	Execute the vim (ex-mode) command {cmd}.  Any ex command that affects
	a buffer or window uses the current buffer/current window.  Does not
	return a result other than a standard Tcl error code.  After this
	command is completed, the "::vim::current" variable is updated.
	The "-quiet" flag suppresses any error messages from vim.
	Examples:
>		::vim::command "set ts=8"
>		::vim::command "%s/foo/bar/g"
	To execute normal-mode commands, use "normal" (see |:normal|):
>		set cmd "jj"
>		::vim::command "normal $cmd"
	See also |tcl-window-command| and |tcl-buffer-command|.

	::vim::expr {expr}				*tcl-expr*
	Evaluates the expression {expr} using vim's internal expression
	evaluator (see |expression|).   Any expression that queries a buffer
	or window property uses the current buffer/current window.  Returns
	the result as a string.
	Examples:
>		set perl_available [::vim::expr has("perl")]
	See also |tcl-window-expr| and |tcl-buffer-expr|.

	::vim::option {opt}				*tcl-option*
	::vim::option {opt} {value}
	Without second argument, queries the value of a vim option.  With this
	argument, sets the vim option to {value}, and returns the previous
	value as the result.  Any options that are marked as 'local to buffer'
	or 'local to window' affect the current buffer/current window. For
	boolean options, {value} should be "0" or "1", or any of the keywords
	"on", "off" or "toggle".  See |option-summary| for a list of options.
	Example:
>		::vim::option ts 8
	See also |tcl-window-option| and |tcl-buffer-option|.

	::vim::window {option}				*tcl-window*
	Provides access to vim windows.  Currently only the "list" option is
	implemented. This creates a window command (see |tcl-window-cmds|) for
	each window, and returns a list of the command names as the result.
	Example:
>		set wins [::vim::window list]
>		foreach w $wins { $w height 4 }
	This command might be replaced by a variable in future versions.
	See also |tcl-var-current| for the current window.

==============================================================================
3. Tcl variables					*tcl-variables*

The ::vim namespace contains a few variables.  These are created when the Tcl
interpreter is called from vim and set to current values.

>	::vim::current		# array containing "current" objects
>	::vim::lbase		# number of first line
>	::vim::range		# array containing current range numbers
>	line			# current line as a string (:tcldo only)
>	lnum			# current line number (:tcldo only)

Variables:
	::vim::current					*tcl-var-current*
	This is an array providing access to various "current" objects
	available in vim.  The contents of this array are updated after
	"::vim::command" is called, as this might change vim's current
	settings (e.g., by deleting the current buffer).
	The "buffer" element contains the name of the buffer command for the
	current buffer.  This can be used directly to invoke buffer commands
	(see |tcl-buffer-cmds|).  This element is read-only.
	Example:
>		$::vim::current(buffer) insert begin "Hello world"
	The "window" element contains the name of the window command for the
	current window.  This can be used directly to invoke window commands
	(see |tcl-window-cmds|).  This element is read-only.
	Example:
>		$::vim::current(window) height 10

	::vim::lbase					*tcl-var-lbase*
	This variable controls how Tcl treats line numbers.  If it is set to
	'1', then lines and columns start at 1.  This way, line numbers from
	Tcl commands and vim expressions are compatible.  If this variable is
	set to '0', then line numbers and columns start at 0 in Tcl.  This is
	useful if you want to treat a buffer as a Tcl list or a line as a Tcl
	string and use standard Tcl commands that return an index ("lsort" or
	"string first", for example).  The default value is '1'.  Currently,
	any non-zero values is treated as '1', but your scripts should not
	rely on this.  See also |tcl-linenumbers|.

	::vim::range					*tcl-var-range*
	This is an array with three elements, "start", "begin" end "end".  It
	contains the line numbers of the start and end row of the current
	range.  "begin" is the same as "start".  This variable is read-only.
	See |tcl-examples|.

	line						*tcl-var-line*
	lnum						*tcl-var-lnum*
	These global variables are only available if the ":tcldo" ex command
	is being executed.  They contain the text and line number of the
	current line.  When the Tcl command invoked by ":tcldo" is completed,
	the current line is set to the contents of the "line" variable, unless
	the variable was unset by the Tcl command.  The "lnum" variable is
	read-only.  These variables are not in the "::vim" namespace so they
	can be used in ":tcldo" without much typing (this might be changed in
	future versions).  See also |tcl-linenumbers|.

==============================================================================
4. Tcl window commands					*tcl-window-cmds*

Window commands represent vim windows.  They are created by several commands:
	::vim::window list			|tcl-window|
	"windows" option of a buffer command	|tcl-buffer-windows|
The ::vim::current(window) variable contains the name of the window command
for the current window.  A window command is automatically deleted when the
corresponding vim window is closed.

Lets assume the name of the window command is stored in the Tcl variable "win",
i.e. "$win" calls the command.  The following options are available:

>	$win buffer		# Create Tcl command for window's buffer.
>	$win command {cmd}	# Execute ex command in windows context.
>	$win cursor		# Get current cursor position.
>	$win cursor {var}	# Set cursor position from array variable.
>	$win cursor {row} {col}	# Set cursor position.
>	$win delcmd {cmd}	# Call Tcl command when window is closed.
>	$win expr {expr}	# Evaluate vim expression in windows context.
>	$win height		# Report the window's height.
>	$win height {n}		# Set the window's height.
>	$win option {opt} [val]	# Get/Set vim option in windows context.
>

Options:
	$win buffer					*tcl-window-buffer*
	Creates a Tcl command for the window's buffer, and returns its name as
	the result.  The name should be stored in a variable:
>		set buf [$win buffer]
	$buf is now a valid Tcl command.  See |tcl-buffer-cmds| for the
	available options.

	$win cursor					*tcl-window-cursor*
	$win cursor {var}
	$win cursor {row} {col}
	Without argument, reports the current cursor position as a string.
	This can be converted to a Tcl array variable:
>		array set here [$win cursor]
	"here(row)" and "here(column)" now contain the cursor position.
	With a single argument, the argument is interpreted as the name of a
	Tcl array variable, which must contain two elements "row" and "column".
	These are used to set the cursor to the new position:
>		$win cursor here	;# not $here !
	With two arguments, sets the cursor to the specified row and colum:
>		$win cursor $here(row) $here(column)
	Invalid positions result in a standard Tcl error, which can be caught
	with "catch".  The row and column values depend on the "::vim::lbase"
	variable.  See |tcl-var-lbase|.

	$win delcmd {cmd}				*tcl-window-delcmd*
	Registers the Tcl command {cmd} as a deletion callback for the window.