if_lua.jax

*if_lua.txt*    For Vim バージョン 8.1.  Last change: 2015 Oct 16


		  VIMリファレンスマニュアル    by Luis Carvalho


Vim の Lua インターフェイス				*lua* *Lua*

1. コマンド			|lua-commands|
2. vim モジュール		|lua-vim|
3. List ユーザーデータ		|lua-list|
4. Dict ユーザーデータ		|lua-dict|
5. Blob ユーザーデータ		|lua-blob|
6. Funcref ユーザーデータ	|lua-funcref|
7. バッファユーザーデータ	|lua-buffer|
8. ウィンドウユーザーデータ	|lua-window|
9. luaeval() Vim 関数		|lua-luaeval|
10. 動的ローディング		|lua-dynamic|

{Vi にはこれらのコマンドはありません}

Lua インターフェイスは Vim が |+lua| 機能付きでコンパイルされたときのみ利用で
きます。

==============================================================================
1. コマンド						*lua-commands*

							*:lua*
:[range]lua {chunk}
			Lua チャンク {chunk} を実行する。 {Vi にはありません}

例:
>
	:lua print("Hello, Vim!")
	:lua local curbuf = vim.buffer() curbuf[7] = "line #7"
<

:[range]lua << {endmarker}
{script}
{endmarker}
			Lua スクリプト {script} を実行する。
			{Vi にはありません}
			Note: このコマンドは Lua が組み込まれていない場合は機
			能しません。エラーを避けるには |script-here| を参照。

{endmarker} の前には空白を入れることはできません。"<<" の後の {endmarker} を省
略した場合は |:append| や |:insert| コマンドのようにドット "." で {script} を
閉じます。
|:lua| コマンドのこの書式は主に Vim script の中に Lua コードを埋め込むときに便
利です。

例:
>
	function! CurrentLineInfo()
	lua << EOF
	local linenr = vim.window().line
	local curline = vim.buffer()[linenr]
	print(string.format("Current line [%d] has %d chars",
		linenr, #curline))
	EOF
	endfunction
<

							*:luado*
:[range]luado {body}	Lua 関数 "function (line, linenr) {body} end" を
			[range] で指定された各行に対して実行する。関数の引数に
			は各行のテキスト (末尾の <EOL> 無し) と現在の行番号が
			渡されます。関数の戻り値が文字列なら行のテキストはその
			文字列で置換されます。[range] を省略するとすべてのファ
			イル ("1,$") が処理されます。
							{Vi にはありません}

例:
>
	: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}
			{file} 内の Lua スクリプトを実行する。
			{Vi にはありません}
			引数全体で一つのファイル名として認識されます。

例:
>
	:luafile script.lua
	:luafile %
<

これらすべてのコマンドはコマンドライン (:lua と :luado) かファイル (:luafile)
で指定された Lua チャンクを範囲指定 [range] に対して実行します。Lua インタープ
リターと同様に各チャンクはそれぞれのスコープを持つため、各コマンドの実行で共有
されるのはグローバル変数だけです。すべての Lua デフォルトライブラリが利用可能
です。加えて、Lua の "print" 関数の出力先は Vim のメッセージエリアになり、引数
はタブ文字ではなくスペースで区切られます。

Lua は "vim" モジュール (|lua-vim| 参照) を使って、Vim コマンドを発行したり
バッファ (|lua-buffer|) やウィンドウ (|lua-window|) を管理したりします。ただ
し、コマンドが |sandbox| の中で実行されたときはバッファの変更、新規バッファの
作成、カーソル位置の変更は制限されます。


==============================================================================
2. vim モジュール					*lua-vim*

Lua からは "vim" モジュールを使って Vim を操作します。範囲指定の最初と最後の行
は "vim.firstline" と "vim.lastline" に格納されています。vim モジュールには
バッファ操作、ウィンドウ操作、現在行の取得、Vim 式評価、Vim コマンド実行、など
のルーチンが含まれています。

	vim.list([arg])		"arg" が 1, ..., n の数値をキーに持つ Lua のテ
				ーブルの時、i = 1, ..., n に対して l[i] =
				arg[i] となるようなリスト l を返し (|List| を参
				照) 、そうでなければ空のリストを返します。
				数値以外のキーは戻り値のリストの初期化に使われ
				ません。変換のルールについては |lua-eval| を参照
				してください。例: >
				    :lua t = {math.pi, false, say = 'hi'}
				    :echo luaeval('vim.list(t)')
				    :" [3.141593, v:false], 'say' is ignored
<
	vim.dict([arg])		"arg" が Lua のテーブルの時、"arg" のそれぞれの
				キー k に対して d[k] = arg[k] となるような辞書
				を返し (|Dictionary| を参照) 、そうでなければ
				空の辞書を返します。数値のキーは文字列に変換さ
				れます。文字列以外のキーは戻り値の辞書の初期化
				に使われません。変換のルールについては
				|lua-eval| を参照してください。例: >
				    :lua t = {math.pi, false, say = 'hi'}
				    :echo luaeval('vim.dict(t)')
				    :" {'1': 3.141593, '2': v:false,
				    :" 'say': 'hi'}
<
	vim.funcref({name})	関数 {name} への関数参照を返します (|Funcref|
				を参照) 。その値は Vim の function() と等価で
				す。

	vim.buffer([arg])	"arg" が数値ならバッファリストの "arg" 番の
				バッファを返す。"arg" が文字列ならフルパスか
				ショートパスが "arg" に一致するバッファを返
				す。どちらの場合もバッファが見つからなければ
				'nil' (nil 値、文字列ではない) を返す。その
				他、"toboolean(arg)" が 'true' ならバッファリ
				ストの最初のバッファを、そうでなければカレント
				バッファを返す。

	vim.window([arg])	"arg" が数値なら "arg" 番のウィンドウを返す。
				ウィンドウが無ければ 'nil' (nil 値、文字列では
				ない) を返す。その他、"toboolean(arg)" が
				'true' なら最初のウィンドウを、そうでなければ
				カレントウィンドウを返す。

	vim.type({arg})		{arg} の型を返す。これは Lua の "type" 関数と
				同じようなものですが、{arg} がリスト、辞書、
				関数参照、バッファ、ウィンドウのときに、
				"list"、"dict"、"funcref"、"buffer"、"window"
				をそれぞれ返します。例: >
					:lua l = vim.list()
					:lua print(type(l), vim.type(l))
					:" list
<
	vim.command({cmd})	Vim の Ex コマンド {cmd} を実行する。
				例: >
					:lua vim.command"set tw=60"
					:lua vim.command"normal ddp"
<
	vim.eval({expr})	式 {expr} (|expression| 参照) を評価してその結
				果を Lua の値に変換して返す。
				Vim の文字列と数値はそのまま Lua の文字列と数
				値に変換される。Vim のリストと辞書は Lua の
				ユーザーデータに変換される (|lua-list| と
				|lua-dict| を参照)。
				例: >
					:lua tw = vim.eval"&tw"
					:lua print(vim.eval"{'a': 'one'}".a)
<
	vim.line()		現在行 (末尾の <EOL> 無し) を返す。型は Lua 文
				字列。

	vim.beep()		ビープ音を鳴らす。

	vim.open({fname})	ファイル {fname} 用の新しいバッファを開いて返
				す。Note: カレントバッファは変更されません。


==============================================================================
3. List ユーザーデータ					*lua-list*

List ユーザーデータは vim のリストを表します。Vim のリストに近い形で操作できる
ようになっています。リストはオブジェクトなので、Lua 内で参照しているリストを変
更すると、それは Vim 内にも影響します。逆も同様です。リスト "l" は以下のプロパ
ティとメソッドを持っています:

プロパティ
----------
	o "#l" はリスト "l" の要素数。Vim の "len(l)" と同じ。
	o "l[k]" は "l" の k 個目の要素を返す。"l" のインデックスは Vim と同じ
	  で、0 を基準とする。
	  k 個目の要素を変更するには、単に "l[k] = newitem" とする。
	  "l[k] = nil" で k 個目の要素を "l" から削除できる。
	o "l()" は "l" のイテレータを返す。

メソッド
--------
	o "l:add(item)" は "item" を "l" の末尾に追加する。
	o "l:insert(item[, pos])" は "item" を "pos" (省略可) の位置に挿入す
	  る。"pos" のデフォルト値は 0。

例:
>
	:let l = [1, 'item']
	:lua l = vim.eval('l') -- same 'l'
	:lua l:add(vim.list())
	:lua l[0] = math.pi
	:echo l[0] " 3.141593
	:lua l[0] = nil -- remove first item
	:lua l:insert(true, 1)
	:lua print(l, #l, l[0], l[1], l[-1])
	:lua for item in l() do print(item) end
<

==============================================================================
4. Dict ユーザーデータ					*lua-dict*

list ユーザーデータと同様、dict ユーザーデータは vim の辞書を表します。辞書も
オブジェクトなので、Lua と Vim 間で参照が保持されます。辞書 "d" は以下のプロパ
ティを持っています。

プロパティ
----------
	o "#d" は辞書 "d" の要素数。Vim の "len(d)" と同じ。
	o "d.key" または "d['key']" は "d" の "key" 要素の値を返す。
	   このキーの値を変更するには、単に "d.key = newvalue" とする。
	   "d.key = nil" で "d" から要素を削除できる。
	o "d()" は "d" のイテレータを返す。Vim の "items(d)" と同じ。

例:
>
	:let d = {'n':10}
	:lua d = vim.eval('d') -- same 'd'
	:lua print(d, d.n, #d)
	:let d.self = d
	:lua for k, v in d() do print(d, k, v) end
	:lua d.x = math.pi
	:lua d.self = nil -- remove entry
	:echo d
<

==============================================================================
5. Blob ユーザーデータ					*lua-blob*

Blob ユーザーデータは vim の Blob を表します。Blob "b" は以下のプロパティを持
っています。

プロパティ
----------
	o "#b" は Blob "b" の要素数。Vim の"len(b)" と同じ。
	o "b[k]" は "b" の k 個目の要素を返す。"b" のインデックスは Vim と同じ
	  で、0 を基準とする。
	  k 個目の要素を変更するには、単に "b[k] = number" とする。特に、
	  "b[#b] = number" で末尾にバイトを追加できる。

メソッド
--------
	o "b:add(bytes)" は "bytes" を "b" の末尾に追加する。

例:
>
	:let b = 0z001122
	:lua b = vim.eval('b') -- same 'b'
	:lua print(b, b[0], #b)
	:lua b[1] = 32
	:lua b[#b] = 0x33 -- append a byte to tail
	:lua b:add("\x80\x81\xfe\xff")
	:echo b
<

==============================================================================
6. Funcref ユーザーデータ				*lua-funcref*

Funcref ユーザーデータは Vim における関数参照変数を表します。"dict" 属性付きで
定義された Vim の関数参照 はその呼び出し時に "self" に適切に辞書が代入できるよ
うに、辞書のメンバーとして取得できなければなりません (下記の例を参照してくださ
い) 。Lua の関数参照 "f" は次のプロパティを持っています:

プロパティ
----------
	o "#f" は "f" が参照している関数の名前です
	o "f(...)" は "f" が参照している関数を (引数と共に) 呼びます

例:
>
	:function I(x)
	:  return a:x
	:  endfunction
	:let R = function('I')
	:lua i1 = vim.funcref('I')
	:lua i2 = vim.eval('R')
	:lua print(#i1, #i2) -- both 'I'
	:lua print(i1, i2, #i2(i1) == #i1(i2))
	:function Mylen() dict
	:  return len(self.data)
	:  endfunction
	:let mydict = {'data': [0, 1, 2, 3]}
	:lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen')
	:echo mydict.len()
	:lua l = d.len -- assign d as 'self'
	:lua print(l())
<

==============================================================================
7. バッファユーザーデータ				*lua-buffer*

バッファユーザーデータは Vim のバッファを表します。バッファユーザーデータ "b"
は以下のプロパティとメソッドを持っています:

プロパティ
----------
	o "b()"		"b" をカレントバッファに設定する。
	o "#b"		バッファ "b" の行数。
	o "b[k]"	バッファの k 行目。"b[k] = newline" で k 行目を文字列
			"newline" で置換する。"b[k] = nil" で k 行目を削除す
			る。
	o "b.name"	バッファ "b" のショートパス (読込専用)。
	o "b.fname"	バッファ "b" のフルパス (読込専用)。
	o "b.number"	バッファ "b" のバッファリスト内の位置 (読込専用)。

メソッド
--------
	o "b:insert(newline[, pos])"
			文字列 "newline" をバッファの "pos" の位置 (省略可) に
			挿入する。"pos" を省略した場合は "#b + 1" に挿入される。
			"pos == 0" の場合は "newline" は 1 行目に挿入される。
	o "b:next()"	 バッファリストの "b" の次のバッファを返す。
	o "b:previous()" バッファリストの "b" の前のバッファを返す。
	o "b:isvalid()"	 バッファ "b" が実在するバッファ (メモリが開放されてい
			 ない) なら 'true' (boolean) を返す。

例:
>
	:lua b = vim.buffer() -- current buffer
	:lua print(b.name, b.number)
	:lua b[1] = "first line"
	:lua b:insert("FIRST!", 0)
	:lua b[1] = nil -- delete top line
	:lua for i=1,3 do b:insert(math.random()) end
	:3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end
	:lua vim.open"myfile"() -- open buffer and set it as current

	function! ListBuffers()
	lua << EOF
	local b = vim.buffer(true) -- first buffer in list
	while b ~= nil do
		print(b.number, b.name, #b)
		b = b:next()
	end
	vim.beep()
	EOF
	endfunction
<
どの Lua のバージョンであるかを見るには: >
	:lua print(_VERSION)

もし LuaJIT を使っているならばこれも使えます: >
	:lua print(jit.version)
<

==============================================================================
8. ウィンドウユーザーデータ				*lua-window*

ウィンドウオブジェクトは Vim のウィンドウを表します。ウィンドウユーザーデータ
"w" は以下のプロパティとメソッドを持っています:

プロパティ
----------
	o "w()"		"w" をカレントウィンドウに設定する。
	o "w.buffer"	ウィンドウ "w" のバッファ (読込専用)。
	o "w.line"	ウィンドウ "w" のカーソルの行。
	o "w.col"	ウィンドウ "w" のカーソルの列。
	o "w.width"	ウィンドウ "w" の幅。
	o "w.height"	ウィンドウ "w" の高さ。

メソッド
--------
	o "w:next()"	 "w" の次のウィンドウを返す。
	o "w:previous()" "w" の前のウィンドウを返す。
	o "w:isvalid()"	ウィンドウ "w" が実在するウィンドウ (メモリが開放され
			ていない) なら 'true' を返す。

例:
>
	:lua w = vim.window() -- current window
	:lua print(w.buffer.name, w.line, w.col)
	:lua w.width = w.width + math.random(10)
	:lua w.height = 2 * math.random() * w.height
	:lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end
	:lua print("There are " .. n .. " windows")
<

==============================================================================
9. luaeval() Vim 関数					*lua-luaeval* *lua-eval*

"luaeval" は "vim.eval" と対となる関数で Lua の値を Vim に渡すことができます。
"luaeval" は式文字列と任意の引数を受け取り、式の結果を返します。意味的には次の
Lua コードと同じです:
>
	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 "_A" には "luaeval" の引数が渡されます。Lua の数値、文字列、リスト、Blob、
辞書そして Funcref ユーザーデータはそれぞれの Vim の型に変換されます。ただし、
Lua のブール値は数値に変換されます。リスト、辞書および関数参照以外のユーザーデ
ータを含む、それ以外の Lua の型を変換しようとするとエラーが返されます。

例: >

	:echo luaeval('math.pi')
	:lua a = vim.list():add('newlist')
	:let a = luaeval('a')
	:echo a[0] " 'newlist'
	: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)


==============================================================================
10. 動的ローディング					*lua-dynamic*

MS-Windows と Unix では Lua ライブラリを動的にロードすることができます。
|+lua/dyn| が |:version| の出力に含まれている時に利用できます。

これにより、Vim は必要な時だけ Lua DLL もしくは共有ライブラリを検索します。
もしあなたが Lua インターフェイスを必要としておらず使わなければ Lua DLL もしく
は共有ライブラリ無しで Vim を使うことができます。

MS-Windows ~

Lua インターフェイスを利用するには Lua DLL が検索パス内になければなりません。
コンソールウィンドウ内で "path" と入力し、どのディレクトリが使われているかを
確認してください。'luadll' オプションで Lua の DLL を指定する事ができます。
DLL のバージョンは Vim と共にコンパイルされた Lua のバージョンと一致していな
ければなりません。

Unix ~

コンパイル時に指定された DYNAMIC_LUA_DLL ファイルの代わりに 'luadll'
オプションで Lua 共有ライブラリを指定できます。共有ライブラリのバージョンは
Vim と共にコンパイルされた Lua のバージョンと一致していなければなりません。


==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl: