diff options
| -rw-r--r-- | runtime/doc/if_lua.txt | 403 | ||||
| -rw-r--r-- | runtime/doc/if_mzsch.txt | 286 | ||||
| -rw-r--r-- | runtime/doc/if_perl.txt | 294 | ||||
| -rw-r--r-- | runtime/doc/if_ruby.txt | 216 | ||||
| -rw-r--r-- | runtime/doc/if_tcl.txt | 533 |
5 files changed, 0 insertions, 1732 deletions
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt deleted file mode 100644 index 2b322ddbae..0000000000 --- a/runtime/doc/if_lua.txt +++ /dev/null @@ -1,403 +0,0 @@ -*if_lua.txt* For Vim version 7.4. Last change: 2013 Sep 04 - - - VIM REFERENCE MANUAL by Luis Carvalho - - -The Lua Interface to Vim *lua* *Lua* - -1. Commands |lua-commands| -2. The vim module |lua-vim| -3. List userdata |lua-list| -4. Dict userdata |lua-dict| -5. Funcref userdata |lua-funcref| -6. Buffer userdata |lua-buffer| -7. Window userdata |lua-window| -8. The luaeval function |lua-luaeval| - -{Vi does not have any of these commands} - -The Lua interface is available only when Vim was compiled with the -|+lua| feature. - -============================================================================== -1. Commands *lua-commands* - - *:lua* -:[range]lua {chunk} - Execute Lua chunk {chunk}. {not in Vi} - -Examples: -> - :lua print("Hello, Vim!") - :lua local curbuf = vim.buffer() curbuf[7] = "line #7" -< - -:[range]lua << {endmarker} -{script} -{endmarker} - Execute Lua script {script}. {not in Vi} - Note: This command doesn't work when the Lua - 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 |:lua| command is mainly useful for including Lua code -in Vim scripts. - -Example: -> - function! CurrentLineInfo() - lua << EOF - local linenr = vim.window().line - local curline = vim.buffer()[linenr] - print(string.format("Current line [%d] has %d chars", - linenr, #curline)) - EOF - endfunction -< - - *:luado* -:[range]luado {body} Execute Lua function "function (line, linenr) {body} - end" for each line in the [range], with the function - argument being set to the text of each line in turn, - without a trailing <EOL>, and the current line number. - If the value returned by the function is a string it - becomes the text of the line in the current turn. The - default for [range] is the whole file: "1,$". - {not in Vi} - -Examples: -> - :luado return string.format("%s\t%d", line:reverse(), #line) - - :lua require"lpeg" - :lua -- balanced parenthesis grammar: - :lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" } - :luado if bp:match(line) then return "-->\t" .. line end -< - - *:luafile* -:[range]luafile {file} - Execute Lua script in {file}. {not in Vi} - The whole argument is used as a single file name. - -Examples: -> - :luafile script.lua - :luafile % -< - -All these commands execute a Lua chunk from either the command line (:lua and -:luado) or a file (:luafile) with the given line [range]. Similarly to the Lua -interpreter, each chunk has its own scope and so only global variables are -shared between command calls. All Lua default libraries are available. In -addition, Lua "print" function has its output redirected to the Vim message -area, with arguments separated by a white space instead of a tab. - -Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim -and manage buffers (|lua-buffer|) and windows (|lua-window|). However, -procedures that alter buffer content, open new buffers, and change cursor -position are restricted when the command is executed in the |sandbox|. - - -============================================================================== -2. The vim module *lua-vim* - -Lua interfaces Vim through the "vim" module. The first and last line of the -input range are stored in "vim.firstline" and "vim.lastline" respectively. The -module also includes routines for buffer, window, and current line queries, -Vim evaluation and command execution, and others. - - vim.list([arg]) Returns an empty list or, if "arg" is a Lua - table with numeric keys 1, ..., n (a - "sequence"), returns a list l such that l[i] = - arg[i] for i = 1, ..., n (see |List|). - Non-numeric keys are not used to initialize - the list. See also |lua-eval| for conversion - rules. Example: > - :lua t = {math.pi, false, say = 'hi'} - :echo luaeval('vim.list(t)') - :" [3.141593, 0], 'say' is ignored -< - vim.dict([arg]) Returns an empty dictionary or, if "arg" is a - Lua table, returns a dict d such that d[k] = - arg[k] for all string keys k in "arg" (see - |Dictionary|). Number keys are converted to - strings. Keys that are not strings are not - used to initialize the dictionary. See also - |lua-eval| for conversion rules. Example: > - :lua t = {math.pi, false, say = 'hi'} - :echo luaeval('vim.dict(t)') - :" {'say': 'hi'}, numeric keys ignored -< - vim.funcref({name}) Returns a Funcref to function {name} (see - |Funcref|). It is equivalent to Vim's - "function". NOT IMPLEMENTED YET - - vim.buffer([arg]) If "arg" is a number, returns buffer with - number "arg" in the buffer list or, if "arg" - is a string, returns buffer whose full or short - name is "arg". In both cases, returns 'nil' - (nil value, not string) if the buffer is not - found. Otherwise, if "toboolean(arg)" is - 'true' returns the first buffer in the buffer - list or else the current buffer. - - vim.window([arg]) If "arg" is a number, returns window with - number "arg" or 'nil' (nil value, not string) - if not found. Otherwise, if "toboolean(arg)" - is 'true' returns the first window or else the - current window. - - vim.type({arg}) Returns the type of {arg}. It is equivalent to - Lua's "type" function, but returns "list", - "dict", "funcref", "buffer", or "window" if - {arg} is a list, dictionary, funcref, buffer, - or window, respectively. Examples: > - :lua l = vim.list() - :lua print(type(l), vim.type(l)) - :" userdata list -< - vim.command({cmd}) Executes the vim (ex-mode) command {cmd}. - Examples: > - :lua vim.command"set tw=60" - :lua vim.command"normal ddp" -< - vim.eval({expr}) Evaluates expression {expr} (see |expression|), - converts the result to Lua, and returns it. - Vim strings and numbers are directly converted - to Lua strings and numbers respectively. Vim - lists and dictionaries are converted to Lua - userdata (see |lua-list| and |lua-dict|). - Examples: > - :lua tw = vim.eval"&tw" - :lua print(vim.eval"{'a': 'one'}".a) -< - vim.line() Returns the current line (without the trailing - <EOL>), a Lua string. - - vim.beep() Beeps. - - vim.open({fname}) Opens a new buffer for file {fname} and - returns it. Note that the buffer is not set as - current. - - -============================================================================== -3. List userdata *lua-list* - -List userdata represent vim lists, and the interface tries to follow closely -Vim's syntax for lists. Since lists are objects, changes in list references in -Lua are reflected in Vim and vice-versa. A list "l" has the following -properties and methods: - -Properties ----------- - o "#l" is the number of items in list "l", equivalent to "len(l)" - in Vim. - o "l[k]" returns the k-th item in "l"; "l" is zero-indexed, as in Vim. - To modify the k-th item, simply do "l[k] = newitem"; in - particular, "l[k] = nil" removes the k-th item from "l". - o "l()" returns an iterator for "l". - -Methods -------- - o "l:add(item)" appends "item" to the end of "l". - o "l:insert(item[, pos])" inserts "item" at (optional) - position "pos" in the list. The default value for "pos" is 0. - -Examples: -> - :let l = [1, 'item'] - :lua l = vim.eval('l') -- same 'l' - :lua l:add(vim.list()) - :lua l[0] = math.pi - :echo l[0] " 3.141593 - :lua l[0] = nil -- remove first item - :lua l:insert(true, 1) - :lua print(l, #l, l[0], l[1], l[-1]) - :lua for item in l() do print(item) end -< - -============================================================================== -4. Dict userdata *lua-dict* - -Similarly to list userdata, dict userdata represent vim dictionaries; since -dictionaries are also objects, references are kept between Lua and Vim. A dict -"d" has the following properties: - -Properties ----------- - o "#d" is the number of items in dict "d", equivalent to "len(d)" - in Vim. - o "d.key" or "d['key']" returns the value at entry "key" in "d". - To modify the entry at this key, simply do "d.key = newvalue"; in - particular, "d.key = nil" removes the entry from "d". - o "d()" returns an iterator for "d" and is equivalent to "items(d)" in - Vim. - -Examples: -> - :let d = {'n':10} - :lua d = vim.eval('d') -- same 'd' - :lua print(d, d.n, #d) - :let d.self = d - :lua for k, v in d() do print(d, k, v) end - :lua d.x = math.pi - :lua d.self = nil -- remove entry - :echo d -< - -============================================================================== -5. Funcref userdata *lua-funcref* - -Funcref userdata represent funcref variables in Vim. Funcrefs that were -defined with a "dict" attribute need to be obtained as a dictionary key -in order to have "self" properly assigned to the dictionary (see examples -below.) A funcref "f" has the following properties: - -Properties ----------- - o "#f" is the name of the function referenced by "f" - o "f(...)" calls the function referenced by "f" (with arguments) - -Examples: -> - :function I(x) - : return a:x - : endfunction - :let R = function('I') - :lua i1 = vim.funcref('I') - :lua i2 = vim.eval('R') - :lua print(#i1, #i2) -- both 'I' - :lua print(i1, i2, #i2(i1) == #i1(i2)) - :function Mylen() dict - : return len(self.data) - : endfunction - :let mydict = {'data': [0, 1, 2, 3]} - :lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen') - :echo mydict.len() - :lua l = d.len -- assign d as 'self' - :lua print(l()) -< - -============================================================================== -6. Buffer userdata *lua-buffer* - -Buffer userdata represent vim buffers. A buffer userdata "b" has the following -properties and methods: - -Properties ----------- - o "b()" sets "b" as the current buffer. - o "#b" is the number of lines in buffer "b". - o "b[k]" represents line number k: "b[k] = newline" replaces line k - with string "newline" and "b[k] = nil" deletes line k. - o "b.name" contains the short name of buffer "b" (read-only). - o "b.fname" contains the full name of buffer "b" (read-only). - o "b.number" contains the position of buffer "b" in the buffer list - (read-only). - -Methods -------- - o "b:insert(newline[, pos])" inserts string "newline" at (optional) - position "pos" in the buffer. The default value for "pos" is - "#b + 1". If "pos == 0" then "newline" becomes the first line in - the buffer. - o "b:next()" returns the buffer next to "b" in the buffer list. - o "b:previous()" returns the buffer previous to "b" in the buffer - list. - o "b:isvalid()" returns 'true' (boolean) if buffer "b" corresponds to - a "real" (not freed from memory) Vim buffer. - -Examples: -> - :lua b = vim.buffer() -- current buffer - :lua print(b.name, b.number) - :lua b[1] = "first line" - :lua b:insert("FIRST!", 0) - :lua b[1] = nil -- delete top line - :lua for i=1,3 do b:insert(math.random()) end - :3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end - :lua vim.open"myfile"() -- open buffer and set it as current - - function! ListBuffers() - lua << EOF - local b = vim.buffer(true) -- first buffer in list - while b ~= nil do - print(b.number, b.name, #b) - b = b:next() - end - vim.beep() - EOF - endfunction -< - -============================================================================== -7. Window userdata *lua-window* - -Window objects represent vim windows. A window userdata "w" has the following -properties and methods: - -Properties ----------- - o "w()" sets "w" as the current window. - o "w.buffer" contains the buffer of window "w" (read-only). - o "w.line" represents the cursor line position in window "w". - o "w.col" represents the cursor column position in window "w". - o "w.width" represents the width of window "w". - o "w.height" represents the height of window "w". - -Methods -------- - o "w:next()" returns the window next to "w". - o "w:previous()" returns the window previous to "w". - o "w:isvalid()" returns 'true' (boolean) if window "w" corresponds to - a "real" (not freed from memory) Vim window. - -Examples: -> - :lua w = vim.window() -- current window - :lua print(w.buffer.name, w.line, w.col) - :lua w.width = w.width + math.random(10) - :lua w.height = 2 * math.random() * w.height - :lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end - :lua print("There are " .. n .. " windows") -< - -============================================================================== -8. The luaeval function *lua-luaeval* *lua-eval* - -The (dual) equivalent of "vim.eval" for passing Lua values to Vim is -"luaeval". "luaeval" takes an expression string and an optional argument and -returns the result of the expression. It is semantically equivalent in Lua to: -> - local chunkheader = "local _A = select(1, ...) return " - function luaeval (expstr, arg) - local chunk = assert(loadstring(chunkheader .. expstr, "luaeval")) - return chunk(arg) -- return typval - end -< -Note that "_A" receives the argument to "luaeval". Lua numbers, strings, and -list, dict, and funcref userdata are converted to their Vim respective types, -while Lua booleans are converted to numbers. An error is thrown if conversion -of any of the remaining Lua types, including userdata other than lists, dicts, -and funcrefs, is attempted. - -Examples: > - - :echo luaeval('math.pi') - :lua a = vim.list():add('newlist') - :let a = luaeval('a') - :echo a[0] " 'newlist' - :function Rand(x,y) " random uniform between x and y - : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) - : endfunction - :echo Rand(1,10) - - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/if_mzsch.txt b/runtime/doc/if_mzsch.txt deleted file mode 100644 index b42570a75a..0000000000 --- a/runtime/doc/if_mzsch.txt +++ /dev/null @@ -1,286 +0,0 @@ -*if_mzsch.txt* For Vim version 7.4. Last change: 2012 Dec 17 - - - VIM REFERENCE MANUAL by Sergey Khorev - - -The MzScheme Interface to Vim *mzscheme* *MzScheme* - -1. Commands |mzscheme-commands| -2. Examples |mzscheme-examples| -3. Threads |mzscheme-threads| -4. Vim access from MzScheme |mzscheme-vim| -5. mzeval() Vim function |mzscheme-mzeval| -6. Using Function references |mzscheme-funcref| -7. Dynamic loading |mzscheme-dynamic| - -{Vi does not have any of these commands} - -The MzScheme interface is available only if Vim was compiled with the -|+mzscheme| feature. - -Based on the work of Brent Fulgham. -Dynamic loading added by Sergey Khorev - -MzScheme and PLT Scheme names have been rebranded as Racket. For more -information please check http://racket-lang.org - -Futures and places of Racket version 5.x up to and including 5.3.1 do not -work correctly with processes created by Vim. -The simplest solution is to build Racket on your own with these features -disabled: > - ./configure --disable-futures --disable-places --prefix=your-install-prefix - -To speed up the process, you might also want to use --disable-gracket and ---disable-docs - -============================================================================== -1. Commands *mzscheme-commands* - - *:mzscheme* *:mz* -:[range]mz[scheme] {stmt} - Execute MzScheme statement {stmt}. {not in Vi} - -:[range]mz[scheme] << {endmarker} -{script} -{endmarker} - Execute inlined MzScheme script {script}. - Note: This command doesn't work if the MzScheme - feature wasn't compiled in. To avoid errors, see - |script-here|. - - *:mzfile* *:mzf* -:[range]mzf[ile] {file} Execute the MzScheme script in {file}. {not in Vi} - -All of these commands do essentially the same thing - they execute a piece of -MzScheme code, with the "current range" set to the given line -range. - -In the case of :mzscheme, the code to execute is in the command-line. -In the case of :mzfile, the code to execute is the contents of the given file. - -MzScheme interface defines exception exn:vim, derived from exn. -It is raised for various Vim errors. - -During compilation, the MzScheme interface will remember the current MzScheme -collection path. If you want to specify additional paths use the -'current-library-collection-paths' parameter. E.g., to cons the user-local -MzScheme collection path: > - :mz << EOF - (current-library-collection-paths - (cons - (build-path (find-system-path 'addon-dir) (version) "collects") - (current-library-collection-paths))) - EOF -< - -All functionality is provided through module vimext. - -The exn:vim is available without explicit import. - -To avoid clashes with MzScheme, consider using prefix when requiring module, -e.g.: > - :mzscheme (require (prefix vim- vimext)) -< -All the examples below assume this naming scheme. - - *mzscheme-sandbox* -When executed in the |sandbox|, access to some filesystem and Vim interface -procedures is restricted. - -============================================================================== -2. Examples *mzscheme-examples* -> - :mzscheme (display "Hello") - :mz (display (string-append "Using MzScheme version " (version))) - :mzscheme (require (prefix vim- vimext)) ; for MzScheme < 4.x - :mzscheme (require (prefix-in vim- 'vimext)) ; MzScheme 4.x - :mzscheme (vim-set-buff-line 10 "This is line #10") -< -Inline script usage: > - function! <SID>SetFirstLine() - :mz << EOF - (display "!!!") - (require (prefix vim- vimext)) - ; for newer versions (require (prefix-in vim- 'vimext)) - (vim-set-buff-line 1 "This is line #1") - (vim-beep) - EOF - endfunction - - nmap <F9> :call <SID>SetFirstLine() <CR> -< -File execution: > - :mzfile supascript.scm -< -Vim exception handling: > - :mz << EOF - (require (prefix vim- vimext)) - ; for newer versions (require (prefix-in vim- 'vimext)) - (with-handlers - ([exn:vim? (lambda (e) (display (exn-message e)))]) - (vim-eval "nonsense-string")) - EOF -< -Auto-instantiation of vimext module (can be placed in your |vimrc|): > - function! MzRequire() - :redir => l:mzversion - :mz (version) - :redir END - if strpart(l:mzversion, 1, 1) < "4" - " MzScheme versions < 4.x: - :mz (require (prefix vim- vimext)) - else - " newer versions: - :mz (require (prefix-in vim- 'vimext)) - endif - endfunction - - if has("mzscheme") - silent call MzRequire() - endif -< -============================================================================== -3. Threads *mzscheme-threads* - -The MzScheme interface supports threads. They are independent from OS threads, -thus scheduling is required. The option 'mzquantum' determines how often -Vim should poll for available MzScheme threads. -NOTE -Thread scheduling in the console version of Vim is less reliable than in the -GUI version. - -============================================================================== -4. Vim access from MzScheme *mzscheme-vim* - - *mzscheme-vimext* -The 'vimext' module provides access to procedures defined in the MzScheme -interface. - -Common ------- - (command {command-string}) Perform the vim ":Ex" style command. - (eval {expr-string}) Evaluate the vim expression into - respective MzScheme object: |Lists| are - represented as Scheme lists, - |Dictionaries| as hash tables, - |Funcref|s as functions (see also - |mzscheme-funcref|) - NOTE the name clashes with MzScheme eval, - use module qualifiers to overcome this. - (range-start) Start/End of the range passed with - (range-end) the Scheme command. - (beep) beep - (get-option {option-name} [buffer-or-window]) Get Vim option value (either - local or global, see set-option). - (set-option {string} [buffer-or-window]) - Set a Vim option. String must have option - setting form (like optname=optval, or - optname+=optval, etc.) When called with - {buffer} or {window} the local option will - be set. The symbol 'global can be passed - as {buffer-or-window}. Then |:setglobal| - will be used. - -Buffers *mzscheme-buffer* -------- - (buff? {object}) Is object a buffer? - (buff-valid? {object}) Is object a valid buffer? (i.e. - corresponds to the real Vim buffer) - (get-buff-line {linenr} [buffer]) - Get line from a buffer. - (set-buff-line {linenr} {string} [buffer]) - Set a line in a buffer. If {string} is #f, - the line gets deleted. The [buffer] - argument is optional. If omitted, the - current buffer will be used. - (get-buff-line-list {start} {end} [buffer]) - Get a list of lines in a buffer. {Start} - and {end} are 1-based and inclusive. - (set-buff-line-list {start} {end} {string-list} [buffer]) - Set a list of lines in a buffer. If - string-list is #f or null, the lines get - deleted. If a list is shorter than - {end}-{start} the remaining lines will - be deleted. - (get-buff-name [buffer]) Get a buffer's text name. - (get-buff-num [buffer]) Get a buffer's number. - (get-buff-size [buffer]) Get buffer line count. - (insert-buff-line-list {linenr} {string/string-list} [buffer]) - Insert a list of lines into a buffer after - {linenr}. If {linenr} is 0, lines will be - inserted at start. - (curr-buff) Get the current buffer. Use other MzScheme - interface procedures to change it. - (buff-count) Get count of total buffers in the editor. - (get-next-buff [buffer]) Get next buffer. - (get-prev-buff [buffer]) Get previous buffer. Return #f when there - are no more buffers. - (open-buff {filename}) Open a new buffer (for file "name") - (get-buff-by-name {buffername}) Get a buffer by its filename or #f - if there is no such buffer. - (get-buff-by-num {buffernum}) Get a buffer by its number (return #f if - there is no buffer with this number). - -Windows *mzscheme-window* ------- - (win? {object}) Is object a window? - (win-valid? {object}) Is object a valid window (i.e. corresponds - to the real Vim window)? - (curr-win) Get the current window. - (win-count) Get count of windows. - (get-win-num [window]) Get window number. - (get-win-by-num {windownum}) Get window by its number. - (get-win-buffer [window]) Get the buffer for a given window. - (get-win-height [window]) - (set-win-height {height} [window]) Get/Set height of window. - (get-win-width [window]) - (set-win-width {width} [window])Get/Set width of window. - (get-win-list [buffer]) Get list of windows for a buffer. - (get-cursor [window]) Get cursor position in a window as - a pair (linenr . column). - (set-cursor (line . col) [window]) Set cursor position. - -============================================================================== -5. mzeval() Vim function *mzscheme-mzeval* - -To facilitate bi-directional interface, you can use |mzeval()| function to -evaluate MzScheme expressions and pass their values to VimL. - -============================================================================== -6. Using Function references *mzscheme-funcref* - -MzScheme interface allows use of |Funcref|s so you can call Vim functions -directly from Scheme. For instance: > - function! MyAdd2(arg) - return a:arg + 2 - endfunction - mz (define f2 (vim-eval "function(\"MyAdd2\")")) - mz (f2 7) -< or : > - :mz (define indent (vim-eval "function('indent')")) - " return Vim indent for line 12 - :mz (indent 12) -< - -============================================================================== -7. Dynamic loading *mzscheme-dynamic* *E815* - -On MS-Windows the MzScheme libraries can be loaded dynamically. The |:version| -output then includes |+mzscheme/dyn|. - -This means that Vim will search for the MzScheme DLL files only when needed. -When you don't use the MzScheme interface you don't need them, thus you can -use Vim without these DLL files. - -To use the MzScheme interface the MzScheme DLLs must be in your search path. -In a console window type "path" to see what directories are used. - -The names of the DLLs must match the MzScheme version Vim was compiled with. -For MzScheme version 209 they will be "libmzsch209_000.dll" and -"libmzgc209_000.dll". To know for sure look at the output of the ":version" -command, look for -DDYNAMIC_MZSCH_DLL="something" and --DDYNAMIC_MZGC_DLL="something" in the "Compilation" info. - -====================================================================== - vim:tw=78:ts=8:sts=4:ft=help:norl: diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt deleted file mode 100644 index 7be5f06f68..0000000000 --- a/runtime/doc/if_perl.txt +++ /dev/null @@ -1,294 +0,0 @@ -*if_perl.txt* For Vim version 7.4. Last change: 2013 Oct 05 - - - VIM REFERENCE MANUAL by Sven Verdoolaege - and Matt Gerassimof - -Perl and Vim *perl* *Perl* - -1. Editing Perl files |perl-editing| -2. Compiling VIM with Perl interface |perl-compiling| -3. Using the Perl interface |perl-using| -4. Dynamic loading |perl-dynamic| - -{Vi does not have any of these commands} - -The Perl interface only works when Vim was compiled with the |+perl| feature. - -============================================================================== -1. Editing Perl files *perl-editing* - -Vim syntax highlighting supports Perl and POD files. Vim assumes a file is -Perl code if the filename has a .pl or .pm suffix. Vim also examines the first -line of a file, regardless of the filename suffix, to check if a file is a -Perl script (see scripts.vim in Vim's syntax directory). Vim assumes a file -is POD text if the filename has a .POD suffix. - -To use tags with Perl, you need a recent version of Exuberant ctags. Look -here: - http://ctags.sourceforge.net - -Alternatively, you can use the Perl script pltags.pl, which is shipped with -Vim in the $VIMRUNTIME/tools directory. This script has currently more -features than Exuberant ctags' Perl support. - -============================================================================== -2. Compiling VIM with Perl interface *perl-compiling* - -To compile Vim with Perl interface, you need Perl 5.004 (or later). Perl must -be installed before you compile Vim. Vim's Perl interface does NOT work with -the 5.003 version that has been officially released! It will probably work -with Perl 5.003_05 and later. - -The Perl patches for Vim were made by: - Sven Verdoolaege <skimo@breughel.ufsia.ac.be> - Matt Gerassimof - -Perl for MS-Windows can be found at: http://www.perl.com/ -The ActiveState one should work. - -============================================================================== -3. Using the Perl interface *perl-using* - - *:perl* *:pe* -:pe[rl] {cmd} Execute Perl command {cmd}. The current package - is "main". Simple example to test if `:perl` is - working: > - :perl VIM::Msg("Hello") - -:pe[rl] << {endpattern} -{script} -{endpattern} - Execute Perl script {script}. - {endpattern} must NOT be preceded by any white space. - If {endpattern} is omitted, it defaults to a dot '.' - like for the |:append| and |:insert| commands. Using - '.' helps when inside a function, because "$i;" looks - like the start of an |:insert| command to Vim. - This form of the |:perl| command is mainly useful for - including perl code in vim scripts. - Note: This command doesn't work when the Perl feature - wasn't compiled in. To avoid errors, see - |script-here|. - - -Example vim script: > - - function! WhitePearl() - perl << EOF - VIM::Msg("pearls are nice for necklaces"); - VIM::Msg("rubys for rings"); - VIM::Msg("pythons for bags"); - VIM::Msg("tcls????"); - EOF - endfunction -< - - *:perldo* *:perld* -:[range]perld[o] {cmd} Execute Perl command {cmd} for each line in the - [range], with $_ being set to the text of each line in - turn, without a trailing <EOL>. Setting $_ will change - the text, but note that it is not possible to add or - delete lines using this command. - The default for [range] is the whole file: "1,$". - -Here are some things you can try: > - - :perl $a=1 - :perldo $_ = reverse($_);1 - :perl VIM::Msg("hello") - :perl $line = $curbuf->Get(42) -< - *E299* -Executing Perl commands in the |sandbox| is limited. ":perldo" will not be -possible at all. ":perl" will be evaluated in the Safe environment, if -possible. - - - *perl-overview* -Here is an overview of the functions that are available to Perl: > - - :perl VIM::Msg("Text") # displays a message - :perl VIM::Msg("Error", "ErrorMsg") # displays an error message - :perl VIM::Msg("remark", "Comment") # displays a highlighted message - :perl VIM::SetOption("ai") # sets a vim option - :perl $nbuf = VIM::Buffers() # returns the number of buffers - :perl @buflist = VIM::Buffers() # returns array of all buffers - :perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c' - :perl @winlist = VIM::Windows() # returns array of all windows - :perl $nwin = VIM::Windows() # returns the number of windows - :perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1 - :perl ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0 - :perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile> - :perl $curwin->SetHeight(10) # sets the window height - :perl @pos = $curwin->Cursor() # returns (row, col) array - :perl @pos = (10, 10) - :perl $curwin->Cursor(@pos) # sets cursor to @pos - :perl $curwin->Cursor(10,10) # sets cursor to row 10 col 10 - :perl $mybuf = $curwin->Buffer() # returns the buffer object for window - :perl $curbuf->Name() # returns buffer name - :perl $curbuf->Number() # returns buffer number - :perl $curbuf->Count() # returns the number of lines - :perl $l = $curbuf->Get(10) # returns line 10 - :perl @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5 - :perl $curbuf->Delete(10) # deletes line 10 - :perl $curbuf->Delete(10, 20) # delete lines 10 through 20 - :perl $curbuf->Append(10, "Line") # appends a line - :perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines - :perl @l = ("L1", "L2", "L3") - :perl $curbuf->Append(10, @l) # appends L1, L2 and L3 - :perl $curbuf->Set(10, "Line") # replaces line 10 - :perl $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11 - :perl $curbuf->Set(10, @l) # replaces 3 lines -< - *perl-Msg* -VIM::Msg({msg}, {group}?) - Displays the message {msg}. The optional {group} - argument specifies a highlight group for Vim to use - for the message. - - *perl-SetOption* -VIM::SetOption({arg}) Sets a vim option. {arg} can be any argument that the - ":set" command accepts. Note that this means that no - spaces are allowed in the argument! See |:set|. - - *perl-Buffers* -VIM::Buffers([{bn}...]) With no arguments, returns a list of all the buffers - in an array context or returns the number of buffers - in a scalar context. For a list of buffer names or - numbers {bn}, returns a list of the buffers matching - {bn}, using the same rules as Vim's internal - |bufname()| function. - WARNING: the list becomes invalid when |:bwipe| is - used. Using it anyway may crash Vim. - - *perl-Windows* -VIM::Windows([{wn}...]) With no arguments, returns a list of all the windows - in an array context or returns the number of windows - in a scalar context. For a list of window numbers - {wn}, returns a list of the windows with those - numbers. - WARNING: the list becomes invalid when a window is - closed. Using it anyway may crash Vim. - - *perl-DoCommand* -VIM::DoCommand({cmd}) Executes Ex command {cmd}. - - *perl-Eval* -VIM::Eval({expr}) Evaluates {expr} and returns (success, value) in list - context or just value in scalar context. - success=1 indicates that val contains the value of - {expr}; success=0 indicates a failure to evaluate - the expression. '@x' returns the contents of register - x, '&x' returns the value of option x, 'x' returns the - value of internal |variables| x, and '$x' is equivalent - to perl's $ENV{x}. All |functions| accessible from - the command-line are valid for {expr}. - A |List| is turned into a string by joining the items - and inserting line breaks. - - *perl-SetHeight* -Window->SetHeight({height}) - Sets the Window height to {height}, within screen - limits. - - *perl-GetCursor* -Window->Cursor({row}?, {col}?) - With no arguments, returns a (row, col) array for the - current cursor position in the Window. With {row} and - {col} arguments, sets the Window's cursor position to - {row} and {col}. Note that {col} is numbered from 0, - Perl-fashion, and thus is one less than the value in - Vim's ruler. - -Window->Buffer() *perl-Buffer* - Returns the Buffer object corresponding to the given - Window. - - *perl-Name* -Buffer->Name() Returns the filename for the Buffer. - - *perl-Number* -Buffer->Number() Returns the number of the Buffer. - - *perl-Count* -Buffer->Count() Returns the number of lines in the Buffer. - - *perl-Get* -Buffer->Get({lnum}, {lnum}?, ...) - Returns a text string of line {lnum} in the Buffer - for each {lnum} specified. An array can be passed - with a list of {lnum}'s specified. - - *perl-Delete* -Buffer->Delete({lnum}, {lnum}?) - Deletes line {lnum} in the Buffer. With the second - {lnum}, deletes the range of lines from the first - {lnum} to the second {lnum}. - - *perl-Append* -Buffer->Append({lnum}, {line}, {line}?, ...) - Appends each {line} string after Buffer line {lnum}. - The list of {line}s can be an array. - - *perl-Set* -Buffer->Set({lnum}, {line}, {line}?, ...) - Replaces one or more Buffer lines with specified - {lines}s, starting at Buffer line {lnum}. The list of - {line}s can be an array. If the arguments are - invalid, replacement does not occur. - -$main::curwin - The current window object. - -$main::curbuf - The current buffer object. - - - *script-here* -When using a script language in-line, you might want to skip this when the -language isn't supported. But this mechanism doesn't work: > - if has('perl') - perl << EOF - this will NOT work! - EOF - endif -Instead, put the Perl/Python/Ruby/etc. command in a function and call that -function: > - if has('perl') - function DefPerl() - perl << EOF - this works - EOF - endfunction - call DefPerl() - endif -Note that "EOF" must be at the start of the line. - -============================================================================== -4. Dynamic loading *perl-dynamic* - -On MS-Windows and Unix the Perl library can be loaded dynamically. The -|:version| output then includes |+perl/dyn|. - -This means that Vim will search for the Perl DLL or shared library file only -when needed. When you don't use the Perl interface you don't need it, thus -you can use Vim without this file. - - -MS-Windows ~ - -You can download Perl from http://www.perl.org. The one from ActiveState was -used for building Vim. - -To use the Perl interface the Perl DLL must be in your search path. -If Vim reports it cannot find the perl512.dll, make sure your $PATH includes -the directory where it is located. The Perl installer normally does that. -In a console window type "path" to see what directories are used. - -The name of the DLL must match the Perl version Vim was compiled with. -Currently the name is "perl512.dll". That is for Perl 5.12. To know for -sure edit "gvim.exe" and search for "perl\d*.dll\c". - -============================================================================== - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt deleted file mode 100644 index 0a32d87851..0000000000 --- a/runtime/doc/if_ruby.txt +++ /dev/null @@ -1,216 +0,0 @@ -*if_ruby.txt* For Vim version 7.4. Last change: 2012 Aug 02 - - - VIM REFERENCE MANUAL by Shugo Maeda - -The Ruby Interface to Vim *ruby* *Ruby* - - -1. Commands |ruby-commands| -2. The VIM module |ruby-vim| -3. VIM::Buffer objects |ruby-buffer| -4. VIM::Window objects |ruby-window| -5. Global variables |ruby-globals| -6. Dynamic loading |ruby-dynamic| - -{Vi does not have any of these commands} - *E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273* - -The Ruby interface only works when Vim was compiled with the |+ruby| feature. - -The home page for ruby is http://www.ruby-lang.org/. You can find links for -downloading Ruby there. - -============================================================================== -1. Commands *ruby-commands* - - *:ruby* *:rub* -:rub[y] {cmd} Execute Ruby command {cmd}. A command to try it out: > - :ruby print "Hello" - -:rub[y] << {endpattern} -{script} -{endpattern} - Execute Ruby script {script}. - {endpattern} must NOT be preceded by any white space. - If {endpattern} is omitted, it defaults to a dot '.' - like for the |:append| and |:insert| commands. This - form of the |:ruby| command is mainly useful for - including ruby code in vim scripts. - Note: This command doesn't work when the Ruby feature - wasn't compiled in. To avoid errors, see - |script-here|. - -Example Vim script: > - - function! RedGem() - ruby << EOF - class Garnet - def initialize(s) - @buffer = VIM::Buffer.current - vimputs(s) - end - def vimputs(s) - @buffer.append(@buffer.count,s) - end - end - gem = Garnet.new("pretty") - EOF - endfunction -< - - *:rubydo* *:rubyd* *E265* -:[range]rubyd[o] {cmd} Evaluate Ruby command {cmd} for each line in the - [range], with $_ being set to the text of each line in - turn, without a trailing <EOL>. Setting $_ will change - the text, but note that it is not possible to add or - delete lines using this command. - The default for [range] is the whole file: "1,$". - - *:rubyfile* *:rubyf* -:rubyf[ile] {file} Execute the Ruby script in {file}. This is the same as - ":ruby load 'file'", but allows file name completion. - -Executing Ruby commands is not possible in the |sandbox|. - -============================================================================== -2. The VIM module *ruby-vim* - -Ruby code gets all of its access to vim via the "VIM" module. - -Overview > - print "Hello" # displays a message - VIM.command(cmd) # execute an Ex command - num = VIM::Window.count # gets the number of windows - w = VIM::Window[n] # gets window "n" - cw = VIM::Window.current # gets the current window - num = VIM::Buffer.count # gets the number of buffers - b = VIM::Buffer[n] # gets buffer "n" - cb = VIM::Buffer.current # gets the current buffer - w.height = lines # sets the window height - w.cursor = [row, col] # sets the window cursor position - pos = w.cursor # gets an array [row, col] - name = b.name # gets the buffer file name - line = b[n] # gets a line from the buffer - num = b.count # gets the number of lines - b[n] = str # sets a line in the buffer - b.delete(n) # deletes a line - b.append(n, str) # appends a line after n - line = VIM::Buffer.current.line # gets the current line - num = VIM::Buffer.current.line_number # gets the current line number - VIM::Buffer.current.line = "test" # sets the current line number -< - -Module Functions: - - *ruby-message* -VIM::message({msg}) - Displays the message {msg}. - - *ruby-set_option* -VIM::set_option({arg}) - Sets a vim option. {arg} can be any argument that the ":set" command - accepts. Note that this means that no spaces are allowed in the - argument! See |:set|. - - *ruby-command* -VIM::command({cmd}) - Executes Ex command {cmd}. - - *ruby-evaluate* -VIM::evaluate({expr}) - Evaluates {expr} using the vim internal expression evaluator (see - |expression|). Returns the expression result as a string. - A |List| is turned into a string by joining the items and inserting - line breaks. - -============================================================================== -3. VIM::Buffer objects *ruby-buffer* - -VIM::Buffer objects represent vim buffers. - -Class Methods: - -current Returns the current buffer object. -count Returns the number of buffers. -self[{n}] Returns the buffer object for the number {n}. The first number - is 0. - -Methods: - -name Returns the name of the buffer. -number Returns the number of the buffer. -count Returns the number of lines. -length Returns the number of lines. -self[{n}] Returns a line from the buffer. {n} is the line number. -self[{n}] = {str} - Sets a line in the buffer. {n} is the line number. -delete({n}) Deletes a line from the buffer. {n} is the line number. -append({n}, {str}) - Appends a line after the line {n}. -line Returns the current line of the buffer if the buffer is - active. -line = {str} Sets the current line of the buffer if the buffer is active. -line_number Returns the number of the current line if the buffer is - active. - -============================================================================== -4. VIM::Window objects *ruby-window* - -VIM::Window objects represent vim windows. - -Class Methods: - -current Returns the current window object. -count Returns the number of windows. -self[{n}] Returns the window object for the number {n}. The first number - is 0. - -Methods: - -buffer Returns the buffer displayed in the window. -height Returns the height of the window. -height = {n} Sets the window height to {n}. -width Returns the width of the window. -width = {n} Sets the window width to {n}. -cursor Returns a [row, col] array for the cursor position. -cursor = [{row}, {col}] - Sets the cursor position to {row} and {col}. - -============================================================================== -5. Global variables *ruby-globals* - -There are two global variables. - -$curwin The current window object. -$curbuf The current buffer object. - -============================================================================== -6. Dynamic loading *ruby-dynamic* - -On MS-Windows and Unix the Ruby library can be loaded dynamically. The -|:version| output then includes |+ruby/dyn|. - -This means that Vim will search for the Ruby DLL file or shared library only -when needed. When you don't use the Ruby interface you don't need it, thus -you can use Vim even though this library file is not on your system. - -You need to install the right version of Ruby for this to work. You can find -the package to download from: -http://www.garbagecollect.jp/ruby/mswin32/en/download/release.html -Currently that is ruby-1.9.1-p429-i386-mswin32.zip - -To use the Ruby interface the Ruby DLL must be in your search path. In a -console window type "path" to see what directories are used. - -The name of the DLL must match the Ruby version Vim was compiled with. -Currently the name is "msvcrt-ruby191.dll". That is for Ruby 1.9.1. To know -for sure edit "gvim.exe" and search for "ruby\d*.dll\c". - -If you want to build Vim with Ruby 1.9.1, you need to edit the config.h file -and comment-out the check for _MSC_VER. -You may also need to rename the include directory name to match the version, -strangely for Ruby 1.9.3 the directory is called 1.9.1. - -============================================================================== - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/if_tcl.txt b/runtime/doc/if_tcl.txt deleted file mode 100644 index d6726a3546..0000000000 --- a/runtime/doc/if_tcl.txt +++ /dev/null @@ -1,533 +0,0 @@ -*if_tcl.txt* For Vim version 7.4. Last change: 2012 Aug 02 - - - 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* *E281* - -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 -< - - *: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 the Tcl library can be loaded dynamically. The |:version| -output then includes |+tcl/dyn|. - -This means that Vim will search for the Tcl DLL file only when needed. When -you don't use the Tcl interface you don't need it, thus you can use Vim -without this DLL file. - -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 name of the DLL must match the Tcl version Vim was compiled with. -Currently the name is "tcl83.dll". That is for Tcl 8.3. To know for sure -edit "gvim.exe" and search for "tcl\d*.dll\c". - -============================================================================== - vim:tw=78:ts=8:ft=help:norl: |