*vital/Lua/Prelude.txt*		crucial functions for lua integration

Maintainer: ujihisa <ujihisa at gmail com>

==============================================================================
CONTENTS				*Vital.Lua.Prelude-contents*

INTRODUCTION			|Vital.Lua.Prelude-introduction|
  USAGE				|Vital.Lua.Prelude-usage|
INTERFACE			|Vital.Lua.Prelude-interface|
  Functions			  |Vital.Lua.Prelude-functions|

==============================================================================
INTRODUCTION				*Vital.Lua.Prelude-introduction*

*Vital.Lua.Prelude* provides

* common way to make your own function available both from Vim script and from
  Lua.
* automatic loading of corresponding files; this loads a Lua file
  autoload/foo.lua when you use a Vim script file autoload/foo.vim which both
  can be used from Lua/Vim.
* useful functions defined in Lua.Prelude, like from_lua() and to_lua().
* easy way to call Lua function from Vim script.

==============================================================================
USAGE					*Vital.Lua.Prelude-usage*

When you write function "f" it can be used from both (vim or lua) code. You
can write bridge function below:

sample.vim
>
	let s:V = vital#sample#new()
	let s:P = s:V.import('Lua.Prelude')
        " s:LuaP is namespace of Vital.Lua.Prelude
	let s:LuaP = s:P.lua_namespace()
        " s:sfile will be namespace
	let s:sfile = expand('<sfile>:p')

	function! s:init_context()
	  " load and evaluate sample.lua
	  call luaeval('dofile(_A)', s:P.luafile_of(s:sfile))
	endfunction
	call s:init_context()

	function! s:f(x, y)
	  return luaeval('_G[_A[0]].vim.f(_A[1], _A[2])', [s:sfile, a:x, a:y])
	endfunction
<
sample.lua
>
	local public = {lua = {}, vim = {}}
	-- You can call Vital.Lua.Prelude functions via table P
	local P = _G[vim.eval('s:LuaP')].lua

	function public.lua.f(x, y)
	  ...
	end
	...
	function public.vim.f(x, y)
	  -- type conversion and call public.lua.f
	  ...
	end
	...

	-- Make your namespace
	_G[vim.eval('s:sfile')] = public
<

==============================================================================
INTERFACE				*Vital.Lua.Prelude-interface*
------------------------------------------------------------------------------
FUNCTIONS				*Vital.Lua.Prelude-functions*

luafile_of({sfile})			      *Vital.Lua.Prelude.luafile_of()*

	Only as a vim interface; Lua script can't call this function directly.
	Convert vim script filename to lua script filename. Lua script file
	must be placed on the same directory of vim script file.

map({list}, {f})				     *Vital.Lua.Prelude.map()*

	Only as a lua interface; Vim script can't call this function directly.
>
	map({10, 20, 30}, function(e) return e + 1 end)
	# == {11, 21, 31}
<

to_lua({vobj})					  *Vital.Lua.Prelude.to_lua()*

	Only as a lua interface; Vim script can't call this function directly.
	TODO

from_lua({lobj})				*Vital.Lua.Prelude.from_lua()*

	Only as a lua interface; Vim script can't call this function directly.
	TODO

==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl
