home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vim53os2.zip / vim-5.3 / doc / if_tcl.txt < prev    next >
Text File  |  1998-08-30  |  21KB  |  481 lines
  1. *if_tcl.txt*    For Vim version 5.3.  Last modification: 1998 Aug 17
  2.  
  3.           VIM REFERENCE MANUAL    by Ingo Wilken
  4.  
  5. The Tcl Interface to Vim                    *tcl*
  6.  
  7. 1. Commands                |tcl-ex-commands|
  8. 2. Tcl commands                |tcl-commands|
  9. 3. Tcl variables            |tcl-variables|
  10. 4. Tcl window commands            |tcl-window-cmds|
  11. 5. Tcl buffer commands            |tcl-buffer-cmds|
  12. 6. Output from Tcl            |tcl-output|
  13. 7. Known bugs & problems        |tcl-bugs|
  14. 8. Examples                |tcl-examples|
  15.  
  16. {Vi does not have any of these commands}
  17.  
  18. The Tcl interface only works when Vim was compiled with the |+tcl| feature.
  19.  
  20. WARNING: This is a BETA release!  Things might be different in the final
  21. version.  There are probably still some bugs.  Please send bug reports,
  22. comments, ideas etc to Ingo.Wilken@informatik.uni-oldenburg.de
  23.  
  24. ==============================================================================
  25. 1. Commands                        *tcl-ex-commands*
  26.  
  27.                             *:tcl* *:tc*
  28. :tc[l] {cmd}        Execute Tcl command {cmd}. {not in Vi}
  29.  
  30.                             *:tcldo* *:tcld*
  31. :[range]tcld[o] {cmd}    Execute Tcl command {cmd} for each line in [range]
  32.             with the variable "line" being set to the text of each
  33.             line in turn, and "lnum" to the line number.  Setting
  34.             "line" will change the text, but note that it is not
  35.             possible to add or delete lines using this command.
  36.             If {cmd} returns an error, the command is interrupted.
  37.             See |tcl-var-line| and |tcl-var-lnum|.  {not in Vi}
  38.  
  39.                             *:tclfile* *:tclf*
  40. :tclf[ile] {file}    Execute the Tcl script in {file}. {not in Vi}
  41.  
  42.  
  43. Note that Tcl objects (like variables) persist from one command to the next,
  44. just as in the Tcl shell.
  45.  
  46. ==============================================================================
  47. 2. Tcl commands                        *tcl-commands*
  48.  
  49. Tcl code gets all of its access to vim via commands in the "::vim" namespace.
  50. The following commands are implemented:
  51.  
  52. >    ::vim::beep            # Guess.
  53. >    ::vim::buffer {n}        # Create Tcl command for one buffer.
  54. >    ::vim::buffer list        # Create Tcl commands for all buffers.
  55. >    ::vim::command [-quiet] {cmd}    # Execute an ex command.
  56. >    ::vim::expr {expr}        # Use Vim's expression evaluator.
  57. >    ::vim::option {opt}        # Get vim option.
  58. >    ::vim::option {opt} {val}    # Set vim option.
  59. >    ::vim::window list        # Create Tcl commands for all windows.
  60.  
  61. Commands:
  62.     ::vim::beep                    *tcl-beep*
  63.     Honk.  Does not return a result.
  64.  
  65.     ::vim::buffer {n}                *tcl-buffer*
  66.     ::vim::buffer exists {n}
  67.     ::vim::buffer list
  68.     Provides access to vim buffers.  With an integer argument, creates a
  69.     buffer command (see |tcl-buffer-cmds|) for the buffer with that
  70.     number, and returns its name as the result.  Invalid buffer numbers
  71.     result in a standard Tcl error.  To test for valid buffer numbers,
  72.     vim's internal functions can be used:
  73. >        set nbufs [::vim::expr bufnr("$")]
  74. >        set isvalid [::vim::expr "bufexists($n)"]
  75.     The "list" option creates a buffer command for each valid buffer, and
  76.     returns a list of the command names as the result.
  77.     Example:
  78. >        set bufs [::vim::buffer list]
  79. >        foreach b $bufs { $b append end "The End!" }
  80.     The "exists" option checks if a buffer with the given number exists.
  81.     Example:
  82. >        if { [::vim::buffer exists $n] } { ::vim::command ":e #$n" }
  83.     This command might be replaced by a variable in future versions.
  84.     See also |tcl-var-current| for the current buffer.
  85.  
  86.     ::vim::command {cmd}                *tcl-command*
  87.     ::vim::command -quiet {cmd}
  88.     Execute the vim (ex-mode) command {cmd}.  Any ex command that affects
  89.     a buffer or window uses the current buffer/current window.  Does not
  90.     return a result other than a standard Tcl error code.  After this
  91.     command is completed, the "::vim::current" variable is updated.
  92.     The "-quiet" flag suppresses any error messages from vim.
  93.     Examples:
  94. >        ::vim::command "set ts=8"
  95. >        ::vim::command "%s/foo/bar/g"
  96.     To execute normal-mode commands, use "normal" (see |:normal|):
  97. >        set cmd "jj"
  98. >        ::vim::command "normal $cmd"
  99.     See also |tcl-window-command| and |tcl-buffer-command|.
  100.  
  101.     ::vim::expr {expr}                *tcl-expr*
  102.     Evaluates the expression {expr} using vim's internal expression
  103.     evaluator (see |expression|).   Any expression that queries a buffer
  104.     or window property uses the current buffer/current window.  Returns
  105.     the result as a string.
  106.     Examples:
  107. >        set perl_available [::vim::expr has("perl")]
  108.     See also |tcl-window-expr| and |tcl-buffer-expr|.
  109.  
  110.     ::vim::option {opt}                *tcl-option*
  111.     ::vim::option {opt} {value}
  112.     Without second argument, queries the value of a vim option.  With this
  113.     argument, sets the vim option to {value}, and returns the previous
  114.     value as the result.  Any options that are marked as 'local to buffer'
  115.     or 'local to window' affect the current buffer/current window. For
  116.     boolean options, {value} should be "0" or "1", or any of the keywords
  117.     "on", "off" or "toggle".  See |option-summary| for a list of options.
  118.     Example:
  119. >        ::vim::option ts 8
  120.     See also |tcl-window-option| and |tcl-buffer-option|.
  121.  
  122.     ::vim::window {option}                *tcl-window*
  123.     Provides access to vim windows.  Currently only the "list" option is
  124.     implemented. This creates a window command (see |tcl-window-cmds|) for
  125.     each window, and returns a list of the command names as the result.
  126.     Example:
  127. >        set wins [::vim::window list]
  128. >        foreach w $wins { $w height 4 }
  129.     This command might be replaced by a variable in future versions.
  130.     See also |tcl-var-current| for the current window.
  131.  
  132. ==============================================================================
  133. 3. Tcl variables                    *tcl-variables*
  134.  
  135. The ::vim namespace contains a few variables.  These are created when the Tcl
  136. interpreter is called from vim and set to current values.
  137.  
  138. >    ::vim::current        # array containing "current" objects
  139. >    ::vim::lbase        # number of first line
  140. >    ::vim::range        # array containing current range numbers
  141. >    line            # current line as a string (:tcldo only)
  142. >    lnum            # current line number (:tcldo only)
  143.  
  144. Variables:
  145.     ::vim::current                    *tcl-var-current*
  146.     This is an array providing access to various "current" objects
  147.     available in vim.  The contents of this array are updated after
  148.     "::vim::command" is called, as this might change vim's current
  149.     settings (e.g., by deleting the current buffer).
  150.     The "buffer" element contains the name of the buffer command for the
  151.     current buffer.  This can be used directly to invoke buffer commands
  152.     (see |tcl-buffer-cmds|).  This element is read-only.
  153.     Example:
  154. >        $::vim::current(buffer) insert begin "Hello world"
  155.     The "window" element contains the name of the window command for the
  156.     current window.  This can be used directly to invoke window commands
  157.     (see |tcl-window-cmds|).  This element is read-only.
  158.     Example:
  159. >        $::vim::current(window) height 10
  160.  
  161.     ::vim::lbase                    *tcl-var-lbase*
  162.     This variable controls how Tcl treats line numbers.  If it is set to
  163.     '1', then lines and columns start at 1.  This way, line numbers from
  164.     Tcl commands and vim expressions are compatible.  If this variable is
  165.     set to '0', then line numbers and columns start at 0 in Tcl.  This is
  166.     useful if you want to treat a buffer as a Tcl list or a line as a Tcl
  167.     string and use standard Tcl commands that return an index ("lsort" or
  168.     "string first", for example).  The default value is '1'.  Currently,
  169.     any non-zero values is treated as '1', but your scripts should not
  170.     rely on this.  See also |tcl-linenumbers|.
  171.  
  172.     ::vim::range                    *tcl-var-range*
  173.     This is an array with three elements, "start", "begin" end "end".  It
  174.     contains the line numbers of the start and end row of the current
  175.     range.  "begin" is the same as "start".  This variable is read-only.
  176.     See |tcl-examples|.
  177.  
  178.     line                        *tcl-var-line*
  179.     lnum                        *tcl-var-lnum*
  180.     These global variables are only available if the ":tcldo" ex command
  181.     is being executed.  They contain the text and line number of the
  182.     current line.  When the Tcl command invoked by ":tcldo" is completed,
  183.     the current line is set to the contents of the "line" variable, unless
  184.     the variable was unset by the Tcl command.  The "lnum" variable is
  185.     read-only.  These variables are not in the "::vim" namespace so they
  186.     can be used in ":tcldo" without much typing (this might be changed in
  187.     future versions).  See also |tcl-linenumbers|.
  188.  
  189. ==============================================================================
  190. 4. Tcl window commands                    *tcl-window-cmds*
  191.  
  192. Window commands represent vim windows.  They are created by several commands:
  193.     ::vim::window list            |tcl-window|
  194.     "windows" option of a buffer command    |tcl-buffer-windows|
  195. The ::vim::current(window) variable contains the name of the window command
  196. for the current window.  A window command is automatically deleted when the
  197. corresponding vim window is closed.
  198.  
  199. Lets assume the name of the window command is stored in the Tcl variable "win",
  200. i.e. "$win" calls the command.  The following options are available:
  201.  
  202. >    $win buffer        # Create Tcl command for window's buffer.
  203. >    $win command {cmd}    # Execute ex command in windows context.
  204. >    $win cursor        # Get current cursor position.
  205. >    $win cursor {var}    # Set cursor position from array variable.
  206. >    $win cursor {row} {col}    # Set cursor position.
  207. >    $win delcmd {cmd}    # Call Tcl command when window is closed.
  208. >    $win expr {expr}    # Evaluate vim expression in windows context.
  209. >    $win height        # Report the window's height.
  210. >    $win height {n}        # Set the window's height.
  211. >    $win option {opt} [val]    # Get/Set vim option in windows context.
  212. >
  213.  
  214. Options:
  215.     $win buffer                    *tcl-window-buffer*
  216.     Creates a Tcl command for the window's buffer, and returns its name as
  217.     the result.  The name should be stored in a variable:
  218. >        set buf [$win buffer]
  219.     $buf is now a valid Tcl command.  See |tcl-buffer-cmds| for the
  220.     available options.
  221.  
  222.     $win cursor                    *tcl-window-cursor*
  223.     $win cursor {var}
  224.     $win cursor {row} {col}
  225.     Without argument, reports the current cursor position as a string.
  226.     This can be converted to a Tcl array variable:
  227. >        array set here [$win cursor]
  228.     "here(row)" and "here(column)" now contain the cursor position.
  229.     With a single argument, the argument is interpreted as the name of a
  230.     Tcl array variable, which must contain two elements "row" and "column".
  231.     These are used to set the cursor to the new position:
  232. >        $win cursor here    ;# not $here !
  233.     With two arguments, sets the cursor to the specified row and colum:
  234. >        $win cursor $here(row) $here(column)
  235.     Invalid positions result in a standard Tcl error, which can be caught
  236.     with "catch".  The row and column values depend on the "::vim::lbase"
  237.     variable.  See |tcl-var-lbase|.
  238.  
  239.     $win delcmd {cmd}                *tcl-window-delcmd*
  240.     Registers the Tcl command {cmd} as a deletion callback for the window.
  241.     This command is executed (in the global scope) just before the window
  242.     is closed.  Complex commands should be build with "list":
  243. >        $win delcmd [list puts vimerr "window deleted"]
  244.     See also |tcl-buffer-delcmd|.
  245.  
  246.     $win height                    *tcl-window-height*
  247.     $win height {n}
  248.     Without argument, reports the window's current height.  With an
  249.     argument, tries to set the window's height to {n}, then reports the
  250.     new height (which might be different from {n}).
  251.  
  252.     $win command [-quiet] {cmd}            *tcl-window-command*
  253.     $win expr {expr}                *tcl-window-expr*
  254.     $win option {opt} [val]                *tcl-window-option*
  255.     These are similar to "::vim::command" etc., except that everything is
  256.     done in the context of the window represented by $win, instead of the
  257.     current window.  For example, setting an option that is marked 'local
  258.     to window' affects the window $win.  Anything that affects or queries
  259.     a buffer uses the buffer displayed in this window (i.e. the buffer
  260.     that is represented by "$win buffer").  See |tcl-command|, |tcl-expr|
  261.     and |tcl-option| for more information.
  262.     Example:
  263. >        $win option number on
  264.  
  265. ==============================================================================
  266. 5. Tcl buffer commands                    *tcl-buffer-cmds*
  267.  
  268. Buffer commands represent vim buffers.  They are created by several commands:
  269.     ::vim::buffer {N}            |tcl-buffer|
  270.     ::vim::buffer list            |tcl-buffer|
  271.     "buffer" option of a window command    |tcl-window-buffer|
  272. The ::vim::current(buffer) variable contains the name of the buffer command
  273. for the current buffer.  A buffer command is automatically deleted when the
  274. corresponding vim buffer is destroyed.  Whenever the buffer's contents are
  275. changed, all marks in the buffer are automatically adjusted.  Any changes to
  276. the buffer's contents made by Tcl commands can be undone with the "undo" vim
  277. command (see |undo|).
  278.  
  279. Lets assume the name of the buffer command is stored in the Tcl variable "buf",
  280. i.e. "$buf" calls the command.  The following options are available:
  281.  
  282. >    $buf append {n} {str}    # Append a line to buffer, after line {n}.
  283. >    $buf command {cmd}    # Execute ex command in buffers context.
  284. >    $buf count        # Report number of lines in buffer.
  285. >    $buf delcmd {cmd}    # Call Tcl command when buffer is deleted.
  286. >    $buf delete {n}        # Delete a single line.
  287. >    $buf delete {n} {m}    # Delete several lines.
  288. >    $buf expr {expr}    # Evaluate vim expression in buffers context.
  289. >    $buf get {n}        # Get a single line as a string.
  290. >    $buf get {n} {m}    # Get several lines as a list.
  291. >    $buf insert {n} {str}    # Insert a line in buffer, as line {n}.
  292. >    $buf last        # Report line number of last line in buffer.
  293. >    $buf mark {mark}    # Report position of buffer mark.
  294. >    $buf name        # Report name of file in buffer.
  295. >    $buf number        # Report number of this buffer.
  296. >    $buf option {opt} [val]    # Get/Set vim option in buffers context.
  297. >    $buf set {n} {text}    # Replace a single line.
  298. >    $buf set {n} {m} {list}    # Replace several lines.
  299. >    $buf windows        # Create Tcl commands for buffer's windows.
  300.  
  301.                             *tcl-linenumbers*
  302. Most buffer commands take line numbers as arguments.  How Tcl treats these
  303. numbers depends on the "::vim::lbase" variable (see |tcl-var-lbase|).  Instead
  304. of line numbers, several keywords can be also used: "top", "start", "begin",
  305. "first", "bottom", "end" and "last".
  306.  
  307. Options:
  308.     $buf append {n} {str}                *tcl-buffer-append*
  309.     $buf insert {n} {str}                *tcl-buffer-insert*
  310.     Add a line to the buffer.  With the "insert" option, the string
  311.     becomes the new line {n}, with "append" it is inserted after line {n}.
  312.     Example:
  313. >        $buf insert top "This is the beginning."
  314. >        $buf append end "This is the end."
  315.     To add a list of lines to the buffer, use a loop:
  316. >        foreach line $list { $buf append $num $line ; incr num }
  317.  
  318.     $buf count                    *tcl-buffer-count*
  319.     Reports the total number of lines in the buffer.
  320.  
  321.     $buf delcmd {cmd}                *tcl-buffer-delcmd*
  322.     Registers the Tcl command {cmd} as a deletion callback for the buffer.
  323.     This command is executed (in the global scope) just before the buffer
  324.     is deleted.  Complex commands should be build with "list":
  325. >        $buf delcmd [list puts vimerr "buffer [$buf number] gone"]
  326.     See also |tcl-window-delcmd|.
  327.  
  328.     $buf delete {n}                    *tcl-buffer-delete*
  329.     $buf delete {n} {m}
  330.     Deletes line {n} or lines {n} through {m} from the buffer.
  331.     This example deletes everything except the last line:
  332. >        $buf delete first [expr [$buf last] - 1]
  333.  
  334.     $buf get {n}                    *tcl-buffer-get*
  335.     $buf get {n} {m}
  336.     Gets one or more lines from the buffer.  For a single line, the result
  337.     is a string; for several lines, a list of strings.
  338.     Example:
  339. >        set topline [$buf get top]
  340.  
  341.     $buf last                    *tcl-buffer-last*
  342.     Reports the line number of the last line.  This value depends on the
  343.     "::vim::lbase" variable.  See |tcl-var-lbase|.
  344.  
  345.     $buf mark {mark}                *tcl-buffer-mark*
  346.     Reports the position of the named mark as a string, similar to the
  347.     cursor position of the "cursor" option of a window command (see
  348.     |tcl-window-cursor|).  This can be converted to a Tcl array variable:
  349. >        array set mpos [$buf mark "a"]
  350.     "mpos(column)" and "mpos(row)" now contain the position of the mark.
  351.     If the mark is not set, a standard Tcl error results.
  352.  
  353.     $buf name
  354.     Reports the name of the file in the buffer.  For a buffer without a
  355.     file, this is an empty string.
  356.  
  357.     $buf number
  358.     Reports the number of this buffer.  See |:buffers|.
  359.     This example deletes a buffer from vim:
  360. >        ::vim::command "bdelete [$buf number]"
  361.  
  362.     $buf set {n} {string}                *tcl-buffer-set*
  363.     $buf set {n} {m} {list}
  364.     Replace one or several lines in the buffer.  If the list contains more
  365.     elements than there are lines to replace, they are inserted into the
  366.     buffer.  If the list contains fewer elements, any unreplaced line is
  367.     deleted from the buffer.
  368.  
  369.     $buf windows                    *tcl-buffer-windows*
  370.     Creates a window command for each window that displays this buffer, and
  371.     returns a list of the command names as the result.
  372.     Example:
  373. >        set winlist [$buf windows]
  374. >        foreach win $winlist { $win height 4 }
  375.     See |tcl-window-cmds| for the available options.
  376.  
  377.     $buf command [-quiet] {cmd}            *tcl-buffer-command*
  378.     $buf expr {exr}                    *tcl-buffer-expr*
  379.     $buf option {opt} [val]                *tcl-buffer-option*
  380.     These are similar to "::vim::command" etc., except that everything is
  381.     done in the context of the buffer represented by $buf, instead of the
  382.     current buffer.  For example, setting an option that is marked 'local
  383.     to buffer' affects the buffer $buf.  Anything that affects or queries
  384.     a window uses the first window in vim's window list that displays this
  385.     buffer (i.e. the first entry in the list returned by "$buf windows").
  386.     See |tcl-command|, |tcl-expr| and |tcl-option| for more information.
  387.     Example:
  388. >        if { [$buf option modified] } { $buf command "w" }
  389.  
  390. ==============================================================================
  391. 6. Output from Tcl                    *tcl-output*
  392.  
  393. Two new I/O streams are available in Tcl, "vimout" and "vimerr".  All output
  394. directed to them is displayed in the vim message area, as information messages
  395. and error messages, respectively.  The standard Tcl output streams stdout and
  396. stderr are mapped to vimout and vimerr, so that a normal "puts" command can be
  397. used to display messages in vim.
  398.  
  399. ==============================================================================
  400. 7. Known bugs & problems                *tcl-bugs*
  401.  
  402. The standard "exit" command is replaced by a version that tells vim to delete
  403. the Tcl interpreter when the current command or script is completed, and
  404. returns an error.  Another call to ":tcl", ":tcldo" or ":tclfile" then creates
  405. a new Tcl interpreter.  Unfortunately, there's a side effect:  "exit" no
  406. longer is a sure way to terminate the script.  The error from "exit" can be
  407. caught (using "catch"), and script processing continues from this point.  This
  408. is a design flaw in Tcl, and cannot be fixed without massive hacking.
  409.  
  410. Calling ":tcl", ":tcldo" or ":tclfile" from inside Tcl (via "::vim::command")
  411. may have unexpected side effects.  The command is executed in the master
  412. interpreter - making "::vim::command" available in a safe child interpreter
  413. therefore makes the child unsafe.  Global variables "line" or "lnum" are
  414. destroyed when ":tcldo" is called.  (The final version should probably catch
  415. attemts to execute ":tcl" etc from within Tcl, and just return an error.)
  416.  
  417. Input from stdin is currently not supported.
  418.  
  419. ==============================================================================
  420. 8. Examples:                        *tcl-examples*
  421.  
  422. Here are a few small (and maybe useful) Tcl scripts.
  423.  
  424. This script sorts the lines of the entire buffer (assume it contains a list
  425. of names or something similar):
  426.     set buf $::vim::current(buffer)
  427.     set lines [$buf get top bottom]
  428.     set lines [lsort -dictionary $lines]
  429.     $buf set top bottom $lines
  430.  
  431. This script reverses the lines in the buffer.  Note the use of "::vim::lbase"
  432. and "$buf last" to work with any line number setting.
  433.     set buf $::vim::current(buffer)
  434.     set t $::vim::lbase
  435.     set b [$buf last]
  436.     while { $t < $b } {
  437.         set tl [$buf get $t]
  438.         set bl [$buf get $b]
  439.         $buf set $t $bl
  440.         $buf set $b $tl
  441.         incr t
  442.         incr b -1
  443.     }
  444.  
  445. This script adds a consecutive number to each line in the current range:
  446.     set buf $::vim::current(buffer)
  447.     set i $::vim::range(start)
  448.     set n 1
  449.     while { $i <= $::vim::range(end) } {
  450.         set line [$buf get $i]
  451.         $buf set $i "$n\t$line"
  452.         incr i ; incr n
  453.     }
  454.  
  455. The same can also be done quickly with two ex commands, using ":tcldo":
  456.     :tcl set n 1
  457.     :[range]tcldo set line "$n\t$line" ; incr n
  458.  
  459. This procedure runs an ex command on each buffer (idea stolen from Ron Aaron):
  460.     proc eachbuf { cmd } {
  461.         foreach b [::vim::buffer list] {
  462.             $b command $cmd
  463.         }
  464.     }
  465. Use it like this:
  466.     :tcl eachbuf %s/foo/bar/g
  467. Be careful with Tcl's string and backslash substitution, tough. If in doubt,
  468. surround the ex command with curly braces.
  469.  
  470.  
  471. If you want to add some Tcl procedures permanently to vim, just place them in
  472. a file (e.g. "~/.vimrc.tcl" on Unix machines), and add these lines to your
  473. startup file (usually "~/.vimrc" on Unix):
  474.     if has("tcl")
  475.         tclfile ~/.vimrc.tcl
  476.     endif
  477.  
  478. ==============================================================================
  479.  vim:tw=78:ts=8:sw=8:
  480.  
  481.