diff options
Diffstat (limited to 'runtime/doc/lua.txt')
| -rw-r--r-- | runtime/doc/lua.txt | 175 |
1 files changed, 154 insertions, 21 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 5a49d36503..60c7a60d25 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -95,6 +95,66 @@ Note: plugins using shell which will not work with paths containing semicolons it is better to not have them in 'runtimepath' at all. +============================================================================== +Lua Syntax Information *lua-syntax-help* + +While Lua has a simple syntax, there are a few things to understand, +particularly when looking at the documentation above. + + *lua-syntax-call-function* + +Lua functions can be called in multiple ways. Consider the function: > + + local example_func = function(a, b) + print("A is: ", a) + print("B is: ", b) + end + + +The first way to call a function is: > + + example_func(1, 2) + -- ==== Result ==== + -- A is: 1 + -- B is: 2 +< + This way of calling a function is familiar to most scripting languages. + In Lua, it's important to understand that any function arguments that are + not supplied are automatically set to `nil`. For example: > + + example_func(1) + -- ==== Result ==== + -- A is: 1 + -- B is: nil +< + + Additionally, if any extra parameters are passed, they are discarded + completely. + +In Lua, it is also possible (when only one argument is passed) to call the +function without any parentheses. This is most often used to approximate +"keyword"-style arguments with a single dictionary. For example: > + + local func_with_opts = function(opts) + local will_do_foo = opts.foo + local filename = opts.filename + + ... + end + + func_with_opts { foo = true, filename = "hello.world" } +< + + In this style, each "parameter" is passed via keyword. It is still valid + to call the function in this style: > + + func_with_opts({ foo = true, filename = "hello.world" }) +< + + But often in the documentation, you will see the former rather than the + latter style, due to its brevity (this is vim after all!). + + ------------------------------------------------------------------------------ LUA PLUGIN EXAMPLE *lua-require-example* @@ -415,6 +475,8 @@ To avoid the error use |vim.schedule_wrap()| to defer the callback: > vim.api.nvim_command('echomsg "test"') end)) +(For one-shot timers, see |vim.defer_fn()|, which automatically adds the wrapping.) + Example: repeating timer 1. Save this code to a file. 2. Execute it with ":luafile %". > @@ -512,6 +574,9 @@ retained for the lifetime of a buffer but this is subject to change. A plugin should keep a reference to the parser object as long as it wants incremental updates. +Parser methods *lua-treesitter-parser* + +tsparser:parse() *tsparser:parse()* Whenever you need to access the current syntax tree, parse the buffer: > tstree = parser:parse() @@ -528,6 +593,16 @@ shouldn't be done directly in the change callback anyway as they will be very frequent. Rather a plugin that does any kind of analysis on a tree should use a timer to throttle too frequent updates. +tsparser:set_included_ranges(ranges) *tsparser:set_included_ranges()* + Changes the ranges the parser should consider. This is used for + language injection. `ranges` should be of the form (all zero-based): > + { + {start_node, end_node}, + ... + } +< + NOTE: `start_node` and `end_node` are both inclusive. + Tree methods *lua-treesitter-tree* tstree:root() *tstree:root()* @@ -698,25 +773,26 @@ VIM.HIGHLIGHT *lua-highlight* Nvim includes a function for highlighting a selection on yank (see for example https://github.com/machakann/vim-highlightedyank). To enable it, add > - au TextYankPost * silent! lua require'vim.highlight'.on_yank() + au TextYankPost * silent! lua vim.highlight.on_yank() < to your `init.vim`. You can customize the highlight group and the duration of the highlight via > - au TextYankPost * silent! lua require'vim.highlight'.on_yank("IncSearch", 500) + au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} < If you want to exclude visual selections from highlighting on yank, use > -au TextYankPost * silent! lua return (not vim.v.event.visual) and require'vim.highlight'.on_yank() + au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} < -vim.highlight.on_yank([{higroup}, {timeout}, {event}]) - *vim.highlight.on_yank()* - Highlights the yanked text. Optional arguments are the highlight group - to use ({higroup}, default `"IncSearch"`), the duration of highlighting - in milliseconds ({timeout}, default `500`), and the event structure - that is fired ({event}, default `vim.v.event`). - +vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* + Highlights the yanked text. The fields of the optional dict {opts} + control the highlight: + - {higroup} highlight group for yanked region (default `"IncSearch"`) + - {timeout} time in ms before highlight is cleared (default `150`) + - {on_macro} highlight when executing macro (default `false`) + - {on_visual} highlight when yanking visual selection (default `true`) + - {event} event structure (default `vim.v.event`) vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive}) *vim.highlight.range()* @@ -726,7 +802,6 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclu or blockwise, see |setreg|; default to characterwise) and whether the range is inclusive (default false). - ------------------------------------------------------------------------------ VIM.REGEX *lua-regex* @@ -846,6 +921,9 @@ vim.defer_fn({fn}, {timeout}) *vim.defer_fn* Defers calling {fn} until {timeout} ms passes. Use to do a one-shot timer that calls {fn}. + Note: The {fn} is |schedule_wrap|ped automatically, so API functions are + safe to call. + Parameters: ~ {fn} Callback to call once {timeout} expires {timeout} Time in ms to wait before calling {fn} @@ -1018,6 +1096,9 @@ inspect({object}, {options}) *vim.inspect()* https://github.com/kikito/inspect.lua https://github.com/mpeterv/vinspect +make_meta_accessor({get}, {set}, {del}) *vim.make_meta_accessor()* + TODO: Documentation + paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the |TUI|) pastes text into the editor. @@ -1133,7 +1214,7 @@ list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* |vim.tbl_extend()| pesc({s}) *vim.pesc()* - Escapes magic chars in a Lua pattern string. + Escapes magic chars in a Lua pattern. Parameters: ~ {s} String to escape @@ -1177,8 +1258,7 @@ startswith({s}, {prefix}) *vim.startswith()* tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* Add the reverse lookup values to an existing table. For - example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = - 1 }` + example: tbl_add_reverse_lookup { A = 1 } == { [1] = 'A , A = 1 }` Parameters: ~ {o} table The table to add the reverse to. @@ -1193,6 +1273,37 @@ tbl_contains({t}, {value}) *vim.tbl_contains()* Return: ~ true if `t` contains `value` +tbl_count({t}) *vim.tbl_count()* + Counts the number of non-nil values in table `t` . +> + + vim.tbl_count({ a=1, b=2 }) => 2 + vim.tbl_count({ 1, 2 }) => 2 +< + + Parameters: ~ + {t} Table + + Return: ~ + Number that is the number of the value in table + + See also: ~ + https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua + +tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* + Merges recursively two or more map-like tables. + + Parameters: ~ + {behavior} Decides what to do if a key is found in more + than one map: + • "error": raise an error + • "keep": use value from the leftmost map + • "force": use value from the rightmost map + {...} Two or more map-like tables. + + See also: ~ + |tbl_extend()| + tbl_extend({behavior}, {...}) *vim.tbl_extend()* Merges two or more map-like tables. @@ -1207,6 +1318,13 @@ tbl_extend({behavior}, {...}) *vim.tbl_extend()* See also: ~ |extend()| +tbl_filter({func}, {t}) *vim.tbl_filter()* + Filter a table using a predicate function + + Parameters: ~ + {func} function or callable table + {t} table + tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. @@ -1225,11 +1343,19 @@ tbl_isempty({t}) *vim.tbl_isempty()* Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua@paramt Table to check tbl_islist({t}) *vim.tbl_islist()* - Table + Determine whether 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. + + Parameters: ~ + {t} Table Return: ~ - true: A non-empty array, false: A non-empty table, nil: An - empty table + `true` if array-like table, else `false` . tbl_keys({t}) *vim.tbl_keys()* Return a list of all keys used in a table. However, the order @@ -1244,6 +1370,13 @@ tbl_keys({t}) *vim.tbl_keys()* See also: ~ Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua +tbl_map({func}, {t}) *vim.tbl_map()* + Apply a function to all values of a table. + + Parameters: ~ + {func} function or callable table + {t} table + tbl_values({t}) *vim.tbl_values()* Return a list of all values used in a table. However, the order of the return table of values is not guaranteed. @@ -1288,12 +1421,12 @@ validate({opt}) *vim.validate()* => NOP (success) < > - vim.validate{arg1={1, 'table'}} - => error('arg1: expected table, got number') + 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') + vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} + => error('arg1: expected even number, got 3') < Parameters: ~ |