Merge #9740 from KillTheMule/luadoc

1 files changed, 169 insertions, 116 deletions

diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index b97341e319..7f90074ff0 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -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 modules					*lua-require*
+Importing Lua modules					*lua-require*
 
 Nvim automatically adjusts `package.path` and `package.cpath` according to
 effective 'runtimepath' value.  Adjustment happens whenever 'runtimepath' is
@@ -258,7 +258,77 @@ position are restricted when the command is executed in the |sandbox|.
 
 
 ==============================================================================
-vim.*							*lua-vim* *lua-stdlib*
+luaeval()						*lua-luaeval* *lua-eval*
+							*luaeval()*
+
+The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is
+"luaeval". "luaeval" takes an expression string and an optional argument used 
+for _A inside expression 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
+
+Lua nils, numbers, strings, tables and booleans are converted to their
+respective VimL types. An error is thrown if conversion of any other Lua types
+is attempted.
+
+The magic global "_A" contains the second argument to luaeval().
+
+Example: >
+    :echo luaeval('_A[1] + _A[2]', [40, 2])
+    42
+    :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
+    foo
+
+Lua tables are used as both dictionaries and lists, so it is impossible to
+determine whether empty table is meant to be empty list or empty dictionary.
+Additionally lua does not have integer numbers. To distinguish between these
+cases there is the following agreement:
+
+0. Empty table is empty list.
+1. Table with N incrementally growing integral numbers, starting from 1 and 
+   ending with N is considered to be a list.
+2. Table with string keys, none of which contains NUL byte, is considered to 
+   be a dictionary.
+3. Table with string keys, at least one of which contains NUL byte, is also 
+   considered to be a dictionary, but this time it is converted to 
+   a |msgpack-special-map|.
+							*lua-special-tbl*
+4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point 
+   value:
+   - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to 
+     a floating-point 1.0. Note that by default integral lua numbers are 
+     converted to |Number|s, non-integral are converted to |Float|s. This 
+     variant allows integral |Float|s.
+   - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty 
+     dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is 
+     converted to a dictionary `{'a': 42}`: non-string keys are ignored. 
+     Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. 
+     are errors.
+   - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well 
+     as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not 
+     form a 1-step sequence from 1 to N are ignored, as well as all 
+     non-integral keys.
+
+Examples: >
+
+    :echo luaeval('math.pi')
+    :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)
+
+Note that currently second argument to `luaeval` undergoes VimL to lua 
+conversion, so changing containers in lua do not affect values in VimL. Return 
+value is also always converted. When converting, |msgpack-special-dict|s are 
+treated specially.
+
+==============================================================================
+Lua standard modules					*lua-stdlib*
 
 The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
 various functions and sub-modules.  It is always loaded, thus require("vim")
@@ -292,7 +362,7 @@ Note that underscore-prefixed functions (e.g. "_os_proc_children") are
 internal/private and must not be used by plugins.
 
 ------------------------------------------------------------------------------
-vim.api.* functions
+VIM.API							*lua-api*
 
 `vim.api` exposes the full Nvim |API| as a table of Lua functions.
 
@@ -302,55 +372,18 @@ For example, to use the "nvim_get_current_line()" API function, call
     print(tostring(vim.api.nvim_get_current_line()))
 
 ------------------------------------------------------------------------------
-vim.* builtin functions
-
-vim.deepcopy({object})                                         *vim.deepcopy*
-	Performs a deep copy of the given object, and returns that copy.
-	For a non-table object, that just means a usual copy of the object,
-	while for a table all subtables are copied recursively.
-
-vim.gsplit({s}, {sep}, {plain})                                  *vim.gsplit*
-	Split a given string by a separator. Returns an iterator of the 
-	split components. The separator can be a lua pattern, see
-		    https://www.lua.org/pil/20.2.html
-	Setting {plain} to `true` turns off pattern matching, as it is passed
-	to `string:find`, see 
-		http://lua-users.org/wiki/StringLibraryTutorial
-
-	Parameters:~
-		{s}     String: String to split
-		{sep}   String: Separator pattern. If empty, split by chars.
-		{plain} Boolean: If false, match {sep} verbatim
-
-	Return:~
-		Iterator of strings, which are the components of {s} after
-		splitting	
-
-vim.split({s}, {sep}, {plain})                                    *vim.split*
-	Split a given string by a separator. Returns a table containing the 
-	split components. The separator can be a lua pattern, see
-		    https://www.lua.org/pil/20.2.html
-	Setting {plain} to `true` turns off pattern matching, as it is passed
-	to `string:find`, see 
-		http://lua-users.org/wiki/StringLibraryTutorial
-
-	Parameters:~
-		{s}     String: String to split
-		{sep}   String: Separator pattern. If empty, split by chars.
-		{plain} Boolean: If false, match {sep} verbatim
-
-	Return:~
-		Table of strings, which are the components of {s} after
-		splitting	
+VIM							*lua-util*
+
+vim.inspect({object}, {options})                                 *vim.inspect*
+	Return a human-readable representation of the passed object. See
+	         https://github.com/kikito/inspect.lua
+	for details and possible options.
 
 vim.stricmp(a, b)					*lua-vim.stricmp*
 	Function used for case-insensitive string comparison.  Takes two 
 	string arguments and returns 0, 1 or -1 if strings are equal, a is 
 	greater then b or a is lesser then b respectively.
 
-vim.trim({string})                                                  *vim.trim*
-	Returns the string with all leading and trailing whitespace removed.
-	
 vim.type_idx						*lua-vim.type_idx*
 	Type index for use in |lua-special-tbl|.  Specifying one of the 
 	values from |lua-vim.types| allows typing the empty table (it is 
@@ -386,86 +419,106 @@ vim.types						*lua-vim.types*
 	`vim.types.dictionary` will not change or that `vim.types` table will 
 	only contain values for these three types.
 
-------------------------------------------------------------------------------
-vim.* runtime functions
+==============================================================================
+Lua module: vim                                                      *lua-vim*
 
-Those functions are only available after the runtime files have been loaded.
-In particular, they are not available when using `nvim -u NONE`.
+trim({s})                                                         *vim.trim()*
+                Trim whitespace (Lua pattern "%%s") from both sides of a
+                string.
 
-vim.inspect({object}, {options})                                 *vim.inspect*
-	Return a human-readable representation of the passed object. See
-	         https://github.com/kikito/inspect.lua
-	for details and possible options.
+                Parameters: ~
+                    {s}  String to trim
 
-==============================================================================
-luaeval()						*lua-luaeval* *lua-eval*
-							*luaeval()*
+                Return: ~
+                    String with whitespace removed from its beginning and end
 
-The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is
-"luaeval". "luaeval" takes an expression string and an optional argument used 
-for _A inside expression 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
+                See also: ~
+                    https://www.lua.org/pil/20.2.html
 
-Lua nils, numbers, strings, tables and booleans are converted to their
-respective VimL types. An error is thrown if conversion of any other Lua types
-is attempted.
 
-The magic global "_A" contains the second argument to luaeval().
 
-Example: >
-    :echo luaeval('_A[1] + _A[2]', [40, 2])
-    42
-    :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
-    foo
 
-Lua tables are used as both dictionaries and lists, so it is impossible to
-determine whether empty table is meant to be empty list or empty dictionary.
-Additionally lua does not have integer numbers. To distinguish between these
-cases there is the following agreement:
+deepcopy({orig})                                              *vim.deepcopy()*
+                Returns a deep copy of the given object. Non-table objects are
+                copied as in a typical Lua assignment, whereas table objects
+                are copied recursively.
 
-0. Empty table is empty list.
-1. Table with N incrementally growing integral numbers, starting from 1 and 
-   ending with N is considered to be a list.
-2. Table with string keys, none of which contains NUL byte, is considered to 
-   be a dictionary.
-3. Table with string keys, at least one of which contains NUL byte, is also 
-   considered to be a dictionary, but this time it is converted to 
-   a |msgpack-special-map|.
-							*lua-special-tbl*
-4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point 
-   value:
-   - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to 
-     a floating-point 1.0. Note that by default integral lua numbers are 
-     converted to |Number|s, non-integral are converted to |Float|s. This 
-     variant allows integral |Float|s.
-   - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty 
-     dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is 
-     converted to a dictionary `{'a': 42}`: non-string keys are ignored. 
-     Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. 
-     are errors.
-   - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well 
-     as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not 
-     form a 1-step sequence from 1 to N are ignored, as well as all 
-     non-integral keys.
+                Parameters: ~
+                    {orig}  Table to copy
 
-Examples: >
+                Return: ~
+                    New table of copied keys and (nested) values.
 
-    :echo luaeval('math.pi')
-    :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)
+gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
+                Splits a string at each instance of a separator.
 
-Note that currently second argument to `luaeval` undergoes VimL to lua 
-conversion, so changing containers in lua do not affect values in VimL. Return 
-value is also always converted. When converting, |msgpack-special-dict|s are 
-treated specially.
+                Parameters: ~
+                    {s}      String to split
+                    {sep}    Separator string or pattern
+                    {plain}  If `true` use `sep` literally (passed to
+                             String.find)
 
-==============================================================================
- vim:tw=78:ts=8:et:ft=help:norl:
+                Return: ~
+                    Iterator over the split components
+
+                See also: ~
+                    |vim.split()|
+                    https://www.lua.org/pil/20.2.html
+                    http://lua-users.org/wiki/StringLibraryTutorial
+
+split({s}, {sep}, {plain})                                       *vim.split()*
+                Splits a string at each instance of a separator.
+
+                Examples: >
+                 split(":aa::b:", ":")     --> {'','aa','','bb',''}
+                 split("axaby", "ab?")     --> {'','x','y'}
+                 split(x*yz*o, "*", true)  --> {'x','yz','o'}
+<
+
+                Parameters: ~
+                    {s}      String to split
+                    {sep}    Separator string or pattern
+                    {plain}  If `true` use `sep` literally (passed to
+                             String.find)
+
+                Return: ~
+                    List-like table of the split components.
+
+                See also: ~
+                    |vim.gsplit()|
+
+tbl_contains({t}, {value})                                *vim.tbl_contains()*
+                Checks if a list-like (vector) table contains `value` .
+
+                Parameters: ~
+                    {t}      Table to check
+                    {value}  Value to compare
+
+                Return: ~
+                    true if `t` contains `value`
+
+tbl_extend({behavior}, {...})                               *vim.tbl_extend()*
+                Merges 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: ~
+                    |extend()|
+
+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.
+
+                Parameters: ~
+                    {t}  List-like table
+
+                Return: ~
+                    Flattened copy of the given list-like table.
+
+ vim:tw=78:ts=8:ft=help:norl: