runtime/doc/if_lua.txt

   1 *if_lua.txt*    For Vim version 7.2.  Last change: 2008 Aug 31
   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 to
  93 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#if$value$is a buffer userdata and
 112                                 $false$otherwise (see|lua-buffer|).
 113
 114         $vim.buffer($[arg]$)$   If$arg$is a number, returns buffer with number
 115                                 $arg$in the buffer list or, if$arg$is
 116                                 a string, returns buffer whose full or short
 117                                 name is$arg$. In both cases, returns#nil#if
 118                                 the buffer is not found. Otherwise, if
 119                                 $toboolean(arg)$is#true#returns the first
 120                                 buffer in the buffer list or else the current
 121                                 buffer.
 122
 123         $vim.iswindow(value)$   Returns#true#if$value$is a window userdata and
 124                                 $false$otherwise (see|lua-window|).
 125
 126         $vim.window($[arg]$)$   If$arg$is a number, returns window with number
 127                                 $arg$or#nil#if not found. Otherwise, if
 128                                 $toboolean(arg)$is#true#returns the first
 129                                 window or else the current window.
 130
 131         $vim.command(${cmd}$)$  Executes the vim (ex-mode) command {cmd}.
 132                                 Examples: >
 133                                         :lua vim.command"set tw=60"
 134                                         :lua vim.command"normal ddp"
 135 <
 136         $vim.eval(${expr}$)$    Evaluates expression {expr} (see|expression|),
 137                                 converts the result to Lua, and returns it.
 138                                 Vim strings and numbers are directly converted
 139                                 to Lua strings and numbers respectively. Vim
 140                                 lists and dictionaries are converted to Lua
 141                                 tables (lists become integer-keyed tables).
 142                                 Examples: >
 143                                         :lua tw = vim.eval"&tw"
 144                                         :lua print(vim.eval"{'a': 'one'}".a)
 145 <
 146         $vim.line()$            Returns the current line (without the trailing
 147                                 <EOL>), a Lua string.
 148
 149         $vim.beep()$            Beeps.
 150
 151         $vim.open(${fname}$)$   Opens a new buffer for file {fname} and
 152                                 returns it. Note that the buffer is not set as
 153                                 current.
 154
 155
 156 ==============================================================================
 157 3. Buffer userdata                                      *lua-buffer*
 158
 159 Buffer userdata represent vim buffers. A buffer userdata$b$has the following
 160 properties and methods:
 161
 162 Properties
 163 ----------
 164         #o#$b()$sets$b$as the current buffer.
 165         #o#$#b$is the number of lines in buffer$b$.
 166         #o#$b[k]$represents line number$k$:$b[k] = newline$replaces line$k$
 167             with string$newline$and$b[k] =$#nil#deletes line$k$.
 168         #o#$b.name$contains the short name of buffer$b$(read-only).
 169         #o#$b.fname$contains the full name of buffer$b$(read-only).
 170         #o#$b.number$contains the position of buffer$b$in the buffer list
 171             (read-only).
 172
 173 Methods
 174 -------
 175         #o#$b:insert(newline$[, pos]$)$inserts string$newline$at position$pos$
 176             in the buffer. The default value for$pos$is$#b + 1$. If$pos == 0$
 177             then$newline$becomes the first line in the buffer.
 178         #o#$b:next()$returns the buffer next to$b$in the buffer list.
 179         #o#$b:previous()$returns the buffer previous to$b$in the buffer list.
 180         #o#$b:isvalid()$returns#true#if buffer$b$corresponds to a "real" (not
 181             freed from memory) Vim buffer.
 182
 183 Examples:
 184 >
 185         :lua b = vim.buffer() -- current buffer
 186         :lua print(b.name, b.number)
 187         :lua b[1] = "first line"
 188         :lua b:insert("FIRST!", 0)
 189         :lua b[1] = nil -- delete top line
 190         :lua for i=1,3 do b:insert(math.random()) end
 191         :3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end
 192         :lua vim.open"myfile"() -- open buffer and set it as current
 193
 194         function! ListBuffers()
 195         lua << EOF
 196         local b = vim.buffer(true) -- first buffer in list
 197         while b ~= nil do
 198                 print(b.number, b.name, #b)
 199                 b = b:next()
 200         end
 201         vim.beep()
 202         EOF
 203         endfunction
 204 <
 205
 206 ==============================================================================
 207 4. Window userdata                                      *lua-window*
 208
 209 Window objects represent vim windows. A window userdata$w$has the following
 210 properties and methods:
 211
 212 Properties
 213 ----------
 214         #o#$w()$sets$w$as the current window.
 215         #o#$w.buffer$contains the buffer of window$w$(read-only).
 216         #o#$w.line$represents the cursor line position in window$w$.
 217         #o#$w.col$represents the cursor column position in window$w$.
 218         #o#$w.width$represents the width of window$w$.
 219         #o#$w.height$represents the height of window$w$.
 220
 221 Methods
 222 -------
 223         #o#$w:next()$returns the window next to$w$.
 224         #o#$w:previous()$returns the window previous to$w$.
 225         #o#$w:isvalid()$returns#true#if window$w$corresponds to a "real" (not
 226             freed from memory) Vim window.
 227
 228 Examples:
 229 >
 230         :lua w = vim.window() -- current window
 231         :lua print(w.buffer.name, w.line, w.col)
 232         :lua w.width = w.width + math.random(10)
 233         :lua w.height = 2 * math.random() * w.height
 234         :lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end
 235         :lua print("There are " .. n .. " windows")
 236 <
 237
 238 ==============================================================================
 239  vim:tw=78:ts=8:ft=help:norl: