Merge #4411 from ZyX-I/luaviml'/lua

5 files changed, 193 insertions, 7 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 3b9c11770e..911fe43819 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2136,6 +2136,7 @@ lispindent({lnum})		Number	Lisp indent for line {lnum}
 localtime()			Number	current time
 log({expr})			Float	natural logarithm (base e) of {expr}
 log10({expr})			Float	logarithm of Float {expr} to base 10
+luaeval({expr}[, {expr}])	any	evaluate Lua expression
 map({expr1}, {expr2})		List/Dict  change each item in {expr1} to {expr}
 maparg({name}[, {mode} [, {abbr} [, {dict}]]])
 				String or Dict
@@ -5109,6 +5110,9 @@ log10({expr})						*log10()*
 			:echo log10(0.01)
 <			-2.0
 
+luaeval({expr}[, {expr}])
+		Evaluate Lua expression {expr} and return its result converted 
+		to Vim data structures. See |lua-luaeval| for more details.
 
 map({expr1}, {expr2})					*map()*
 		{expr1} must be a |List| or a |Dictionary|.
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
new file mode 100644
index 0000000000..932564170d
--- /dev/null
+++ b/runtime/doc/if_lua.txt
@@ -0,0 +1,174 @@
+*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 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
+
+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. 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|.
+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.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 06196dbefa..c15587cffd 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1331,6 +1331,9 @@ tag	      command	      action ~
 |:ltag|		:lt[ag]		jump to tag and add matching tags to the
 				location list
 |:lunmap|	:lu[nmap]	like ":unmap!" but includes Lang-Arg mode
+|:lua|		:lua		execute Lua command
+|:luado|	:luad[o]	execute Lua command for each line
+|:luafile|	:luaf[ile]	execute Lua script file
 |:lvimgrep|	:lv[imgrep]	search for pattern in files
 |:lvimgrepadd|	:lvimgrepa[dd]	like :vimgrep, but append to current list
 |:lwindow|	:lw[indow]	open or close location window
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 1d09b532a4..acb6fd0fa4 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -950,6 +950,7 @@ Various:					*various-functions*
 	taglist()		get list of matching tags
 	tagfiles()		get a list of tags files
 
+	luaeval()		evaluate Lua expression
 	py3eval()		evaluate Python expression (|+python3|)
 	pyeval()		evaluate Python expression (|+python|)
 	pyxeval()		evaluate |python_x| expression
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index de2dd601c5..e6184fd528 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -214,22 +214,15 @@ Additional differences:
 
 - |shada-c| has no effect.
 - |shada-s| now limits size of every item and not just registers.
-- When reading ShaDa files items are merged according to the timestamp.
-  |shada-merging|
 - 'viminfo' option got renamed to 'shada'. Old option is kept as an alias for
   compatibility reasons.
 - |:wviminfo| was renamed to |:wshada|, |:rviminfo| to |:rshada|.  Old
   commands are still kept.
-- When writing (|:wshada| without bang or at exit) it merges much more data,
-  and does this according to the timestamp.  Vim merges only marks.
-  |shada-merging|
 - ShaDa file format was designed with forward and backward compatibility in
   mind. |shada-compatibility|
 - Some errors make ShaDa code keep temporary file in-place for user to decide
   what to do with it.  Vim deletes temporary file in these cases.
   |shada-error-handling|
-- Vim keeps no timestamps at all, neither in viminfo file nor in the instance
-  itself.
 - ShaDa file keeps search direction (|v:searchforward|), viminfo does not.
 
 |printf()| returns something meaningful when used with `%p` argument: in Vim 
@@ -240,6 +233,17 @@ coerced to strings. See |id()| for more details, currently it uses
 
 |c_CTRL-R| pasting a non-special register into |cmdline| omits the last <CR>.
 
+Lua interface (|if_lua.txt|):
+
+- `:lua print("a\0b")` will print `a^@b`, like with `:echomsg "a\nb"` . In Vim 
+  that prints `a` and `b` on separate lines, exactly like
+  `:lua print("a\nb")` .
+- `:lua error('TEST')` will print “TEST” as the error in Vim and “E5105: Error 
+  while calling lua chunk: [string "<VimL compiled string>"]:1: TEST” in 
+  Neovim.
+- Lua has direct access to Neovim api via `vim.api`.
+- Currently most of features are missing.
+
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
 				     *if_lua* *if_perl* *if_mzscheme* *if_tcl*