diff options
Diffstat (limited to 'runtime/doc/lua.txt')
| -rw-r--r-- | runtime/doc/lua.txt | 193 |
1 files changed, 115 insertions, 78 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index f336ba0c36..509ed7bf2c 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -9,7 +9,7 @@ Lua engine *lua* *Lua* Type |gO| to see the table of contents. ============================================================================== -Introduction *lua-intro* +INTRODUCTION *lua-intro* The Lua 5.1 language is builtin and always available. Try this command to get an idea of what lurks beneath: > @@ -30,7 +30,7 @@ finds and loads Lua modules. The conventions are similar to VimL plugins, with some extra features. See |lua-require-example| for a walkthrough. ============================================================================== -Importing Lua modules *lua-require* +IMPORTING LUA MODULES *lua-require* *lua-package-path* Nvim automatically adjusts `package.path` and `package.cpath` according to @@ -233,7 +233,7 @@ lua/charblob.lua: > } ============================================================================== -Commands *lua-commands* +COMMANDS *lua-commands* These commands execute a Lua chunk from either the command line (:lua, :luado) or a file (:luafile) on the given line [range]. As always in Lua, each chunk @@ -456,7 +456,7 @@ management. Try this command to see available functions: > :lua print(vim.inspect(vim.loop)) -Reference: http://docs.libuv.org +Reference: https://github.com/luvit/luv/blob/master/docs.md Examples: https://github.com/luvit/luv/tree/master/examples *E5560* *lua-loop-callbacks* @@ -622,6 +622,15 @@ Node methods *lua-treesitter-node* tsnode:parent() *tsnode:parent()* Get the node's immediate parent. +tsnode:iter_children() *tsnode:iter_children()* + Iterates over all the direct children of {tsnode}, regardless of + wether they are named or not. + Returns the child node plus the eventual field name corresponding to + this child node. + +tsnode:field({name}) *tsnode:field()* + Returns a table of the nodes corresponding to the {name} field. + tsnode:child_count() *tsnode:child_count()* Get the node's number of children. @@ -747,14 +756,15 @@ Here is a list of built-in predicates : ((node1) @left (node2) @right (#eq? @left @right)) < `match?` *ts-predicate-match?* - This will match if the provived lua regex matches the text + `vim-match?` *ts-predicate-vim-match?* + This will match if the provived vim regex matches the text corresponding to a node : > ((idenfitier) @constant (#match? @constant "^[A-Z_]+$")) < Note: the `^` and `$` anchors will respectively match the start and end of the node's text. - `vim-match?` *ts-predicate-vim-match?* - This will match the same way than |match?| but using vim + `lua-match?` *ts-predicate-lua-match?* + This will match the same way than |match?| but using lua regexes. `contains?` *ts-predicate-contains?* @@ -773,6 +783,11 @@ vim.treesitter.query.add_predicate({name}, {handler}) This adds a predicate with the name {name} to be used in queries. {handler} should be a function whose signature will be : > handler(match, pattern, bufnr, predicate) +< + *vim.treesitter.query.list_predicates()* +vim.treesitter.query.list_predicates() + +This lists the currently available predicates to use in queries. Treesitter syntax highlighting (WIP) *lua-treesitter-highlight* @@ -891,11 +906,6 @@ vim.api.{func}({...}) *vim.api* Example: call the "nvim_get_current_line()" API function: > print(tostring(vim.api.nvim_get_current_line())) -vim.call({func}, {...}) *vim.call()* - Invokes |vim-function| or |user-function| {func} with arguments {...}. - See also |vim.fn|. Equivalent to: > - vim.fn[func]({...}) - vim.in_fast_event() *vim.in_fast_event()* Returns true if the code is executing as part of a "fast" event handler, where most of the API is disabled. These are low-level events @@ -1055,22 +1065,6 @@ vim.wait({time}, {callback} [, {interval}]) *vim.wait()* end < -vim.fn.{func}({...}) *vim.fn* - Invokes |vim-function| or |user-function| {func} with arguments {...}. - To call autoload functions, use the syntax: > - vim.fn['some#function']({...}) -< - Unlike vim.api.|nvim_call_function| this converts directly between Vim - objects and Lua objects. If the Vim function returns a float, it will - 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. - vim.type_idx *vim.type_idx* Type index for use in |lua-special-tbl|. Specifying one of the values from |vim.types| allows typing the empty table (it is @@ -1106,64 +1100,103 @@ vim.types *vim.types* `vim.types.dictionary` will not change or that `vim.types` table will only contain values for these three types. -============================================================================== -Vim Internal Variables *lua-vim-internal-variables* - -Built-in Vim dictionaries can be accessed and set idiomatically in Lua by each -of the following tables. - -To set a value: > - - vim.g.my_global_variable = 5 -< +------------------------------------------------------------------------------ +LUA-VIMSCRIPT BRIDGE *lua-vimscript* -To read a value: > +Nvim Lua provides an interface to Vimscript variables and functions, and +editor commands and options. - print(vim.g.my_global_variable) -< +vim.call({func}, {...}) *vim.call()* + Invokes |vim-function| or |user-function| {func} with arguments {...}. + See also |vim.fn|. + Equivalent to: > + vim.fn[func]({...}) -To delete a value: > +vim.cmd({cmd}) *vim.cmd()* + Invokes an Ex command (the ":" commands, Vimscript statements). + See also |ex-cmd-index|. + Example: > + vim.cmd('echo 42') - vim.g.my_global_variable = nil +vim.fn.{func}({...}) *vim.fn* + Invokes |vim-function| or |user-function| {func} with arguments {...}. + To call autoload functions, use the syntax: > + vim.fn['some#function']({...}) < + Unlike vim.api.|nvim_call_function| this converts directly between Vim + objects and Lua objects. If the Vim function returns a float, it will + be represented directly as a Lua number. Empty lists and dictionaries + both are represented by an empty table. -vim.g *vim.g* - Table with values from |g:| - Keys with no values set will result in `nil`. - -vim.b *vim.b* - Gets a buffer-scoped (b:) variable for the current buffer. - Keys with no values set will result in `nil`. - -vim.w *vim.w* - Gets a window-scoped (w:) variable for the current window. - Keys with no values set will result in `nil`. + Note: |v:null| values as part of the return value is represented as + |vim.NIL| special value -vim.t *vim.t* - Gets a tabpage-scoped (t:) variable for the current table. - Keys with no values set will result in `nil`. + Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only + enumerates functions that were called at least once. -vim.v *vim.v* - Gets a v: variable. - Keys with no values set will result in `nil`. + *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 Vimscript +variables from Lua. -Vim Internal Options *lua-vim-internal-options* +Example: > -Read, set and clear vim |options| in Lua by each of the following tables. + vim.g.foo = 5 -- Set the g:foo Vimscript variable. + print(vim.g.foo) -- Get and print the g:foo Vimscript variable. + vim.g.foo = nil -- Delete (:unlet) the Vimscript 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`. + +vim.env *vim.env* + Environment variables defined in the editor session. + See |expand-env| and |:let-environment| for the Vimscript behavior. + Invalid or unset key returns `nil`. + Example: > + vim.env.FOO = 'bar' + print(vim.env.TERM) +< + *lua-vim-options* +From Lua you can work with editor |options| by reading and setting items in +these Lua tables: -vim.o *vim.o* - Table with values from |options| - Invalid keys will result in an error. +vim.o *vim.o* + Get or set editor options, like |:set|. Invalid key is an error. + Example: > + vim.o.cmdheight = 4 + print(vim.o.columns) -vim.bo *vim.bo* - Gets a buffer-scoped option for the current buffer. - Invalid keys will result in an error. +vim.bo *vim.bo* + Get or set buffer-scoped |local-options|. Invalid key is an error. + Example: > + vim.bo.buflisted = true + print(vim.bo.comments) -vim.wo *vim.wo* - Gets a window-scoped option for the current window. - Invalid keys will result in an error. +vim.wo *vim.wo* + Get or set window-scoped |local-options|. Invalid key is an error. + Example: > + vim.wo.cursorcolumn = true + print(vim.wo.foldmarker) ============================================================================== @@ -1419,17 +1452,21 @@ tbl_flatten({t}) *vim.tbl_flatten()* Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua tbl_isempty({t}) *vim.tbl_isempty()* + Checks if a table is empty. + + Parameters: ~ + {t} Table to check + See also: ~ - Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua@paramt Table to check + https://github.com/premake/premake-core/blob/master/src/base/table.lua tbl_islist({t}) *vim.tbl_islist()* - Determine whether a Lua table can be treated as an array. + Tests if a Lua table can be treated as an array. - An empty table `{}` will default to being treated as an array. - Use `vim.emtpy_dict()` to create a table treated as an empty - dict. Empty tables returned by `rpcrequest()` and `vim.fn` - functions can be checked using this function whether they - represent empty API arrays and vimL lists. + Empty table `{}` is assumed to be an array, unless it was + created by |vim.empty_dict()| or returned as a dict-like |API| + or Vimscript result, for example from |rpcrequest()| or + |vim.fn|. Parameters: ~ {t} Table |