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
7The Lua Interface to Vim				*lua* *Lua*
8
91. Commands			|lua-commands|
102. The vim module		|lua-vim|
113. Buffer userdata		|lua-buffer|
124. Window userdata		|lua-window|
13
14{Vi does not have any of these commands}
15
16The Lua interface is available only when Vim was compiled with the
17|+lua| feature.
18
19==============================================================================
201. Commands						*lua-commands*
21
22							*:lua*
23:[range]lua {chunk}
24			Execute Lua chunk {chunk}.    {not in Vi}
25
26Examples:
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
41omitted from after the "<<", a dot '.' must be used after {script}, like
42for the |:append| and |:insert| commands.
43This form of the |:lua| command is mainly useful for including Lua code
44in Vim scripts.
45
46Example:
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
67Examples:
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
82Examples:
83>
84	:luafile script.lua
85	:luafile %
86<
87
88All 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
90interpreter, each chunk has its own scope and so only global variables are
91shared between command calls. Lua default libraries "table", "string", "math",
92and "package" are available, "io" and "debug" are not, and "os" is restricted
93to functions "date", "clock", "time", "difftime", and "getenv". In addition,
94Lua "print" function has its output redirected to the Vim message area, with
95arguments separated by a white space instead of a tab.
96
97Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim
98and manage buffers (|lua-buffer|) and windows (|lua-window|). However,
99procedures that alter buffer content, open new buffers, and change cursor
100position are restricted when the command is executed in the |sandbox|.
101
102
103==============================================================================
1042. The vim module					*lua-vim*
105
106Lua interfaces Vim through the "vim" module. The first and last line of the
107input range are stored in "vim.firstline" and "vim.lastline" respectively. The
108module also includes routines for buffer, window, and current line queries,
109Vim 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==============================================================================
1603. Buffer userdata					*lua-buffer*
161
162Buffer userdata represent vim buffers. A buffer userdata "b" has the following
163properties and methods:
164
165Properties
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
176Methods
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
188Examples:
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==============================================================================
2124. Window userdata					*lua-window*
213
214Window objects represent vim windows. A window userdata "w" has the following
215properties and methods:
216
217Properties
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
226Methods
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
233Examples:
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:
245