Adding upstream version 2:8.1.0875.upstream/2%8.1.0875upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 547 insertions, 0 deletions

diff --git a/runtime/doc/if_tcl.txt b/runtime/doc/if_tcl.txt
new file mode 100644
index 0000000..e822dfd
--- /dev/null
+++ b/runtime/doc/if_tcl.txt
@@ -0,0 +1,547 @@
+*if_tcl.txt*    For Vim version 8.1.  Last change: 2016 Jan 01
+
+
+		  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|
+9. Dynamic loading			|tcl-dynamic|
+
+{Vi does not have any of these commands} *E280*
+
+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 <Ingo.Wilken@informatik.uni-oldenburg.de>
+
+==============================================================================
+1. Commands				*tcl-ex-commands* *E571* *E572*
+
+							*:tcl* *:tc*
+:tc[l] {cmd}		Execute Tcl command {cmd}.  A simple check if `:tcl`
+			is working: >
+				:tcl puts "Hello"
+
+:[range]tc[l] << {endmarker}
+{script}
+{endmarker}
+			Execute Tcl script {script}.
+			Note: This command doesn't work when the Tcl feature
+			wasn't compiled in.  To avoid errors, see
+			|script-here|.
+
+{endmarker} must NOT be preceded by any white space.  If {endmarker} is
+omitted from after the "<<", a dot '.' must be used after {script}, like for
+the |:append| and |:insert| commands.
+This form of the |:tcl| command is mainly useful for including tcl code in Vim
+scripts.
+
+Example: >
+	function! DefineDate()
+	    tcl << EOF
+	    proc date {} {
+		return [clock format [clock seconds]]
+	    }
+	EOF
+	endfunction
+<
+To see what version of Tcl you have: >
+	:tcl puts [info patchlevel]
+<
+
+							*: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.
+
+Executing Tcl commands is not possible in the |sandbox|.
+
+==============================================================================
+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.  A |List| is turned into a string by joining
+	the items and inserting line breaks.
+	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.  The
+	global value is not changed, use the ":set" command for that.  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" and "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.
+
+Let's 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 column: >
+		$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.
+	This command is executed (in the global scope) just before the window
+	is closed.  Complex commands should be build with "list": >
+		$win delcmd [list puts vimerr "window deleted"]
+<	See also |tcl-buffer-delcmd|.
+
+	$win height					*tcl-window-height*
+	$win height {n}
+	Without argument, reports the window's current height.  With an
+	argument, tries to set the window's height to {n}, then reports the
+	new height (which might be different from {n}).
+
+	$win command [-quiet] {cmd}			*tcl-window-command*
+	$win expr {expr}				*tcl-window-expr*
+	$win option {opt} [val]				*tcl-window-option*
+	These are similar to "::vim::command" etc., except that everything is
+	done in the context of the window represented by $win, instead of the
+	current window.  For example, setting an option that is marked 'local
+	to window' affects the window $win.  Anything that affects or queries
+	a buffer uses the buffer displayed in this window (i.e. the buffer
+	that is represented by "$win buffer").  See |tcl-command|, |tcl-expr|
+	and |tcl-option| for more information.
+	Example: >
+		$win option number on
+
+==============================================================================
+5. Tcl buffer commands					*tcl-buffer-cmds*
+
+Buffer commands represent vim buffers.  They are created by several commands:
+	::vim::buffer {N}			|tcl-buffer|
+	::vim::buffer list			|tcl-buffer|
+	"buffer" option of a window command	|tcl-window-buffer|
+The ::vim::current(buffer) variable contains the name of the buffer command
+for the current buffer.  A buffer command is automatically deleted when the
+corresponding vim buffer is destroyed.  Whenever the buffer's contents are
+changed, all marks in the buffer are automatically adjusted.  Any changes to
+the buffer's contents made by Tcl commands can be undone with the "undo" vim
+command (see |undo|).
+
+Let's assume the name of the buffer command is stored in the Tcl variable "buf",
+i.e. "$buf" calls the command.  The following options are available: >
+
+	$buf append {n} {str}	# Append a line to buffer, after line {n}.
+	$buf command {cmd}	# Execute Ex command in buffers context.
+	$buf count		# Report number of lines in buffer.
+	$buf delcmd {cmd}	# Call Tcl command when buffer is deleted.
+	$buf delete {n}		# Delete a single line.
+	$buf delete {n} {m}	# Delete several lines.
+	$buf expr {expr}	# Evaluate vim expression in buffers context.
+	$buf get {n}		# Get a single line as a string.
+	$buf get {n} {m}	# Get several lines as a list.
+	$buf insert {n} {str}	# Insert a line in buffer, as line {n}.
+	$buf last		# Report line number of last line in buffer.
+	$buf mark {mark}	# Report position of buffer mark.
+	$buf name		# Report name of file in buffer.
+	$buf number		# Report number of this buffer.
+	$buf option {opt} [val]	# Get/Set vim option in buffers context.
+	$buf set {n} {text}	# Replace a single line.
+	$buf set {n} {m} {list}	# Replace several lines.
+	$buf windows		# Create Tcl commands for buffer's windows.
+<
+							*tcl-linenumbers*
+Most buffer commands take line numbers as arguments.  How Tcl treats these
+numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|).  Instead
+of line numbers, several keywords can be also used: "top", "start", "begin",
+"first", "bottom", "end" and "last".
+
+Options:
+	$buf append {n} {str}				*tcl-buffer-append*
+	$buf insert {n} {str}				*tcl-buffer-insert*
+	Add a line to the buffer.  With the "insert" option, the string
+	becomes the new line {n}, with "append" it is inserted after line {n}.
+	Example: >
+		$buf insert top "This is the beginning."
+		$buf append end "This is the end."
+<	To add a list of lines to the buffer, use a loop: >
+		foreach line $list { $buf append $num $line ; incr num }
+<
+	$buf count					*tcl-buffer-count*
+	Reports the total number of lines in the buffer.
+
+	$buf delcmd {cmd}				*tcl-buffer-delcmd*
+	Registers the Tcl command {cmd} as a deletion callback for the buffer.
+	This command is executed (in the global scope) just before the buffer
+	is deleted.  Complex commands should be build with "list": >
+		$buf delcmd [list puts vimerr "buffer [$buf number] gone"]
+<	See also |tcl-window-delcmd|.
+
+	$buf delete {n}					*tcl-buffer-delete*
+	$buf delete {n} {m}
+	Deletes line {n} or lines {n} through {m} from the buffer.
+	This example deletes everything except the last line: >
+		$buf delete first [expr [$buf last] - 1]
+<
+	$buf get {n}					*tcl-buffer-get*
+	$buf get {n} {m}
+	Gets one or more lines from the buffer.  For a single line, the result
+	is a string; for several lines, a list of strings.
+	Example: >
+		set topline [$buf get top]
+<
+	$buf last					*tcl-buffer-last*
+	Reports the line number of the last line.  This value depends on the
+	"::vim::lbase" variable.  See |tcl-var-lbase|.
+
+	$buf mark {mark}				*tcl-buffer-mark*
+	Reports the position of the named mark as a string, similar to the
+	cursor position of the "cursor" option of a window command (see
+	|tcl-window-cursor|).  This can be converted to a Tcl array variable: >
+		array set mpos [$buf mark "a"]
+<	"mpos(column)" and "mpos(row)" now contain the position of the mark.
+	If the mark is not set, a standard Tcl error results.
+
+	$buf name
+	Reports the name of the file in the buffer.  For a buffer without a
+	file, this is an empty string.
+
+	$buf number
+	Reports the number of this buffer.  See |:buffers|.
+	This example deletes a buffer from vim: >
+		::vim::command "bdelete [$buf number]"
+<
+	$buf set {n} {string}				*tcl-buffer-set*
+	$buf set {n} {m} {list}
+	Replace one or several lines in the buffer.  If the list contains more
+	elements than there are lines to replace, they are inserted into the
+	buffer.  If the list contains fewer elements, any unreplaced line is
+	deleted from the buffer.
+
+	$buf windows					*tcl-buffer-windows*
+	Creates a window command for each window that displays this buffer, and
+	returns a list of the command names as the result.
+	Example: >
+		set winlist [$buf windows]
+		foreach win $winlist { $win height 4 }
+<	See |tcl-window-cmds| for the available options.
+
+	$buf command [-quiet] {cmd}			*tcl-buffer-command*
+	$buf expr {expr}				*tcl-buffer-expr*
+	$buf option {opt} [val]				*tcl-buffer-option*
+	These are similar to "::vim::command" etc., except that everything is
+	done in the context of the buffer represented by $buf, instead of the
+	current buffer.  For example, setting an option that is marked 'local
+	to buffer' affects the buffer $buf.  Anything that affects or queries
+	a window uses the first window in vim's window list that displays this
+	buffer (i.e. the first entry in the list returned by "$buf windows").
+	See |tcl-command|, |tcl-expr| and |tcl-option| for more information.
+	Example: >
+		if { [$buf option modified] } { $buf command "w" }
+
+==============================================================================
+6. Miscellaneous; Output from Tcl		*tcl-misc* *tcl-output*
+
+The standard Tcl commands "exit" and "catch" are replaced by custom versions.
+"exit" terminates the current Tcl script and returns to vim, which deletes the
+Tcl interpreter.  Another call to ":tcl" then creates a new Tcl interpreter.
+"exit" does NOT terminate vim!  "catch" works as before, except that it does
+not prevent script termination from "exit".  An exit code != 0 causes the ex
+command that invoked the Tcl script to return an error.
+
+Two new I/O streams are available in Tcl, "vimout" and "vimerr".  All output
+directed to them is displayed in the vim message area, as information messages
+and error messages, respectively.  The standard Tcl output streams stdout and
+stderr are mapped to vimout and vimerr, so that a normal "puts" command can be
+used to display messages in vim.
+
+==============================================================================
+7. Known bugs & problems				*tcl-bugs*
+
+Calling one of the Tcl Ex commands from inside Tcl (via "::vim::command") may
+have unexpected side effects.  The command creates a new interpreter, which
+has the same abilities as the standard interpreter - making "::vim::command"
+available in a safe child interpreter therefore makes the child unsafe.  (It
+would be trivial to block nested :tcl* calls or ensure that such calls from a
+safe interpreter create only new safe interpreters, but quite pointless -
+depending on vim's configuration, "::vim::command" may execute arbitrary code
+in any number of other scripting languages.)  A call to "exit" within this new
+interpreter does not affect the old interpreter; it only terminates the new
+interpreter, then script processing continues normally in the old interpreter.
+
+Input from stdin is currently not supported.
+
+==============================================================================
+8. Examples:						*tcl-examples*
+
+Here are a few small (and maybe useful) Tcl scripts.
+
+This script sorts the lines of the entire buffer (assume it contains a list
+of names or something similar):
+	set buf $::vim::current(buffer)
+	set lines [$buf get top bottom]
+	set lines [lsort -dictionary $lines]
+	$buf set top bottom $lines
+
+This script reverses the lines in the buffer.  Note the use of "::vim::lbase"
+and "$buf last" to work with any line number setting.
+	set buf $::vim::current(buffer)
+	set t $::vim::lbase
+	set b [$buf last]
+	while { $t < $b } {
+		set tl [$buf get $t]
+		set bl [$buf get $b]
+		$buf set $t $bl
+		$buf set $b $tl
+		incr t
+		incr b -1
+	}
+
+This script adds a consecutive number to each line in the current range:
+	set buf $::vim::current(buffer)
+	set i $::vim::range(start)
+	set n 1
+	while { $i <= $::vim::range(end) } {
+		set line [$buf get $i]
+		$buf set $i "$n\t$line"
+		incr i ; incr n
+	}
+
+The same can also be done quickly with two Ex commands, using ":tcldo":
+	:tcl set n 1
+	:[range]tcldo set line "$n\t$line" ; incr n
+
+This procedure runs an Ex command on each buffer (idea stolen from Ron Aaron):
+	proc eachbuf { cmd } {
+		foreach b [::vim::buffer list] {
+			$b command $cmd
+		}
+	}
+Use it like this:
+	:tcl eachbuf %s/foo/bar/g
+Be careful with Tcl's string and backslash substitution, tough.  If in doubt,
+surround the Ex command with curly braces.
+
+
+If you want to add some Tcl procedures permanently to vim, just place them in
+a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your
+startup file (usually "~/.vimrc" on Unix):
+	if has("tcl")
+		tclfile ~/.vimrc.tcl
+	endif
+
+==============================================================================
+9. Dynamic loading					*tcl-dynamic*
+
+On MS-Windows and Unix the Tcl library can be loaded dynamically.  The
+|:version| output then includes |+tcl/dyn|.
+
+This means that Vim will search for the Tcl DLL or shared library file only
+when needed.  When you don't use the Tcl interface you don't need it, thus you
+can use Vim without this file.
+
+
+MS-Windows ~
+
+To use the Tcl interface the Tcl DLL must be in your search path.  In a
+console window type "path" to see what directories are used.  The 'tcldll'
+option can be also used to specify the Tcl DLL.
+
+The name of the DLL must match the Tcl version Vim was compiled with.
+Currently the name is "tcl86.dll".  That is for Tcl 8.6.  To know for sure
+edit "gvim.exe" and search for "tcl\d*.dll\c".
+
+
+Unix ~
+
+The 'tcldll' option can be used to specify the Tcl shared library file instead
+of DYNAMIC_TCL_DLL file what was specified at compile time.  The version of
+the shared library must match the Tcl version Vim was compiled with.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: