doc,functests: Add documentation

Missing: updates to various lists.

runtime/doc/if_lua.txt

@@ -0,0 +1,173 @@
+*if_lua.txt*    For Neovim
+
+
+		  VIM REFERENCE MANUAL    by Luis Carvalho
+
+
+The Lua Interface to Vim				*lua* *Lua*
+
+1. Commands			|lua-commands|
+2. The vim module		|lua-vim|
+3. The luaeval function		|lua-luaeval|
+
+==============================================================================
+1. Commands						*lua-commands*
+
+							*:lua*
+:[range]lua {chunk}
+			Execute Lua chunk {chunk}.    {not in Vi}
+
+Examples:
+>
+	:lua vim.api.nvim_command('echo "Hello, Neovim!"')
+<
+
+:[range]lua << {endmarker}
+{script}
+{endmarker}
+			Execute Lua script {script}.  {not in Vi}
+			Note: This command doesn't work when the Lua
+			feature wasn't compiled in.  To avoid errors, see
+			|script-here|.
+
+{endmarker} must NOT be preceded by any white space.  If {endmarker} is
+omitted from after the "<<", a dot '.' must be used after {script}, like
+for the |:append| and |:insert| commands.
+This form of the |:lua| command is mainly useful for including Lua code
+in Vim scripts.
+
+Example:
+>
+	function! CurrentLineInfo()
+	lua << EOF
+	local linenr = vim.api.nvim_win_get_cursor(0)[1]
+	local curline = vim.api.nvim_buf_get_lines(
+		0, linenr, linenr + 1, false)[1]
+	print(string.format("Current line [%d] has %d bytes",
+		linenr, #curline))
+	EOF
+	endfunction
+
+Note that in example variables are prefixed with local: they will disappear 
+when block finishes. This is not the case for globals.
+
+To see what version of Lua you have: >
+	:lua print(_VERSION)
+
+If you use LuaJIT you can also use this: >
+	:lua print(jit.version)
+<
+
+							*:luado*
+:[range]luado {body}	Execute Lua function "function (line, linenr) {body}
+			end" for each line in the [range], with the function
+			argument being set to the text of each line in turn,
+			without a trailing <EOL>, and the current line number.
+			If the value returned by the function is a string it
+			becomes the text of the line in the current turn. The
+			default for [range] is the whole file: "1,$".
+							{not in Vi}
+
+Examples:
+>
+	:luado return string.format("%s\t%d", line:reverse(), #line)
+
+	:lua require"lpeg"
+	:lua -- balanced parenthesis grammar:
+	:lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" }
+	:luado if bp:match(line) then return "-->\t" .. line end
+<
+
+							*:luafile*
+:[range]luafile {file}
+			Execute Lua script in {file}. {not in Vi}
+			The whole argument is used as a single file name.
+
+Examples:
+>
+	:luafile script.lua
+	:luafile %
+<
+
+All these commands execute a Lua chunk from either the command line (:lua and
+:luado) or a file (:luafile) with the given line [range]. Similarly to the Lua
+interpreter, each chunk has its own scope and so only global variables are
+shared between command calls. All Lua default libraries are available. In
+addition, Lua "print" function has its output redirected to the Vim message
+area, with arguments separated by a white space instead of a tab.
+
+Lua uses the "vim" module (see |lua-vim|) to issue commands to Neovim
+and manage buffers (|lua-buffer|) and windows (|lua-window|). However,
+procedures that alter buffer content, open new buffers, and change cursor
+position are restricted when the command is executed in the |sandbox|.
+
+
+==============================================================================
+2. The vim module					*lua-vim*
+
+Lua interfaces Vim through the "vim" module. Currently it only has `api` 
+submodule which is a table with all API functions. Descriptions of these 
+functions may be found in |api-funcs.txt|.
+
+==============================================================================
+3. The luaeval function					*lua-luaeval* *lua-eval*
+							*luaeval()*
+
+The (dual) equivalent of "vim.eval" for passing Lua values to Vim is
+"luaeval". "luaeval" takes an expression string and an optional argument 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
+
+Note that "_A" receives the argument to "luaeval". Lua nils, numbers, strings, 
+tables and booleans are converted to their Vim respective types. An error is 
+thrown if conversion of any of the remaining Lua types is attempted.
+
+Note 2: lua tables are used as both dictionaries and lists, thus making it 
+impossible to determine whether empty table is meant to be empty list or empty 
+dictionary. 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|.
+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 resulting containers in lua do not affect values in 
+VimL. Return value is also always converted. When converting, 
+|msgpack-special-dict|s are treated specially.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl:

test/functional/lua/commands_spec.lua

@@ -2,8 +2,10 @@
 local helpers = require('test.functional.helpers')(after_each)
 
 local eq = helpers.eq
+local NIL = helpers.NIL
 local clear = helpers.clear
 local meths = helpers.meths
+local funcs = helpers.funcs
 local source = helpers.source
 local dedent = helpers.dedent
 local exc_exec = helpers.exc_exec
@@ -54,4 +56,10 @@ describe(':lua command', function()
     ]])
     eq({'', 'ETTS', 'TTSE', 'STTE'}, curbufmeths.get_lines(0, 100, false))
   end)
+  it('preserves global and not preserves local variables', function()
+    eq('', redir_exec('lua gvar = 42'))
+    eq('', redir_exec('lua local lvar = 100500'))
+    eq(NIL, funcs.luaeval('lvar'))
+    eq(42, funcs.luaeval('gvar'))
+  end)
 end)

test/functional/lua/luaeval_spec.lua

@@ -46,6 +46,7 @@ describe('luaeval()', function()
          funcs.luaeval('{n=1, f=1.5, s="string", l={4, 2}}'))
       -- Not tested: nil inside containers: behaviour will most likely change.
       eq(NIL, funcs.luaeval('nil'))
+      eq({['']=1}, funcs.luaeval('{[""]=1}'))
     end)
   end)
   describe('recursive lua values', function()