@@ -10,9 +10,10 @@ The Lua Interface to Vim *lua* *Lua*
10102. The vim module | lua-vim |
11113. List userdata | lua-list |
12124. Dict userdata | lua-dict |
13- 5. Buffer userdata | lua-buffer |
14- 6. Window userdata | lua-window |
15- 7. The luaeval function | lua-luaeval |
13+ 5. Funcref userdata | lua-funcref |
14+ 6. Buffer userdata | lua-buffer |
15+ 7. Window userdata | lua-window |
16+ 8. The luaeval function | lua-luaeval |
1617
1718{Vi does not have any of these commands}
1819
@@ -110,9 +111,31 @@ input range are stored in "vim.firstline" and "vim.lastline" respectively. The
110111module also includes routines for buffer, window, and current line queries,
111112Vim evaluation and command execution, and others.
112113
113- vim.list() Returns an empty list (see | List | ).
114-
115- vim.dict() Returns an empty dictionary (see | Dictionary | ).
114+ vim.list([arg] ) Returns an empty list or, if "arg" is a Lua
115+ table with numeric keys 1, ..., n (a
116+ "sequence"), returns a list l such that l[i] =
117+ arg[i] for i = 1, ..., n (see | List | ).
118+ Non-numeric keys are not used to initialize
119+ the list. See also | lua-eval | for conversion
120+ rules. Example: >
121+ :lua t = {math.pi, false, say = 'hi'}
122+ :echo luaeval('vim.list(t)')
123+ :" [3.141593, 0], 'say' is ignored
124+ <
125+ vim.dict([arg] ) Returns an empty dictionary or, if "arg" is a
126+ Lua table, returns a dict d such that d[k] =
127+ arg[k] for all string keys k in "arg" (see
128+ | Dictionary | ). Number keys are converted to
129+ strings. Keys that are not strings are not
130+ used to initialize the dictionary. See also
131+ | lua-eval | for conversion rules. Example: >
132+ :lua t = {math.pi, false, say = 'hi'}
133+ :echo luaeval('vim.dict(t)')
134+ :" {'say': 'hi'}, numeric keys ignored
135+ <
136+ vim.funcref({name} ) Returns a Funcref to function {name} (see
137+ | Funcref | ). It is equivalent to Vim's
138+ "function".
116139
117140 vim.buffer([arg] ) If "arg" is a number, returns buffer with
118141 number "arg" in the buffer list or, if "arg"
@@ -131,9 +154,9 @@ Vim evaluation and command execution, and others.
131154
132155 vim.type({arg} ) Returns the type of {arg} . It is equivalent to
133156 Lua's "type" function, but returns "list",
134- "dict", "buffer", or "window" if {arg} is a
135- list, dictionary, buffer, or window ,
136- respectively. Examples: >
157+ "dict", "funcref", " buffer", or "window" if
158+ {arg} is a list, dictionary, funcref, buffer ,
159+ or window, respectively. Examples: >
137160 :lua l = vim.list()
138161 :lua print(type(l), vim.type(l))
139162 :" userdata list
@@ -229,7 +252,40 @@ Examples:
229252<
230253
231254==============================================================================
232- 5. Buffer userdata *lua-buffer*
255+ 5. Funcref userdata *lua-funcref*
256+
257+ Funcref userdata represent funcref variables in Vim. Funcrefs that were
258+ defined with a "dict" attribute need to be obtained as a dictionary key
259+ in order to have "self" properly assigned to the dictionary (see examples
260+ below.) A funcref "f" has the following properties:
261+
262+ Properties
263+ ----------
264+ o "#f" is the name of the function referenced by "f"
265+ o "f(...)" calls the function referenced by "f" (with arguments)
266+
267+ Examples:
268+ >
269+ :function I(x)
270+ : return a:x
271+ : endfunction
272+ :let R = function('I')
273+ :lua i1 = vim.funcref('I')
274+ :lua i2 = vim.eval('R')
275+ :lua print(#i1, #i2) -- both 'I'
276+ :lua print(i1, i2, #i2(i1) == #i1(i2))
277+ :function Mylen() dict
278+ : return len(self.data)
279+ : endfunction
280+ :let mydict = {'data': [0, 1, 2, 3]}
281+ :lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen')
282+ :echo mydict.len()
283+ :lua l = d.len -- assign d as 'self'
284+ :lua print(l())
285+ <
286+
287+ ==============================================================================
288+ 6. Buffer userdata *lua-buffer*
233289
234290Buffer userdata represent vim buffers. A buffer userdata "b" has the following
235291properties and methods:
@@ -281,7 +337,7 @@ Examples:
281337<
282338
283339==============================================================================
284- 6 . Window userdata *lua-window*
340+ 7 . Window userdata *lua-window*
285341
286342Window objects represent vim windows. A window userdata "w" has the following
287343properties and methods:
@@ -313,7 +369,7 @@ Examples:
313369<
314370
315371==============================================================================
316- 7 . The luaeval function *lua-luaeval* *lua-eval*
372+ 8 . The luaeval function *lua-luaeval* *lua-eval*
317373
318374The (dual) equivalent of "vim.eval" for passing Lua values to Vim is
319375"luaeval". "luaeval" takes an expression string and an optional argument and
@@ -325,7 +381,13 @@ returns the result of the expression. It is semantically equivalent in Lua to:
325381 return chunk(arg) -- return typval
326382 end
327383<
328- Note that "_A" receives the argument to "luaeval". Examples: >
384+ Note that "_A" receives the argument to "luaeval". Lua numbers, strings, and
385+ list, dict, and funcref userdata are converted to their Vim respective types,
386+ while Lua booleans are converted to numbers. An error is thrown if conversion
387+ of any of the remaining Lua types, including userdata other than lists, dicts,
388+ and funcrefs, is attempted.
389+
390+ Examples: >
329391
330392 :echo luaeval('math.pi')
331393 :lua a = vim.list():add('newlist')
0 commit comments