diff options
Diffstat (limited to 'runtime/doc/if_lua.txt')
| -rw-r--r-- | runtime/doc/if_lua.txt | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index 97d851a20f..911197acd4 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -327,6 +327,38 @@ Return value is also always converted. When converting, |msgpack-special-dict|s are treated specially. ============================================================================== +v:lua function calls *v:lua-call* + +The special prefix `v:lua` can be used in vimL expressions to call lua +functions which are global or nested inside global tables. The expression +`v:lua.func(arg1, arg2)` is equivalent to executing the lua code +`return func(...)` where the args have been converted to lua values. In addition +`v:lua.somemod.func(args)` will work like `return somemod.func(...)` . + +`v:lua` can also be used in function options like 'omnifunc'. As an +example, consider the following lua implementation of an omnifunc: > + + function mymod.omnifunc(findstart, base) + if findstart == 1 then + return 0 + else + return {'stuff', 'steam', 'strange things'} + end + end + vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.mymod.omnifunc') + +A limitation is that the plugin module ("mymod" in this case) must +be made available as a global. + +Note: `v:lua` without a call is not allowed in a vimL expression. Funcrefs +to lua functions cannot be created. The following are errors: > + + let g:Myvar = v:lua.myfunc + call SomeFunc(v:lua.mycallback) + let g:foo = v:lua + let g:foo = v:['lua'] + +============================================================================== Lua standard modules *lua-stdlib* The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes @@ -587,6 +619,26 @@ vim.in_fast_event() *vim.in_fast_event()* for input. When this is `false` most API functions are callable (but may be subject to other restrictions such as |textlock|). +vim.NIL *vim.NIL* + Special value used to represent NIL in msgpack-rpc and |v:null| in + vimL interaction, and similar cases. Lua `nil` cannot be used as + part of a lua table representing a Dictionary or Array, as it + is equivalent to a missing value: `{"foo", nil}` is the same as + `{"foo"}` + +vim.rpcnotify({channel}, {method}[, {args}...]) *vim.rpcnotify()* + Sends {event} to {channel} via |RPC| and returns immediately. + If {channel} is 0, the event is broadcast to all channels. + + This function also works in a fast callback |lua-loop-callbacks|. + +vim.rpcrequest({channel}, {method}[, {args}...]) *vim.rpcrequest()* + Sends a request to {channel} to invoke {method} via + |RPC| and blocks until a response is received. + + Note: NIL values as part of the return value is represented as + |vim.NIL| special value + vim.stricmp({a}, {b}) *vim.stricmp()* Compares strings case-insensitively. Returns 0, 1 or -1 if strings are equal, {a} is greater than {b} or {a} is lesser than {b}, @@ -624,6 +676,9 @@ vim.fn.{func}({...}) *vim.fn* be represented directly as a Lua number. Empty lists and dictionaries both are represented by an empty table. + Note: |v:null| values as part of the return value is represented as + |vim.NIL| special value + Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only enumerates functions that were called at least once. @@ -824,4 +879,63 @@ pesc({s}) *vim.pesc()* See also: ~ https://github.com/rxi/lume +validate({opt}) *vim.validate()* + Validates a parameter specification (types and values). + + Usage example: > + + function user.new(name, age, hobbies) + vim.validate{ + name={name, 'string'}, + age={age, 'number'}, + hobbies={hobbies, 'table'}, + } + ... + end +< + + Examples with explicit argument values (can be run directly): > + + vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} + => NOP (success) +< +> + vim.validate{arg1={1, 'table'}} + => error('arg1: expected table, got number') +< +> + vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} + => error('arg1: expected even number, got 3') +< + + Parameters: ~ + {opt} Map of parameter names to validations. Each key is + a parameter name; each value is a tuple in one of + these forms: + 1. (arg_value, type_name, optional) + • arg_value: argument value + • type_name: string type name, one of: ("table", + "t", "string", "s", "number", "n", "boolean", + "b", "function", "f", "nil", "thread", + "userdata") + • optional: (optional) boolean, if true, `nil` + is valid + + 2. (arg_value, fn, msg) + • arg_value: argument value + • fn: any function accepting one argument, + returns true if and only if the argument is + valid + • msg: (optional) error string if validation + fails + +is_callable({f}) *vim.is_callable()* + Returns true if object `f` can be called as a function. + + Parameters: ~ + {f} Any object + + Return: ~ + true if `f` is callable, else false + vim:tw=78:ts=8:ft=help:norl: |