Added Lua interfae. (Luis Carvalho)

1 files changed, 239 insertions, 0 deletions

diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
new file mode 100644
index 000000000..ff3c0f26f
--- /dev/null
+++ b/runtime/doc/if_lua.txt
@@ -0,0 +1,239 @@
+*if_lua.txt*    For Vim version 7.3a.  Last change: 2008 Aug 31
+
+
+		  VIM REFERENCE MANUAL    by Luis Carvalho
+
+
+The Lua Interface to Vim				*lua* *Lua*
+
+1. Commands			|lua-commands|
+2. The vim module		|lua-vim|
+3. Buffer userdata		|lua-buffer|
+4. Window userdata		|lua-window|
+
+{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)${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>. 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. Lua default libraries$table$,$string$,$math$,
+and$package$are available,$io$and$debug$are not, and$os$is restricted to
+functions$date$,$clock$,$time$,$difftime$, and$getenv$. 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.isbuffer(value)$	Returns#true#if$value$is a buffer userdata and
+				$false$otherwise (see|lua-buffer|).
+
+	$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#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.iswindow(value)$	Returns#true#if$value$is a window userdata and
+				$false$otherwise (see|lua-window|).
+
+	$vim.window($[arg]$)$	If$arg$is a number, returns window with number
+				$arg$or#nil#if not found. Otherwise, if
+				$toboolean(arg)$is#true#returns the first
+				window or else the current window.
+
+	$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
+				tables (lists become integer-keyed tables).
+				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. 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 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#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
+<
+
+==============================================================================
+4. 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#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")
+<
+
+==============================================================================
+ vim:tw=78:ts=8:ft=help:norl: