diff options
Diffstat (limited to 'mnv/runtime/doc/if_lua.txt')
| -rw-r--r-- | mnv/runtime/doc/if_lua.txt | 551 |
1 files changed, 551 insertions, 0 deletions
diff --git a/mnv/runtime/doc/if_lua.txt b/mnv/runtime/doc/if_lua.txt new file mode 100644 index 0000000000..210b6a50ec --- /dev/null +++ b/mnv/runtime/doc/if_lua.txt @@ -0,0 +1,551 @@ +*if_lua.txt* For MNV version 10.0. Last change: 2026 Feb 14 + + + MNV REFERENCE MANUAL by Luis Carvalho + + +The Lua Interface to MNV *lua* *Lua* + +1. Commands |lua-commands| +2. The mnv module |lua-mnv| +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() MNV function |lua-luaeval| +10. Dynamic loading |lua-dynamic| + +{only available when MNV was compiled with the |+lua| feature} + +============================================================================== +1. Commands *lua-commands* + + *:lua* +:[range]lua {chunk} + Execute Lua chunk {chunk}. + +Examples: +> + :lua print("Hello, MNV!") + :lua local curbuf = mnv.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 MNV scripts. + +Example: +> + function! CurrentLineInfo() + lua << EOF + local linenr = mnv.window().line + local curline = mnv.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 MNV message +area, with arguments separated by a white space instead of a tab. + +Lua uses the "mnv" module (see |lua-mnv|) to issue commands to MNV +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 mnv module *lua-mnv* + +Lua interfaces MNV through the "mnv" module. The first and last line of the +input range are stored in "mnv.firstline" and "mnv.lastline" respectively. +The module also includes routines for buffer, window, and current line +queries, MNV evaluation and command execution, and others. + + mnv.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('mnv.list(t)') + :" [3.141593, v:false], 'say' is ignored +< + mnv.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('mnv.dict(t)') + :" {'1': 3.141593, '2': v:false, + :" 'say': 'hi'} +< + mnv.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('mnv.blob(s)') + :" 0z31326162.0080FEFF +< + mnv.funcref({name}) Returns a Funcref to function {name} (see + |Funcref|). It is equivalent to MNV's + function(). + + mnv.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. + + mnv.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. + + mnv.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 = mnv.list() + :lua print(type(l), mnv.type(l)) + :" list +< + mnv.command({cmds}) Executes one or more lines of Ex-mode commands + in {cmds}. + Examples: > + :lua mnv.command"set tw=60" + :lua mnv.command"normal ddp" + lua << trim END + mnv.command([[ + new Myfile.js + call search('start') + ]]) + END +< + mnv.eval({expr}) Evaluates expression {expr} (see |expression|), + converts the result to Lua, and returns it. + MNV strings and numbers are directly converted + to Lua strings and numbers respectively. MNV + lists and dictionaries are converted to Lua + userdata (see |lua-list| and |lua-dict|). + Examples: > + :lua tw = mnv.eval"&tw" + :lua print(mnv.eval"{'a': 'one'}".a) +< + mnv.line() Returns the current line (without the trailing + <EOL>), a Lua string. + + mnv.beep() Beeps. + + mnv.open({fname}) Opens a new buffer for file {fname} and + returns it. Note that the buffer is not set + as current. + + mnv.call({name} [, {args}]) + Proxy to call MNV function named {name} with + arguments {args}. Example: > + :lua print(mnv.call('has', 'timers')) +< + mnv.fn Proxy to call MNV functions. Proxy methods + are created on demand. Example: > + :lua print(mnv.fn.has('timers')) +< + mnv.lua_version The Lua version MNV was compiled with, in the + form {major}.{minor}.{patch}, e.g. "5.1.4". + + mnv.version() Returns a Lua table with the MNV version. + The table will have the following keys: + major - major MNV version. + minor - minor MNV version. + patch - latest patch included. + + *lua-mnv-variables* +The MNV editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed +from Lua conveniently and idiomatically by referencing the `mnv.*` Lua tables +described below. In this way you can easily read and modify global MNV script +variables from Lua. + +Example: > + + mnv.g.foo = 5 -- Set the g:foo MNV script variable. + print(mnv.g.foo) -- Get and print the g:foo MNV script variable. + mnv.g.foo = nil -- Delete (:unlet) the MNV script variable. + +mnv.g *mnv.g* + Global (|g:|) editor variables. + Key with no value returns `nil`. + +mnv.b *mnv.b* + Buffer-scoped (|b:|) variables for the current buffer. + Invalid or unset key returns `nil`. + +mnv.w *mnv.w* + Window-scoped (|w:|) variables for the current window. + Invalid or unset key returns `nil`. + +mnv.t *mnv.t* + Tabpage-scoped (|t:|) variables for the current tabpage. + Invalid or unset key returns `nil`. + +mnv.v *mnv.v* + |v:| variables. + Invalid or unset key returns `nil`. + +============================================================================== +3. List userdata *lua-list* + +List userdata represent mnv lists, and the interface tries to follow closely +MNV's syntax for lists. Since lists are objects, changes in list references +in Lua are reflected in MNV 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 MNV. + 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 = mnv.eval('l') -- same 'l' + :lua l:add(mnv.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 mnv dictionaries; since +dictionaries are also objects, references are kept between Lua and MNV. A +dict "d" has the following properties: + +Properties +---------- + o "#d" is the number of items in dict "d", equivalent to "len(d)" + in MNV. + 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 + MNV. + +Examples: +> + :let d = {'n':10} + :lua d = mnv.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 mnv blobs. A blob "b" has the following properties: + +Properties +---------- + o "#b" is the length of blob "b", equivalent to "len(b)" in MNV. + o "b[k]" returns the k-th item in "b"; "b" is zero-indexed, as in MNV. + 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 = mnv.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 MNV. 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 = mnv.funcref('I') + :lua i2 = mnv.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 = mnv.eval('mydict'); d.len = mnv.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 MNV |Funcref| and +can be accessed in MNV scripts. Example: +> + lua <<EOF + mnv.fn.timer_start(1000, function(timer) + print('timer callback') + end) + EOF + +============================================================================== +7. Buffer userdata *lua-buffer* + +Buffer userdata represent mnv 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) MNV buffer. + +Examples: +> + :lua b = mnv.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=mnv.lastline,mnv.firstline,-1 do b[i] = nil end + :lua mnv.open"myfile"() -- open buffer and set it as current + + function! ListBuffers() + lua << EOF + local b = mnv.buffer(true) -- first buffer in list + while b ~= nil do + print(b.number, b.name, #b) + b = b:next() + end + mnv.beep() + EOF + endfunction +< + +============================================================================== +8. Window userdata *lua-window* + +Window objects represent mnv 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) MNV window. + +Examples: +> + :lua w = mnv.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,mnv.window(true) while w~=nil do n,w = n + 1,w:next() end + :lua print("There are " .. n .. " windows") +< + +============================================================================== +9. luaeval() MNV function *lua-luaeval* *lua-eval* + +The (dual) equivalent of "mnv.eval" for passing Lua values to MNV 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 MNV 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 = mnv.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 MNV 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 MNV 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 MNV 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 MNV was compiled with. + + +============================================================================== + mnv:tw=78:ts=8:noet:ft=help:norl: |