Lua 5.1 リファレンスマニュアル
Lua 5.1 リファレンスマニュアル
Lua 5.1 リファレンスマニュアル
Copyright © 2006 Lua.org, PUC-Rio. All rights reserved.
この文書は、 Lua 5.1 Reference Manual を原著者に無断で日本語に訳した、非公式の Lua 5.1 リファレンスマニュアルである。
Luaは拡張プログラミング言語である。 データ記述機能を持ち、汎用の手続き型プログラミングをサポートするようデザインされた。 オブジェクト指向プログラミング、関数型プログラミング、データ駆動型プログラミングもサポートしている。 Luaは、パワフルで軽いスクリプト言語として、それらが必要なあらゆるプログラムに使われることを意図している。 Luaは クリーンな C (つまり、ANSI C と C++ の共通のサブセット) で書かれ、ライブラリとして実装されている。
拡張言語であるため、Luaは「メイン」プログラムを持たない。
ホストクライアント (エンベッディングプログラム、あるいは単にホスト とも呼ぶ) に 組み込まれて 動くだけである。
このホストプログラムは、Luaコードを実行する関数を呼び出したり、Luaの変数を読み書きしたり、Luaから呼ばれるCの関数を登録したりできる。
Cの関数を使ってカスタマイズすることで、共通の構文を持つプログラミング言語で様々な領域を広範囲にカバーすることができる。
Luaのディストリビューションには lua と呼ばれるサンプルのホストプログラムが含まれている。
これはLuaライブラリを使った完全なスタンドアロンのLuaインタプリタを提供している。
Luaはフリーソフトウェアであり、ライセンスにも書かれているように、いかなる保証もなくあるがまま提供される。
このマニュアルに記述されている実装はLuaの公式ウェブサイト www.lua.org で提供されている。
他のすべてのリファレンスマニュアルと同様、この文書はあちこちが無味乾燥である。 Luaのデザインの背後にある決定についての議論は、Luaのウェブサイトにある技術文書を参照のこと。 Luaによるプログラミングの詳しい紹介は、Roberto著 Programming in Lua を参照。
このセクションでは、Luaの字句、構文、意味論について記述する。 言い換えると、このセクションでは、どういったトークンが有効か、それらをどう組み合わせられるのか、そしてその組み合わせは何を意味するのかについて記述している。
言語構造は一般的な拡張BNF記法を使って説明する。
{a} は a の0回以上の繰り返し、[a] は a が省略可能であることを表す。
非終端記号は italic で表され、キーワードは bold、他の終端記号はシングルクォートで囲まれた type writer フォントで表現される。
Luaの完全な構文はこのマニュアルの最後にある。
Luaの 名前 (識別子 とも呼ばれる) は、文字、数字、アンダースコアを組み合わせた任意の文字列である。 ただし数字で始まってはならない。 これは多くの言語の名前の定義に一致する。 「文字」の定義は現在のロケールに依存する。 現在のロケールでアルファベットとみなされる文字はどれも識別子に使える。 識別子は名前変数やテーブルフィールドに使われる。
以下の キーワード は予約されており、名前としては使えない。
and break do else elseif
end false for function if
in local nil not or
repeat return then true until while
Lua は大文字小文字を区別する言語である。
and は予約語だが、And と AND は、2つの異なった、有効な名前である。
慣習的に、アンダースコアと大文字で始まる名前 (例えば _VERSION) は、
Luaが使う内部のグローバル変数として予約されている。
以下の文字列は、その他のトークンである。
+ - * / % ^ #
== ~= <= >= < > =
( ) { } [ ]
; : , . .. ...
文字列リテラル は対になるシングルクォートかダブルクォートで囲まれ、 以下の C のようなエスケープシーケンスを含むことができる。
\a --- ベル
\b --- バックスペース
\f --- 改ページ
\n --- 改行
\r --- 復帰
\t --- 水平タブ
\v --- 垂直タブ
\\ --- バックスラッシュ (円記号)
\" --- 引用符 (ダブルクォート)
\' --- アポストロフィ (シングルクォート)
上記に加えて、
`\改行´
(バックスラッシュに本物の改行が続いたもの)
を記述して文字列中に改行を含めることができる。
さらに `\ddd´ (dddは最大3桁の10進数) というエスケープシーケンスを使って
文字列中の文字をそのコード値で指定することもできる。
(数値エスケープの後に数字が続く場合は、ぴったり3桁使って表現しなければならない。)
Luaの文字列は `\0´ で表されるゼロを含み、いかなる8ビット値も含むことができる。
ダブル(またはシングル)クォートで囲まれた文字列リテラルの中に、 ダブル(またはシングル)クォート、改行、バックスラッシュ、または埋め込まれたゼロを置くためには、 エスケープシーケンスを使わなければならない。 他のすべての文字は直接リテラルの中に入れて構わない (ファイルシステムに対しては制御文字が問題を起こすかもしれないが、Luaは大丈夫である。)
文字列リテラルは 長括弧 で囲む長い形式を使って定義することもできる。
n 段の開き長括弧 は、
開き角括弧に n 個のイコールと、さらに開き角括弧を続けたものである。
つまり、0段の開き長括弧は [[ と書き、
1段の開き長括弧は [=[ と書き、以下同様である。
閉じ長括弧 も同様である。
例えば4段の閉じ長括弧は ]====] と書く。
長い文字列は任意の段数の開き長括弧で始まり、同じ段数の閉じ長括弧で終わる。
この角カッコ形式のリテラルは、複数行に渡って記述できる。
エスケープシーケンスは一切解釈されず、異なる段数の閉じ長括弧は無視する。
これは、正しい段数の閉じ長括弧と埋め込まれたゼロ以外の任意の内容を入れられる。
便利なように、開き長括弧のすぐ後に改行が続いたときは、その改行は文字列に含まれない。
例えば、ASCII (つまり `a´ が97、改行が10、`1´ が49であるような文字コード)
が使われているシステムでは、
以下の4つのリテラルは同じ文字列を表現している。
(1) 'alo\n123"'
(2) "alo\n123\""
(3) '\97lo\10\04923"'
(4) [[alo
123"]]
(5) [==[
alo
123"]==]
数値定数 には省略可能な小数部と省略可能な指数部を書くことができる。
Luaは接頭辞 0x を付けた整数の16進定数も受け付ける。
有効な数値定数の例を挙げると
3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
コメント は文字列の外ならどこでも、二つのハイフン (--) で始めることができる。
もし -- の直後に開き長括弧以外のテキストがあれば、そのコメントは 短いコメント であり、行末まで続く。
そうでなければ、それは 長いコメント であり、対応する閉じ長括弧まで続く。
長いコメントはコードを一時的に無効にするためによく使われる。
Luaは 動的な型の言語 である。 つまり、変数は型を持たず、値が型を持つ。 型定義の構文はない。 すべての値は自分自身で型を保持している。
Luaのすべての値は ファーストクラスの値 である。 つまり、いかなる値も変数に格納でき、他の関数に引数で渡すことができ、戻り値として返すことができる。
Luaには8つの基本型がある。
nil、ブーリアン、数値、文字列、関数、ユーザーデータ、スレッド、テーブル である。
nil は nil 値の型である。その主な性質は他のいかなる値とも異なることであり、通常、役に立つ値がないことを表す。
ブーリアン は false と true の値を持つ型である。
nil と false は共に条件判断で偽となり、他の値は真となる。
数値 は実数 (double) を表現する。
(しかし数値の内部表現としてfloatやlongなど他の型を使うようLuaインタプリタをビルドし直すのは簡単である。
ファイル luaconf.h を参照。)
文字列 は文字の配列を表現する。
Luaは8ビットクリーンであり、
文字列にはゼロ (`\0´) を含むいかなる8ビット文字も含むことができる (2.1 を参照)。
LuaはLuaで書かれた関数もCで書かれた関数も呼べる (2.5.8 を参照)。
ユーザーデータ は任意のCのデータをLuaの変数に格納するために用意された。 この型は生のメモリブロックに相当し、代入と等価比較を除いて、Luaでは演算が定義されていない。 しかしながら、メタテーブル を用いることで、 プログラマはユーザーデータに対する演算を定義することができる (2.8 を参照)。 ユーザーデータはLua内で作ったり変更することはできず、CのAPIを通してのみ可能である。 これは完全にホストプログラムに所有されたデータであることを保証する。
スレッド は実行されているそれぞれのスレッドを表現し、コルーチンを実装するために使われる (2.11 を参照)。 LuaのスレッドとOSのスレッドを混同しないように。 Luaはスレッドをサポートしないシステム上でもコルーチンをサポートする。
テーブル は連想配列である。
すなわち数値だけでなく任意の値 (nil を除く) をキーにできる配列である。
テーブルは 異種混合 できる。
つまりあらゆる型の値 (nil を除く) を持つことができる。
テーブルはLuaの唯一のデータ構造であり、
普通の配列の他、記号表、集合、レコード、グラフ、ツリーなどを表現するために使われる。
レコードを表現するときは、フィールド名をインデックスとして使う。
このための a.name という表現が a["name"] のシンタックスシュガーとして用意されている。
また、Luaでテーブルを作るための便利な表現がいくつかある (2.5.7 を参照)。
インデックスと同様、テーブルフィールドの値には任意の型 (nil を除く) を格納できる。 特に、関数がファーストクラスであるため、テーブルフィールドは関数を格納することができる。 そのためテーブルは メソッド を持つことができる (2.5.9 を参照)。
テーブル、関数、スレッド、ユーザーデータの値は オブジェクト である。 変数はこれらの実際の値は持たず、それらを 参照 しているだけである。 代入、引数渡し、関数の戻り値は、常に値への参照を扱い、値のコピーは行われない。
ライブラリ関数 type は与えられた値の型を表す文字列を返す。
Luaは文字列と数値を実行時に自動的に変換する。
すべての数学演算は、文字列に適用されると、一般的な変換ルールに基づいてその文字列を数値に変換しようとする。
逆に、文字列が期待されるところで数値が使れると、その数値は一般的な形式の文字列に変換される。
数値が文字列に変換される方法を完璧にコントロールする場合は、
文字列ライブラリの format 関数を使う (string.format を参照)。
変数は値を格納する場所である。 Luaには、グローバル変数、ローカル変数、テーブルフィールドの三種類の変数がある。
単発の名前はグローバル変数かローカル変数を表す (または関数の仮引数かもしれないが、それはローカル変数の一種である)。
var ::= Name
(2.1 を参照) で定義されているように、名前は識別子を表す。
明示的にローカルと宣言されない限り、変数はグローバルとみなされる (2.4.7 を参照)。 ローカル変数は レキシカルスコープ を持ち、 そのスコープ内で定義された関数から自由にアクセスできる (2.6 を参照)。
最初の代入が行われる前の変数の値は nil である。
テーブルをインデックス付けするためには角カッコを使う。
var ::= prefixexp `[´ exp `]´
最初の式 (prefixexp) はテーブル、 二番目の式 (exp) はテーブル内のエントリを指定する値でなければならない。 テーブルのインデックスを指定する式は限定された構文を持つ。 詳細は 2.5 を参照。
構文 var.Name は var["Name"] の単なるシンタックスシュガーであり、
テーブルフィールドを示すために使う。
var ::= prefixexp `.´ Name
グローバル変数とテーブルフィールドへアクセスする効果はメタテーブルによって変えられる。
インデックス付き変数 t[i] へのアクセスは
gettable_event(t,i) の呼び出しと等価である
(gettable_event 関数の完全な説明は 2.8 を参照。
この関数はLuaで定義したり呼ぶことはできず、単に説明のため用いているだけである)。
すべてのグローバル変数は、環境テーブル または単に 環境 (2.9 を参照) と呼ばれる通常のLuaのテーブル内に、フィールドとして存在している。
各関数はそれぞれ独自に環境への参照を持ち、
その関数内でのすべてのグローバル変数は、その環境テーブルを参照する。
関数が作られたとき、関数は、それが作られた関数から見える環境を受け継ぐ。
Luaの関数の環境テーブルを取得するには getfenv を呼ぶ。
変更するには setfenv を呼ぶ。
(Cの関数の環境はデバッグライブラリでのみ操作できる (5.9 を参照)。)
グローバル変数 x へのアクセスは _env.x と等価であり、
以下と等価である。
gettable_event(_env, "x")
ただし、_env は関数が実行されている環境を表す
(gettable_event 関数の完全な説明は 2.8 を参照。
この関数はLuaで定義したり読んだりできない。
同様に変数 _env はLuaで定義されていない。
これはただ説明のために用いているだけである)。
LuaはPascalやCと同じように一般的な文のセットをサポートしている。 代入、制御構造、関数呼び出し、テーブルコンストラクタや変数の宣言などである。
Luaの実行の単位は チャンク と呼ばれる。 チャンクは、単純に、順番に実行される文の連なりである。 それぞれの文末には省略可能なセミコロンを置いても良い。
chunk ::= {stat [`;´]}
空文は存在しないため、`;;´ は許されていない。
Luaはチャンクを、可変個の引数を持つ無名関数の本体として扱っている (2.5.9 を参照)。 従って、チャンクはローカル変数を宣言でき、引数を受け取ることができ、戻り値を返せる。
チャンクはファイルやホストプログラム内の文字列として格納されているであろう。 チャンクが実行されるとき、まず仮想マシンの命令にコンパイルされ、それからコンパイル済みコードが仮想マシンのインタプリタによって実行される。
チャンクはバイナリ形式のコンパイル済みコードであっても良い。
詳細は luac プログラムを参照。
ソースプログラムとコンパイル済み形式はどちらを用いても良い。
Luaは自動的にファイル形式を検出し、適切に振る舞う。
文の列はブロックである。 構文的には、ブロックはチャンクと等しい。
block ::= chunk
ブロックは明示的に単一の文とすることもある。
stat ::= do block end
明示的なブロックは変数宣言スコープをコントロールするのに便利である。 明示的なブロックはまた、 他のブロックの途中に return 文や break 文を入れるために使うこともある。
Luaは多重代入を許している。 だから、代入文では左辺に変数リスト、右辺に式リストを書く。 どちらのリストもそれぞれの要素をカンマで区切る。
stat ::= varlist1 `=´ explist1
varlist1 ::= var {`,´ var}
explist1 ::= exp {`,´ exp}
式については 2.5 で議論する。
代入の前に、値リストは変数リストの長さに調節される。 もし必要な数よりも値が多ければ、余分な値は捨てられる。 もし必要な数よりも値が少なければ、必要なだけ nil が追加される。 もし式リストの最後が関数呼び出しなら、調節の前に、その関数のすべての戻り値が値リストに追加される (ただし呼び出しをカッコで囲った場合を除く、2.5 を参照)。
代入文は、まずすべての式を評価し、それから、代入が行われる。 だから、このコード
i = 3
i, a[i] = i+1, 20
は、i に4が代入される前に a[i] の i が (3に) 評価されるため、
a[3] に20が代入される。
a[4] は何の影響もない。
同様に、
x, y = y, x
は x と y の値を交換する。
グローバル変数とテーブルフィールドへの代入の効果は、メタテーブルによって変えられる。
インデックス付き変数への代入 t[i] = val は
settable_event(t,i,val) と等価である
(settable_event 関数の完全な記述は 2.8 を参照。
この関数はLuaで定義したり呼ぶことはできず、
ただ説明のため用いているだけである)。
グローバル変数への代入 x = val は代入 _env.x = val と等価であり、
以下と等価である。
settable_event(_env, "x", val)
ただし、_env は関数が実行されている環境を表す
(変数 _env はLuaに定義されていない。
これはただ説明のために用いているだけである)。
制御構造 if、while、repeat は一般的な意味とよく知られた構文をしている。
stat ::= while exp do block end
stat ::= repeat block until exp
stat ::= if exp then block {elseif exp then block} [else block] end
Luaには for 文もある。 これは2つの種類がある (2.4.5 を参照)。
制御構造の条件式は任意の値をとれる。 false と nil は共に偽である。 nil と false 以外のすべての値は真になる (特に、数値の0や空文字列は真であることに注意)。
repeat--until ループでは、 内側のブロックは until キーワードのところではなく条件式の後に終わる。 つまり、条件式はループブロックの内側で宣言されたローカル変数を参照できる。
return 文は関数やチャンク (これはただの関数である) から値を返すために使う。 関数やチャンクは1個以上の値を返すことができる。 return 文の構文は以下の通り。
stat ::= return [explist1]
break 文は while、repeat、for ループの実行を終了し、 ループの次までスキップする。
stat ::= break
break は最も内側のループを終わらせる。
return 文と break 文はブロックの 最後 の文としてのみ書くことが許される。 return や break をブロックの途中で使うことが本当に必要なら、 明示的な内部ブロックを使う次のような慣用句を使えば良い。
do return end
do break end
これで return も break も (内部) ブロックの最後の文になる。
for 文には、数値用と汎用の2つの形式がある。
数値用 for ループは制御変数が等差数列を辿ってコードブロックを繰り返す。 以下がその構文である。
stat ::= for Name `=´ exp `,´ exp [`,´ exp] do block end
block は name が最初の exp で始まって二番目のexp に達するまで、 三番目の exp ずつ進む間、繰り返される。 より正確には、次のような for 文
for var = e1, e2, e3 do block end
は次のコードに等しい。
do
local _var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3)
if not (_var and _limit and _step) then error() end
while (_step>0 and _var<=_limit) or (_step<=0 and _var>=_limit) do
local var = _var
block
_var = _var + _step
end
end
以下の点に注意:
_var、_limit、_step は見えない変数である。
この名前は説明のために用いられているだけである。
var はループ内でローカルである。
for 文の外側でその値を使うことはできない。
もしループ変数 var の値が必要なら、
ループを出る前に別の変数に代入する必要がある。
汎用 for 文は イテレータ と呼ばれる関数を通して働く。 それぞれの繰り返しについて、新しい値を生成するためにイテレータ関数が呼ばれ、nil になったところで止まる。 汎用 for ループは以下の構文である。
stat ::= for Name {`,´ Name} in explist1 do block end
次のような for 文
for var_1, ..., var_n in explist do block end
は次のコードと等価である。
do
local _f, _s, _var = explist
while true do
local var_1, ... , var_n = _f(_s, _var)
_var = var_1
if _var == nil then break end
block
end
end
以下の点に注意:
explist は一度だけ評価され、
イテレータ 関数、状態、繰り返し変数 の初期値、でなければならない。
_f、_s、_var は見えない変数である。
この名前は説明のために用いられているだけである。
var はループ内でローカルである。
for 文の外側でその値を使うことはできない。
もしループ変数 var の値が必要なら、
ループを出る前に別の変数に代入する必要がある。
副作用を許しているため、関数呼び出しは文として実行できる。
stat ::= functioncall
この場合、戻り値はすべて捨てられる。 関数呼び出しは 2.5.8 で説明する。
ローカル変数はブロックの中どこででも宣言できる。 宣言は初期値の代入を伴ってもよい。
stat ::= local namelist [`=´ explist1]
もしあれば、多重代入と同じ構文で初期値が代入される (2.4.3 を参照)。 そうでなければ、変数はすべて nil で初期化される。
チャンクもまたブロックであるから (2.4.1 を参照)、 明示的なブロックの外側のチャンクでもローカル変数を宣言できる。 そのようなローカル変数のスコープはチャンクの終わりまで続く。
ローカル変数の可視ルールは 2.6 で説明する。
Luaの基本の式を以下に示す。
exp ::= prefixexp exp ::= nil | false | true exp ::= Number exp ::= String exp ::= function exp ::= tableconstructor exp ::= `...´ exp ::= exp binop exp exp ::= unop exp prefixexp ::= var | functioncall | `(´ exp `)´
数値と文字列リテラルは 2.1 で説明した。 変数は 2.3 で説明した。 関数定義は 2.5.9 で説明する。 関数呼び出しは 2.5.8 で説明する。 テーブルコンストラクタは 2.5.7 で説明する。 3つのドットで表される可変引数式は、可変引数関数の中でだけ使える。 これは 2.5.9 で説明する。
二項演算子は算術演算子 (2.5.1 を参照)、 関係演算子 (2.5.2 を参照)、 論理演算子 (2.5.3 を参照) がある。 単項演算子は単項マイナス (2.5.1 を参照)、 単項 not (2.5.3 を参照)、 そして単項 長さ演算子 (2.5.5 を参照) がある。
関数呼び出しと可変引数式は複数の値を返す。 式が文として使われた場合 (2.4.6 を参照) (関数呼び出しに対してのみ可能)、 結果のリストはゼロ個に調節され、つまりすべての戻り値が捨てられる。 他の式の中やリストの途中で使われた場合は、 結果のリストは1個に調節され、残りはすべて捨てられる。 式がリストの最後の要素として使われた場合は、 調節は行われない (カッコで囲った場合を除く)。
いくつか例を挙げる。
f() -- 戻り値は0個に調節される
g(f(), x) -- f()の戻り値は1個に調節される
g(x, f()) -- xに加えてf()のすべての戻り値をgに渡す
a,b,c = f(), x -- f()の戻り値は1個に調節される (そしてcにはnilが入る)
a,b = ... -- aに可変引数の最初の値、bに2番目の値が入る
-- (対応する引数がなかった場合、a、bにはnilが入る)
a,b,c = x, f() -- f()の戻り値は2個に調節される
a,b,c = f() -- f()の戻り値は3個に調節される
return f() -- f()の戻り値をすべて返す
return ... -- 渡された可変引数をすべて返す
return x,y,f() -- x、yとf()のすべての戻り値を返す
{f()} -- f()のすべての戻り値からなるリストを作る
{...} -- 渡された可変引数すべての値からなるリストを作る
{f(), nil} -- f()の戻り値が1個に調節される
カッコに囲まれた式は常にただ1つの値を返す。
つまり、たとえ f が複数の値を返しても、(f(x,y,z)) は常に単一の値となる。
(f(x,y,z)) の値は、f が返す最初の値である。
あるいは f が何も返さなければ、nil となる。
Luaは一般的な算術演算子をサポートしている。
+ (加算)、
- (減算)、* (乗算)、
/ (除算)、% (剰余)、^ (累乗)、
および単項の - (符号反転)。
もしオペランドが数値、あるいは数値に変換できる文字列 (2.2.1を参照)
なら、すべての演算は通常の意味を持つ。
累乗は任意の指数に対して動作する。
例えば、x^(-0.5) は x の平方根の逆数を計算する。
剰余は以下のように定義されている。
a % b == a - math.floor(a/b)*b
つまり、負の無限大に向かって丸められた割り算の余りである。
Luaの関係演算子は以下の通りである。
== ~= < > <= >=
これらの演算子は常に false か true いずれかの結果を返す。
等価 (==) はまずオペランドの型を比較する。
もし型が異なっていたら、結果は false である。
そうでなければ、オペランドの値が比較される。
数値と文字列は一般的な方法で比較する。
オブジェクト (テーブル、ユーザーデータ、スレッド、関数) は 参照 を比較し、
2つのオブジェクトが 同じ オブジェクトである場合だけを等しいとみなす。
新しいオブジェクト (テーブル、ユーザーデータ、関数) を作ったときは常に、
この新しいオブジェクトは、以前に存在していたオブジェクトと異なる。
"eq"メタメソッドを使って、テーブルやユーザーデータをLuaが比較する方法を変えられる (2.8 を参照)。
2.2.1 の変換ルールは等価比較には適用されない。
そのため、"0"==0 は false に評価され、
t[0] と t["0"] は異なったテーブルエントリを示す。
演算子 ~= は正確に等価 (==) の否定である。
関係演算子は次のように働く。 引数が両方数値ならば、それらは適切に比較される。 もし両方の引数が文字列ならば、現在のロケールに従ってその値が比較される。そうでなければ、Luaは"lt"または"le"メタメソッドを試みる (2.8 を参照)。
Luaの論理演算子は次の通りである。
and or not
制御構造 (2.4.4 を参照) と同じく、 すべての論理演算子は false と nil の両方を偽、それ以外のすべてを真とみなす。
否定演算子 not は常に false か true を返す。 論理積演算子 and は、最初の引数が false か nil ならその値を返し、そうでなければ二番目の引数を返す。 論理和演算子 or は最初の引数が false か nil 以外ならその値を返し、そうでなければ二番目の引数を返す。 and と or は共にショートカット評価を行う。 つまり、二番目のオペランドは、それが必要なときだけ評価される。 いくつかの例を示す。
10 or 20 --> 10
10 or error() --> 10
nil or "a" --> "a"
nil and 10 --> nil
false and error() --> false
false and nil --> false
false or nil --> nil
10 and 20 --> 20
(このマニュアルでは `-->´ で式の結果を示す。)
Luaの文字列連結演算子はふたつのドット (`..´) で表す。
もし両方のオペランドが文字列か数値なら、それらは 2.2.1 で述べたルールに従って文字列に変換される。
そうでなければ、"concat"メタメソッドが呼ばれる (2.8 を参照)。
長さ演算子は単項演算子 # で表される。
文字列の長さはそのバイト数である
(つまり、各文字が1バイトだとした場合の、文字列の長さである)。
テーブル t の長さは、
t[n] が nil でなく t[n+1] が nil であるような整数 n と定義されている。
また、t[1] が nil なら n はゼロになりうる。
nil でない値が1から n まで格納されている普通の配列では、
その長さは最後のインデックス n を正しく返す。
配列に「穴」がある場合
(つまり間に nil がある場合)、
#t はどれかの nil のひとつ前を返すかもしれない
(つまり、その nil が配列の終わりであるように見えるのだ)。
Luaでの演算子の優先順位を以下の表に示す。 優先順位は低い方から順に
or
and
< > <= >= ~= ==
..
+ -
* / %
not # - (unary)
^
普通通りに、カッコを使って式の優先順位を変えることができる。
連結 (`..´) と累乗 (`^´) は右結合である。
他の二項演算子はすべて左結合である。
テーブルコンストラクタはテーブルを作る式である。 コンストラクタが評価されるたびに新しいテーブルが作られる。 空のテーブルを作ることも、いくつかのフィールドに初期値を持ったテーブルを作ることもできる。 コンストラクタの構文は以下の通りである。
tableconstructor ::= `{´ [fieldlist] `}´
fieldlist ::= field {fieldsep field} [fieldsep]
field ::= `[´ exp `]´ `=´ exp | Name `=´ exp | exp
fieldsep ::= `,´ | `;´
[exp1] = exp2 形式のフィールドは、
キー exp1 と値 exp2 を持つエントリをテーブルに追加する。
name = exp 形式のフィールドは ["name"] = exp と等価である。
最後の exp 形式のフィールドは、[i] = exp と同じである。
ここで i は1から始まる連続した整数であり、他の形式のフィールドはこのカウンタに影響を与えない。
例えば
a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
は以下と等価である。
do
local t = {}
t[f(1)] = g
t[1] = "x" -- 最初のexp
t[2] = "y" -- 2番目のexp
t.x = 1 -- temp["x"] = 1
t[3] = f(x) -- 3番目のexp
t[30] = 23
t[4] = 45 -- 4番目のexp
a = t
end
もし最後のフィールドが exp 形式で、その式が関数呼び出しか可変引数式であれば、
その戻り値がすべてリストに追加される (2.5.8 を参照)。
これを避けるには、関数呼び出し(あるいは可変引数式)をカッコで囲む (2.5 を参照)。
自動生成コードに便利なように、各フィールドの終わりに省略可能なセミコロンを付けても良い。
Luaの関数呼び出しは以下の構文である。
functioncall ::= prefixexp args
関数呼び出しでは、 まず prefixexp と args が評価される。 もし prefixexp の値が 関数 であれば、与えられた引数でその関数が呼ばれる。 そうでなければ、prefixexp の "call" メタメソッドが呼ばれる。 そのとき prefixexp が最初の引数として渡され、二番目以降に元々の引数が続く (2.8 を参照)。
書式
functioncall ::= prefixexp `:´ Name argsは「メソッド」と呼ばれる。 呼び出し
v:name(...) は v.name(v, ...) のシンタックスシュガーであり、
v の評価がただ一度である点だけが異なる。
引数は以下の構文を持つ。
args ::= `(´ [explist1] `)´ args ::= tableconstructor args ::= String
引数のすべての式は呼び出し前に評価される。
f{...} は f({...}) のシンタックスシュガーであり、新しいテーブルひとつが引数となる。
f'...' (および f"..." や f[[...]]) は
f('...') のシンタックスシュガーであり、引数は文字列リテラルひとつである。
Luaのフリーフォーマット構文の例外として、
関数呼び出しの `(´ の直前で改行することはできない。
この制限によって言語の曖昧さが避けられる。
つまり、この制限がなかった場合、もし次のように書くと
a = f
(g).x(a)
Luaは単一の式 a = f(g).x(a) と解釈したかもしれない。
この場合、2つの文にしたければ間にセミコロンが必要である。
だか実際には、f を呼びたければ (g) の前の改行を取り除かなければならない。
return functioncall のような呼び出し形式は 終端呼び出し と呼ばれる。
Luaは 終端呼び出し最適化 (または 終端再帰最適化) を実装している。
終端呼び出しでは、呼び出された関数は呼び出し側関数のスタックエントリを再利用する。
その結果、終端呼び出しのネスト数の制限なしに (無限に再帰呼び出しして) プログラムを実行できる。
しかしながら、終端呼び出しは呼び出し側関数に関するデバッグ情報を消してしまう。
終端呼び出しは、単一の関数呼び出しで return するという特別な状況でのみ起こることに注意。
この構文では、呼び出した関数の戻り値がそのまま呼び出し側関数の戻り値になる。
よって、以下の例はどれも終端呼び出しではない。
return (f(x)) -- 戻り値が1個に調節されている
return 2 * f(x) -- 戻り値が加工されている
return x, f(x) -- 戻り値が追加されている
f(x); return -- 戻り値が捨てられている
return x or f(x) -- 戻り値が1個に調節されている
関数定義の構文を以下に示す。
function ::= function funcbody funcbody ::= `(´ [parlist1] `)´ block end
以下のシンタックスシュガーは関数定義を単純化する。
stat ::= function funcname funcbody
stat ::= local function Name funcbody
funcname ::= Name {`.´ Name} [`:´ Name]
以下の文
function f () ... end
は次のように変換される。
f = function () ... end
以下の文
function t.a.b.c.f () ... end
は次のように変換される。
t.a.b.c.f = function () ... end
以下の文
local function f () ... end
は次のように変換される。
local f; f = function () ... end
次のようにではない。
local f = function () ... end
(この違いは、関数の中で f を参照できるかどうかである。)
関数定義は実行可能な式であり、関数 型の値を持つ。 Luaがチャンクをコンパイルすると、 その中にある関数の本体もコンパイルされる。 そして、Luaが関数定義を実行したとき、 関数は インスタンス化 (または クローズ) される。 この関数インスタンス (または クロージャ) は式の最終的な値である。 同じ関数の異なるインスタンスは異なるローカル変数と異なる環境テーブルを参照する場合がある。
仮引数はローカル変数として振る舞い、渡された実引数の値で初期化される。
parlist1 ::= namelist [`,´ `...´] | `...´
関数が呼ばれると、実引数リストは仮引数リストの長さに調節される。
ただし、仮引数リストの最後が3つのドット (`...´) である
可変引数 の場合を除く。
可変引数では実引数が調節されず、
代わりに余分の実引数はすべて 可変引数式 によって関数に渡される。
可変引数式もまた3つのドットで書く。
この式の値は、すべての余分の実引数からなるリストである。
これは複数の戻り値を持つ関数に似ている。
可変引数式が他の式の中やリストの途中で使われた場合は、
結果のリストは要素が1個に調節される。
リストの最後の要素で使われた場合は、
調節は行われない(カッコで囲った場合を除く)。
例として、以下の定義を考える。
function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end
この場合、実引数から仮引数と可変引数式へ以下のようにマッピングされる。
呼び出し 仮引数
f(3) a=3, b=nil
f(3, 4) a=3, b=4
f(3, 4, 5) a=3, b=4
f(r(), 10) a=1, b=10
f(r()) a=1, b=2
g(3) a=3, b=nil, ... --> (なし)
g(3, 4) a=3, b=4, ... --> (なし)
g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
g(5, r()) a=5, b=1, ... --> 2 3
関数の結果を返すには return 文を使う (2.4.4 を参照)。 return 文に出会わずに制御が関数の終わりまで達したら、関数は何も返さない。
コロン 構文を使って メソッド を定義できる。
メソッドとは、暗黙の引数 self を余分に持つ関数である。
つまり、以下の構文
function t.a.b.c:f (...) ... end
は、以下の文のシンタックスシュガーである。
t.a.b.c.f = function (self, ...) ... end
Luaはレキシカルスコープを持つ言語である。 変数のスコープは、それが宣言された文の 次 から始まり、 その宣言を含む最も内側のブロックのendで終わる。 以下の例を考えよう。
x = 10 -- グローバル変数
do -- 新しいブロック
local x = x -- 新しい変数 `x'、値は 10
print(x) --> 10
x = x+1
do -- 別のブロック
local x = x+1 -- 別の新しい `x'
print(x) --> 12
end
print(x) --> 11
end
print(x) --> 10 (グローバル変数)
local x = x のような宣言に注意。
新しく定義された x はまだスコープに入っていないので、
右辺の x は外側の変数を参照する。
レキシカルスコープのルールにより、 ローカル変数はそのスコープの内側に定義された関数から自由にアクセスできる。 内部関数から使われるローカル変数は、 内部関数の中では 上位値 または 外部ローカル変数 と呼ばれる。
local 文を実行するたびに新しいローカル変数が宣言されることに注意。 以下の例を考えよ。
a = {}
local x = 20
for i=1,10 do
local y = 0
a[i] = function () y=y+1; return x+y end
end
このループは10個のクロージャ (つまり匿名関数の10個のインスタンス) を作る。
クロージャはすべて同じ x を共有するが、
それぞれ異なった y を持つ。
Luaは組み込み拡張言語であるから、
すべてのLuaアクションはホストプログラムのCのコードがLuaライブラリの関数を呼ぶことによってスタートする
(lua_pcall を参照)。
Luaのコンパイル中や実行中でエラーが起きたときは、制御がCに返され、
適切な動作を行うことができる (例えばエラーメッセージを出すとか)。
Luaコードは error 関数を呼ぶことで明示的にエラーを起こすことができる。
もしLua内でエラーを捕らえる必要があれば、
pcall 関数を使えばよい。
Luaのどの値も メタテーブル を持つことができる。
メタテーブル はLuaの通常のテーブルであるが、
その値に対して特殊な演算をしたときの挙動を定義する。
メタテーブルのフィールドを設定することで、オブジェクトの動作をいくつかの面で変えることができる。
例えば、数値以外の値が加算のオペランドになったとき、
Luaはメタテーブルの "__add" フィールドをチェックする。
もしそれが見つかれば、加算を行うためにその関数が呼ばれる。
メタテーブルのキーを イベント、値を メタメソッド と呼ぶ。
前の例でいうと、"add" がイベントで、加算を行う関数がメタメソッドである。
getmetatable 関数で任意の値のメタテーブルを取り出すことができる。
テーブルのメタテーブルは setmetatable 関数で変更できる。
他の型のメタテーブルをLuaで変えることはできない (デバッグライブラリを除く)。
そのためにはCのAPIを使わなければならない。
テーブルとユーザーデータは独立したメタテーブルを持つことができる (複数のテーブルやユーザーデータが同じメタテーブルを共有することもできる)。 他の型の値は、型ごとに単一のメタテーブルを共有する。 つまりすべての数値に対してひとつだけメタテーブルが存在し、 すべての文字列に対してひとつだけメタテーブルが存在し、 以下同様である。
メタテーブルは、算術演算、関係比較、連結、長さ演算子、インデックス付けについて、オブジェクトがどう振る舞うかを制御する。 また、ユーザーオブジェクトに関しては、オブジェクトがガベージコレクトされたときに呼ばれる関数も定義できる。 各演算には イベント と呼ばれる特殊なキーが関連付けられている。 Luaが値に対してこれらの演算を行うとき、 その値がメタテーブルを持っていてイベントが設定されているかチェックされる。 キーに割り当てられた値 (メタメソッド) はLuaがその演算をどう行うかをコントロールする。
メタテーブルがコントロールできる演算を以下に示す。
各演算は関連付けられた名前で区別される。
各演算のキーは、その名前の前に2つのアンダースコア `__´ が付く文字列である。
例えば、"add"演算のキーは、文字列 "__add" である。
これらの演算の効果は、いかに演算が実行されるかを記述したLuaの関数で説明する。
ここにLuaのコードを示しているのは、単に説明のためである。
実際はインタプリタにハードコードされており、この擬似コードよりも効率的に動作する。
ここで使われている関数
(rawget、tonumber など)
は 5.1 に記述されている。
与えられたオブジェクトのメタメソッドを取り出すコードとして、以下の表現を用いているが、
metatable(obj)[event]これは次のように読んでもらいたい。
rawget(metatable(obj) or {}, event)
つまり、メタメソッドへのアクセスで他のメタメソッドを呼び出すことはなく、 オブジェクトがメタメソッドを持っていなくてもエラーを起こすことはない (その場合は単に nil を返す)。
+ 演算。
以下の getbinhandler 関数は二項演算でLuaがどのようにハンドラを選ぶかを定義する。
まずLuaは最初のオペランドについて試みる。
もしその型が、その演算についてハンドラを定義していなければ、
二番目のオペランドを試みる。
function getbinhandler (op1, op2, event) return metatable(op1)[event] or metatable(op2)[event] end
この関数を使って op1 + op2 の挙動を示すと、
function add_event (op1, op2)
local o1, o2 = tonumber(op1), tonumber(op2)
if o1 and o2 then -- 両方のオペランドが数値か?
return o1 + o2 -- この `+´ はプリミティブな加算
else -- 少なくとも片方は数値ではない
local h = getbinhandler(op1, op2, "__add")
if h then
-- 両方のオペランドに対してハンドラを呼ぶ
return h(op1, op2)
else -- ハンドラがない、デフォルトの動作
error("...")
end
end
end
- 演算。
"add"演算と同じように動作する。
* 演算。
"add"演算と同じように動作する。
* 演算。
"add"演算と同じように動作する。
% 演算。
"add"演算と同じように動作する。
Behavior similar to the "add" operation,
プリミティブ演算として o1 - floor(o1/o2)*o2 を使う。
^ (累乗) 演算。
"add"演算と同じように動作する。
プリミティブ演算として関数 pow (Cの数学ライブラリ) を使う。
- 演算。
function unm_event (op)
local o = tonumber(op)
if o then -- オペランドは数値か？
return -o -- この `-´ はプリミティブな符号反転
else -- オペランドは数値でない
-- オペランドからハンドラを取り出す
local h = metatable(op).__unm
if h then
-- オペランドに対してハンドラを呼ぶ
return h(op)
else -- ハンドラがない、デフォルトの動作
error("...")
end
end
end
.. (連結) 演算。
function concat_event (op1, op2)
if (type(op1) == "string" or type(op1) == "number") and
(type(op2) == "string" or type(op2) == "number") then
return op1 .. op2 -- プリミティブ文字列連結
else
local h = getbinhandler(op1, op2, "__concat")
if h then
return h(op1, op2)
else
error("...")
end
end
end
# 演算。
function len_event (op)
if type(op) == "string" then
return strlen(op) -- プリミティブの文字列長
elseif type(op) == "table" then
return #op -- プリミティブのテーブル長
else
local h = metatable(op).__len
if h then
-- オペランドに対してハンドラを呼ぶ
return h(op)
else -- ハンドラがない、デフォルトの動作
error("...")
end
end
end
テーブルの長さの説明は 2.5.5 を参照。
== 演算。
関数 getcomphandler は、比較演算子のメタメソッドをLuaがどのように選ぶかを定義する。
両方のオブジェクトが同じ型で、その演算に対して同じメタメソッドを持つ場合だけ、
メタメソッドが選択される。
function getcomphandler (op1, op2, event) if type(op1) ~= type(op2) then return nil end local mm1 = metatable(op1)[event] local mm2 = metatable(op2)[event] if mm1 == mm2 then return mm1 else return nil end end"eq"イベントは次のように定義される。
function eq_event (op1, op2)
if type(op1) ~= type(op2) then -- 型が異なるか?
return false -- 異なるオブジェクト
end
if op1 == op2 then -- プリミティブのイコール
return true -- オブジェクトは等しい
end
-- メタメソッドを試す
local h = getcomphandler(op1, op2, "__eq")
if h then
return h(op1, op2)
else
return false
end
end
a ~= b は not (a == b) と等価である。
< 演算。
function lt_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 < op2 -- 数値の比較
elseif type(op1) == "string" and type(op2) == "string" then
return op1 < op2 -- 辞書順の比較
else
local h = getcomphandler(op1, op2, "__lt")
if h then
return h(op1, op2)
else
error("...");
end
end
end
a > b は b < a と等価である.
<= 演算。
function le_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 <= op2 -- 数値の比較
elseif type(op1) == "string" and type(op2) == "string" then
return op1 <= op2 -- 辞書順の比較
else
local h = getcomphandler(op1, op2, "__le")
if h then
return h(op1, op2)
else
h = getcomphandler(op1, op2, "__lt")
if h then
return not h(op2, op1)
else
error("...");
end
end
end
end
a >= b は b <= a と等価である。
"le"メタメソッドがなければ、
Luaは a <= b を not (b < a) とみなして"lt"を試みることに注意。
table[key] インデックスアクセス。
function gettable_event (table, key)
local h
if type(table) == "table" then
local v = rawget(table, key)
if v ~= nil then return v end
h = metatable(table).__index
if h == nil then return nil end
else
h = metatable(table).__index
if h == nil then
error("...");
end
end
if type(h) == "function" then
return h(table, key) -- ハンドラを呼ぶか、
else return h[key] -- 演算を繰り返す
end
end
table[key] = value インデックス代入。
function settable_event (table, key, value)
local h
if type(table) == "table" then
local v = rawget(table, key)
if v ~= nil then rawset(table, key, value); return end
h = metatable(table).__newindex
if h == nil then rawset(table, key, value); return end
else
h = metatable(table).__newindex
if h == nil then
error("...");
end
end
if type(h) == "function" then
return h(table, key,value) -- ハンドラを呼ぶか、
else h[key] = value -- 演算を繰り返す。
end
end
function function_event (func, ...)
if type(func) == "function" then
return func(...) -- プリミティブの関数呼び出し
else
local h = metatable(func).__call
if h then
return h(func, ...)
else
error("...")
end
end
end
スレッド、関数、ユーザーデータ型のオブジェクトは、 メタテーブルに加えてもうひとつ、 関連付けれられたテーブルを持つ。 これを 環境 と呼ぶ。 メタテーブル同様、環境も普通のテーブルである。
ユーザーデータに関連付けられた環境はLuaにとっては意味を持たない。 これはプログラマのために、 ユーザーデータにテーブルを関連付ける機能として存在するだけである。
スレッドに関連付けられた環境は グローバル環境 と呼ぶ。
これは、スレッドと、スレッドが作成した
(loadfile、loadstring または load を使って)
ネストされていない関数のデフォルトの環境として使われ、
Cのコードで直接アクセスできる (3.3 を参照)。
Cの関数に関連付けられた環境はCのコードで直接アクセスできる (3.3 を参照)。 またその関数で作成する他のCの関数のデフォルトの環境として使われる。
Luaの関数に関連付けられた環境は、 その関数の中でアクセスするグローバル変数を解決するために使われる (2.3 を参照)。 またその関数で作成する他のLuaの関数のデフォルトの環境として使われる。
setfenv を呼ぶと走行中のスレッドや Lua の関数の環境を変更できる。
getfenv を呼ぶと走行中のスレッドや Lua の関数の環境を取得できる。
他のオブジェクト (ユーザーデータ、Cの関数、他のスレッド) の環境を操作するには、CのAPIを使わなければならない。
Luaは自動的にメモリを管理する。 つまり、新しいオブジェクトのためのメモリ確保や、オブジェクトが要らなくなったときの解放について、悩まなくてよい。 Luaは死んだオブジェクト (もうアクセスできなくなったオブジェクト) を回収する ガベージコレクタ を時々実行することで、自動的にメモリを管理する。 テーブル、ユーザーデータ、関数、スレッド、文字列といったすべてのLuaオブジェクトは自動管理の対象である。
Luaはインクリメンタルマークアンドスイープコレクタを実装している。 ガベージコレクションの周期を制御するために2つの数値、 ガベージコレクタ停止値 と ガベージコレクタステップ係数 を使うことができる。
ガベージコレクタ停止値は、 どれだけ経ったら新しいサイクルを開始するかを制御する。 値が大きいほどコレクタが消極的になる。 1より小さな値にすると、コレクタがすぐに新しいサイクルを開始する。 2にすると、使われているメモリの合計が2倍になったらコレクタが新しいサイクルを開始する。
ステップ係数は、メモリ確保に対するコレクタの相対速度を制御する。 値が大きいほどコレクタは積極的になるが、 各インクリメンタルステップのサイズが大きくなる。 1より小さな値にすると、コレクタは非常に遅くなり、結果としてサイクルが終わらないかもしれない。 デフォルトの2では、メモリ確保の「2倍」の速度でコレクタが動作する。
Cの lua_gc か
Luaの collectgarbage
を呼ぶと、これらの値を変更できる。
いずれもパーセント値で引数を取る
(従って 100 を渡すと 1.00 を意味する)。
これらの関数でコレクタを直接制御できる
(停止させたり再開させたり)。
CのAPIを使う場合、ユーザーデータにガベージコレクタメタメソッドを設定できる (2.8を参照)。 このメタメソッドは ファイナライザ と呼ばれることもある。 ファイナライザはLuaのガベージコレクタを外部リソースと共に使えるようにする (ファイルやネットワーク接続、データベース接続などを閉じたり、独自に確保したメモリを解放するとか)。
メタテーブルに __gc フィールドを持つユーザーデータがガベージになっても、ガベージコレクタはそれをすぐには回収しない。
その代わり、Luaはそれをリストに入れる。
他のオブジェクトの回収が終わったあと、Luaはリスト内のユーザーデータに対して以下の関数と同等のことを行う。
function gc_event (udata)
local h = metatable(udata).__gc
if h then
h(udata)
end
end
各ガベージコレクションサイクルの終わりに、 作られたときと 逆の順番で ユーザーデータのファイナライザが呼ばれる。 つまり、最初に呼ばれるファイナライザは、一番最近に作られたユーザーデータのものである。
弱参照テーブル は 弱参照 な要素を持つテーブルである。 弱参照はガベージコレクタに無視される。 言い換えると、オブジェクトへの参照が弱参照のみであれば、ガベージコレクタはそのオブジェクトを回収してしまう。
弱参照テーブルは、キー、値、あるいはその両方が弱参照である。
弱参照キーを持つテーブルは、キーは回収されるが、その値は回収されない。
弱参照キーと弱参照値の両方を持つテーブルでは、キーも値も回収の対象になる。
キーと値のどちらか一方が回収されると、キーと値のペア全体がテーブルから除去される。
テーブルの弱参照の性質は、メタテーブルの __mode フィールドで制御できる。
もし __mode フィールドが文字列で、文字 `k´ が含まれていたら、テーブルのキーが弱参照となる。
もし __mode フィールドが文字 `v´ を含んでいたら、テーブルの値が弱参照となる。
メタテーブルとして使った後に、そのテーブルの __mode フィールドの値を変更するべきではない。
このメタテーブルで制御されているテーブルの弱参照の挙動が未定義となる。
Luaはコルーチンをサポートしている。 協調的マルチスレッド と呼ばれることもある。 Luaのコルーチンは独立に実行されるスレッドを表現している。 マルチスレッドシステムのスレッドとは違って、 コルーチンはyield関数を呼んで明示的に実行を中断しなければならない。
コルーチンを作るには coroutine.create を呼ぶ。
これはひとつだけ引数をとり、それにコルーチンのメイン関数を渡す。
create 関数は新しいコルーチンを作成し、その スレッド オブジェクトを返す。
コルーチンはすぐには実行されない。
coroutine.create から返されたスレッドを最初の引数に渡して最初に coroutine.resume を呼んだとき、
そのメイン関数の最初の行からコルーチンの実行が始まる。
coroutine.resume に余分の引数を指定すると、それらはコルーチンのメイン関数に渡される。
コルーチンが開始されたら、終わりに達するか yield を呼ぶまで実行される。
コルーチンは2つの方法で実行を終われる。
メイン関数からreturnして (明示的にか、最後の命令が終わって暗黙的にか) 正常終了したときと、
保護されないエラーが起きて異常終了したときである。
最初の場合では、true と、メイン関数からの戻り値を、coroutine.resume が返す。
エラーの場合は、coroutine.resume は false とエラーメッセージを返す。
コルーチンは coroutine.yield を呼ぶことで中断される。
コルーチンが中断されると、対応する coroutine.resume からすぐに戻る。
コルーチンの中で呼ばれた関数の中で中断されても同様である
(つまり、メイン関数から直接的/間接的に呼ばれた、メイン関数以外の関数の中でも)。
この場合も、coroutine.resume は true を返す。
coroutine.yield に引数が渡されていれば、それも返される。
次に同じコルーチンをresumeすると、中断した場所から実行が再開される。
coroutine.resume に余分な引数を渡すと、coroutine.yield からそれらが返される。
coroutine.wrap 関数は coroutine.create と同様にコルーチンを作成するが、
コルーチン自身を返すのではなく、コルーチンをresumeする関数を返す。
その関数に渡された引数は coroutine.resume に追加の引数として渡される。
coroutine.resume からの戻り値は、最初のひとつ (ブーリアン型のエラーコード) を除いた残りが返される。
coroutine.resume と違って、
この関数はエラーを捕らえることはなく、内部で起きたエラーは呼び出した側に伝搬する。
例として、次のコードを考える。
function foo (a)
print("foo", a)
return coroutine.yield(2*a)
end
co = coroutine.create(function (a,b)
print("co-body", a, b)
local r = foo(a+1)
print("co-body", r)
local r, s = coroutine.yield(a+b, a-b)
print("co-body", r, s)
return b, "end"
end)
print("main", coroutine.resume(co, 1, 10))
print("main", coroutine.resume(co, "r"))
print("main", coroutine.resume(co, "x", "y"))
print("main", coroutine.resume(co, "x", "y"))
これを実行すると、以下の出力を得る。
co-body 1 10 foo 2 main true 4 co-body r main true 11 -9 co-body x y main true 10 end main false cannot resume dead coroutine
このセクションではLuaのためのCのAPIを説明する。
これは、ホストプログラムがLuaに働きかけるためのCの関数のセットである。
すべてのAPI関数と、関連する型、定数は、ヘッダーファイル lua.h で定義されている。
このマニュアルでは「関数」という言葉を使うが、代わりにマクロとして提供されているものもある。 そのようなマクロはすべて、各引数がちょうど一度だけ評価され、いかなる隠れた副作用も発生しない (ただし最初の引数を除く。ここには常にLuaステートを渡す)。
ほとんどのCのライブラリと同様に、
LuaのAPI関数は引数の妥当性や一貫性をチェックしない。
しかし、ファイル luaconf.h の中のマクロ luai_apicheck
を適切に定義してLuaを再コンパイルすると、この動作を変更できる。
LuaはCとの間で値を受け渡しするために 仮想スタック を使う。 スタック内の各要素は、Luaの値 (nil、数値、文字列など) を表している。
LuaがCを呼ぶときは、以前のスタックの状態やまだアクティブなCの関数が使っているスタックに影響されないように、新しいスタックを用意する。
このスタックはCの関数に渡された引数が格納されており、
Cの関数から呼び出し側に返す戻り値を格納するためにも使われる (lua_CFunction を参照)。
利便性のため、ほとんどの問い合わせ用API関数は厳密なスタックの規則に従っていない。
代わりに、インデックス を使って、スタック内の任意の要素にアクセスできる。
プラスのインデックスはスタック内の 絶対 位置を表し (1 から始まる)、
マイナスのインデックスはスタックトップからの相対 オフセット を表す。
具体的に言うと、スタックに n 個の要素があるとして、
インデックス1は最初の要素 (つまり、空のスタックに最初に積まれた要素) を表し、
インデックス n は最後の要素を表す。
インデックス-1も最後の要素 (つまりスタックトップにある要素) を表し、
インデックス -n は最初の要素を表す。
有効な インデックスは1からスタックトップの間だけである
(つまり 1 <= abs(index) <= top)。
LuaのAPIを使うときは、一貫性を保証する責任がある。
特に、スタックオーバーフローに気を付けなければならない。
スタックサイズを伸ばすためには関数 lua_checkstack を使う。
LuaがCを呼ぶときは、
最低でも全体で LUA_MINSTACK 個のスタック要素が利用可能である。
LUA_MINSTACK は20に定義されており、
スタックにどんどん要素を積むようなループがあったりしなければ、
普通はスタック空間を気にしなくても良い。
多くの問い合わせ関数には、スタック空間内で利用可能な任意のインデックス値を使える。
つまり、lua_checkstack を使って設定できる最大スタックの長さまでのインデックスである。
このようなインデックスは 受け入れ可能なインデックス と呼ぶ。
もっと正確には、受け入れ可能なインデックス は以下のように定義される。
(index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace)
0は決して受け入れ可能なインデックスにならない。
特に明記されていなければ、 どの関数も 疑似インデックス と呼ばれる有効なインデックスを受け付ける。 これはスタック内に無いいくつかのLuaの値にCのコードからアクセスするためのものである。 疑似インデックスは、スレッドの環境、関数の環境、レジストリ、Cの関数の上位値にアクセスするために使う (3.4 を参照)。
スレッドの環境 (グローバル変数がある場所) は常に擬似インデックス
LUA_GLOBALSINDEX の位置にある。
走行中のCの関数の環境は常に擬似インデックス
LUA_ENVIRONINDEX の位置にある。
グローバル変数の値にアクセスしたり変更するためには、 環境テーブルに対して普通のテーブル操作を行う。 例えば、グローバル変数の値にアクセスするには以下を行う。
lua_getfield(L, LUA_GLOBALSINDEX, varname);
Cの関数を作成するとき、いくつかの値を関連付けて Cのクロージャ を作ることができる。
これらの値は 上位値 と呼ばれ、
その関数が呼ばれたときにいつでもアクセスできる。
(lua_pushcclosure を参照)。
Cの関数が呼ばれると、特別な疑似インデックスにこれらの値が配置される。
これらの疑似インデックスはマクロ lua_upvalueindex で生成される。
関数に関連付けられた最初の値は lua_upvalueindex(1) の位置にあり、残りも同様である。
現在の関数の上位値の数よりも大きい n で
lua_upvalueindex(n) を呼び出しても、
受け入れ可能な (ただし有効でない) インデックスが生成される。
Luaはレジストリを提供している。
これは定義済みのテーブルで、好きなLuaの値を格納するためにCのコードから使うことができる。
このテーブルは常に疑似インデックス LUA_REGISTRYINDEX に置かれている。
どのCのライブラリもデータを保持するためにこのテーブルを使えるが、
衝突を避けるため他のライブラリが使っていないキーを選ぶ必要がある。
典型的には、ライブラリ名を含む文字列とか、自分のコードで使っているCオブジェクトのアドレスを持つライトユーザーデータを、キーとして使うと良い。
レジストリ内の整数キーは、補助ライブラリで実装されているリファレンスメカニズムで使われており、それゆえ他の目的に使うべきでない。
内部的に、Luaはエラー処理のためにCの longjmp の機能を使う。
(C++を使っているのなら、例外を使うこともできる。luaconf.h ファイルを参照。)
Luaがエラーに直面すると (メモリ不足とか、型エラーとか、構文エラーとか、実行時エラーなど)、
エラーを 発生 させ、つまるところロングジャンプが行われる。
保護された環境 は復帰点をセットするために setjmp を使い、
エラーは最も最近作られたアクティブ復帰点にジャンプすることになる。
APIのほとんどの関数はエラー、例えばメモリ確保エラーなどを起こす可能性がある。
以下の関数は保護モード (つまり、実行するために保護された環境を作る) で実行するため、決してエラーを起こさない。
lua_newstate, lua_close, lua_load,
lua_pcall, and lua_cpcall。
lua_error を呼ぶと、CのコードからLuaのエラーを発生させることが出来る。
以下にCのAPIのすべての関数と型をアルファベット順に示す。
lua_Alloc
typedef void * (*lua_Alloc) (void *ud,
void *ptr,
size_t osize,
size_t nsize);
Luaステートが使うメモリアロケータ関数の型である。
メモリアロケータ関数は realloc に似た機能を提供しなければならないが、
まったく同じではない。
引数は以下の通り。
ud: lua_newstate に渡されたポインタ。
ptr: 割り当て/再割り当て/解放するブロックへのポインタ。
osize: 元のブロックサイズ。
nsize: 新しいブロックサイズ。
osize がゼロの場合、またその場合に限り、ptr は NULLになる。
nsize がゼロの場合、アロケータは NULL を返さなければならない。
osize がゼロでない場合、ptr が指すメモリブロックを解放すべきである。
nsize がゼロでない場合、要求を満たせなければアロケータは NULL を返す。
nsize がゼロでなく osize がゼロの場合、アロケータは malloc のように振る舞うべきである。
nsize と osize が共にゼロでない場合、
osize >=nsize であれば、Luaはアロケータが決して失敗しないものと仮定している。
アロケータ関数の簡単な実装を示そう。
これは lua_newstate が補助ライブラリで使っている。
static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {
(void)ud; /* not used */
(void)osize; /* not used */
if (nsize == 0) {
free(ptr); /* ANSIはfree(NULL)は効果がないと規定している */
return NULL;
}
else
/* ANSIはrealloc(NULL, size)はmalloc(size)と同じと規定している */
return realloc(ptr, nsize);
}
lua_atpanic
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
新しいパニック関数を設定し、古いものを返す。
保護された環境の外側でエラーが起きると、Luaは パニック関数 を呼び、それから exit(EXIT_FAILURE) を呼んでホストアプリケーションを終了する。
パニック関数が戻らなければ(例えばロングジャンプするとかで)、終了しないようにできる。
パニック関数はスタックの一番上にあるエラーメッセージにアクセスできる。
lua_call
void lua_call (lua_State *L, int nargs, int nresults);
関数を呼ぶ。
関数を呼ぶには、以下の手順に従わなければならない。
まず、呼びたい関数をスタックに積む。
次に、その関数に渡す引数を順番通りに積む。
つまり最初の引数を最初に積む。
最後に、lua_call を呼ぶ。
nargs はスタックに積んだ引数の数である。
すべての引数と関数の値は関数を呼んだときにスタックから取り除かれる。
関数が戻るとき、スタックに戻り値が積まれる。
戻り値の数は nresults 個に調節される。
ただし nresults が LUA_MULTRET の場合は調節されない。
この場合、関数の すべての 戻り値が積まれる。
Luaは戻り値をスタック空間に合うようにする。
関数の戻り値は順番通りに (最初の戻り値が最初に) スタックに積まれる。
従って呼び出し後のスタックの一番上は、その最後の戻り値である。
呼び出した関数の中で起きたエラーは上に伝搬される(longjmpを使って)。
以下のLuaコードと等価なことをホストプログラムからはどうすれば良いのかの例を示す。
a = f("how", t.x, 14)
これをCで書くと:
lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* 呼ぶ関数 */
lua_pushstring(L, "how"); /* 最初の引数 */
lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* テーブル`t' */
lua_getfield(L, -1, "x"); /* t.xの結果(2番目の引数)を積む */
lua_remove(L, -2); /* スタックから `t' を取り除く */
lua_pushinteger(L, 14); /* 3番目の引数 */
lua_call(L, 3, 1); /* 3個の引数と1個の戻り値で関数を呼ぶ */
lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* グローバル変数 `a' に代入 */
上のコードは「整合が取れている」ことに注目。
最終的にスタックは元の状態に戻っている。
これは良いプログラミング作法であると考えられる。
lua_CFunction
typedef int (*lua_CFunction) (lua_State *L);
Cの関数の型。
適切にLuaとやりとりするに、Cの関数は、
引数と戻り値の受け渡し方法を定義する以下の手順に従わなければならない。
Cの関数はLuaからの引数をスタックに順番通り受け取る (最初の引数が最初に積まれる)。
つまり、関数の開始時点では、
lua_gettop(L) は関数が受け取った引数の数を返す。
最初の引数(もしあれば)はインデックス1で、最後の引数はインデックス lua_gettop(L) である。
Luaに値を返すには、Cの関数は単にスタックにその値を順番通り (最初の戻り値を最初に) 積み、戻り値の数を返すだけで良い。
戻り値より下のスタックにある余計な値はすべてLuaによって捨てられる。
Luaの関数と同様、Luaから呼ばれるCの関数でも、たくさんの戻り値を返すことができる。
例として、可変個の数値の引数を取り、その平均と合計を返す関数を以下に示す。
static int foo (lua_State *L) {
int n = lua_gettop(L); /* 引数の数 */
lua_Number sum = 0;
int i;
for (i = 1; i <= n; i++) {
if (!lua_isnumber(L, i)) {
lua_pushstring(L, "関数 `average' の引数が正しくありません");
lua_error(L);
}
sum += lua_tonumber(L, i);
}
lua_pushnumber(L, sum/n); /* 最初の戻り値 */
lua_pushnumber(L, sum); /* 2番目の戻り値 */
return 2; /* 戻り値の数 */
}
lua_checkstack
int lua_checkstack (lua_State *L, int extra);
スタックに少なくとも extra 個の空きスロットがあることを保証する。
もしスタックをそのサイズまで伸ばせなければ false を返す。
スタックがすでに指定された長さよりも長ければ、
わざわざスタックを縮めたりせず、何も変えない。
lua_close
void lua_close (lua_State *L);
渡されたLuaステート内のすべてのオブジェクトを破棄し (もしあればガベージコレクションメタメソッドも呼び)、 ステート内で使われていたすべての動的メモリを解放する。 プラットフォームによっては、 ホストプログラムが終了するときにすべてのリソースが自動的に解放されるため、 この関数を呼ぶ必要がないかもしれない。 一方、デーモンやウェブサーバのような長時間実行するプログラムでは、 消費リソースが増大するのを避けるために、 必要なくなったステートはすぐに解放する必要があるだろう。
lua_concat
void lua_concat (lua_State *L, int n);
スタックトップから n 個の値を連結し、それらを取り除き、結果をスタックトップに載せる。
もし n が1ならは、結果はその1つの文字列である (要するに何もしない)。
もし n が0ならば、結果は空文字列である。
連結は通常のLuaの意味論に従って行われる (2.5.4 を参照)。
lua_cpcall
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
Cの関数 func を保護モードで呼ぶ。
func はスタックに1個の引数、ud を持つライトユーザーデータが載った状態で開始する。
エラーが起こった場合、
lua_cpcall は lua_pcall と同じエラーコードを返し、エラーオブジェクトをスタックトップに置く。
そうでなければ0を返し、スタックは何も変えない。
func から返される値はすべて捨てられる。
lua_createtable
void lua_createtable (lua_State *L, int narr, int nrec);
新しい空のテーブルを作り、スタックに積む。
この新しいテーブルは narr 個の配列要素と nrec 個の非配列要素のための割り当て済み空間を持っている。
この事前割り当ては、そのテーブルがたくさんの要素を持つであろうとわかっている場合に役に立つ。
それ以外の場合は、関数 lua_newtable を使っても良い。
lua_dump
int lua_dump (lua_State *L, lua_Writer writer, void *data);
関数をバイナリチャンクとしてダンプする。
スタックトップにLuaの関数を1つ受け取り、1つのバイナリチャンクを生成する。
これは、再びロードされたとき、ダンプされたものと同等の関数を作る。
チャンクの各部を生成するとき、
lua_dump はそれらを書き込むために関数 writer (lua_Writer を参照) を、data を与えて呼ぶ。
戻り値は writer の最後の呼び出しが返したエラーコードである。 0はエラーなしを表す。
この関数はスタックからLuaの関数を取り除かない。
lua_equal
int lua_equal (lua_State *L, int index1, int index2);
受け入れ可能なインデックス index1 と index2 の位置にある2つの値が等しければ1を返す。
そうでなければ0を返す。
どちらかのインデックスが有効でないときも0を返す。
比較はLuaの == 演算子の意味論に従って行われる
(つまり、メタメソッドを呼ぶ場合がある)。
lua_error
int lua_error (lua_State *L);
Luaエラーを生成する。
呼ぶ前に、エラーメッセージ (実際にはどんな型の値でも良い) をスタックトップに置かなければならない。
この関数はロングジャンプを行うので、決して戻ってこない (luaL_error を参照)。
lua_gc
int lua_gc (lua_State *L, int what, int data);
ガベージコレクタを制御する。
この関数は引数 what の値に応じていくつかの仕事を行う。
LUA_GCSTOP--- ガベージコレクタを停止させる。
LUA_GCRESTART--- ガベージコレクタを再開させる。
LUA_GCCOLLECT--- フルガベージコレクションサイクルを実行する。
LUA_GCCOUNT--- Luaが使っている現在のメモリ量を (キロバイトで) 返す。
LUA_GCCOUNTB--- Luaが使っている現在のメモリ量のバイト数を1024で割った余りを返す。
LUA_GCSTEP---
ガベージコレクションのインクリメンタルステップひとつを実行する。
ステップの「サイズ」は data で制御する。
大きな値は大きなステップを意味するが、具体的には定まっていない。
ステップサイズを制御したければ、
data の値を実験的に調整しなければならない。
そのステップでガベージコレクションサイクルが終われば、この関数は1を返す。
LUA_GCSETPAUSE---
コレクタの 停止値 (see 2.10 を参照)
の新しい値として data ÷100を設定する。
関数は以前の停止値を返す。
LUA_GCSETSTEPMUL---
コレクタの ステップ係数 (2.10 を参照)
の新しい値として 引数 ÷100を設定する。
関数は以前のステップ係数の値を返す。
lua_getallocf
lua_Alloc lua_getallocf (lua_State *L, void **ud);
渡されたステートのメモリアロケータ関数を返す。
ud が NULL でなければ、
Luaは lua_newstate に渡されたポインタを
*ud に格納する。
lua_getfenv
void lua_getfenv (lua_State *L, int index);
指定したインデックスの値の環境テーブルをスタックに積む。
lua_getfield
void lua_getfield (lua_State *L, int index, const char *k);
値 t[k] をスタックに積む。
ただし t は指定した有効なインデックス index の値である。
Luaの中でと同様に、この関数は "index" イベントのメタメソッドを呼ぶ場合がある
(2.8 を参照)。
lua_getglobal
void lua_getglobal (lua_State *L, const char *name);
グローバル変数 name の値をスタックに積む。
これはマクロとして定義されている。
#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
lua_getmetatable
int lua_getmetatable (lua_State *L, int index);
指定した受け入れ可能なインデックスの値のメタテーブルをスタックに積む。 インデックスが有効でないか、その値がメタテーブルを持っていなければ、 この関数は0を返し、スタックには何も積まない。
lua_gettable
void lua_gettable (lua_State *L, int index);
値 t[k] をスタックに積む。
ただし t は渡された有効なインデックス index の値で、
k はスタックトップの値である。
この関数はスタックからキーを (そこに結果を置く前に) 取り除く。 Luaの中でと同様に、この関数は "index" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。
lua_gettop
int lua_gettop (lua_State *L);
スタックトップの要素のインデックスを返す。 インデックスは1から始まるので、この戻り値はスタックの要素数と等しい (そしてゼロはスタックが空であることを意味する)。
lua_insert
void lua_insert (lua_State *L, int index);
指定した位置より上の要素をずらして空きスペースを作り、スタックトップの要素をその位置に移動する。 疑似インデックスは、実際のスタック位置ではないため、指定できない。
lua_Integer
typedef ptrdiff_t lua_Integer;
整数値を表現するための、Lua APIで使われる型。
デフォルトでは ptrdiff_t である。
これは通常、マシンが「快適に」扱える最大の整数型である。
lua_isboolean
int lua_isboolean (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がブーリアン型であれば1、そうでなければ0を返す。
lua_iscfunction
int lua_iscfunction (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がCの関数であれば1、そうでなければ0を返す。
lua_isfunction
int lua_isfunction (lua_State *L, int index);
指定した受け入れ可能なインデックスの値が関数 (CかLuaどちらかの) であれば1、そうでなければ0を返す。
lua_islightuserdata
int lua_islightuserdata (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がライトユーザーデータであれば1、そうでなければ0を返す。
lua_isnil
int lua_isnil (lua_State *L, int index);
指定した受け入れ可能なインデックスの値が nil であれば1、そうでなければ0を返す。
lua_isnumber
int lua_isnumber (lua_State *L, int index);
指定した受け入れ可能なインデックスの値が数値か、数値に変換できる文字列であれば1、そうでなければ0を返す。
lua_isstring
int lua_isstring (lua_State *L, int index);
指定した受け入れ可能なインデックスの値が文字列か数値であれば1、そうでなければ0を返す。 (数値の場合、それは文字列に変換される)
lua_istable
int lua_istable (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がテーブルであれば1、そうでなければ0を返す。
lua_isthread
int lua_isthread (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がスレッドであれば1、そうでなければ0を返す。
lua_isuserdata
int lua_isuserdata (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がユーザーデータ (フルかライトどちらかの) であれば1、そうでなければ0を返す。
lua_lessthan
int lua_lessthan (lua_State *L, int index1, int index2);
受け入れ可能なインデックス index1 の値が受け入れ可能なインデックス index2 の値よりも小さければ1、そうでなければ0を返す。
どちらかのインデックスが有効でない場合も0を返す。
比較はLuaの < 演算子の意味論に従って行われる
(つまり、メタメソッドを呼ぶ場合がある)。
lua_load
int lua_load (lua_State *L, lua_Reader reader, void *data,
const char *chunkname);
Luaチャンクをロードする。
エラーがなければ、
lua_load はコンパイルしたチャンクをLuaの関数としてスタックトップに積む。
そうでなければ、エラーメッセージを積む。
lua_load の戻り値は以下の通り。
LUA_ERRSYNTAX ---
コンパイル時に構文エラーが発生。
LUA_ERRMEM ---
メモリ割り当てエラー。
lua_load はチャンクがテキストかバイナリかを自動的に検出し、それに応じてチャンクをロードする (プログラム luac を参照)。
lua_load はチャンクを読み込むためにユーザが提供する reader 関数を使う (see lua_Reader を参照)。
data 引数はそのリーダ関数に渡される値である。
chunkname 引数はチャンクに名前を与える。
これはエラーメッセージやデバッグ情報で使われる (3.8 を参照)。
lua_newstate
lua_State *lua_newstate (lua_Alloc f, void *ud);
新しい独立したステートを作る。
ステートを作れなければ (メモリ不足のために)、NULL を返す。
引数 f はアロケータ関数である。
Luaはこのステートのためのすべてのメモリ確保をこの関数を使って行う。
2番目の引数 ud は、そのアロケータに毎回渡されるポインタである。
lua_newtable
void lua_newtable (lua_State *L);
新しい空のテーブルを作ってスタックに積む。
lua_createtable(L, 0, 0) と同等である。
lua_newthread
lua_State *lua_newthread (lua_State *L);
新しいスレッドを作ってスタックに積み、
その新しいスレッドを表す lua_State へのポインタを返す。
この関数が返した新しいステートは元のステートとすべてのグローバルオブジェクト (テーブルとか) を共有するが、独立した実行スタックを持つ。
スレッドを閉じたり破棄する明示的な関数はない。 スレッドは他のLuaオブジェクト同様、ガベージコレクションの対象である。
lua_newuserdata
void *lua_newuserdata (lua_State *L, size_t size);
この関数は指定されたサイズのメモリブロックを割り当て、 そのアドレスを持つ新しいフルユーザーデータをスタックに積み、 そのアドレスを返す。
ユーザーデータはLua内でCの値を表現する。 フルユーザーデータ はメモリブロックを表す。 これは (テーブルと同じように) オブジェクトである。 作成する必要があり、独自のメタテーブルを持つことができ、 ガベージコレクションされるのを検出できる。 フルユーザーデータは (rawequalの下では) それ自身と比較したときだけ等しい。
Luaが gc メタメソッドを持つフルユーザーデータを回収するとき、
Luaはメタメソッドを呼び、ユーザーデータにファイナライズ済みの印を付ける。
このユーザーデータがもう一度回収されると、Luaは対応するメモリを解放する。
lua_next
int lua_next (lua_State *L, int index);
スタックからキーを取り出し。
指定したインデックスのテーブルからキー・値のペア (取り出したキーの「次」のペア) を積む。
これ以上要素がなければ、 lua_next は (何も積まずに) 0を返す。
典型的な巡回は次のようになる。
/* テーブルはスタックの `t' の位置にあるとする */
lua_pushnil(L); /* 最初のキー */
while (lua_next(L, t) != 0) {
/* 「キー」インデックス-2、「値」はインデックス-1の位置にある */
printf("%s - %s\n",
lua_typename(L, lua_type(L, -2)), lua_typename(L, lua_type(L, -1)));
lua_pop(L, 1); /* 「値」を除去し、「キー」は次の繰り返しのために残す */
}
テーブルを巡回する間、
キーが本物の文字列であるかどうか判らないなら、キーに対して直接 lua_tolstring を呼んではならない。
lua_tolstring は指定したインデックスにある値を 変える ため、次の lua_next の呼び出しを混乱させることを覚えておくように。
lua_Number
typedef double lua_Number;
Luaの数値の型。
デフォルトでは、これはdoubleであるが、
luaconf.h で変えることができる。
コンフィギュレーションファイルを変更することで、 Luaが数値に対して他の型 (floatやlongなど) を使うようにできる。
lua_objlen
size_t lua_objlen (lua_State *L, int index);
指定した受け入れ可能なインデックスの値の「長さ」を返す。
文字列の場合はその文字列の長さ、
テーブルの場合は長さ演算子 (`#´) の結果、
ユーザーデータの場合は割り当てられたメモリブロックのサイズ、
それ以外の場合は0を返す。
lua_pcall
lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
関数を保護モードで呼ぶ。
nargs と nresults は
lua_call と同じである。
もしエラーがなければ
lua_pcall は lua_call とまったく同じように動作する。
しかし、何かエラーが起きた場合は、
lua_pcall はそれを捕らえて、
1つの値 (エラーメッセージ) をスタックに積んでエラーコードを返す。
lua_call 同様、
lua_pcall は常に関数とその引数をスタックから取り除く。
もし errfunc が0であれば、スタックに返されたエラーメッセージは正確に元のエラーメッセージである。
そうでなければ、errfunc は エラーハンドラ関数 のスタックインデックスを指定する
(現在の実装では、疑似インデックスは指定できない)。
実行時エラーが起きると、エラーメッセージを引数としてこの関数が呼ばれ、
その戻り値が lua_pcall から返されるエラーメッセージとなる。
典型的には、エラーハンドラ関数は、エラーメッセージにスタックトレースのようなデバッグ情報を付け加えるのに使う。
そういった情報は lua_pcall から戻った後にはもうスタックから除去されているため、集めることができない。
lua_pcall 関数は成功時は0を返し、
エラーの場合は以下のエラーコードのいずれかを返す (lua.h で定義されている)。
LUA_ERRRUN --- 実行時エラー。
LUA_ERRMEM --- メモリ確保エラー。
このようなエラーでは、Luaはエラーハンドラ関数を呼ばない。
LUA_ERRERR ---
エラーハンドラ関数実行中のエラー。
lua_pop
void lua_pop (lua_State *L, int n);
スタックから n 個の要素を取り除く。
lua_pushboolean
void lua_pushboolean (lua_State *L, int b);
値 b のブーリアン値をスタックに積む。
lua_pushcclosure
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
新しいCのクロージャをスタックに積む。
Cの関数を作るとき、いくつかの値を関連付けて Cのクロージャ を作ることができる (see 3.4)。
これらの値はその関数が呼ばれたときにいつでもアクセスできる。
Cの関数に値を関連付けるには、
まずそれらの値をスタックに積む (複数の値がある場合は、最初の値を最初に積む)。
次に lua_pushcclosureを呼び、
Cの関数を作ってスタックにプッシュする。
引数 n は関数に関連付ける値の数を示す。
lua_pushcclosure はスタックからそれらの値を取り除く。
lua_pushcfunction
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Cの関数をスタックに積む。
この関数はCの関数へのポインタを受け取り、関数 型のLua値をスタックに積む。
この値が呼ばれると、対応するCの関数が呼ばれる。
Luaに登録する関数は引数と戻り値を受け渡すために、
正しい手順に従わなければ鳴らない (lua_CFunction を参照)。
lua_pushcfunction(L, f) の呼び出しは
lua_pushcclosure(L, f, 0) と同等である。
lua_pushfstring
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
書式化文字列をスタックに積み、この文字列を指すポインタを返す。
これはCの関数 sprintf に似ているが、いくつか重要な違いがある。
`だけが使える。%%´ (文字 `%´) `%s´ (長さ制限のないゼロ終端文字列) `%f´ (lua_Number) `%p´ (16進数としてのポインタ) `%d´ (int) `%c´ (文字としてのint)
lua_pushinteger
void lua_pushinteger (lua_State *L, lua_Integer n);
値 n を持つ数値をスタックに積む。
lua_pushlightuserdata
void lua_pushlightuserdata (lua_State *L, void *p);
ライトユーザーデータをスタックに積む。
ユーザーデータはLua内でCの値を表現する。 ライトユーザーデータ はポインタを表す。 それは (数値と同じように) 値である。 作成はせず、メタテーブルも持たず、(作成しないので) 回収もされない。 ライトユーザーデータは、同じCのアドレスを持つ「どの」ライトユーザーデータとも等しい。
lua_pushlstring
void lua_pushlstring (lua_State *L, const char *s, size_t len);
s が指すサイズ len の文字列をスタックに積む。
Luaは与えられた文字列を内部的にコピーする (または再利用する) ため、
sが指すメモリは関数が戻ったあとすぐに解放あるいは再利用してよい。
文字列は埋め込まれたゼロを含んでいても良い。
lua_pushnil
void lua_pushnil (lua_State *L);
nil値をスタックに積む。
lua_pushnumber
void lua_pushnumber (lua_State *L, lua_Number n);
値 n を持つ数値をスタックに積む。
lua_pushstring
void lua_pushstring (lua_State *L, const char *s);
sが指すゼロ終端文字列をスタックに積む。
Luaは与えられた文字列を内部的にコピーする (または再利用する) ため、
s が指すメモリを関数が戻ったあとすぐに解放あるいは再利用してよい。
文字列は埋め込まれたゼロを含むことができない。
最初のゼロで終端するものと仮定される。
lua_pushthread
void lua_pushthread (lua_State *L);
Lが表すスレッドをスタックに積む。
lua_pushvalue
void lua_pushvalue (lua_State *L, int index);
指定した有効なインデックスにある要素のコピーをスタックに積む。
lua_pushvfstring
const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp);
lua_pushfstring と同じであるが、
可変引数の代わりに va_list を渡す点が異なる。
lua_rawequal
int lua_rawequal (lua_State *L, int index1, int index2);
受け入れ可能なインデックス index1 と index2 が
プリミティブに等しい (つまりメタメソッドを呼ばない) とき1を返す。
そうでなければ0を返す。
どちらかのインデックスが有効でないときも0を返す。
lua_rawget
void lua_rawget (lua_State *L, int index);
lua_gettable と同じであるが、
生のアクセスを行う (つまりメタメソッドを呼ばない) 点が異なる。
lua_rawgeti
void lua_rawgeti (lua_State *L, int index, int n);
値 t[n] をスタックに積む。
ただし t は指定した有効なインデックス index の値である。
これは生のアクセスを行う。
つまりメタメソッドを呼ばない。
lua_rawset
void lua_rawset (lua_State *L, int index);
lua_settable と同じであるが、
生の代入である点が異なる (メタメソッドを呼ばない)。
lua_rawseti
void lua_rawseti (lua_State *L, int index, int n);
t[n] = v と同じことを行う。
ただし t は指定した有効なインデックス index の値で、
v はスタックトップの値である。
この関数は値をスタックから取り除く。 これは生の代入を行う。 つまりメタメソッドを呼ばない。
lua_Reader
typedef const char * (*lua_Reader)
(lua_State *L, void *data, size_t *size);
lua_load で使うリーダー関数。
チャンクの新たなピースが必要になるたびに、data 引数を付けてリーダーが呼ばれる。
リーダーはチャンクの新たなピースを埋めたメモリブロックを指すポインタを返し、
その長さを size にセットしなければならない。
ブロックはリーダー関数がもう一度呼ばれるまで存在しなければならない。
チャンクの最後に達したことを伝えるには NULL を返す。
リーダー関数は1以上の任意のサイズのピースを返すことができる。
lua_register
void lua_register (lua_State *L, const char *name, lua_CFunction f);
Cの関数 f をグローバル変数 name の新しい値としてセットする。
これはマクロとして定義されている。
#define lua_register(L,n,f) (lua_pushcfunction(L, f), lua_setglobal(L, n))
lua_remove
void lua_remove (lua_State *L, int index);
指定した有効なインデックスの要素を取り除き、 上の要素をずらして隙間を埋める。 疑似インデックスは、実際のスタック位置でないため、指定できない。
lua_replace
void lua_replace (lua_State *L, int index);
スタックトップの要素を指定した位置へ移動する。 スタックトップの値は取り除く。 他のどの要素もずらさない。 つまり指定した位置の値を置き換える。
lua_resume
int lua_resume (lua_State *L, int narg);
指定したスレッドのコルーチンを再開する。
コルーチンを開始するためには、まず新しいスレッドを作る (lua_newthread を参照)。
次にメイン関数と任意個の引数をスタックに積み、
nargs に引数の数を渡して。
lua_resume を呼ぶ。
コルーチンが中断されたり実行終了したら、呼び出しから戻る。
戻ってきたとき、スタックには lua_yield に渡された値か、本体の関数から返された値がすべて積まれている。
コルーチンがyieldした場合、lua_resume は
LUA_YIELD を返す。
コルーチンがエラーなく実行終了した場合は0を返す。
エラーが起きた場合はエラーコードを返す (lua_pcall を参照)。
エラーの場合、スタックは巻き戻されておらず、従ってその上でデバッグAPIを使うことができる。
スタックトップにエラーメッセージが置かれる。
コルーチンを再開するには、yied から返される結果として渡す値だけをスタックに起き、
lua_resume を呼ぶ。
lua_setallocf
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
指定されたステートのアロケータ関数を f と ud に変更する。
lua_setfenv
int lua_setfenv (lua_State *L, int index);
スタックからテーブルを取り除き、指定したインデックスの値の新しい環境として設定する。
指定したインデックスの値が関数、スレッド、ユーザーデータのどれでもなければ、
lua_setfenv は0を返す。
そうでなければ1を返す。
lua_setfield
void lua_setfield (lua_State *L, int index, const char *k);
t[k] = v を実行する。
ただし t は指定した有効なインデックス index の値で、
v はスタックトップの値である。
この関数は値をスタックから除去する。 Luaの中でのように、この関数は "newindex" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。
lua_setglobal
void lua_setglobal (lua_State *L, const char *name);
スタックから値を取り除き、それをグローバル変数 name の新しい値として設定する。
これはマクロとして定義されている。
#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
lua_setmetatable
int lua_setmetatable (lua_State *L, int index);
スタックからテーブルを取り除き、それを指定した受け入れ可能なインデックスの値の新しいメタテーブルとして設定する。
lua_settable
void lua_settable (lua_State *L, int index);
t[k] = v を実行する。
ただし t は指定した有効なインデックス index の値で、
v はスタックトップの値で、
k はそのひとつ下の値である。
この関数はキーと値の両方をスタックから取り除く。 Luaの中でのように、この関数は "newindex" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。
lua_settop
void lua_settop (lua_State *L, int index);
任意の受け入れ可能なインデックスまたは0を受け取り、
スタックトップをそのインデックスに設定する。
新しいトップが古いものより大きければ、新しい要素は nil で埋められる。
index が0の場合は、スタック要素がすべて削除される。
lua_State
typedef struct lua_State lua_State;
Luaインタプリタの状態全体を保持する不透明な構造体。 Luaライブラリはグローバル変数を使っていないので、完全に再入可能である。 ステートに関するすべての情報はこの構造体に保持されている。
このステートへのポインタは、
無からLuaステートを作成する lua_newstate を除いて、
ライブラリのすべての関数で最初の引数として渡さなければならない。
lua_status
int lua_status (lua_State *L);
スレッド L の状態を返す。
通常のスレッドの状態は0である。
スレッドがエラー終了していればエラーコード、
スレッドが中断していれば LUA_YIELD を返す。
lua_toboolean
int lua_toboolean (lua_State *L, int index);
指定した受け入れ可能なインデックスの値をCのブーリアン値 (0または1) に変換する。
Luaでの条件判断と同様に、
lua_toboolean は
false と nil 以外のすべての値に対して1を返し、
そうでなければ0を返す。
有効でないインデックスを指定した場合も0を返す。
もし本当のブーリアン値だけを調べたい場合は、
lua_isboolean で値の型を判定すること。
lua_tocfunction
lua_CFunction lua_tocfunction (lua_State *L, int index);
指定した受け入れ可能なインデックスの値をCの関数に変換する。
この値はCの関数でなければならなず、それ以外では NULL を返す。
lua_tointeger
lua_Integer lua_tointeger (lua_State *L, int idx);
指定した受け入れ可能なインデックスのLuaの値を符号付き整数型
lua_Integer に変換する。
このLuaの値は数値か、数値に変換できる文字列でなければならない (2.2.1 を参照)。
それ以外の場合、lua_tointeger は0を返す。
数値が整数でなければ、何らかの未規定な方法で整数に丸める。
lua_tolstring
const char *lua_tolstring (lua_State *L, int index, size_t *len);
指定した受け入れ可能なインデックスのLuaの値を文字列 (const char*) に変換する。
もし len が NULL でなければ、
*len に文字列の長さも設定される。
このLuaの値は文字列か数値でなければならず、
それ以外の場合、この関数は NULL を返す。
もしその値が数値であれば、
lua_tolstring はスタック内のその実際の値を文字列に 変換する
(この変換はテーブル巡回中のキーに対して lua_tolstring を使ったときに lua_next を混乱させる)。
lua_tolstring
はLuaステート内部の文字列を指す、完全にアラインメントされたポインタを返す。
この文字列は、その最後に必ずゼロ (`\0´) を持つ (Cでよくやるように) が、
その途中にもゼロを含むことがある。
Luaはガベージコレクションを持っているため、
lua_tolstring の返したポインタが、その値がスタックから取り除かれた後も有効であり続けるという保証はない。
lua_tonumber
lua_Number lua_tonumber (lua_State *L, int index);
指定した受け入れ可能なインデックスにあるLuaの値を数値に変換する
(lua_Number を参照)。
このLuaの値は数値か、数値に変換できる文字列でなければならない
(2.2.1 を参照)。
それ以外の場合、lua_tonumber は0を返す。
lua_topointer
const void *lua_topointer (lua_State *L, int index);
指定した受け入れ可能なインデックスの値をCの汎用ポインタ (void*) に変換する。
この値は、ユーザーデータ、テーブル、スレッド、関数のいずれかである。
それ以外なら lua_topointer は NULL を返す。
Luaは異なるオブジェクトに対しては異なるポインタを返すことを保証する。
ポインタからその元の値に変換する直接的な方法は無い。
典型的には、この関数はデバッグ情報のためにだけ使われる。
lua_tostring
const char *lua_tostring (lua_State *L, int index);
len に NULL を渡して lua_tolstring を呼ぶのと同じ。
lua_tothread
lua_State *lua_tothread (lua_State *L, int index);
指定した受け入れ可能なインデックスの値をLuaのスレッド
(lua_State* で表される) に変換する。
この値はスレッドでなければならず、それ以外では NULL を返す。
lua_touserdata
void *lua_touserdata (lua_State *L, int index);
指定した受け入れ可能なインデックスの値がフルユーザーデータであれば、そのブロックのアドレスを返す。
ライトユーザーデータであれば、そのポインタを返す。
どちらでもなければ NULL を返す。
lua_type
int lua_type (lua_State *L, int index);
指定した受け入れ可能なインデックスの値の型を返す。
有効でないインデックス (つまりその位置に要素がない) の場合は LUA_TNONE を返す。
lua_type が返す型は lua.h で定義されている以下の定数である。
LUA_TNILLUA_TNUMBERLUA_TBOOLEANLUA_TSTRINGLUA_TTABLELUA_TFUNCTIONLUA_TUSERDATALUA_TTHREADLUA_TLIGHTUSERDATA
lua_typename
const char *lua_typename (lua_State *L, int tp);
tp が示す型の名前を返す。
tp は lua_type が返す値のいずれかでなければならない。
lua_Writer
typedef int (*lua_Writer)
(lua_State *L, const void* p, size_t sz, void* ud);
lua_dump で使うライター関数。
新しいチャンクのピースが生成されるたびに、
書き込みバッファ (p)、そのサイズ (sz)、
および lua_dump に渡した data 引数を渡して
lua_dump がライターを呼ぶ。
ライターはエラーコードを返す。
0はエラーなしを意味する。
それ以外の値はエラーを意味し、
lua_dump にそれ以上ライターを呼ぶのをやめさせる。
lua_xmove
void lua_xmove (lua_State *from, lua_State *to, int n);
同じ グローバルステートの異なるスレッド間で値を交換する。
この関数は from のスタックから n 個の値を取り出し、
それらを to のスタックに積む。
lua_yield
int lua_yield (lua_State *L, int nresults);
コルーチンを中断する。
この関数は以下のようにCの関数のreturn式でだけ呼べる。
return lua_yield (L, nresults);
Cの関数がこの方法で lua_yield を呼ぶとコルーチンの実行は中断され、
このコルーチンを開始した lua_resume の呼び出しから戻る。
引数 nresults は lua_resume から返したいスタック上の値の数である。
Luaは組み込みのデバッグ機能を持っていない。 代わりに、そのための関数と フック による特殊なインタフェイスを提供している。 このインタフェイスで、様々な種類のデバッガ、プロファイラ、およびインタプリタの「内部情報」を必要とするその他のツールを作れるようになっている。
lua_Debug
typedef struct lua_Debug {
int event;
const char *name; /* (n) */
const char *namewhat; /* (n) */
const char *what; /* (S) */
const char *source; /* (S) */
int currentline; /* (l) */
int nups; /* (u) 上位値の数 */
int linedefined; /* (S) */
int lastlinedefined; /* (S) */
char short_src[LUA_IDSIZE]; /* (S) */
/* private part */
...
} lua_Debug;
アクティブな関数に関する色々な情報を格納するのに使う構造体。
lua_getstack は後で使うために、この構造体の内部用メンバだけを埋める。
lua_Debug の他のフィールドを役に立つ情報で埋めるには、lua_getinfo を呼ぶ。
lua_Debug の各フィールドは以下のような意味を持っている。
source ---
関数が文字列中で定義されたならば、その文字列である。
関数がファイル中で定義されたならば、`@´ で始まり、その後にファイル名が続く。
short_src ---
エラーメッセージに使う「可読」バージョンの source。
linedefined ---
関数定義の開始位置の行番号。
lastlinedefined ---
関数定義の終了位置の行番号。
what ---
Luaの関数なら "Lua"、
Cの関数なら "C"、
チャンクのメイン部であれば "main"、
関数が終端呼び出ししたならば "tail"。
最後のケースでは、Luaはこの関数について他に何の情報も持っていない。
currentline ---
現在実行中の行番号。
この情報が利用可能でなければ、currentline は -1 に設定される。
name ---
その関数に対する適当な名前。
Luaの関数はファーストクラスの値であるため、固定の名前は持っていない。
複数のグローバル変数に格納されている関数もあれば、テーブルフィールドにのみ格納されているものもある。
lua_getinfo は、その関数がどのように呼ばれたかを調べ、良さそうな名前を探す。
名前が見つからなければ、name は NULL に設定される。
namewhat ---
name フィールドを説明する。
namewhat は、どのように関数が呼ばれたかによって、以下のいずれかになる。
"global", "local", "method",
"field", "upvalue", or ""
(空文字列。他に適当なものがなければこれを使う)。
nups ---
その関数の上位値の数。
lua_gethook
lua_Hook lua_gethook (lua_State *L);
現在のフック関数を返す。
lua_gethookcount
int lua_gethookcount (lua_State *L);
現在のフックカウントを返す。
lua_gethookmask
int lua_gethookmask (lua_State *L);
現在のフックマスクを返す。
lua_getinfo
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
lua_Debug の各フィールドを役に立つ情報で埋める。
エラー (例えば what に不正なを指定したとか) のときは0を返す。
文字列 what の各文字は、構造体 ar のどのフィールドを埋めるかを選択する。
これは lua_Debug の定義で括弧内に書かれた文字で指示する。
`S´ はフィールド source, linedefined, lastlinedefined, what を埋め、
`l´ はフィールド currentline を埋め、以下同様。
さらに、`f´ を指定すると、指定されたレベルで走っている関数をスタックに積む。
アクティブでない (スタック中にない) 関数の情報を得るには、
それをスタックに積んで what を文字 '>' で始まる文字列にする。
例えば、関数 f が定義された行番号を知りたい場合は、次のように書く。
lua_Debug ar;
lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* グローバル変数 `f' を取得 */
lua_getinfo(L, ">S", &ar);
printf("%d\n", ar.linedefined);
lua_getlocal
const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);
指定したアクティベーションレコードのローカル変数についての情報を得る。
引数 ar には、事前に lua_getstack を呼んで埋めるか、フック (lua_Hook を参照) に渡された引数を使うかして、有効なアクティベーションレコードを与えなければならない。
インデックス n は調べるローカル変数を指定する
(1が最初の引数か最初のアクティブなローカル変数で、最後のアクティブなローカル変数まである)。
lua_getlocal はその変数の値をスタックに積み、その名前を返す。
`(´ (開き括弧) で始まる変数名は内部変数を表している
(ループ制御変数、テンポラリ変数、Cの関数のローカル変数など)。
インデックスがアクティブなローカル変数の数より大きいときは、(何も積まずに) NULL を返す。
lua_getstack
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
インタプリタランタイムスタックに関する情報を取得する。
この関数は lua_Debug の一部を、
指定したレベルで実行中の関数の アクティベーションレコード で埋める。
レベル0は現在走っている関数で、レベル n+1 はレベル n の呼び出し元の関数である。
エラーがなければ lua_getstack は1を返す。
スタックの深さよりも大きいレベルが指定された場合は0を返す。
lua_getupvalue
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
クロージャの上位値に関する情報を取得する。
(Luaの関数の上位値は、その関数が使っている外部ローカル変数で、クロージャに取り込まれたもの。)
lua_getupvalue はインデックス n の上位値を取得し、その値をスタックに積み、その名前を返す。
funcindex はスタック中のそのクロージャを指す。
(上位値は関数全体に渡って有効であり、特定の順序も持たない。そのため不定の順序で番号付けられている。)
インデックスが上位値の数より大きい場合は、(何も積まずに) NULL を返す。
Cの関数では、どの上位値に対してもその名前に空文字列 "" を返す。
lua_Hook
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
デバッグフック関数の型。
フックが呼ばれたとき、ar 引数の event フィールドに
フックを起動したイベントが格納されている。
Luaはこれらのイベントを以下の定数で識別する。
LUA_HOOKCALL, LUA_HOOKRET,
LUA_HOOKTAILRET, LUA_HOOKLINE,
LUA_HOOKCOUNT。
さらにlineイベントでは、フィールド currentline も設定される。
ar の他のフィールドを得るには、
lua_getinfo を呼ぶ必要がある。
returnイベントでは、event は通常の LUA_HOOKRET の他に
LUA_HOOKTAILRET が設定される場合がある。
後者はLuaが終端呼び出しした関数からの復帰をシミュレートしたもので、
この場合 lua_getinfo は役に立たない。
Luaがフックを実行している間、他のフック呼び出しは向こうになる。 従って、フック内でLuaの関数やチャンクを呼び出した場合、フックを呼ばずに実行される。
lua_sethook
int lua_sethook (lua_State *L, lua_Hook func, int mask, int count);
デバッグフック関数を設定する。
func はフック関数を指定する。
mask はどのイベントでフックが呼ばれるかを定数
LUA_MASKCALL,
LUA_MASKRET,
LUA_MASKLINE,
LUA_MASKCOUNT の論理和で指定する。
count 引数はmaskが LUA_MASKCOUNT を含むときだけ意味を持つ。
それぞれのイベントについて以下の状況でフックが呼ばれる。
count 命令を実行した直後に呼ばれる
(このイベントはLuaの関数を実行している間だけ起こる)。
mask にゼロを設定すればフックが無効になる。
lua_setlocal
const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);
指定したアクティベーションレコードのローカル変数の値を設定する。
引数 ar および n は lua_getlocal と同じである
(lua_getlocal を参照)。
この関数はlua_setlocal はスタックトップの値をその変数に格納し、その名前を返す。
またその値をスタックから取り除く。
インデックスがアクティブなローカル変数の数よりも大きければ、(何も取り除かずに) NULL を返す。
lua_setupvalue
const char *lua_setupvalue (lua_State *L, int funcindex, int n);
クロージャの上位値の値を設定する。
引数 funcindex および n は lua_getupvalue と同じである
(lua_getupvalue を参照)。
この関数はスタックトップの値をその上位値に格納し、その名前を返す。
またその値をスタックから取り除く。
インデックスが上位値の数よりも大きければ、(何も取り除かずに) NULL を返す。
補助ライブラリ はCとLuaのインタフェイスとなるいくつかの便利な関数を提供する。 基本APIはCとLuaの対話の基本的な関数を提供するが、補助ライブラリはいくつかの共通の作業をする高レベルな関数を提供する。
補助ライブラリのすべての関数はヘッダーファイル lauxlib.h に定義され、接頭語 luaL_ が付いている。
補助ライブラリのすべての関数は基本APIの上に構築されており、そのためこのAPIでできないことは何も提供していない。
補助ライブラリにはCの関数の引数をチェックするための関数がいくつかある。
これらは常に luaL_check* または luaL_opt* という名前である。
これらの関数はチェックが妥当(satisfied?)でなかったときエラーを生成する。
エラーメッセージは引数で書式化される ("bad argument #1" など) ため、
他のスタック値に対してこれらの関数を使うべきではない。
補助ライブラリのすべての関数と型をアルファベット順に示す。
luaL_addchar
void luaL_addchar (luaL_Buffer B, char c);
文字 c をバッファ B に追加する
(luaL_Buffer を参照)。
luaL_addlstring
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
s が指す長さ l の文字列をバッファ B に追加する。
(luaL_Buffer を参照)。
文字列は埋め込まれたゼロを含んでいても良い。
luaL_addsize
void luaL_addsize (luaL_Buffer B, size_t n);
バッファエリア (luaL_prepbuffer を参照) に前回コピーされた長さ n の文字列をバッファ B に追加する。
(luaL_Buffer を参照)。
luaL_addstring
void luaL_addstring (luaL_Buffer *B, const char *s);
s が指すゼロ終端文字列をバッファ B に追加する
(luaL_Buffer を参照)。
文字列に埋め込まれたゼロを含むことはできない。
luaL_addvalue
void luaL_addvalue (luaL_Buffer *B);
スタックトップの値をバッファ B に追加する
(luaL_Buffer を参照)。
その値はスタックから取り除かれる。
これはバッファに追加する値をスタックから取る唯一の文字列バッファ用関数である。
luaL_argcheck
void luaL_argcheck (lua_State *L, int cond, int numarg,
const char *extramsg);
cond が真であることを確認する。
もし違ったら、メッセージ
"bad argument #<numarg> to <func> (<extramsg>)"
のエラーを生成する。
ただし func はコールスタックから取得する。
luaL_argerror
int luaL_argerror (lua_State *L, int numarg, const char *extramsg);
メッセージ
"bad argument #<numarg> to <func> (<extramsg>)"
のエラーを生成する。
ただし func はコールスタックから取得する。
この関数は決して戻らないが、
Cの関数で return luaL_argerror ... として使うのが慣習である。
luaL_Buffer
typedef struct luaL_Buffer luaL_Buffer;
文字列バッファ の型。
文字列バッファはCのコードでLuaの文字列片(strings piecemeal)を組み立てるのに使う。 これは以下のように使用する。
luaL_Buffer 型の変数 b を宣言する。
luaL_buffinit(L, &b) を呼んでそれを初期化する。
luaL_add* 関数のどれかを使ってバッファに文字列片を追加する。
luaL_pushresult(&b) を呼ぶ。
これは最終的な文字列をスタックトップに残す。
通常の操作をしている間、
文字列バッファはいくつかのスタックスロットを使う。
従ってバッファを使っている間は、スタックトップがどこにあるか判っていると仮定できない。
バッファ操作の正しい(successive)呼び出しの間、整合が取れている限りはスタックを使うことができる。
つまり、バッファ操作を呼び出すときは、
スタックが前回バッファ操作した直後と同じ高さでなければならない。
(luaL_addvalue はこのルールの唯一の例外である。)
luaL_pushresult を呼んだあと、
スタックはバッファが初期化される前の高さに戻り、その上に最終的な文字列が積まれる。
luaL_buffinit
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
バッファ B を初期化する。
この関数はいかなる空間も割り当てない。
バッファは変数として宣言しなければならない
(luaL_Buffer を参照)。
luaL_callmeta
int luaL_callmeta (lua_State *L, int obj, const char *e);
メタメソッドを呼ぶ。
インデックス obj のオブジェクトがメタテーブルを持っていて、
このメタテーブルがフィールド e を持っていれば、
この関数はこのフィールドを呼び出し、引数としてそのオブジェクトを渡す。
この場合、この関数は1を返し、呼び出しの戻り値をスタックに積む。
メタテーブルがないかメタメソッドがない場合、
この関数は (スタックに何も積まずに) 0を返す。
luaL_checkany
void luaL_checkany (lua_State *L, int narg);
関数が位置 arg に任意の型 (nil を含む) の引数を持つかチェックする。
luaL_checkint
int luaL_checkint (lua_State *L, int narg);
関数の第 narg 引数が数値であるかをチェックし、
その値を int にキャストして返す。
luaL_checkinteger
lua_Integer luaL_checkinteger (lua_State *L, int narg);
関数の第 narg 引数が数値であるかをチェックし、
その値を lua_Integer にキャストして返す。
luaL_checklong
long luaL_checklong (lua_State *L, int narg);
関数の第 narg 引数が数値であるかをチェックし、
その値を long にキャストして返す。
luaL_checklstring
const char *luaL_checklstring (lua_State *L, int narg, size_t *l);
関数の第 narg 引数が文字列であるかをチェックし、その文字列を返す。
l が NULL でなければ、
*l に文字列の長さを格納する。
luaL_checknumber
lua_Number luaL_checknumber (lua_State *L, int narg);
関数の第 narg 引数が数値であるかをチェックし、
その数値を返す。
luaL_checkoption
int luaL_checkoption (lua_State *L, int narg, const char *def,
const char *const lst[]);
関数の第 narg 引数が文字列であるかチェックし、
配列 lst (NULL終端でなければならない) からその文字列を検索する。
def が NULL でなければ、
関数が第 narg 引数を持たないかその引数が nil であった場合のデフォルト値として使う。
文字列が見つかった配列インデックスを返す。 引数が文字列でないか文字列が見つからなければエラーを発生する。
この関数は文字列をCの列挙型に変換するのに役に立つ。 Luaのライブラリにおける通常の慣例では、オプションを選択するのに、数値でなく文字列を使う。
luaL_checkstack
void luaL_checkstack (lua_State *L, int sz, const char *msg);
スタックサイズを top + sz 個の要素に伸ばす。
スタックがそのサイズに伸ばせなければエラーを発生する。
msg はそのエラーメッセージに入れる追加の文字列である。
luaL_checkstring
const char *luaL_checkstring (lua_State *L, int narg);
関数の第 narg 引数が文字列であるかチェックし、その文字列を返す。
luaL_checktype
void luaL_checktype (lua_State *L, int narg, int t);
関数の第 narg 引数が型 t であるかチェックする。
luaL_checkudata
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
関数の第 narg 引数が型 tname のユーザーデータであるかチェックする
(luaL_newmetatable を参照)。
luaL_error
int luaL_error (lua_State *L, const char *fmt, ...);
エラーを発生させる。
エラーメッセージの書式は fmt と追加の引数で与えられる。
これは lua_pushfstring のと同じルールに従う。
また、メッセージの最初にエラーが発生したファイル名と行番号を、それらの情報が利用可能ならば、追加する。
この関数は決して戻らないが、
Cの関数で return luaL_error ... のように使うのが慣例である。
luaL_getmetafield
int luaL_getmetafield (lua_State *L, int obj, const char *e);
インデックス obj のオブジェクトのメタテーブルのフィールド e をスタックに積む。
そのオブジェクトがメタテーブルを持っていないか、メタテーブルがそのフィールドを持っていなければ
0 を返して何も積まない。
luaL_getmetatable
void luaL_getmetatable (lua_State *L, const char *tname);
レジストリの名前 tname に関連付けられたメタテーブルをスタックに積む
(luaL_newmetatable を参照)。
luaL_gsub
const char *luaL_gsub (lua_State *L, const char *s,
const char *p, const char *r);
文字列 s 中の文字列 p をすべて文字列 r で置換したコピーを作る。
その結果の文字列をスタックに積み、それを返す。
luaL_loadbuffer
int luaL_loadbuffer (lua_State *L, const char *buff,
size_t sz, const char *name);
Luaのチャンクとしてバッファをロードする。
この関数は lua_load を使って buff が指すサイズ sz のバッファに格納されているチャンクをロードする。
この関数は lua_load と同じ結果を返す。
name はデバッグ情報やエラーメッセージで使うチャンク名である。
luaL_loadfile
int luaL_loadfile (lua_State *L, const char *filename);
Luaのチャンクとしてファイルをロードする。
この関数は lua_load を使って名前 filename のファイルに格納されているチャンクをロードする。
filename が NULL の場合は標準入力から読み込む。
ファイルが # で始まっていたら、その最初の行を無視する。
この関数は lua_load と同じ結果を返すが、
追加のエラーコードとしてファイルを開けなかったり読めなかった場合は LUA_ERRFILE を返す。
luaL_loadstring
int luaL_loadstring (lua_State *L, const char *s);
Luaのチャンクとして文字列をロードする。
この関数は lua_load を使ってゼロ終端文字列 s に格納されているチャンクをロードする。
この関数は lua_load と同じ結果を返す。
luaL_newmetatable
int luaL_newmetatable (lua_State *L, const char *tname);
レジストリにキー tname がすでにあれば 0 を返す。
そうでなければ、ユーザーデータのメタテーブルとして使う新しいテーブルを作り、
それをレジストリにキー tname と共に追加して 1 を返す。
どちらの場合もレジストリの tname に関連付けられた最終的な値をスタックに積む。
luaL_newstate
lua_State *luaL_newstate (void);
標準のCの realloc 関数をベースにしたアロケータ関数を使って
lua_newstate を呼び、新しいLuaステートを作成する。
また、致命的エラーの場合に標準エラー出力にエラーメッセージを出力するパニック関数
(lua_atpanic を参照) を設定する。
新しいステートを返す。
メモリ確保エラーの場合は NULL を返す。
luaL_openlibs
void luaL_openlibs (lua_State *L);
指定したステートにすべての標準Luaライブラリを開く。
luaL_optint
int luaL_optint (lua_State *L, int narg, int d);
関数の第 narg 引数が数値であれば、その数値を int にキャストして返す。
その引数が存在しないか nil であれば、d を返す。
さもなくばエラーを発生する。
luaL_optinteger
lua_Integer luaL_optinteger (lua_State *L, int narg, lua_Integer d);
関数の第 narg 引数が数値であれば、
その数値を lua_Integer にキャストして返す。
その引数が存在しないか nil であれば、d を返す。
さもなくばエラーを発生する。
luaL_optlong
long luaL_optlong (lua_State *L, int narg, long d);
関数の第 narg 引数が数値であれば、その数値を long にキャストして返す。
その引数が存在しないか nil であれば、d を返す。
さもなくばエラーを発生する。
luaL_optlstring
const char *luaL_optlstring (lua_State *L, int narg,
const char *d, size_t *l);
関数の第 narg 引数が文字列であれば、その文字列を返す。
引数が存在しないか nil であれば、d を返す。
さもなくばエラーを発生する。
l が NULL でなければ、結果の長さを *l に格納する。
luaL_optnumber
lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);
関数の第 narg 引数が数値であれば、その数値を返す。
その引数が存在しないか nil であれば、d を返す。
さもなくばエラーを発生する。
luaL_optstring
const char *luaL_optstring (lua_State *L, int narg, const char *d);
関数の第 narg 引数が文字列であれば、その文字列を返す。
その引数が存在しないか nil であれば、d を返す。
さもなくばエラーを発生する。
luaL_prepbuffer
char *luaL_prepbuffer (luaL_Buffer *B);
バッファ B に追加するための文字列を格納できる、
サイズ LUAL_BUFFERSIZE の領域のアドレスを返す
(luaL_Buffer を参照)。
文字列をこの領域に格納したあと、文字列のサイズを渡して
luaL_addsize
を呼び、実際にバッファに追加しなければならない。
luaL_pushresult
void luaL_pushresult (luaL_Buffer *B);
スタックトップに最終的な文字列を残してバッファ B の使用を終える。
luaL_ref
int luaL_ref (lua_State *L, int t);
インデックス t のテーブルにスタックトップのオブジェクトに対する リファレンス を作成し、それを返す(そしてオブジェクトをスタックから取り除く)。
リファレンスは一意な整数のキーである。
テーブル t に整数キーを手動で追加しなければ、
luaL_ref は返すキーの一意性を保証する。
lua_rawgeti(L, t, r) を呼ぶと、リファレンス r が参照するオブジェクトを取得できる。
luaL_unref はリファレンスとそれに関連付けられたオブジェクトを解放する。
スタックトップのオブジェクトが nil の場合、
luaL_ref は定数 LUA_REFNIL を返す。
定数 LUA_NOREF は luaL_ref
が返すいかなるリファレンスとも異なることが保証されている。
luaL_Reg
typedef struct luaL_Reg {
const char *name;
lua_CFunction func;
} luaL_Reg;
luaL_register が登録する関数の配列の型。
name は関数の名前で、func は関数へのポインタである。
luaL_Reg の配列は
name と func が共に NULL である番兵エントリで終わらなければならない。
luaL_register
void luaL_register (lua_State *L, const char *libname,
const luaL_Reg *l);
ライブラリを開く。
libname に NULL を渡して呼ぶと、
単純にリスト l
(luaL_Reg を参照)
の関数をすべてスタックトップのテーブルに登録する。
libname がNULLでなければ、
新しいテーブル t を作成し、
それをグローバル変数 libname の値として設定し、
package.loaded[libname] の値として設定し、
そしてリスト l の関数をすべてそこに登録する。
もし package.loaded[libname] か変数 libname にテーブルが存在すれば、
新しいテーブルを作る代わりにそれを再利用する。
いずれの場合も、この関数はスタックトップにそのテーブルを置く。
luaL_typename
const char *luaL_typename (lua_State *L, int idx);
インデックス idx の値の型の名前を返す。
luaL_typerror
int luaL_typerror (lua_State *L, int narg, const char *tname);
<location>: bad argument <narg> to <function> (<tname> expected, got <realt>)のようなメッセージのエラーを生成する。 ただし
<location> は luaL_where によって生成されたもので、
<function> は現在の関数の名前、
and <realt> は実引数の型名である。
luaL_unref
void luaL_unref (lua_State *L, int t, int ref);
インデックス t のテーブルからリファレンス ref を解放する
(luaL_ref を参照)。
エントリがテーブルから取り除かれるので、参照されていたオブジェクトは回収され得る。
リファレンス ref も再利用するために解放される。
ref が LUA_NOREF または LUA_REFNIL の場合、
luaL_unref は何もしない。
luaL_where
void luaL_where (lua_State *L, int lvl);
コールスタックのレベル lvl の制御の現在位置を識別する文字列をスタックに積む。
典型的にこの文字列は <chunkname>:<currentline>: のような書式になっている。
レベル0は実行中の関数、
レベル1は実行中の関数の呼び出し元の関数、
以下同様である。
この関数はエラーメッセージの接頭辞を構築するために使う。
Lua標準ライブラリは、CのAPIを使って直接実装された便利な関数を提供する。
いくつかは言語の本質的なサービスを提供するものであり
(例えば type や getmetatable)、
残りは「外部の」サービスへのアクセスを提供するものである (例えば I/O)。
また、Lua自身で実装可能であるが、便利さやパフォーマンス要求のためにCで実装されたものもある (例えば sort)。
すべてのライブラリは公開されているCのAPIを使って実装されており、独立したCのモジュールで提供されている。 現在、Luaには以下の標準ライブラリがある。
これらのライブラリを使うには、Cのホストプログラムで
すべての標準ライブラリを開く luaL_openlibs を呼ばなければならない。
代わりに、
luaopen_base (基本ライブラリ用)、
luaopen_package (パッケージライブラリ用)、
luaopen_string (文字列ライブラリ用)、
luaopen_table (テーブルライブラリ用)、
luaopen_math (数学ライブラリ用)、
luaopen_io (I/OライブラリとOSライブラリ用)、
luaopen_debug (デバッグライブラリ用)
を呼んで個別に開くこともできる。
これらは lualib.h に定義されているが、
直接呼ぶべきではなく、他のLuaのC関数と同様に
----
例えば lua_call を使って
----
呼ばなければならない。
基本ライブラリはLuaへのコアな機能を提供する。 アプリケーションにこのライブラリを含めない場合は、その機能を提供する代わりの実装を用意する必要があるか慎重に調べるべきである。
assert (v [, message])v が偽 (すなわち nil または false) であればエラーを発生させる。
そうでなければ、そのすべての引数を返す。
message はエラーメッセージを指定する。
省略された場合は "assertion failed!" である。
collectgarbage (opt [, arg])
この関数はガベージコレクタへの汎用インタフェイスである。
最初の引数 opt によって異なる機能を実行する。
arg で制御する。
大きな値は大きなステップを意味するが、具体的には定まっていない。
ステップサイズを制御したければ、
arg の値を実験的に調整しなければならない。
このステップでコレクションサイクルが終わった場合は true を返す。
arg÷100に設定する。
arg÷100に設定する
(2.10 を参照)。
dofile (filename)stdin) から読み取って実行する。
dofileはチャンクから返されたすべての値をそのまま返す。
エラーが起きた場合は、呼び出し側に伝搬される (つまり dofile は保護モードで動くのではない)。
error (message [, level])message をエラーメッセージとして返す。
関数 error は戻らない。
通常、error はメッセージの先頭にエラーの位置に関する何らかの情報を追加する。
level 引数は、エラーメッセージがエラー位置をどのように得るかを指定する。
レベル1では (デフォルト)、error 関数を呼んだ場所がエラー位置である。
レベル2は error を呼んだ関数を呼んだ位置を指す。
以下同様である。
レベル0を渡すとメッセージにエラー位置情報を追加しない。
_G_G._G = _G である。
Lua自身はこの変数を使用しないので、この値を変更しても環境には何の影響もなく、逆もまた同じである
(環境を変えるには setfenv を使う)。
getfenv (f)f はLuaの関数か、関数のスタックレベルを示す数値である。
レベル1はgetfenvを呼んだ関数である。
もし与えられた関数がLuaの関数でなかったり、fが0の場合は、getfenv はグローバル環境を返す。
f のデフォルト値は1である。
getmetatable (object)
もし object がメタテーブルを持っていなければ nil を返す。
もしobjectのメタテーブルが "__metatable" フィールドを持っていれば、その値を返す。
そうでなければobjectのメタテーブルを返す。
ipairs (t)
3つの値、イテレータ関数、テーブル t、および0を返す。
for i,v in ipairs(t) do ... end
は (1,t[1])、(2,t[2])、…のペアを、最初に値にnilが現れるまで繰り返す。
巡回中にテーブルを変更する際の注意は next を参照。
load (func [, chunkname])
そのピースを取得する関数 func を使ってチャンクをロードする。
func は前回の戻り値と連結する文字列を返さなければならない。
nil を返す (または戻り値なし) とチャンクの終わりを知らせる。
エラーがなければ、コンパイルされたチャンクが関数として返され、 そうでなければ nil とエラーメッセージが返される。 返された関数の環境はグローバル環境である。
chunkname はエラーメッセージやデバッグ情報のためのチャンク名を指定する。
loadfile ([filename])
load と同じであるが、
ファイル filename からチャンクを読み込む。
ファイル名を与えなければ標準入力から読み込む。
loadstring (string [, chunkname])
load と同じであるが、
指定した文字列からチャンクを読み込む。
与えられた文字列をロードして実行するには、以下の慣用句を使う。
assert(loadstring(s))()
next (table [, index])
テーブルの全フィールドを巡回するための関数である。
最初の引数はテーブルを、二番目の引数はこのテーブルのインデックスを渡す。
next はテーブル内の次のインデックスと、その値を返す。
二番目の引数に nil を渡すと、初期インデックスとその値が返される。
最後のインデックスで呼び出すか、空のテーブルに対して nil で呼び出すと、
next は nil を返す。
二番目の引数が省略された場合は nil と解釈される。
特に、next(t) を使うとテーブルが空かどうか調べることができる。
Luaにはフィールドの宣言がない。
テーブル内にフィールドが存在しないのと、nil 値が格納されたフィールドには、何の違いも無い。
ゆえに、next は nil でない値を持つフィールドのみを考慮する。
インデックスが列挙される順番は、数値のインデックスに対しても、不定である
(数値順にテーブルを巡回するには、数値用の for 文や ipairs 関数を使う)。
テーブルの巡回中に、もし存在していないフィールドに新たに値が割り当てられたら、next の動作は 未定義 である。
しかし既存のフィールドは変更してもよい。
特に、既存のフィールドを消去するのは構わない。
pairs (t)
3つの値、next 関数、テーブル t、nil を返す。
for k,v in pairs(t) do ... end
はテーブル t のすべてのキー・値ペアについて繰り返す。
巡回中にテーブルを変更する際の注意は next を参照。
+
pcall (f, arg1, arg2, ...)
保護モードで、与えられた引数で f を呼び出す。
つまり f の内部で発生したエラーは伝搬されず、
代わりに pcall がエラーを捕らえ、ステータスコードを返す。
最初の引数はステータスコード (ブーリアン型) で、エラーなしに呼び出しが成功したときは真を返す。
その場合、f の戻り値もすべて、最初の戻り値に続いて返される。
エラーが起こった場合、pcall は false とエラーメッセージを返す。
print (e1, e2, ...)tostring で文字列に変換してから標準出力 (stdout) に表示する。
print は書式化出力を意図したものではなく、
典型的にはデバッグのために、値を表示する簡単な方法として用意されているだけである。
書式化出力には string.format を使う。
rawequal (v1, v2)v1 と v2 が等しいかどうか調べる。
ブーリアンを返す。
rawget (table, index)table[index] の本当の値を得る。
table はテーブルでなければならない。
index は nil 以外のどんな値でも良い。
rawset (table, index, value)table[index] に value をセットする。
table はテーブルでなければならない。
index は nil 以外のどんな値でも良い。
value はどんなLuaの値でも良い。
select (index, ...)
index が数値であれば、
index 番目以降の引数をすべて返す。
そうでなければ、index は文字列 "#" でなければならない。
この場合 select は受け取った余分の引数の合計数を返す。
setfenv (f, table)
指定された関数で使われる環境を変更する。
f はLuaの関数か、関数のスタックレベルを指定する数値である。
レベル1は setfenv を呼び出した関数を示す。
setfenv は与えられた関数を返す。
特殊なケースとして、fに0が与えられると、setfenv は走行中のスレッドの環境を変える。
この場合、setfenv は何も返さない。
setmetatable (table, metatable)
table のメタテーブルを変更する
(Luaから他の型のメタテーブルを変更することはできない。Cからのみ可能である)。
もし metatable が nil であれば、table のメタテーブルは除去される。
元のメタテーブルが "__metatable" フィールドを持っていると、エラーを発する。
この関数は table を返す。
tonumber (e [, base])tonumber は数値を返す。
そうでなければ nil を返す。
省略可能な引数は数値を解釈する際の基数を指定する。
基数は2から36の整数を指定できる。
10より大きい基数では、`A´が10を表し、`B´が11を表し、
以下同様に続き、`Z´が35を表す (大文字でも小文字でも良い)。
基数が10 (デフォルト) の場合 は、数値に小数部や指数部を付けることができる (2.1 を参照)。
他の基数では、符号なしの整数のみを受け付ける。
tostring (e)string.format を使う。
もし e のメタテーブルが "__tostring" フィールドを持っていたら、
e を引数に、その関連付けられた値が呼び出され、その戻り値が結果として使われる。
type (v)
"nil" (という文字列。nil 値ではなく。)
"number"
"string"
"boolean"
"table"
"function"
"thread"
"userdata"
unpack (list [, i [, j]])return list[i], list[i+1], ..., list[j]デフォルトでは、
i は1で j
は長さ演算子 (2.5.5 を参照) 定義されているリストの長さである。
_VERSION"Lua 5.1" である。
xpcall (f, err)
この関数は pcall に似ているが、エラーハンドラを指定できる点が異なる。
xpcall は保護モードで f を呼び出し、
err をエラーハンドラとして使う。
f の内部で発生したエラーは伝搬されない。
代わりに、xpcall がエラーを捕らえ、エラーオブジェクトを引数に err を呼ぶ。
最初の戻り値はステータスコード (ブーリアン型) で、
エラーが起きなかった場合は true を返す。
その場合、最初の戻り値に続いて f の戻り値もすべて返される。
エラーが起きた場合、xpcall は false と err の戻り値を返す。
コルーチン関連の操作は基本ライブラリのサブライブラリであり、テーブル coroutine 内に置かれている。
コルーチンに関する一般的な説明は 2.11 を参照。
coroutine.create (f)
f を本体とする新しいコルーチンを作る。
f はLuaの関数でなければならない。
"thread" 型の新しいコルーチンオブジェクトを返す。
coroutine.resume (co [, val1, ..., valn])
コルーチン co の実行を開始/再開する。
コルーチンを最初にresumeしたとき、その本体の実行が開始される。
値 val1, ... は本体の関数に引数として渡される。
コルーチンが中断されていた場合、resume はそれを再開し、
yield からの戻り値として val1, ... が渡される。
コルーチンがエラー無く実行されれば、
resume は true に加えて yield に渡された値 (コルーチンが中断された場合)、
もしくは本体の関数から返された値 (コルーチンが終了した場合) を返す。
エラーが起きたら、resume は false とエラーメッセージを返す。
coroutine.running ()走行中のコルーチンを返す。 メインスレッドで呼ばれた場合は nil を返す。
coroutine.status (co)
コルーチン co の状態を文字列で返す。
"running" ... コルーチンは走行中。
"suspended" ... コルーチンは yield の呼び出しで中断されているが、まだ実行中である。
"normal" ... コルーチンはアクティブであるが走行中でない(つまり他のコルーチンをresumeしている)。
"dead" ... コルーチンの本体の関数が終了したか、エラーで停止した。
coroutine.wrap (f)
f を本体とする新しいコルーチンを作成する。
f はLuaの関数でなければならない。
coroutine.wrap は、呼ばれるたびにコルーチンを再開する関数を返す。
関数に渡された引数は resume に余分に渡される引数と同じ動作をし、
戻り値は resume から最初のブーリアンを除いた値と同じである。
もしエラーが起きた場合、エラーは伝搬する。
coroutine.yield ([val1, ..., valn])
呼ばれたコルーチンの実行を中断する。
コルーチンは、Cの関数やメタメソッド、イテレータを中断することはできない。
yield に渡された引数は resume から追加の戻り値として返される。
Luaでモジュールを構築したりロードしたりする基本的な機能を提供する。
2つの関数 require および module はグローバル環境に直接エクスポートされる。
それ以外はすべてテーブル package にエクスポートされる。
module (name [, ...])
モジュールを作成する。
package.loaded[name] にテーブルがあれば、
このテーブルがモジュールである。
そうでなければ、指定した名前のグローバルなテーブル t があれば、
このテーブルがモジュールである。
そうでなければ、新しいテーブル t を作成し、
グローバル変数 name の値と
package.loaded[name] の値にそれを設定する。
またこの関数は指定された名前で t._NAME を、
モジュール (t それ自身) で t._M を、
パッケージ名 (完全なモジュール名から最後の部分を除いたもの、下記参照) で t_PACKAGE を初期化する。
最後に、module は現在の関数の新しい環境および package.loaded[name] の新しい値として t を設定する。
従って require は t を返す。
もし name が複合名
(つまり、ドットで各部が区切られたもの) であれば、
module はそれぞれの部分についてテーブルを作る (または、すでに存在すれば再利用する)。
例えば、name が a.b.c の場合、
module はグローバル変数 a のフィールド b
のフィールド c にモジュールテーブルを格納する。
この関数はモジュール名の後に省略可能な オプション を渡すことができる。 この各オプションはモジュール全体に適用される関数である。
require (modname)
指定したモジュールをロードする。
この関数は modname がすでにロードされているかどうかを決定するために
まずテーブル package.loaded を探す。
もしすでにロードされていれば、require は
package.loaded[modname] に格納されている値を返す。
そうでなければ、モジュールの ローダ を探す。
ローダを探すために、
require はまず package.preload[modname] を問い合わせる。
もしそこに値があれば、この値 (関数であるべきである) がローダである。
そうでなければ、require は package.path に格納されているパスを使う
Luaのローダを探す。
それも失敗したら、package.cpath に格納されているパスを使うCのローダを探す。
それもまた失敗したら、オールインワンローダ (下記参照) を試す。
Cのライブラリをロードする場合、
require はまずアプリケーションをそのライブラリとリンクするためのダイナミックリンク機能を使う。
次にこのライブラリ内からローダとして使うためのCの関数を探す。
このCの関数は "luaopen_" にモジュール名を付けた名前であるが、
ドットはアンダースコアに置換する。
さらに、モジュール名にハイフンが含まれていれば、
その最初のハイフンまでの接頭辞は (ハイフンも含めて) 取り除かれる。
例えば、モジュール名が a.v1-b.c の場合、関数名は luaopen_b_c となる。
require がLuaのライブラリにもCのライブラリにもモジュールを見つけられなければ、
オールインワンローダ を呼ぶ。
このローダはCのパスを見て、指定したモジュールのルート名に対するライブラリを探す。
例えば a.b.c が要求された場合、a というCのライブラリを探す。
もし見つかれば、そのサブモジュールに対するオープン関数をその中から探す。
先の例でいうと、luaopen_a_b_c となる。
この機能により、いくつものCのサブモジュールをひとつのライブラリに納めることができる。
その場合でも各サブモジュールは、それぞれ独自のオープン関数を持つ。
ローダが見つかれば、
require は単一の引数 modname を渡してローダを呼ぶ。
ローダが何らかの値を返すと、
require はそれを package.loaded[modname] に格納する。
ローダが値を返さず、package.loaded[modname] に何の値も格納されていなければ、
require はこのエントリに true を格納する。
いずれにせよ、require は最終的な package.loaded[modname] の値を返す。
モジュールのロードまたは実行でエラーがあったり、そのモジュールのローダが見つからなければ、
require はエラーを発生する。
package.cpath
Cのローダを探すために require が使うパス。
Luaは環境変数 LUA_CPATH
(に加えて、luaconf.h に定義されているもうひとつのデフォルトパス)
を使って、
Luaのパス package.path と同じ方法で
Cのパス package.cpath を初期化する。
package.loaded
すでにロードされたモジュールを管理するために
require が使うテーブル。
モジュール modname が要求され、
package.loaded[modname] が偽でなければ、
require は単に、そこに格納されている値を返す。
package.loadlib (libname, funcname)
ホストプログラムをCのライブラリ libname と動的リンクする。
このライブラリの中で関数 funcname を探し、その関数をCの関数として返す
(従って、funcname は呼び出し規約
(lua_CFunction を参照)
に従わなければならない)。
これは低レベルな関数であり、パッケージシステムやモジュールシステムを完全に迂回する。
require と異なり、
パス探索を行ったり拡張子を自動的に付加したりしない。
libname はCのライブラリの完全なファイル名でなければならず、
必要ならパスや拡張子も含めなければならない。
funcname はCのライブラリがエクスポートしている完全な名前でなければならない
(使っているCコンパイラやリンカに依存するであろう)。
この関数はANSI Cのサポート範囲外である。
従って、これはいくつかのプラットフォーム (Windows, Linux, Mac OS X, Solaris, BSD,
および dlfcn 標準をサポートする他のUnixシステム)
でしか利用できない。
package.path
Luaのローダを探すために require が使うパス。
起動時にLuaは環境変数 LUA_PATH の値、
またはその環境変数が定義されていなければ
luaconf.h で定義されているデフォルトパスで、この変数を初期化する。
環境変数の値に ";;" があれば、それをデフォルトパスで置換する。
パスはセミコロンで区切られた一連の テンプレート である。
各テンプレートについて、
require は
テンプレート内の疑問符 (interrogation mark) を ファイル名 に置換し、
結果のファイル名をロードしようと試みる。
このファイル名は、モジュール名のドットを
「ディレクトリ区切り文字」 (Unixの "/" のような) で置き換えたものである。
例えば、Luaのパスが
"./?.lua;./?.lc;/usr/local/?/init.lua"であった場合、モジュール
foo のLuaのローダの検索は、
ファイル ./foo.lua、./foo.lc、
/usr/local/foo/init.lua のロードをこの順序で試みる。
package.preload
特定のモジュールのローダを格納するテーブル
(require を参照)。
package.seeall (module)
__index フィールドがグローバル環境を参照するメタテーブルを
module にセットする。
従ってこのモジュールはグローバル環境から値を継承する。
関数 module へのオプションとして使われる。
このライブラリは、検索や部分文字列の抽出、パターンマッチングといった、文字列操作のための一般的な機能を提供する。 Luaの文字列のインデックス付けは、最初の文字が1の位置である (Cのように0ではない)。 文字列の末尾から逆方向にマイナス値で指定することもできる。 つまり、最後の文字は -1 の位置で示される。
文字列ライブラリはすべて、テーブル string 内の関数として提供される。
また、__index フィールドが自身を指す文字列用メタテーブルをセットする。
従って、文字列関数はオブジェクト指向スタイルで使うことができる。
例えば、string.bytes(s, i) は s:byte(i) と書くこともできる。
string.byte (s [, i [, j]])s[i], s[i+1], ..., s[j] の内部コードの数値を返す。
i のデフォルトは1、
j のデフォルトは i である。
文字コードの数値は、プラットフォームを超えての可搬性がないことに注意。
string.char (i1, i2, ...)文字コードの数値は、プラットフォームを超えての可搬性がないことに注意。
string.dump (function)
指定された関数のバイナリ表現を保持する文字列を返す。
loadstring にこの文字列を渡すことで、関数のコピーを作ることができる。
function は上位値を持たないLua関数でなければならない。
string.find (s, pattern [, init [, plain]])s 内で pattern の最初のマッチを探す。
もしマッチが見つかれば、find は s 内でこのパターンがマッチした開始位置と終了位置のインデックスを返す。
そうでなければ nil を返す。
三番目の省略可能な引数 init は検索開始位置を指定し、デフォルト値は1で、負の値も使える。
四番目の省略可能な引数 plain に true が指定されると、
パターンマッチング機能はオフになり、
pattern 中の「魔法の」文字は無くなって、ただの「部分文字列を検索する」操作になる。
plain を与える場合は init も与えなければならないことに注意。
もしパターン内にキャプチャが指定されていれば、 マッチ成功時にキャプチャされた文字列が2つのインデックスの後に返される。
string.format (formatstring, e1, e2, ...)*、l、L、n、p、h
はサポートされてなくて、追加の q がある点だけが異なる。
q オプションは、Luaインタプリタで安全に読み戻せる適切な形式の文字列に書式化する。
その文字列はダブルクォートの間に書かれ、
文字列中のダブルクォート、改行、埋め込まれたゼロ、バックスラッシュは正しくエスケープされる。
例えば、
string.format('%q', 'a string with "quotes" and \n new line')
は次のような文字列を生成する。
"a string with \"quotes\" and \ new line"
c、d、E、e、f,
g、G、i、o、u,
X、x はすべて数値の引数を期待し、
q と s は文字列を期待する。
この関数は埋め込まれたゼロを含む文字列を受け付けない。
string.gmatch (s, pattern)
呼ばれるたびに文字列 s から pattern でキャプチャされた部分を次々と返すような、イテレータ関数を返す。
pattern にキャプチャが指定されていなければ、それぞれの呼び出しごとに、マッチした文字列全体を返す。
例えば、以下のループでは
s = "hello world from Lua"
for w in string.gmatch(s, "%a+") do
print(w)
end
文字列 s のすべての単語について繰り返し、それぞれを別々の行に出力する。
次の例は、与えられた文字列から key=value のペアを集めてテーブルへ入れる。
t = {}
s = "from=world, to=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
t[k] = v
end
string.gsub (s, pattern, repl [, n])pattern をすべて repl によって指定された置換文字列に置き換えた s のコピーを返す。
repl は文字列、テーブル、または関数でもよい。
gsub は二番目の値として、置換が行われた回数も返す。
repl が文字列であれば、その値が置換に使われる。
文字 % はエスケープ文字として機能する。
repl 内に現れる %n は (n は1から9)、
n 番目にキャプチャされた部分文字列を表す (以下を見よ)。
シーケンス %0 はマッチ全体を表す。
シーケンス %% は1個の % を表す。
repl がテーブルであれば、
そのテーブルは最初のキャプチャをキーとしてマッチのたびに問い合わせられる。
パターンにキャプチャがなければ、マッチ全体がキーとして使われる。
repl が関数であれば、マッチが現れるたびにこの関数が呼ばれる。
関数にはキャプチャされた部分文字列が順番にすべて渡される。
パターンにキャプチャが指定されていなければ、マッチした全体が唯一の引数として渡される。
テーブル問い合わせまたは関数呼び出しから返された値が文字列か数値であれば、
それが置換文字列として使われる。
そうでなくて false か nil であれば、置換は行われない
(つまり、文字列中の元のマッチが維持される)。
省略可能な最後の引数 n は置換が行われる最大回数を制限する。
例えば、n が1なら最初に現れる pattern だけが置換される。
いくつか例を示す。
x = string.gsub("hello world", "(%w+)", "%1 %1")
--> x="hello hello world world"
x = string.gsub("hello world", "%w+", "%0 %0", 1)
--> x="hello hello world"
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
--> x="world hello Lua from"
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
--> x="home = /home/roberto, user = roberto"
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
return loadstring(s)()
end)
--> x="4+5 = 9"
local t = {name="lua", version="5.1"}
x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t)
--> x="lua-5.1.tar.gz"
string.len (s)"" の長さは0である。
文字列中のゼロも数えるので、"a\000b\000c" の長さは5である。
string.lower (s)string.match (s, pattern [, init])s から pattern の最初の マッチ を探す。
見つかった場合、match はパターンのキャプチャを返し、
そうでなければ nil を返す。
pattern にキャプチャがなければ、マッチ全体が返される。
3つめの省略可能な数値の引数 init は検索を開始する位置を指定する。
デフォルト値は1で、負の値を指定してもよい。
string.rep (s, n)s のコピーを n 個連結した文字列を返す。
string.reverse (s)s を反転した文字列を返す。
string.sub (s, i [, j])s の、位置 i から位置 j までの部分文字列を返す。
i にも j にも、負の値を使える。
j が省略されたときは -1 とみなされる (つまり文字列の長さと同じ)。
特に、string.sub(s,1,j) は s の先頭から j 文字を取り出し、
string.sub(s, -i) は s の最後の i 文字を取り出す。
string.upper (s)文字クラス は文字の集合を表す。 以下の組み合わせを文字クラスの指定に使うことができる。
^$()%.[]*+-? 以外の文字)
--- 文字 x それ自身を表す。
. --- (ドット) すべての文字を表す。
%a --- すべてのletterを表す。
%c --- すべての制御文字を表す。
%d --- すべての数字を表す。
%l --- すべての小文字を表す。
%p --- すべての区切り記号を表す。
%s --- すべての空白文字を表す。
%u --- すべての大文字を表す。
%w --- すべての英数文字を表す。
%x --- すべての十六進数字を表す。
%z --- 0として表現される文字を表す。
%x (x は英数文字以外) ---
文字 x 自身を表す。
これは魔法の文字をエスケープする標準的な方法である。
いかなる区切り文字 (魔法の文字でなくても) は前に `%´ を付けることでそれ自身を表すことができる。
[set] ---
set 内のすべての文字の和からなるクラスを表す。
終わりの文字と `-´ で繋げることで、文字の範囲を表す。
上で挙げた %x 形式のすべてのクラスも、set の中で使うことができる。
それ以外の set 内の文字は、それ自身を表す。
例えば、[%w_] (または [_%w]) は、すべての英数にアンダースコアを加えたものを表す。
[0-7] は八進数字を表し、
[0-7%l%-] は八進数字と小文字と `-´ を表す。
範囲とクラスの相互作用は未定義である。
つまり、[%a-z] や [a-%%] のようなパターンは意味を持たない。
[^set] ---
set の補集合を表す。
set の内容は上で説明したものと同じである。
%a、%cなど) はすべて、対応する大文字は補集合を表す。
例えば %S は空白以外のすべての文字を表す。
文字、空白、その他の文字のグループの定義については、現在のロケールに依存する。
特に、クラス [a-z] は %l と等価ではないかもしれない。
パターンの要素 は以下のいずれかである。
*´ が続いたもの。
そのクラスの文字の0回以上の繰り返しにマッチする。
この繰り返し要素は、可能な限り長いシーケンスにマッチする。
+´ が続いたもの。
そのクラスの文字の1回以上の繰り返しにマッチする。
この繰り返し要素は、可能な限り長いシーケンスにマッチする。
-´ が続いたもの。
そのクラスの文字の0回以上の繰り返しにマッチする。
`*´ と異なり、この繰り返し要素は可能な限り 短い シーケンスにマッチする。
?´ が続いたもの。
そのクラスの文字の0回または1回の出現にマッチする。
%n (n は1から9)。
これは、n 番目にキャプチャされた文字列にマッチするような要素である (下の説明を参照)。
%bxy (x と y は異なる文字)。
これは x で始まって y で終わる文字列にマッチするような要素である。
x と y は 対応が取れる。
つまり、文字列を左から右に読んでいって、
x が現れるたびにカウントを +1 し、y では -1 したとき、
最後の y はカウントが0になる最初の y である。
例えば、要素 %b() はカッコの対応が取れた式にマッチする。
pattern はパターン要素の列である。
パターンの最初に現れる `^´ は対象文字列の先頭にマッチを固定する。
パターンの最後に現れる `$´ は対象文字列の最後にマッチを固定する。
他の位置では、`^´ や `$´ は特別な意味を持たず、それ自身を表す。
パターンはカッコで囲まれたサブパターンを持つことができ、それらは キャプチャ と呼ばれる。
マッチが成功したとき、対象文字列の中でキャプチャにマッチした部分が保存 (キャプチャ) され、後で使うことができる。
キャプチャはその左カッコによって番号付けされる。
例えば、パターン "(a*(.)%w(%s*))" では、
"a*(.)%w(%s*)" にマッチする部分が最初のキャプチャとして保存され (だから1番になる)、
"." にマッチする文字が2番にキャプチャされ、
"%s*" にマッチする部分が3番になる。
特殊なケースとして、空キャプチャ () は文字列の現在位置 (数値) をキャプチャする。
例えば、文字列 "flaaap" にパターン "()aa()" を適用すると、
2つのキャプチャ3と5を得られる。
パターンには途中にゼロを含むことができない。代わりに %z を使う。
table 内にすべての関数が提供される。
これらの関数でテーブルの「長さ」について言及するときは、
それは長さ演算子の結果を意味している。
table.concat (table [, sep [, i [, j]]])table[i]..sep..table[i+1] ... sep..table[j] を返す。
sep のデフォルト値は空文字列で、
i のデフォルト値は1、
j のデフォルト値はテーブルの長さである。
i が j よりも大きい場合は空文字列を返す。
table.insert (table, [pos,] value)
table の位置 pos に要素 value を挿入する。
空きスペースが必要なら、他の要素を上にずらす。
pos のデフォルト値は n+1 である。
n はテーブルの長さである (2.5.5 を参照)。
table.insert(t,x) の呼び出しは、テーブル t の最後に x を挿入する。
table.maxn (table)指定したテーブルの最大の正の数値インデックスを返す。 テーブルが正の数値インデックスを持たなければゼロを返す。 (結果を得るために、この関数はテーブル全体を線形に巡回する。)
table.remove (table [, pos])
table から位置 pos の要素を取り除き、
必要なら他の要素を下にずらして空白を埋める。
取り除かれた要素の値が返される。
pos のデフォルト値は n である。
n はテーブルの長さである。
table.remove(t) の呼び出しは、テーブル t の最後の要素を取り除く。
table.sort (table [, comp])table[1] から table[n] までのテーブル要素を、指定された順序で その場で ソートする。
n はテーブルの長さである。
comp を与える場合、それは関数でなくてはならず、テーブルの要素を2つ受け取り、最初の要素が二番目よりも小さいときに真を返さなければならない
(ソート後、not comp(a[i+1],a[i]) が真になる)。
comp が与えられなければ、標準のLuaの演算子 < が代わりに使われる。
ソートのアルゴリズムは安定でない。 つまり、指定された順序において等しいと考えられる要素は、ソートによってその相対位置が変わるかもしれない。
このライブラリは標準C数学ライブラリへのインタフェイスである。
math テーブルの中にすべての関数が提供される。
このライブラリは以下の関数を提供する:
math.abs math.acos math.asin math.atan math.atan2
math.ceil math.cos math.cosh math.deg math.exp
math.floor math.fmod math.frexp math.ldexp math.log
math.log10 math.max math.min math.modf math.pow
math.rad math.random math.randomseed math.sin
math.sinh math.sqrt math.tan math.tanh
加えて、変数 math.pi と、値 HUGE_VAL を持つ変数 math.huge も提供される。
これらのほとんどは、Cライブラリの対応する関数への単なるインタフェイスである。
すべての三角関数はラジアンを使う。
関数 math.deg と math.rad はラジアンと度を変換する。
関数 math.max は引数の中の最大値を返す。
同様に math.min は最小値を求める。
共に1つ、2つ、あるいはもっとたくさんの引数を渡すことができる。
関数 math.modf はCの関数 modf に対応する。
これは2つの値、引数の整数部と小数部を返す。
関数 math.frexp も2つの値、
引数の正規化した小数部と指数部を返す。
関数 math.random と math.randomseed
は ANSI C で提供される単純なランダム生成関数 rand と srand へのインタフェイスである
(統計的な性質は保証されない)。
引数無しで呼ばれると、math.random は [0,1) の範囲の実数の疑似乱数を返す。
数値 n を渡すと、math.random は [1,n] の範囲の整数の疑似乱数を返す。
2つの引数 l と u を渡して呼んだときは、
math.random は [l,u] の範囲の整数の疑似乱数を返す。
math.randomseed 関数は疑似乱数発生器の「シード値」を設定する。
同じシード値からは同じ数列が生成される。
I/Oライブラリは2つの異なったスタイルのファイル操作を提供する。 ひとつめは暗黙のファイルディスクリプタを使うもので、 それらはデフォルト入力ファイルとデフォルト出力ファイルに対して作用し、 すべての入出力操作はデフォルトファイルを通して行われる。 ふたつめのスタイルでは明示的なファイルディスクリプタを用いる。
暗黙のファイルディスクリプタを使う場合は、すべての操作はテーブル io で提供される。
明示的なファイルディスクリプタを使う場合は、
すべての操作は io.open が返すファイルディスクリプタのメソッドとして提供される。
テーブル io は、
Cで使われる意味と同じの3つの定義済みファイルディスクリプタ
io.stdin、io.stdout、io.stderr
も提供する。
例外なく、すべてのI/O関数は失敗時に nil (および二番目の戻り値としてエラーメッセージ) を返し、 成功時は nil 以外の何らかの値を返す。
io.close ([file])
file:close() と等価である。
file が省略されると、デフォルト出力ファイルを閉じる。
io.flush ()
デフォルト出力ファイルに対する file:flush と等価である。
io.input ([file])ファイル名を与えて呼ぶと、その名前のファイルを (テキストモードで) 開き、 そのハンドルをデフォルト入力ファイルに設定する。 ファイルハンドルを与えて呼ぶと、単純にそのファイルハンドルがデフォルト入力ファイルに設定される。 引数無しで呼ぶと、現在のデフォルト入力ファイルを返す。
エラーが起きた場合、この関数はエラーコードを返す変わりにエラーを発する。
io.lines ([filename])指定されたファイル名を読み込みモードで開き、 呼ばれるたびにファイルから1行ずつ返すイテレータ関数を返す。 つまり、
for line in io.lines(filename) do ... end
はファイルのすべての行について繰り返す。
イテレータ関数は、ファイルの終わりを検出すると nil を返し (ループを終えるため)、自動的にファイルを閉じる。
io.lines() (ファイル名を渡さない) は io.input():lines() と等価である。
すなわち、デフォルト入力ファイルの各行について繰り返す。
この場合は、ループが終わってもファイルを閉じない。
io.open (filename [, mode])
この関数は mode で指定されたモードでファイルを開く。
新しいファイルハンドルを返すか、エラーの場合は nil とエラーメッセージを返す。
mode 文字列は以下のいずれかである。
mode 文字列は最後に `b´ も付けることができ、
システムによってはバイナリモードでファイルを開くために必要である。
この文字列は標準Cの関数 fopen で使われるのと同じである。
io.output ([file])
io.input と同じであるが、デフォルト出力ファイルに対する操作である。
io.popen ([prog [, mode]])
分離されたプロセスの中でプログラム prog を開始し、
このプログラムからのデータを読み込む
(デフォルトの、mode が "r" の場合)
ためか、このプログラムにデータを書き込む
(mode が "w" の場合)
ためのファイルハンドルを返す。
この関数はシステム依存であり、すべてのプラットフォームで利用可能なわけではない。
io.read (format1, ...)
io.input():read と等価である。
io.tmpfile ()テンポラリファイルのハンドルを返す。 このファイルは更新モードでオープンされ、プログラムの終了時に自動的に削除される。
io.type (obj)
obj が有効なファイルハンドルかどうかチェックする。
obj がオープンされているファイルハンドルなら、文字列 "file" を返す。
obj がクローズされたファイルハンドルなら、文字列 "closed file" を返す。
obj がファイルハンドルでなければ nil を返す。
io.write (value1, ...)io.output():write と等価である。
file:close ()file を閉じる。
ファイルハンドルがガベージコレクトされたときはそのファイルは自動的に閉じられるが、
それがいつ起きるかは予測不能であることに注意せよ。
file:flush ()file に書き込まれたデータを保存する。
file:lines ()呼ばれるたびにファイルから新しい行を返すイテレータ関数を返す。 つまり、
for line in file:lines() do ... end
はファイルのすべての行に対して繰り返す
(io.lines と異なり、この関数はループの終わりでファイルを閉じない)。
file:read (format1, ...)
何を読むかを指定する書式に従って、ファイル file から読み込む。
各書式について、読み込んだ文字を文字列 (または数値) として返し、
指定された書式でデータを読めなければ nil を返す。
書式を指定せずに呼ばれた場合は、次の行全体を読むデフォルトの書式が使われる (以下を参照)。
利用可能なフォーマットは次の通り。
file:seek ([whence] [, offset])
ファイルの先頭から計ったファイル位置を設定/取得する。
位置は文字列 whence で指定された基準位置に offset を加えた値で示す。
whence は以下のいずれかである。
seek はファイル先頭からのバイト数で最終的なファイル位置を返す。
この関数が失敗すると nil とエラー文字列を返す。
whence のデフォルト値は "cur" で、
offset は0である。
つまり、file:seek() の呼び出しは、何も変化させずに、現在の位置を返す。
file:seek("set") はファイルの先頭に位置を変更する (そして0を返す)。
file:seek("end") はファイルの終わりに位置を変更し、ファイルの長さを返す。
file:setvbuf (mode [, size])出力ファイルのバッファリングモードを設定する。 設定可能なモードは3つある。
flush した場合 (5.7 を参照))
だけ行われる。
sizes でバッファのサイズをバイト単位で指定できる。
デフォルトのサイズは適当である。
file:write (value1, ...)
引数のそれぞれの値を file に書き込む。
引数は文字列か数字でなければならない。
それ以外の値を書き込むには、
write の前に tostring か string.format を使う。
このライブラリはテーブル os を通して提供される。
os.clock ()プログラムが使ったCPU時間の概算値を秒で返す。
os.date ([format [, time]])
与えられた文字列 format に従って書式化した日付と時刻を含む文字列、またはテーブルを返す。
time 引数が存在すれば、それが書式化される時刻となる
(この値の説明は os.time 関数を参照)。
そうでなければ、date は現在時刻を書式化する。
format が `!´ で始まっていたら、
日付は世界時 (Universal Time) で書式化される。
このオプション文字の後、
format が *t であれば、
date は以下のフィールドを持つテーブルを返す。
year (4桁の数値)
month (1--12)
day (1--31)
hour (0--23)
min (0--59)
sec (0--61)
wday (曜日、日曜日が1)
yday (1月1日から数えた日数)
isdst (夏時間を示すフラグ、ブーリアン)
format が *t でなければ、
date は日付を文字列として返す。
Cの関数 strftime と同じルールに従って書式化される。
引数なしで呼ばれた場合、
date はホストシステムと現在のロケールに依存する一般的な日付と時刻の表現を返す。
(つまり、os.date() は os.date("%c") と等価である)。
os.difftime (t2, t1)
時刻 t1 から時刻 t2 までの秒数を返す。
POSIX や Windows、その他のいくつかのシステムでは、
この値は t2-t1 に等しい。
os.execute ([command])
この関数はCの関数 system と等価である。
command はOSのシェルによって実行されるコマンドを渡す。
システムに依存するステータスコードを返す。
command を省略すると、シェルが利用可能ならゼロ以外を返し、そうでなければゼロを返す。
os.exit ([code])
省略可能な code でCの関数 exit を呼んでホストプログラムを終了させる。
code のデフォルト値は成功を表すコードである。
os.getenv (varname)
プロセスの環境変数 varname の値を返す。
変数が未定義なら nil を返す。
os.remove (filename)指定された名前のファイルまたはディレクトリを消す。 消すディレクトリは空でなければならない。 この関数が失敗した場合は nil とエラーメッセージを返す。
os.rename (oldname, newname)
oldname という名前のファイルまたはディレクトリを newname にリネームする。
この関数が失敗した場合は nil とエラーメッセージを返す。
os.setlocale (locale [, category])
プログラムの現在のロケールを設定する。
locale はロケールを表す文字列である。
category は変更したいカテゴリを表す省略可能な文字列で、以下のいずれかである。
"all", "collate", "ctype",
"monetary", "numeric", or "time"。
デフォルトのカテゴリは "all" である。
この関数は新しいロケールの名前を返す。
あるいは要求が受け付けられなければ nil を返す。
os.time ([table])
引数無しで呼ばれたときは現在の時刻を返し、
引数がある場合は、与えられたテーブルで指定された日付と時刻を表す時刻を返す。
このテーブルはフィールド year, month, and day を持たなければならず、
省略可能だがフィールド hour, min, sec, and isdst があっても良い
(これらのフィールドの説明は os.date 関数を参照).
戻り値は数値であり、その意味はシステムに依存する。
POSIX や Windows、およびいくつかのシステムでは、
特定の開始時刻 (「エポック」)からの経過時間を秒で表している。
それ以外のシステムでは、その意味は不明であり、
time の戻り値は
date と difftime の引数としてのみ使うことができる。
os.tmpname ()テンポラリファイルとして使えるファイル名を返す。 このファイルは使う前に明示的にオープンする必要があり、 要らなくなったら明示的に削さなければならない。
このライブラリはLuaプログラムへのデバッグインタフェイスの機能を提供する。 このライブラリを使うときは注意すべきである。 ここで提供される関数はデバッグやそれに似たプロファイリングのようなタスクにのみ使うべきである。 普通のプログラミングツールとしてこれらを使う誘惑に抵抗するように。 これらは非常に遅い。 さらに言えば、いくつかの関数はLuaコードについてのいくつかの仮定 (関数のローカル変数は他の関数からアクセスできないとか、ユーザーデータのメタテーブルはLuaから変更できないとか) を侵害し、安全なコードを危うくする恐れがある。
このライブラリのすべての関数は debug テーブル内に提供される。
debug.debug ()
ユーザーとの対話モードに入り、ユーザーが入力した文字列を実行する。
単純なコマンドや他のデバッグ機能を使って、
ユーザーはグローバル変数やローカル変数を調べたり値を変更したり式を評価したりその他ができる。
ユーザーが cont だけの行を入力すると対話モードを終えて実行を継続する。
debug.debug で実行されるコマンドは、
どの関数のレキシカルスコープにも入っていないので、
ローカル変数へは直接アクセスできないことに注意。
debug.getfenv (o)o の環境を返す。
debug.gethook ()
現在のフック関数、フックマスク、フックカウント (debug.sethook 関数で設定されたもの) を返す。
debug.getinfo (function [, what])
関数に関する情報をテーブルに入れて返す。
関数を直接指定するか数値を指定することができる。
数値は、関数が走っているコールスタックのレベルを意味し、
レベル0は現在の関数 (getinfo 自身)、
レベル1は getinfo を呼び出した関数で、以下同様。
function がアクティブな関数の数よりも大きい数値であれば getinfo は nil を返す。
what はどのフィールドを埋めるかを記述する文字列で、
戻り値のテーブルには lua_getinfo から返されるフィールドがすべて含まれている。
what のデフォルト値では有効なすべての情報を取得する。
もし存在すれば、`f´ オプションは func という名前のフィールドにその関数自身を入れる。
例えば、式 debug.getinfo(1,"n").name は現在の関数の名前を返す (もし適当な名前があれば)。
debug.getinfo(print) は print 関数に関するすべての利用可能な情報を持つテーブルを返す。
debug.getlocal (level, local)
スタックレベル level の関数の、インデックス local のローカル変数の、名前と値を返す。
最初の引数かローカル変数がインデックス1で、以下同様に最後の有効なローカル変数まで続く。
もし指定されたインデックスのローカル変数がなければ nil を返し、
level が範囲外であればエラーを発する
(debug.getinfo を使ってレベルが有効かどうかチェックできる)。
`(´ (開き括弧) で始まる変数名は内部的な変数
(ループ制御変数、一時変数、Cの関数のローカルなど) を表している。
debug.getmetatable (object)
指定した object のメタテーブルを返す。
メタテーブルを持っていなければ nil を返す。
debug.getregistry ()レジストリテーブル (3.5 を参照) を返す。
debug.getupvalue (func, up)
関数 func の、インデックス up の上位値の、名前と値を返す。
指定されたインデックスの上位値が存在しなければ nil を返す。
debug.setfenv (object, table)
指定した object の環境を指定した table にする。
debug.sethook (hook, mask [, count])
指定された関数をフックに設定する。
文字列 mask と数値 count は、いつフックが呼ばれるかを記述する。
文字列maskは以下の文字からなる。
"c" --- フックはLuaが関数を呼ぶたびに呼ばれる。
"r" --- フックはLuaが関数から戻るたびに呼ばれる。
"l" --- フックはLuaがコードの新しい行に入るたびに呼ばれる。
count がゼロでなければ、フックは count 命令が実行されるたびに、その直後に呼ばれる。
引数なしで呼ぶとフックは無効になる。
フックが呼ばれたとき、最初の引数はフックを起動したイベントを示す以下のいずれかの文字列である。
"call", "return" "tail return",
"line", "count"。
lineイベントの場合、フックは二番目の引数に新しい行番号が得られる。
"tail return" を除いて、
フックの内部でレベル2の getinfo を呼べば、実行中の関数に関する情報をもっと得られる
(レベル0は getinfo 関数自身で、レベル1はフック関数である)。
"tail return" はLuaが復帰をシミュレートしているだけであり、
getinfo は正しくないデータを返すだろう。
debug.setlocal (level, local, value)
スタックレベル level の関数の、インデックス local のローカル変数に、値 value を格納する。
指定されたインデックスのローカル変数が存在しなければ nil を返し、
level が範囲外であればエラーを発する
(getinfo を使ってレベルが有効かどうかチェックできる)。
そうでなければ、ローカル変数の名前を返す。
debug.setmetatable (object, table)
指定した object のメタテーブルを指定した table
(nil でも良い) にする。
debug.setupvalue (func, up, value)
関数 func の、インデックス up の上位値に、値 value を格納する。
指定されたインデックスの上位値が存在しなければ nil を返す。
そうでなければ、上位値の名前を返す。
debug.traceback ([message])
コールスタックのトレースバックを出力した文字列を返す。
省略可能な message 文字列は、トレースバックの最初に付け加えられる。
この関数は典型的には、より良いエラーメッセージを生成するために xpcall と一緒に使われる。
LuaはCのホストプログラムに組み込まれる拡張言語としてデザインされたにも関わらず、
スタンドアロンの言語としてもよく使われる。
スタンドアロンの言語としてのLuaインタプリタは、単純に lua と呼ばれ、
標準のディストリビューションと共に提供されている。
スタンドアロンのインタプリタは、
デバッグライブラリを含むすべての標準ライブラリを持っている。
使い方は以下の通り。
lua [options] [script [args]]
オプションは以下の通り。
- ファイルの代わりに stdin から実行する。
-e stat 文字列 stat を実行する。
-l mod mod を "requires" する。
-i script を実行した後、対話モードに入る。
-v バージョン情報を出力する。
-- オプションの処理を止める。
- オプションの処理を止め、stdin をファイルとして実行する。
lua は指定された script に args を文字列として渡して実行する。
引数なしで呼ばれた場合、
stdin (標準入力) が端末であれば lua -v -i、
そうでなければ lua - として振る舞う。
どの引数も適用される前に、
インタプリタは環境変数 LUA_INIT を調べる。
その書式が @filename であれば、そのファイルを実行する。
そうでなければ、その文字列自身を実行する。
-i 以外のすべてのオプションは順番に処理される。
例えば、以下のようなコマンドは
$ lua -e'a=1' -e 'print(a)' script.lua
まず a に1を代入し、それから a の値 (つまり `1´) を表示し、最後にファイル script.lua を実行する
(ここで、$ はシェルプロンプトである。キミのシェルプロンプトは違うかもしれない)。
スクリプトを実行する前に、lua はコマンドライン引数を arg という名前のグローバルなテーブルに格納する。
スクリプト名がインデックス0に格納され、
最初のｈきすうがスクリプト名の後のインデックス1に格納され、以下同様である。
スクリプト名の前のすべての引数 (つまり、インタプリタの名前やオプション) は負のインデックスに割り当てられる。
つまり、次のような場合
$ lua -la b.lua t1 t2
インタプリタはまずファイル a.lua を実行し、
次に以下のようなテーブルを作る。
arg = { [-2] = "lua", [-1] = "-la",
[0] = "b.lua",
[1] = "t1", [2] = "t2" }
そして最後にファイル b.lua を実行する。
スクリプトは引数として arg[1], arg[2], ... が渡されて呼ばれる。
可変引数式 `...´ を使って引数にアクセスすることもできる。
対話モードでは、不完全な文を書いたときは、それが完全な文になるまで待つ。
グローバル変数 _PROMPT が文字列を持っていれば、
その値がプロンプトに使われる。
同様に、グローバル変数 _PROMPT2 が文字列を持っていれば、
その値が第二プロンプトに使われる
(不完全な文である間使われる)。
つまり、プロンプトはコマンドラインから直に変更できる。
$ lua -e"_PROMPT='myprompt> '" -i
(外側のクォート対はシェルのための、内側はLuaのためのもの。)
また、_PROMPT に代入することで、Luaのプログラムからも変更できる。
対話モードに入るには -i が要ることに注意。
そうでなければ、プログラムは _PROMPT に代入した直後に何も出力せず終わるであろう。
UnixシステムでスクリプトインタプリタとしてLuaを使えるようにするために、
スタンドアロンインタプリタはチャンクが # で始まっていれば最初の行をスキップする。
従って、chmod +x と #! 形式を使って、
Luaスクリプトを実行可能なプログラムにすることができる。
#!/usr/local/bin/lua(もちろん、キミのマシンではLuaインタプリタは違う場所にあるかもしれない。 もし
PATH の通るところに lua があれば、
#!/usr/bin/env luaがより移植性の高い解決法である)。
プログラムをLua5.0からLua5.1に移行する際に見つかるかもしれない非互換の一覧を示す。
ほとんどの非互換は適切なオプションを使ってコンパイルすることで避けられる
(ファイル luaconf.h を参照)。
しかしながら、これらの互換用オプションはすべて次のバージョンのLuaでは削除される予定である。
arg から
可変引数式に変更された。
(luaconf.h のオプション LUA_COMPAT_VARARG)
[[...]]) はネストできなくなった。
この場合、新しい構文 ([=[...]=]) を使うことができる。
(luaconf.h のオプション LUA_COMPAT_LSTR)
string.gfind は string.gmatch に名前が変更された。
(オプション LUA_COMPAT_GFIND)
string.gsub の3番目の引数に関数を渡した場合、
この関数が nil または false を返すと、
空文字列でなくマッチした文字列全体に置換するようになった。
table.setn は廃止された。
関数 table.getn は新しい長さ演算子 (#) が対応する。
関数の代わりに演算子を使う。
(オプション LUA_COMPAT_GETN)
loadlib は package.loadlib に名前が変更された。
(オプション LUA_COMPAT_LOADLIB)
math.mod は math.fmod に名前が変更された。
(オプション LUA_COMPAT_MOD)
table.foreach および table.foreachi は廃止された。
ループには代わりに pairs または ipairs を使う。
require に大幅な変更が行われた。
しかしながら、新しい動作は以前とほぼ互換性がある。
ただし require は LUA_PATH の代わりに
package.path からパスを取得する。
collectgarbage の引数が変更された。
関数 gcinfo は廃止された。
代わりに collectgarbage("count") を使う。
luaopen_* 関数は通常のCの関数のようには直接は呼べなくなった。
これらはLuaの関数のようにLuaを通して呼ばなければならない。
lua_open は、ユーザ独自のメモリ確保関数を指定できる lua_newstate に置き換えられた。
標準のメモリ確保関数 (realloc をベースとする) を使ってステートを作るには、
標準ライブラリの luaL_newstate を使う。
luaL_getn および luaL_setn
(補助ライブラリにあった) は廃止された。
luaL_getn の代わりに lua_objlen を使う。
luaL_setn の代わりは存在しない。
luaL_openlib は luaL_register に置き換えられた。
Luaの完全な構文を拡張BNF記法で示す。 これは演算子の優先順位や、 return および break 文がブロックの 最後の 文としてしか使えないといった いくつかの構文的制限は記述していない。
chunk ::= {stat [`;´]} [laststat[`;´]]
block ::= chunk
stat ::= varlist1 `=´ explist1 |
functioncall |
do block end |
while exp do block end |
repeat block until exp |
if exp then block {elseif exp then block} [else block] end |
for Name `=´ exp `,´ exp [`,´ exp] do block end |
for namelist in explist1 do block end |
function funcname funcbody |
local function Name funcbody |
local namelist [`=´ explist1]
laststat ::= return [explist1] | break
funcname ::= Name {`.´ Name} [`:´ Name]
varlist1 ::= var {`,´ var}
var ::= Name | prefixexp `[´ exp `]´ | prefixexp `.´ Name
namelist ::= Name {`,´ Name}
explist1 ::= {exp `,´} exp
exp ::= nil | false | true | Number | String | `...´ |
function | prefixexp | tableconstructor | exp binop exp | unop exp
prefixexp ::= var | functioncall | `(´ exp `)´
functioncall ::= prefixexp args | prefixexp `:´ Name args
args ::= `(´ [explist1] `)´ | tableconstructor | String
function ::= function funcbody
funcbody ::= `(´ [parlist1] `)´ block end
parlist1 ::= namelist [`,´ `...´] | `...´
tableconstructor ::= `{´ [fieldlist] `}´
fieldlist ::= field {fieldsep field} [fieldsep]
field ::= `[´ exp `]´ `=´ exp | Name `=´ exp | exp
fieldsep ::= `,´ | `;´
binop ::= `+´ | `-´ | `*´ | `/´ | `^´ | `%´ | `..´ |
`<´ | `<=´ | `>´ | `>=´ | `==´ | `~=´ |
and | or
unop ::= `-´ | not | `#´