Adding upstream version 2:9.1.0016.upstream/2%9.1.0016

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 550 insertions, 0 deletions

diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
new file mode 100644
index 0000000..e779d0a
--- /dev/null
+++ b/runtime/doc/if_lua.txt
@@ -0,0 +1,550 @@
+*if_lua.txt*    For Vim version 9.1.  Last change: 2021 Aug 06
+
+
+		  VIM REFERENCE MANUAL    by Luis Carvalho
+
+
+The Lua Interface to Vim				*lua* *Lua*
+
+1. Commands			|lua-commands|
+2. The vim module		|lua-vim|
+3. List userdata		|lua-list|
+4. Dict userdata		|lua-dict|
+5. Blob userdata		|lua-blob|
+6. Funcref userdata		|lua-funcref|
+7. Buffer userdata		|lua-buffer|
+8. Window userdata		|lua-window|
+9. luaeval() Vim function	|lua-luaeval|
+10. Dynamic loading		|lua-dynamic|
+
+{only available when Vim was compiled with the |+lua| feature}
+
+==============================================================================
+1. Commands						*lua-commands*
+
+							*:lua*
+:[range]lua {chunk}
+			Execute Lua chunk {chunk}.
+
+Examples:
+>
+	:lua print("Hello, Vim!")
+	:lua local curbuf = vim.buffer() curbuf[7] = "line #7"
+<
+
+:[range]lua << [trim] [{endmarker}]
+{script}
+{endmarker}
+			Execute Lua script {script}.
+			Note: This command doesn't work when the Lua
+			feature wasn't compiled in.  To avoid errors, see
+			|script-here|.
+
+If [endmarker] is omitted from after the "<<", a dot '.' must be used after
+{script}, like for the |:append| and |:insert| commands.  Refer to
+|:let-heredoc| for more information.
+
+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
+<
+To see what version of Lua you have: >
+	:lua print(_VERSION)
+
+If you use LuaJIT you can also use this: >
+	:lua print(jit.version)
+<
+
+							*:luado*
+:[range]luado {body}	Execute Lua function "function (line, linenr) {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>, and the current line number.
+			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,$".
+
+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}.
+			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. All Lua default libraries are available. 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.list([arg])		Returns an empty list or, if "arg" is a Lua
+				table with numeric keys 1, ..., n (a
+				"sequence"), returns a list l such that l[i] =
+				arg[i] for i = 1, ..., n (see |List|).
+				Non-numeric keys are not used to initialize
+				the list. See also |lua-eval| for conversion
+				rules. Example: >
+				    :lua t = {math.pi, false, say = 'hi'}
+				    :echo luaeval('vim.list(t)')
+				    :" [3.141593, v:false], 'say' is ignored
+<
+	vim.dict([arg])		Returns an empty dictionary or, if "arg" is a
+				Lua table, returns a dict d such that d[k] =
+				arg[k] for all string keys k in "arg" (see
+				|Dictionary|). Number keys are converted to
+				strings. Keys that are not strings are not
+				used to initialize the dictionary. See also
+				|lua-eval| for conversion rules. Example: >
+				    :lua t = {math.pi, false, say = 'hi'}
+				    :echo luaeval('vim.dict(t)')
+				    :" {'1': 3.141593, '2': v:false,
+				    :" 'say': 'hi'}
+<
+	vim.blob([arg])		Returns an empty blob or, if "arg" is a Lua
+				string, returns a blob b such that b is
+				equivalent to "arg" as a byte string.
+				Examples: >
+				    :lua s = "12ab\x00\x80\xfe\xff"
+				    :echo luaeval('vim.blob(s)')
+				    :" 0z31326162.0080FEFF
+<
+	vim.funcref({name})	Returns a Funcref to function {name} (see
+				|Funcref|). It is equivalent to Vim's
+				function().
+
+	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'
+				(nil value, not string) 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.window([arg])	If "arg" is a number, returns window with
+				number "arg" or 'nil' (nil value, not string)
+				if not found. Otherwise, if "toboolean(arg)"
+				is 'true' returns the first window or else the
+				current window.
+
+	vim.type({arg})		Returns the type of {arg}. It is equivalent to
+				Lua's "type" function, but returns "list",
+				"dict", "funcref", "buffer", or "window" if
+				{arg} is a list, dictionary, funcref, buffer,
+				or window, respectively. Examples: >
+					:lua l = vim.list()
+					:lua print(type(l), vim.type(l))
+					:" list
+<
+	vim.command({cmds})	Executes one or more lines of Ex-mode commands
+				in {cmds}.
+				Examples: >
+					:lua vim.command"set tw=60"
+					:lua vim.command"normal ddp"
+					lua << trim END
+					  vim.command([[
+					      new Myfile.js
+					      call search('start')
+					  ]])
+					END
+<
+	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
+				userdata (see |lua-list| and |lua-dict|).
+				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.
+
+	vim.call({name} [, {args}])
+				Proxy to call Vim function named {name} with
+				arguments {args}.  Example: >
+					:lua print(vim.call('has', 'timers'))
+<
+	vim.fn			Proxy to call Vim functions. Proxy methods are
+				created on demand.  Example: >
+					:lua print(vim.fn.has('timers'))
+<
+	vim.lua_version		The Lua version Vim was compiled with, in the
+				form {major}.{minor}.{patch}, e.g. "5.1.4".
+
+	vim.version()		Returns a Lua table with the Vim version.
+				The table will have the following keys:
+					major - major Vim version.
+					minor - minor Vim version.
+					patch - latest patch included.
+
+                                                        *lua-vim-variables*
+The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
+from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
+described below. In this way you can easily read and modify global Vim script
+variables from Lua.
+
+Example: >
+
+    vim.g.foo = 5     -- Set the g:foo Vim script variable.
+    print(vim.g.foo)  -- Get and print the g:foo Vim script variable.
+    vim.g.foo = nil   -- Delete (:unlet) the Vim script variable.
+
+vim.g                                                   *vim.g*
+        Global (|g:|) editor variables.
+        Key with no value returns `nil`.
+
+vim.b                                                   *vim.b*
+        Buffer-scoped (|b:|) variables for the current buffer.
+        Invalid or unset key returns `nil`.
+
+vim.w                                                   *vim.w*
+        Window-scoped (|w:|) variables for the current window.
+        Invalid or unset key returns `nil`.
+
+vim.t                                                   *vim.t*
+        Tabpage-scoped (|t:|) variables for the current tabpage.
+        Invalid or unset key returns `nil`.
+
+vim.v                                                   *vim.v*
+        |v:| variables.
+        Invalid or unset key returns `nil`.
+
+==============================================================================
+3. List userdata					*lua-list*
+
+List userdata represent vim lists, and the interface tries to follow closely
+Vim's syntax for lists. Since lists are objects, changes in list references in
+Lua are reflected in Vim and vice-versa. A list "l" has the following
+properties and methods:
+
+NOTE: In patch 8.2.1066 array indexes were changed from zero-based to
+one-based.  You can check with: >
+	    if has("patch-8.2.1066")
+
+Properties
+----------
+	o "#l" is the number of items in list "l", equivalent to "len(l)"
+	    in Vim.
+	o "l[k]" returns the k-th item in "l"; "l" is one-indexed, as in Lua.
+	    To modify the k-th item, simply do "l[k] = newitem"; in
+	    particular, "l[k] = nil" removes the k-th item from "l". Item can
+	    be added to the end of the list by "l[#l + 1] = newitem"
+	o "l()" returns an iterator for "l".
+	o "table.insert(l, newitem)" inserts an item at the end of the list.
+	    (only Lua 5.3 and later)
+	o "table.insert(l, position, newitem)" inserts an item at the
+	    specified position. "position" is one-indexed.  (only Lua 5.3 and
+	    later)
+	o "table.remove(l, position)" removes an item at the specified
+	    position. "position" is one-indexed.
+
+
+Methods
+-------
+	o "l:add(item)" appends "item" to the end of "l".
+	o "l:insert(item[, pos])" inserts "item" at (optional)
+	    position "pos" in the list. The default value for "pos" is 0.
+
+Examples:
+>
+	:let l = [1, 'item']
+	:lua l = vim.eval('l') -- same 'l'
+	:lua l:add(vim.list())
+	:lua l[1] = math.pi
+	:echo l[0] " 3.141593
+	:lua l[1] = nil -- remove first item
+	:lua l:insert(true, 1)
+	:lua print(l, #l, l[1], l[2])
+	:lua l[#l + 1] = 'value'
+	:lua table.insert(l, 100)
+	:lua table.insert(l, 2, 200)
+	:lua table.remove(l, 1)
+	:lua for item in l() do print(item) end
+
+==============================================================================
+4. Dict userdata					*lua-dict*
+
+Similarly to list userdata, dict userdata represent vim dictionaries; since
+dictionaries are also objects, references are kept between Lua and Vim. A dict
+"d" has the following properties:
+
+Properties
+----------
+	o "#d" is the number of items in dict "d", equivalent to "len(d)"
+	    in Vim.
+	o "d.key" or "d['key']" returns the value at entry "key" in "d".
+	    To modify the entry at this key, simply do "d.key = newvalue"; in
+	    particular, "d.key = nil" removes the entry from "d".
+	o "d()" returns an iterator for "d" and is equivalent to "items(d)" in
+	    Vim.
+
+Examples:
+>
+	:let d = {'n':10}
+	:lua d = vim.eval('d') -- same 'd'
+	:lua print(d, d.n, #d)
+	:let d.self = d
+	:lua for k, v in d() do print(d, k, v) end
+	:lua d.x = math.pi
+	:lua d.self = nil -- remove entry
+	:echo d
+<
+
+==============================================================================
+5. Blob userdata					*lua-blob*
+
+Blob userdata represent vim blobs. A blob "b" has the following properties:
+
+Properties
+----------
+	o "#b" is the length of blob "b", equivalent to "len(b)" in Vim.
+	o "b[k]" returns the k-th item in "b"; "b" is zero-indexed, as in Vim.
+	    To modify the k-th item, simply do "b[k] = number"; in particular,
+	    "b[#b] = number" can append a byte to tail.
+
+Methods
+-------
+	o "b:add(bytes)" appends "bytes" to the end of "b".
+
+Examples:
+>
+	:let b = 0z001122
+	:lua b = vim.eval('b') -- same 'b'
+	:lua print(b, b[0], #b)
+	:lua b[1] = 32
+	:lua b[#b] = 0x33 -- append a byte to tail
+	:lua b:add("\x80\x81\xfe\xff")
+	:echo b
+<
+
+==============================================================================
+6. Funcref userdata					*lua-funcref*
+
+Funcref userdata represent funcref variables in Vim. Funcrefs that were
+defined with a "dict" attribute need to be obtained as a dictionary key
+in order to have "self" properly assigned to the dictionary (see examples
+below.) A funcref "f" has the following properties:
+
+Properties
+----------
+	o "#f" is the name of the function referenced by "f"
+	o "f(...)" calls the function referenced by "f" (with arguments)
+
+Examples:
+>
+	:function I(x)
+	:  return a:x
+	:  endfunction
+	:let R = function('I')
+	:lua i1 = vim.funcref('I')
+	:lua i2 = vim.eval('R')
+	:lua print(#i1, #i2) -- both 'I'
+	:lua print(i1, i2, #i2(i1) == #i1(i2))
+	:function Mylen() dict
+	:  return len(self.data)
+	:  endfunction
+	:let mydict = {'data': [0, 1, 2, 3]}
+	:lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen')
+	:echo mydict.len()
+	:lua l = d.len -- assign d as 'self'
+	:lua print(l())
+<
+Lua functions and closures are automatically converted to a Vim |Funcref| and
+can be accessed in Vim scripts.  Example:
+>
+	lua <<EOF
+	vim.fn.timer_start(1000, function(timer)
+	    print('timer callback')
+	end)
+	EOF
+
+==============================================================================
+7. 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 (optional)
+	    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' (boolean) 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
+<
+
+==============================================================================
+8. 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' (boolean) 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")
+<
+
+==============================================================================
+9. luaeval() Vim function				*lua-luaeval* *lua-eval*
+
+The (dual) equivalent of "vim.eval" for passing Lua values to Vim is
+"luaeval". "luaeval" takes an expression string and an optional argument and
+returns the result of the expression. It is semantically equivalent in Lua to:
+>
+	local chunkheader = "local _A = select(1, ...) return "
+	function luaeval (expstr, arg)
+	    local chunk = assert(loadstring(chunkheader .. expstr, "luaeval"))
+	    return chunk(arg) -- return typval
+	end
+<
+Note that "_A" receives the argument to "luaeval". Lua numbers, strings, and
+list, dict, blob, and funcref userdata are converted to their Vim respective
+types, while Lua booleans are converted to numbers. An error is thrown if
+conversion of any of the remaining Lua types, including userdata other than
+lists, dicts, blobs, and funcrefs, is attempted.
+
+Examples: >
+
+	:echo luaeval('math.pi')
+	:lua a = vim.list():add('newlist')
+	:let a = luaeval('a')
+	:echo a[0] " 'newlist'
+	:function Rand(x,y) " random uniform between x and y
+	:  return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y})
+	:  endfunction
+	:echo Rand(1,10)
+
+
+==============================================================================
+10. Dynamic loading				    *lua-dynamic*
+
+On MS-Windows and Unix the Lua library can be loaded dynamically.  The
+|:version| output then includes |+lua/dyn|.
+
+This means that Vim will search for the Lua DLL or shared library file only
+when needed.  When you don't use the Lua interface you don't need it, thus
+you can use Vim without this file.
+
+
+MS-Windows ~
+
+To use the Lua interface the Lua DLL must be in your search path.  In a
+console window type "path" to see what directories are used.  The 'luadll'
+option can be also used to specify the Lua DLL.  The version of the DLL must
+match the Lua version Vim was compiled with.
+
+
+Unix ~
+
+The 'luadll' option can be used to specify the Lua shared library file instead
+of DYNAMIC_LUA_DLL file what was specified at compile time.  The version of
+the shared library must match the Lua version Vim was compiled with.
+
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: