Mercurial > vim

comparison runtime/doc/if_lua.txt @ 2373:f149bb1cf5be vim73

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Make it possible to load Lua dynamically on Unix. (Luis Carvalho)
author Bram Moolenaar <bram@vim.org>
date Thu, 22 Jul 2010 21:32:16 +0200
parents 12b829477c60
children f766a1c87f69
comparison
equal deleted inserted replaced
2372:a42d19b78c93 2373:f149bb1cf5be
1 *if_lua.txt* For Vim version 7.3b. Last change: 2008 Aug 31 1 *if_lua.txt* For Vim version 7.3b. Last change: 2010 Jul 22
2 2
3 3
4 VIM REFERENCE MANUAL by Luis Carvalho 4 VIM REFERENCE MANUAL by Luis Carvalho
5 5
6 6
54 EOF 54 EOF
55 endfunction 55 endfunction
56 < 56 <
57 57
58 *:luado* 58 *:luado*
59 :[range]luado {body} Execute Lua function$function (line)${body}$end$ for 59 :[range]luado {body} Execute Lua function "function (line) {body} end" for
60 each line in the [range], with the function argument 60 each line in the [range], with the function argument
61 being set to the text of each line in turn, without a 61 being set to the text of each line in turn, without a
62 trailing <EOL>. If the value returned by the function 62 trailing <EOL>. If the value returned by the function
63 is a string it becomes the text of the line in the 63 is a string it becomes the text of the line in the
64 current turn. The default for [range] is the whole 64 current turn. The default for [range] is the whole
65 file: "1,$". {not in Vi} 65 file: "1,$". {not in Vi}
66 66
67 Examples: 67 Examples:
68 > 68 >
69 :luado return string.format("%s\t%d", line:reverse(), #line) 69 :luado return string.format("%s\t%d", line:reverse(), #line)
70 70
86 < 86 <
87 87
88 All these commands execute a Lua chunk from either the command line (:lua and 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 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 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$, 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 92 and "package" are available, "io" and "debug" are not, and "os" is restricted
93 functions$date$,$clock$,$time$,$difftime$, and$getenv$. In addition, 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 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. 95 arguments separated by a white space instead of a tab.
96 96
97 Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim 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, 98 and manage buffers (|lua-buffer|) and windows (|lua-window|). However,
99 procedures that alter buffer content, open new buffers, and change cursor 99 procedures that alter buffer content, open new buffers, and change cursor
102 102
103 ============================================================================== 103 ==============================================================================
104 2. The vim module *lua-vim* 104 2. The vim module *lua-vim*
105 105
106 Lua interfaces Vim through the "vim" module. The first and last line of the 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 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, 108 module also includes routines for buffer, window, and current line queries,
109 Vim evaluation and command execution, and others. 109 Vim evaluation and command execution, and others.
110 110
111 $vim.isbuffer(value)$ Returns#true#if$value$is a buffer userdata and 111 vim.isbuffer(value) Returns 'true' (boolean, not string) if
112 $false$otherwise (see |lua-buffer|). 112 "value" is a buffer userdata and 'false'
113 113 otherwise (see |lua-buffer|).
114 $vim.buffer($[arg]$)$ If$arg$is a number, returns buffer with number 114
115 $arg$in the buffer list or, if$arg$is 115 vim.buffer([arg]) If "arg" is a number, returns buffer with
116 a string, returns buffer whose full or short 116 number "arg" in the buffer list or, if "arg"
117 name is$arg$. In both cases, returns#nil#if 117 is a string, returns buffer whose full or short
118 the buffer is not found. Otherwise, if 118 name is "arg". In both cases, returns 'nil'
119 $toboolean(arg)$is#true#returns the first 119 (nil value, not string) if the buffer is not
120 buffer in the buffer list or else the current 120 found. Otherwise, if "toboolean(arg)" is
121 buffer. 121 'true' returns the first buffer in the buffer
122 122 list or else the current buffer.
123 $vim.iswindow(value)$ Returns#true#if$value$is a window userdata and 123
124 $false$otherwise (see |lua-window|). 124 vim.iswindow(value) Returns 'true' (boolean, not string) if
125 125 "value" is a window userdata and
126 $vim.window($[arg]$)$ If$arg$is a number, returns window with number 126 'false' otherwise (see |lua-window|).
127 $arg$or#nil#if not found. Otherwise, if 127
128 $toboolean(arg)$is#true#returns the first 128 vim.window([arg]) If "arg" is a number, returns window with
129 window or else the current window. 129 number "arg" or 'nil' (nil value, not string)
130 130 if not found. Otherwise, if "toboolean(arg)"
131 $vim.command(${cmd}$)$ Executes the vim (ex-mode) command {cmd}. 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}.
132 Examples: > 135 Examples: >
133 :lua vim.command"set tw=60" 136 :lua vim.command"set tw=60"
134 :lua vim.command"normal ddp" 137 :lua vim.command"normal ddp"
135 < 138 <
136 $vim.eval(${expr}$)$ Evaluates expression {expr} (see |expression|), 139 vim.eval({expr}) Evaluates expression {expr} (see |expression|),
137 converts the result to Lua, and returns it. 140 converts the result to Lua, and returns it.
138 Vim strings and numbers are directly converted 141 Vim strings and numbers are directly converted
139 to Lua strings and numbers respectively. Vim 142 to Lua strings and numbers respectively. Vim
140 lists and dictionaries are converted to Lua 143 lists and dictionaries are converted to Lua
141 tables (lists become integer-keyed tables). 144 tables (lists become integer-keyed tables).
142 Examples: > 145 Examples: >
143 :lua tw = vim.eval"&tw" 146 :lua tw = vim.eval"&tw"
144 :lua print(vim.eval"{'a': 'one'}".a) 147 :lua print(vim.eval"{'a': 'one'}".a)
145 < 148 <
146 $vim.line()$ Returns the current line (without the trailing 149 vim.line() Returns the current line (without the trailing
147 <EOL>), a Lua string. 150 <EOL>), a Lua string.
148 151
149 $vim.beep()$ Beeps. 152 vim.beep() Beeps.
150 153
151 $vim.open(${fname}$)$ Opens a new buffer for file {fname} and 154 vim.open({fname}) Opens a new buffer for file {fname} and
152 returns it. Note that the buffer is not set as 155 returns it. Note that the buffer is not set as
153 current. 156 current.
154 157
155 158
156 ============================================================================== 159 ==============================================================================
157 3. Buffer userdata *lua-buffer* 160 3. Buffer userdata *lua-buffer*
158 161
159 Buffer userdata represent vim buffers. A buffer userdata$b$has the following 162 Buffer userdata represent vim buffers. A buffer userdata "b" has the following
160 properties and methods: 163 properties and methods:
161 164
162 Properties 165 Properties
163 ---------- 166 ----------
164 #o#$b()$sets$b$as the current buffer. 167 o "b()" sets "b" as the current buffer.
165 #o#$#b$is the number of lines in buffer$b$. 168 o "#b" is the number of lines in buffer "b".
166 #o#$b[k]$represents line number$k$:$b[k] = newline$replaces line$k$ 169 o "b[k]" represents line number k: "b[k] = newline" replaces line k
167 with string$newline$and$b[k] =$#nil#deletes line$k$. 170 with string "newline" and "b[k] = nil" deletes line k.
168 #o#$b.name$contains the short name of buffer$b$(read-only). 171 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). 172 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 173 o "b.number" contains the position of buffer "b" in the buffer list
171 (read-only). 174 (read-only).
172 175
173 Methods 176 Methods
174 ------- 177 -------
175 #o#$b:insert(newline$[, pos]$)$inserts string$newline$at position$pos$ 178 o "b:insert(newline[, pos])" inserts string "newline" at (optional)
176 in the buffer. The default value for$pos$is$#b + 1$. If$pos == 0$ 179 position "pos" in the buffer. The default value for "pos" is
177 then$newline$becomes the first line in the buffer. 180 "#b + 1". If "pos == 0" then "newline" becomes the first line in
178 #o#$b:next()$returns the buffer next to$b$in the buffer list. 181 the buffer.
179 #o#$b:previous()$returns the buffer previous to$b$in the buffer list. 182 o "b:next()" returns the buffer next to "b" in the buffer list.
180 #o#$b:isvalid()$returns#true#if buffer$b$corresponds to a "real" (not 183 o "b:previous()" returns the buffer previous to "b" in the buffer
181 freed from memory) Vim buffer. 184 list.
185 o "b:isvalid()" returns 'true' (boolean) if buffer "b" corresponds to
186 a "real" (not freed from memory) Vim buffer.
182 187
183 Examples: 188 Examples:
184 > 189 >
185 :lua b = vim.buffer() -- current buffer 190 :lua b = vim.buffer() -- current buffer
186 :lua print(b.name, b.number) 191 :lua print(b.name, b.number)
204 < 209 <
205 210
206 ============================================================================== 211 ==============================================================================
207 4. Window userdata *lua-window* 212 4. Window userdata *lua-window*
208 213
209 Window objects represent vim windows. A window userdata$w$has the following 214 Window objects represent vim windows. A window userdata "w" has the following
210 properties and methods: 215 properties and methods:
211 216
212 Properties 217 Properties
213 ---------- 218 ----------
214 #o#$w()$sets$w$as the current window. 219 o "w()" sets "w" as the current window.
215 #o#$w.buffer$contains the buffer of window$w$(read-only). 220 o "w.buffer" contains the buffer of window "w" (read-only).
216 #o#$w.line$represents the cursor line position in window$w$. 221 o "w.line" represents the cursor line position in window "w".
217 #o#$w.col$represents the cursor column position in window$w$. 222 o "w.col" represents the cursor column position in window "w".
218 #o#$w.width$represents the width of window$w$. 223 o "w.width" represents the width of window "w".
219 #o#$w.height$represents the height of window$w$. 224 o "w.height" represents the height of window "w".
220 225
221 Methods 226 Methods
222 ------- 227 -------
223 #o#$w:next()$returns the window next to$w$. 228 o "w:next()" returns the window next to "w".
224 #o#$w:previous()$returns the window previous to$w$. 229 o "w:previous()" returns the window previous to "w".
225 #o#$w:isvalid()$returns#true#if window$w$corresponds to a "real" (not 230 o "w:isvalid()" returns 'true' (boolean) if window "w" corresponds to
226 freed from memory) Vim window. 231 a "real" (not freed from memory) Vim window.
227 232
228 Examples: 233 Examples:
229 > 234 >
230 :lua w = vim.window() -- current window 235 :lua w = vim.window() -- current window
231 :lua print(w.buffer.name, w.line, w.col) 236 :lua print(w.buffer.name, w.line, w.col)