share/vim/vim73/doc/if_lua.txt

   1 *if_lua.txt*    For Vim version 7.3.  Last change: 2010 Jul 22
   2
   3
   4                   VIM REFERENCE MANUAL    by Luis Carvalho
   5
   6
   7 The Lua Interface to Vim                                *lua* *Lua*
   8
   9 1. Commands                     |lua-commands|
  10 2. The vim module               |lua-vim|
  11 3. Buffer userdata              |lua-buffer|
  12 4. Window userdata              |lua-window|
  13
  14 {Vi does not have any of these commands}
  15
  16 The Lua interface is available only when Vim was compiled with the
  17 |+lua| feature.
  18
  19 ==============================================================================
  20 1. Commands                                             *lua-commands*
  21
  22                                                         *:lua*
  23 :[range]lua {chunk}
  24                         Execute Lua chunk {chunk}.    {not in Vi}
  25
  26 Examples:
  27 >
  28         :lua print("Hello, Vim!")
  29         :lua local curbuf = vim.buffer() curbuf[7] = "line #7"
  30 <
  31
  32 :[range]lua << {endmarker}
  33 {script}
  34 {endmarker}
  35                         Execute Lua script {script}.  {not in Vi}
  36                         Note: This command doesn't work when the Lua
  37                         feature wasn't compiled in.  To avoid errors, see
  38                         |script-here|.
  39
  40 {endmarker} must NOT be preceded by any white space.  If {endmarker} is
  41 omitted from after the "<<", a dot '.' must be used after {script}, like
  42 for the |:append| and |:insert| commands.
  43 This form of the |:lua| command is mainly useful for including Lua code
  44 in Vim scripts.
  45
  46 Example:
  47 >
  48         function! CurrentLineInfo()
  49         lua << EOF
  50         local linenr = vim.window().line
  51         local curline = vim.buffer()[linenr]
  52         print(string.format("Current line [%d] has %d chars",
  53                 linenr, #curline))
  54         EOF
  55         endfunction
  56 <
  57
  58                                                         *:luado*
  59 :[range]luado {body}    Execute Lua function "function (line) {body} end" for
  60                         each line in the [range], with the function argument
  61                         being set to the text of each line in turn, without a
  62                         trailing <EOL>. If the value returned by the function
  63                         is a string it becomes the text of the line in the
  64                         current turn. The default for [range] is the whole
  65                         file: "1,$".                  {not in Vi}
  66
  67 Examples:
  68 >
  69         :luado return string.format("%s\t%d", line:reverse(), #line)
  70
  71         :lua require"lpeg"
  72         :lua -- balanced parenthesis grammar:
  73         :lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" }
  74         :luado if bp:match(line) then return "-->\t" .. line end
  75 <
  76
  77                                                         *:luafile*
  78 :[range]luafile {file}
  79                         Execute Lua script in {file}. {not in Vi}
  80                         The whole argument is used as a single file name.
  81
  82 Examples:
  83 >
  84         :luafile script.lua
  85         :luafile %
  86 <
  87
  88 All these commands execute a Lua chunk from either the command line (:lua and
  89 :luado) or a file (:luafile) with the given line [range]. Similarly to the Lua
  90 interpreter, each chunk has its own scope and so only global variables are
  91 shared between command calls. Lua default libraries "table", "string", "math",
  92 and "package" are available, "io" and "debug" are not, and "os" is restricted
  93 to functions "date", "clock", "time", "difftime", and "getenv". In addition,
  94 Lua "print" function has its output redirected to the Vim message area, with
  95 arguments separated by a white space instead of a tab.
  96
  97 Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim
  98 and manage buffers (|lua-buffer|) and windows (|lua-window|). However,
  99 procedures that alter buffer content, open new buffers, and change cursor
 100 position are restricted when the command is executed in the |sandbox|.
 101
 102
 103 ==============================================================================
 104 2. The vim module                                       *lua-vim*
 105
 106 Lua interfaces Vim through the "vim" module. The first and last line of the
 107 input range are stored in "vim.firstline" and "vim.lastline" respectively. The
 108 module also includes routines for buffer, window, and current line queries,
 109 Vim evaluation and command execution, and others.
 110
 111         vim.isbuffer(value)     Returns 'true' (boolean, not string) if
 112                                 "value" is a buffer userdata and 'false'
 113                                 otherwise (see |lua-buffer|).
 114
 115         vim.buffer([arg])       If "arg" is a number, returns buffer with
 116                                 number "arg" in the buffer list or, if "arg"
 117                                 is a string, returns buffer whose full or short
 118                                 name is "arg". In both cases, returns 'nil'
 119                                 (nil value, not string) if the buffer is not
 120                                 found. Otherwise, if "toboolean(arg)" is
 121                                 'true' returns the first buffer in the buffer
 122                                 list or else the current buffer.
 123
 124         vim.iswindow(value)     Returns 'true' (boolean, not string) if
 125                                 "value" is a window userdata and
 126                                 'false' otherwise (see |lua-window|).
 127
 128         vim.window([arg])       If "arg" is a number, returns window with
 129                                 number "arg" or 'nil' (nil value, not string)
 130                                 if not found. Otherwise, if "toboolean(arg)"
 131                                 is 'true' returns the first window or else the
 132                                 current window.
 133
 134         vim.command({cmd})      Executes the vim (ex-mode) command {cmd}.
 135                                 Examples: >
 136                                         :lua vim.command"set tw=60"
 137                                         :lua vim.command"normal ddp"
 138 <
 139         vim.eval({expr})        Evaluates expression {expr} (see |expression|),
 140                                 converts the result to Lua, and returns it.
 141                                 Vim strings and numbers are directly converted
 142                                 to Lua strings and numbers respectively. Vim
 143                                 lists and dictionaries are converted to Lua
 144                                 tables (lists become integer-keyed tables).
 145                                 Examples: >
 146                                         :lua tw = vim.eval"&tw"
 147                                         :lua print(vim.eval"{'a': 'one'}".a)
 148 <
 149         vim.line()              Returns the current line (without the trailing
 150                                 <EOL>), a Lua string.
 151
 152         vim.beep()              Beeps.
 153
 154         vim.open({fname})       Opens a new buffer for file {fname} and
 155                                 returns it. Note that the buffer is not set as
 156                                 current.
 157
 158
 159 ==============================================================================
 160 3. Buffer userdata                                      *lua-buffer*
 161
 162 Buffer userdata represent vim buffers. A buffer userdata "b" has the following
 163 properties and methods:
 164
 165 Properties
 166 ----------
 167         o "b()" sets "b" as the current buffer.
 168         o "#b" is the number of lines in buffer "b".
 169         o "b[k]" represents line number k: "b[k] = newline" replaces line k
 170             with string "newline" and "b[k] = nil" deletes line k.
 171         o "b.name" contains the short name of buffer "b" (read-only).
 172         o "b.fname" contains the full name of buffer "b" (read-only).
 173         o "b.number" contains the position of buffer "b" in the buffer list
 174             (read-only).
 175
 176 Methods
 177 -------
 178         o "b:insert(newline[, pos])" inserts string "newline" at (optional)
 179             position "pos" in the buffer. The default value for "pos" is
 180             "#b + 1". If "pos == 0" then "newline" becomes the first line in
 181             the buffer.
 182         o "b:next()" returns the buffer next to "b" in the buffer list.
 183         o "b:previous()" returns the buffer previous to "b" in the buffer
 184             list.
 185         o "b:isvalid()" returns 'true' (boolean) if buffer "b" corresponds to
 186             a "real" (not freed from memory) Vim buffer.
 187
 188 Examples:
 189 >
 190         :lua b = vim.buffer() -- current buffer
 191         :lua print(b.name, b.number)
 192         :lua b[1] = "first line"
 193         :lua b:insert("FIRST!", 0)
 194         :lua b[1] = nil -- delete top line
 195         :lua for i=1,3 do b:insert(math.random()) end
 196         :3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end
 197         :lua vim.open"myfile"() -- open buffer and set it as current
 198
 199         function! ListBuffers()
 200         lua << EOF
 201         local b = vim.buffer(true) -- first buffer in list
 202         while b ~= nil do
 203                 print(b.number, b.name, #b)
 204                 b = b:next()
 205         end
 206         vim.beep()
 207         EOF
 208         endfunction
 209 <
 210
 211 ==============================================================================
 212 4. Window userdata                                      *lua-window*
 213
 214 Window objects represent vim windows. A window userdata "w" has the following
 215 properties and methods:
 216
 217 Properties
 218 ----------
 219         o "w()" sets "w" as the current window.
 220         o "w.buffer" contains the buffer of window "w" (read-only).
 221         o "w.line" represents the cursor line position in window "w".
 222         o "w.col" represents the cursor column position in window "w".
 223         o "w.width" represents the width of window "w".
 224         o "w.height" represents the height of window "w".
 225
 226 Methods
 227 -------
 228         o "w:next()" returns the window next to "w".
 229         o "w:previous()" returns the window previous to "w".
 230         o "w:isvalid()" returns 'true' (boolean) if window "w" corresponds to
 231             a "real" (not freed from memory) Vim window.
 232
 233 Examples:
 234 >
 235         :lua w = vim.window() -- current window
 236         :lua print(w.buffer.name, w.line, w.col)
 237         :lua w.width = w.width + math.random(10)
 238         :lua w.height = 2 * math.random() * w.height
 239         :lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end
 240         :lua print("There are " .. n .. " windows")
 241 <
 242
 243 ==============================================================================
 244  vim:tw=78:ts=8:ft=help:norl: