Lua 5.3 リファレンスマニュアル

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

0 – 日本語訳について

この文章は Lua 5.3 Reference Manual を原著者に無断で日本語に訳した非公式のLua 5.3リファレンスマニュアルです。

1 – 序文

Luaは拡張プログラミング言語です。データ記述機能を持ち、汎用的な手続き型プログラミングをサポートするよう設計されています。またオブジェクト指向プログラミング、関数型プログラミング、データ駆動型プログラミングもサポートしています。 Luaはパワフルで軽量な組み込み型のスクリプト言語として、そういったものが必要なあらゆるプログラムで使われることを意図しています。 Luaはライブラリとして実装されており、クリーンなC、つまり標準規格のCとC++の共通のサブセットで書かれています。

拡張言語であるため、Luaには「メイン」プログラムの概念がありません。ホストクライアント (エンベッディングプログラムまたは単にホストと呼ばれることもあります) に組み込まれて動作するだけです。ホストプログラムからLuaのコード片を実行する関数を呼んだり、Luaの変数を読み書きしたり、Luaのコードから呼ばれるCの関数を登録したりできます。 Cの関数を用いることで様々な領域に幅広く対応することができ、同じ構文的な枠組みを共有しながらもカスタマイズしたプログラミング言語を作ることができます。 Luaの配布物には lua という名前のサンプルホストプログラムが含まれています。これはLuaのライブラリを使用した完全なスタンドアロンのLuaインタプリタで、対話的な用途やバッチ処理のために使うことができます。

ライセンスにも述べられているように、Luaはフリーソフトウェアであり、慣例により無保証で提供されます。このマニュアルで述べられている実装はLuaの公式ウェブサイト www.lua.org から入手可能です。

他のあらゆるリファレンスマニュアル同様、この文章も無味乾燥です。 Luaの設計に関する議論はLuaのウェブサイトで入手可能な技術論文を参照してください。 Luaによるプログラミングの詳細な入門にはRobertoの著書 Programming in Lua を参照してください。

2 – 基本コンセプト

この節ではLuaの基本コンセプトについて説明します。

2.1 – 値と型

Luaは動的型付き言語です。つまり変数は型を持たず、値のみが型を持ちます。 Luaには型定義がありません。すべての値はそれ自身が型を保持しています。

Luaの値はすべてファーストクラスの値です。つまりすべての値は変数に格納することができ、他の関数に渡すことができ、戻り値として返すことができます。

Luaには8つの基本型があります。

nil
ブーリアン
数値
文字列
関数
ユーザーデータ
スレッド
テーブル

nil型にはひとつの値 nil だけがあります。その主な性質は他のいかなる値とも異なることであり、通常、役に立つ値がないことを表します。 ブーリアン型にはふたつの値 false と true があります。条件判断においては nil と false は両方とも偽であり、それ以外の値はすべて真です。数値型は整数と実数 (浮動小数点数) の両方を表します。 文字列型は不変のバイト列を表します。 Luaは8ビットクリーンです。つまり文字列は任意の8ビット値 (ゼロ ('\0') を含む) を持つことができます。またLuaはエンコーディングについて関知しません。つまり文字列の内容について何の仮定も設けていません。

数値型には2種類の内部表現 (あるいは2つのサブタイプ) があります。ひとつは整数で、もうひとつは浮動小数点数です。それぞれの表現がいつ使われるかについては明確なルールがありますが、両者は必要に応じて自動的に変換されます (§3.4.3 を参照)。そのためプログラマは整数と浮動小数点数の違いをほとんど無視することもできますし、各数値の表現について完全に制御を握ることもできます。標準のLuaでは64ビットの整数と倍精度 (64ビット) の浮動小数点数を使用しますが、 32ビットの整数や単精度 (32ビット) の浮動小数点数を使用するようにLuaをコンパイルすることもできます。整数と浮動小数点数の両方に32ビットを用いるオプションは、小さなマシンや組み込みシステムでは特に魅力的でしょう。 (ファイル luaconf.h のマクロ LUA_32BITS を参照してください。)

LuaはLuaで書かれた関数もCで書かれた関数も呼ぶ (そして操作する) ことができます (§3.4.10 を参照)。これらはどちらも関数型として表されます。

ユーザーデータ型は任意のCのデータをLuaの変数に格納するために用意されています。ユーザーデータの値は生のメモリブロックを表します。ユーザーデータには2種類あります。 フルユーザーデータはLuaによって管理されるメモリブロックを持つオブジェクトで、ライトユーザーデータは単なるCのポインタ値です。ユーザーデータには等値比較以外の定義済みの演算はありません。 メタテーブルを使うとフルユーザーデータの値に対してプログラマが演算を定義することができます (§2.4 を参照)。ユーザーデータの値はLuaで作成したり変更することはできず、CのAPIを使ってのみ可能です。これによりホストプログラムによって所有されるデータの整合性が保証されます。

スレッド型は独立した実行のスレッドを表し、コルーチンを実装するために使われます (§2.6 を参照)。 LuaのスレッドはOSのスレッドとは無関係です。スレッドがネイティブにサポートされていないシステムも含め、すべてのシステム上でLuaはコルーチンをサポートしています。

テーブル型は連想配列を実装しています。つまり数値だけでなく nil とNaN以外のあらゆるLuaの値をインデックスとして使える配列です。 (NaN、すなわちNot a Numberとは、 0/0 のような未定義または表現不可能な数値演算の結果を表すために使われる特殊な値です。) テーブルは異種混合できます。つまりあらゆる型の値 (nil を除く) を格納することができます。 nil 値を持つキーはテーブルに格納されているとみなされません。逆に言うと、テーブルに格納されていないキーには nil 値が関連付けられています。

テーブルはLuaで唯一のデータを構造化する仕組みです。通常の配列のほか、シーケンス、記号表、集合、レコード、グラフ、ツリーなどを表現するために使うことができます。レコードを表現する場合、Luaではフィールド名をインデックスとして使います。この表現をサポートするため、 a.name が a["name"] のシンタックスシュガーとして用意されています。 Luaにはテーブルを作成する便利な方法がいくつかあります (§3.4.9 を参照)。

すべての正の数値キーの集合が {1..n} であるようなテーブルをシーケンスと言います。ただしnは何らかの負でない整数であり、そのシーケンスの長さと言います (§3.4.7 を参照)。

インデックスと同様、テーブルフィールドの値にも任意の型を格納できます。特に、関数がファーストクラスの値であるため、テーブルフィールドには関数を格納できます。そのためテーブルはメソッドを持つことができます (§3.4.11 を参照)。

テーブルのインデックス検索はLuaの生の等値比較の定義に従います。 i と j が生の等値 (つまりメタメソッドなしで等しい) である場合に限り、式 a[i] と a[j] は同じテーブル要素を指します。特に、小数点以下の端数のない浮動小数点数は、対応する整数と等値です (例えば 1.0 == 1)。曖昧さを避けるため、端数のない浮動小数点数をキーとして使用すると、対応する整数に変換されます。例えば、 a[2.0] = true と書くと、テーブルに挿入される実際のキーは整数の 2 になります。 (それに対して、 2 と "2" は異なる値なので、異なるテーブルエントリを指します。)

テーブル、関数、スレッド、および (フル) ユーザーデータの値はオブジェクトです。変数はこれらの値を実際には格納せず、それらを参照するだけです。代入、引数渡し、関数の戻り値の受け取りは、常にそれらの参照を扱います。これらの操作はいかなる意味でも値のコピーを行いません。

ライブラリ関数 type は指定された値の型を表す文字列を返します (§6.1 を参照)。

2.2 – 環境とグローバル環境

§3.2 および §3.3.3 で述べるように、自由名 var への参照はすべて構文的に _ENV.var に変換されます (自由名とはいかなる宣言にも束縛されていない名前のことです)。またすべてのチャンクは _ENV という名前の外部ローカル変数のスコープ内でコンパイルされます (§3.3.2 を参照)。そのため _ENV 自身はチャンク内で自由名となることはありません。

この外部変数 _ENV の存在と自由名の変換にもかかわらず、 _ENV は完全に正規の名前です。例えばそのような名前の新しい変数や引数を定義しても構いません。自由名への参照はすべて、Luaの通常の可視性ルール (§3.5 を参照) に従い、プログラム内のその地点で可視な _ENV が使われます。

_ENV の値として使われるテーブルは環境と言います。

Luaにはグローバル環境と呼ばれる特別な環境があります。この値はCのレジストリの特別なインデックスに配置されています (§4.5 を参照)。 Luaでは、グローバル変数 _G がこの値で初期化されます。 (_G は内部的に使われることはありません。)

チャンクがロードされるとき、その _ENV 上位値のデフォルト値はグローバル環境になります (load を参照)。そのため、デフォルトではLuaコード内の自由名はグローバル環境のエントリを参照します (それらはグローバル変数と言います)。さらに、すべての標準ライブラリはグローバル環境にロードされ、その関数のいくつかはその環境を操作します。 load (または loadfile) を使うとチャンクを異なる環境にロードすることができます。 (Cではチャンクをロードしてからその最初の上位値の値を変更する必要があります。)

2.3 – エラー処理

Luaは組み込み型の拡張言語なので、Luaのすべての活動はホストプログラム内のCのコードがLuaのライブラリ関数を呼ぶことから始まります。 (スタンドアロンのLuaを使うときは lua アプリケーションがホストプログラムです。) Luaのチャンクのコンパイル中や実行中にエラーが発生すると、制御がホストに戻り、適切な処置を取ることができます (例えばエラーメッセージを表示するなど)。

Luaのコードからは error 関数を呼ぶことでエラーを明示的に発生できます。 Luaでエラーをキャッチする必要がある場合は、 pcall または xpcall を使って保護モードで関数を呼びます。

エラーが発生すると、エラーオブジェクト (エラーメッセージとも言います) がそのエラーに関する情報とともに伝播されます。 Lua自身からエラーが発生するときは、エラーオブジェクトは必ず文字列ですが、プログラムからは任意の値をエラーオブジェクトとしてエラーを発生させることができます。それらのエラーオブジェクトをどう扱うかは、そのLuaのプログラムやホスト次第です。

xpcall や lua_pcall を使うと、エラーが発生した場合に呼ばれるメッセージハンドラを指定できます。この関数は、元のエラーメッセージを受け取って新しいエラーメッセージを返します。メッセージハンドラはエラーでスタックが巻き戻される前に呼ばれるので、エラーに関する情報をより多く集めることができます。例えばスタックを調査してスタックトレースを作成するなどです。このメッセージハンドラは、保護された呼び出しによって保護された状態のまま呼ばれるので、メッセージハンドラ内でエラーが発生すると、そのメッセージハンドラが再度呼ばれます。あまりに長くこれが繰り返された場合は、あきらめて適当なメッセージが返されます。

2.4 – メタテーブルとメタメソッド

Luaの値はすべてメタテーブルを持つことができます。 メタテーブルは通常のLuaのテーブルですが、いくつかの特別な演算に対する、その値の動作を定義します。メタテーブルの特定のフィールドを設定すると、値に対する演算の動作をいくつかの面で変更できます。例えば、数値でない値を加算すると、その値のメタテーブルの "__add" フィールドに格納されている関数が調べられます。もしあれば、加算を実行するためにその関数が呼ばれます。

メタテーブルのキーはイベントの名前から取られています。対応する値はメタメソッドと言います。先程の例では "add" がイベントで、加算を実行する関数がメタメソッドです。

getmetatable 関数を使うと任意の値のメタテーブルを検索することができます。

setmetatable 関数を使うとテーブルのメタテーブルを変更できます。それ以外の型のメタテーブルをLuaのコードから変更することはできません (デバッグライブラリ (§6.10) を使った場合を除く)。そのためにはCのAPIを使う必要があります。

テーブルとフルユーザーデータは個々に独立したメタテーブルを持ちます (複数のテーブルやユーザーデータの間で、同じメタテーブルを共有することもできます)。それ以外の型の値は、型ごとにひとつのメタテーブルを共有します。つまり、すべての数値に対してひとつのメタテーブルがあり、すべての文字列に対してひとつのメタテーブルがあり、以下同様です。デフォルトでは値はメタテーブルを持ちません。しかし文字列ライブラリによって文字列型に対するメタテーブルが設定されます (§6.4 を参照)。

メタテーブルを使うと、算術演算、ビット演算、順序比較、連結、長さ演算、呼び出し、インデックス検索において、オブジェクトがどのように振る舞うかを制御できます。またユーザーデータやテーブルがガベージコレクタに回収されたときに呼ばれる関数も定義できます (§2.5)。

メタテーブルによって制御されるイベントの詳細な一覧を以下に示します。それぞれの演算は対応するイベント名で識別されます。それぞれのイベントに対するキーは、その名前の前に2個のアンダースコア '__' を付けた文字列です。例えば "add" 演算に対するキーは文字列 "__add" です。メタメソッドに対する検索は常に生であることに注意してください。つまりメタメソッドへのアクセスによって他のメタメソッドが呼ばれることはありません。

単項演算子 (反数、長さ、ビット否定) の場合、メタメソッドには第1引数と同じ値の第2引数がダミーで渡されます。この余分な引数は (これらの演算子を二項演算子のように動作させることによって) Luaの内部構造を単純化するためだけのものであり、将来のバージョンでは削除される可能性があります。 (ほとんどの場合、この余分な引数は無意味です。)

"add": + 演算。加算のいずれかの引数が数値 (または数値に変換可能な文字列) でなければ、メタメソッドの呼び出しが試みられます。まず第1引数が調べられます (それが有効な場合であっても)。それが "__add" イベントのメタメソッドを定義していなければ、第2引数が調べられます。メタメソッドが見つかれば、そのメタメソッドにその2つの引数が渡され、その呼び出しの戻り値 (1個の値に調節されます) が演算の結果になります。メタメソッドが見つからなければエラーが発生します。
"sub": - 演算。 "add" 演算と同様の動作をします。
"mul": * 演算。 "add" 演算と同様の動作をします。
"div": / 演算。 "add" 演算と同様の動作をします。
"mod": % 演算。 "add" 演算と同様の動作をします。
"pow": ^ (累乗) 演算。 "add" 演算と同様の動作をします。
"unm": - (単項マイナス) 演算。 "add" 演算と同様の動作をします。
"idiv": // (切り捨て除算) 演算。 "add" 演算と同様の動作をします。
"band": & (ビットごとの論理積) 演算。 "add" 演算と同様の動作をしますが、メタメソッドが試みられるのはいずれかの引数が整数でなく、整数に変換可能な値でもない場合です (§3.4.3 を参照)。
"bor": | (ビットごとの論理和) 演算。 "band" 演算と同様の動作をします。
"bxor": ~ (ビットごとの排他的論理和) 演算。 "band" 演算と同様の動作をします。
"bnot": ~ (ビットごとの単項否定) 演算。 "band" 演算と同様の動作をします。
"shl": << (ビットごとの左シフト) 演算。 "band" 演算と同様の動作をします。
"shr": >> (ビットごとの右シフト) 演算。 "band" 演算と同様の動作をします。
"concat": .. (連結) 演算。 "add" 演算と同様の動作をしますが、メタメソッドが試みられるのはいずれかの引数が文字列でも数値でもない場合です (数値は常に文字列に変換可能です)
"len": # (長さ) 演算。オブジェクトが文字列でなければメタメソッドが試みられます。メタメソッドがあれば、そのメタメソッドにそのオブジェクトが引数として渡され、その呼び出しの戻り値 (常に1個の値に調節されます) が演算の結果になります。メタメソッドがなく、オブジェクトがテーブルであれば、テーブルの長さ演算が使われます (§3.4.7 を参照)。それ以外の場合はエラーが発生します。
"eq": == (等値比較) 演算。 "add" 演算と同様の動作をしますが、メタメソッドが試みられるのは比較する値が両方ともテーブルであるか両方ともフルユーザーデータであり、それらが生で等しくない場合です。呼び出しの結果は常にブーリアンに変換されます。
"lt": < (より小さい) 演算。 "add" と同様の動作をしますが、メタメソッドが試みられるのは比較する値が両方とも数値でなく両方とも文字列でない場合です。呼び出しの結果は常にブーリアンに変換されます。
"le": <= (小さいまたは等しい) 演算。他の演算と異なり、小さいまたは等しい演算は2種類のイベントを用います。まず "lt" 演算と同様に、両方の引数の "__le" メタメソッドが検索されます。それが見つからなければ、 a <= b は not (b < a) と同等であるという仮定によって "__lt" イベントが試みられます。他の比較演算同様、結果は常にブーリアンです。 ("__lt" イベントのこの使われ方は将来のバージョンでは削除される可能性があります。また、本当の "__le" メタメソッドよりも性能的に不利です。)
"index": インデックス付きアクセス table[key]。このイベントは table がテーブルでないか、 table に key が存在しない場合に発生します。メタメソッドは table に対して検索されます。
このイベントのメタメソッドは、メタメソッドという名前にもかかわらず、テーブルであっても構いません。メタメソッドが関数であれば、 table と key を引数としてその関数が呼ばれます。メタメソッドがテーブルであれば、そのテーブルを key で検索した結果が最終結果になります。 (この検索は生ではなく正規のものであり、さらなるメタメソッドが呼ばれる場合があります。)
"newindex": インデックス付き代入 table[key] = value。 indexイベント同様、このイベントは table がテーブルでないか、 table に key が存在しない場合に発生します。メタメソッドは table に対して検索されます。
indexイベント同様、このイベントのメタメソッドは関数とテーブルのどちらでも構いません。メタメソッドが関数であれば、 table、 key、 value を引数としてその関数が呼ばれます。メタメソッドがテーブルであれば、そのテーブルに対して同じ key と value でインデックス付き代入を行います。 (この代入は生ではなく正規のものであり、さらなるメタメソッドが呼ばれる場合があります。)
"newindex" メタメソッドが存在する場合、本来の代入は実行されません (もし必要であれば、メタメソッド内で rawset を呼んで自分で代入を実行してください。)
"call": 呼び出し演算 func(args)。このイベントは関数でない値を呼ぼうとしたときに発生します (つまり func が関数でない場合です)。メタメソッドは func に対して検索されます。もしあれば、そのメタメソッドが呼ばれます。そのとき第1引数に func が渡され、第2引数以降に元の呼び出しの引数 (args) が渡されます。

テーブルをオブジェクトのメタテーブルとして設定する前に必要なすべてのメタメソッドをそのテーブルに追加しておくのは良い習慣です。特に "__gc" メタメソッドはこの順序に従った場合に限り動作します (§2.5.1 を参照)。

2.5 – ガベージコレクション

Luaは自動メモリ管理を行います。つまり新しいオブジェクトのためのメモリ確保や使わなくなったオブジェクトの解放について悩まなくていいということです。 死んだオブジェクト (つまりLuaからアクセス可能でなくなったオブジェクト) を回収するガベージコレクタにより、Luaのメモリは自動的に管理されます。 Luaが使うメモリ (文字列、テーブル、ユーザーデータ、関数、スレッド、内部構造体など) はすべて自動管理の対象です。

Luaにはインクリメンタルマークアンドスイープコレクタが実装されています。ガベージコレクションのサイクルを制御するためにガベージコレクタ停止期間およびガベージコレクタステップ係数という2つの数値が使われます。両方とも単位はパーセントです (つまり値100が内部的な値の1を表します)。

ガベージコレクタ停止期間はコレクタが新しいサイクルを開始するまでに待機する時間の長さを制御します。大きな値ほどコレクタが消極的になります。 100より小さな値を指定すると待機せずに新しいサイクルを開始するという意味になります。 200の値を指定すると使用中の合計メモリが2倍になるまで待機してから新しいサイクルを開始するという意味になります。

ガベージコレクタステップ係数はメモリ確保に対するコレクタの相対速度を制御します。大きな値ほどコレクタは積極的になりますが、各インクリメンタルステップのサイズも増加します。 100より小さな値は指定するべきではありません。コレクタが非常に遅くなり、サイクルを完了できなくなる可能性があります。デフォルトは200です。これはメモリ確保の「2倍」の速度でコレクタを動作させるという意味になります。

ステップ係数を非常に大きな値 (使用する可能性のあるバイト数の最大値より10%以上大きな値) にするとストップザワールドコレクタのように動作します。さらに停止期間を200に設定すると昔のバージョンのLuaのように動作します。つまりメモリ使用量が2倍になるたびに完全なコレクションを実行します。

これらの数値を変更するには、Cで lua_gc を呼ぶか、Luaで collectgarbage を呼びます。また。これらの関数を使うとコレクタを直接制御 (停止、再開など) することができます。

2.5.1 – ガベージコレクションメタメソッド

ガベージコレクタメタメソッドをテーブルに対して設定することができます (§2.4 を参照)。 CのAPIを使えばフルユーザーデータに対しても設定することができます。このメタメソッドはファイナライザとも言います。ファイナライザを使うと、Luaのガベージコレクションを外部リソースの管理と連携させることができます (ファイルやネットワーク接続、データベース接続を閉じたり、独自に確保したメモリを解放するなど)。

オブジェクト (テーブルまたはユーザーデータ) が回収されるときにファイナライズするためには、それをファイナライズ用にマークしなければなりません。オブジェクトにメタテーブルを設定したとき、そのメタテーブルに文字列 "__gc" をキーとするフィールドがあれば、そのオブジェクトはファイナライズ用にマークされます。 __gc フィールドを持たないメタテーブルを設定し、後にそのメタテーブルにそのフィールドを作成した場合、そのオブジェクトはファイナライズ用にマークされません。

マークしたオブジェクトがゴミになったとき、そのオブジェクトは直ちにはガベージコレクタに回収されません。代わりに、あるリストに格納されます。ガベージコレクションの後、そのリストが走査され、リスト内の各オブジェクトに対して __gc メタメソッドが検索されます。それが関数であれば、そのオブジェクトを引数としてその関数が呼ばれます。そのメタメソッドが関数でなければ、単に無視されます。

各ガベージコレクションサイクルの終わりに、そのサイクルで回収されたオブジェクトのファイナライザが、ファイナライズ用にマークされたのと逆の順序で呼ばれます。つまり最後にマークされたオブジェクトのファイナライザが最初に呼ばれるファイナライザになります。ファイナライザの呼び出しは通常のコードの実行中に任意の地点で発生する可能性があります。

回収されたオブジェクトは、まだファイナライザで使われるので、蘇生されます。通常、この蘇生は一時的なものであり、そのオブジェクトのメモリは次のガベージコレクションサイクルで解放されます。しかし、もしファイナライザがそのオブジェクトをどこかグローバルな場所 (例えばグローバル変数) に格納すると、その蘇生は永続的なものになります。そのオブジェクトが再びファイナライズ用にマークされると、オブジェクトが到達不可能になった次のサイクルに再びファイナライザが呼ばれます。いずれの場合でも、オブジェクトのメモリはそのオブジェクトが到達不可能かつファイナライズ用にマークされていない場合にだけ解放されます。

ステートを閉じると (lua_close を参照)、ファイナライズ用にマークされたすべてのオブジェクトのファイナライザがマークされたのと逆の順序で呼ばれます。このフェーズ中にファイナライザ内でオブジェクトをマークしても、そのマークには効果がありません。

2.5.2 – 弱参照テーブル

弱参照テーブルは要素が弱参照であるテーブルです。弱参照はガベージコレクタから無視されます。別の言い方をすると、あるオブジェクトへの参照が弱参照のみであれば、そのオブジェクトはガベージコレクタによって回収されます。

弱参照テーブルは、キー、値、またはその両方が弱参照です。値が弱参照なテーブルでは、値は回収されますが、キーは回収されません。キーと値の両方が弱参照なテーブルでは、キーと値の両方が回収されます。いずれの場合でも、キーと値のどちらかが回収されると、そのペア全体がテーブルから削除されます。テーブルの弱参照の性質は、そのメタテーブルの __mode フィールドで制御されます。 __mode フィールドが文字列であり、その文字列に 'k' の文字が含まれていれば、そのテーブルのキーは弱参照になります。 __mode に 'v' が含まれていれば、そのテーブルの値は弱参照になります。

キーが弱参照で値が強参照なテーブルは短命テーブルと言います。短命テーブルでは、キーが到達可能な場合に限り、値が到達可能とみなされます。つまり、キーへの参照が値を経由するものしかない場合、そのペアは削除されます。

テーブルの弱参照の性質を変更した場合、その効果は次の回収サイクルまで現れない場合があります。例えば弱参照から強参照に変更した場合、変更の効果が現れるまでの間に、そのテーブルからいくつかの項目が回収されてしまう可能性があります。

明示的に生成するタイプのオブジェクトだけが弱参照テーブルから削除されます。数値や軽量C関数のような値はガベージコレクションの対象ではなく、弱参照テーブルから削除されません (対応する値が回収された場合を除きます)。文字列はガベージコレクションの対象ですが、明示的に生成するものではないので弱参照テーブルからは削除されません。

蘇生されたオブジェクト (つまりファイナライズされたオブジェクトと、ファイナライズされたオブジェクトを経由してのみアクセス可能なオブジェクト) は、弱参照テーブルでは特殊な動作をします。値が弱参照の場合はファイナライザが実行される前に削除されますが、キーが弱参照の場合はファイナライザが実行された後、次のコレクションで、それらのオブジェクトが実際に解放された時にのみ削除されます。この動作は、ファイナライザから弱参照テーブルを参照して、そのオブジェクトに関連付けられた値にアクセスできるようにするためのものです。

弱参照テーブルが蘇生された場合、その要素は次のサイクルまで正しくクリアされない場合があります。

2.6 – コルーチン

Luaはコルーチンをサポートしています。 協調的マルチスレッドとも言います。 Luaのコルーチンは独立した実行のスレッドを表します。しかしマルチスレッドシステムのスレッドと異なり、コルーチンは明示的にyield関数を呼んだときだけ実行が中断されます。

coroutine.create を呼ぶとコルーチンを作成できます。その唯一の引数は作成するコルーチンのメイン関数です。 create 関数はコルーチンを作成し、そのハンドル (スレッド型のオブジェクト) を返すだけで、コルーチンの実行は開始しません。

coroutine.resume を呼ぶとコルーチンを実行できます。 coroutine.create から返されたスレッドを最初の引数に指定した coroutine.resume の初回の呼び出しでそのコルーチンの実行が開始され、そのメイン関数が呼ばれます。 coroutine.resume に渡した残りの引数は、その関数に引数として渡されます。コルーチンが実行を開始すると、終了するかyieldするまで実行が続けられます。

コルーチンの実行終了には2通りの場合があります。コルーチンのメイン関数が (明示的に、または最後の命令が終わって暗黙的に) リターンすると、正常終了になります。保護されていないエラーが発生すると、異常終了になります。正常終了の場合、 coroutine.resume は true と、そのコルーチンのメイン関数から返されたすべての値を返します。エラーの場合、 coroutine.resume は false とエラーメッセージを返します。

coroutine.yield を呼ぶとコルーチンをyieldできます。コルーチンをyieldすると、対応する coroutine.resume から直ちに戻ります。ネストした関数呼び出しの中 (つまり、メイン関数でなく、メイン関数から直接または間接的に呼ばれた関数の中) でyieldが発生した場合でも同様です。 yieldした場合、 coroutine.resume は true に加えて、 coroutine.yield に渡された値をすべて返します。次に同じコルーチンがresumeされると、そのyieldした場所、つまり coroutine.yield の呼び出しから戻るところから実行が続行されます。その際 coroutine.resume に渡した残りの引数がすべて返されます。

coroutine.create と同様に coroutine.wrap 関数もコルーチンを作成しますが、コルーチン自体を返すのではなく関数を返します。その関数を呼ぶと、そのコルーチンがresumeされます。この関数に渡した引数はすべて coroutine.resume に追加の引数として渡されます。 coroutine.wrap は、 coroutine.resume が返した値を、最初のひとつ (ブーリアンのエラーコード) を除き、すべて返します。 coroutine.resume と異なり、 coroutine.wrap はエラーをキャッチしません。あらゆるエラーは呼び出し元に伝播されます。

コルーチンがどのように動作するかの例として、以下のコードを考えてみてください。

     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

CのAPIを使ってコルーチンを作成、操作することもできます。 lua_newthread 関数、 lua_resume 関数、 lua_yield 関数を参照してください。

3 – 言語

この節ではLuaの字句、構文、意味論について説明します。別の言い方をすると、この節ではどのようなトークンが有効なのか、それをどのように組み合わせられるのか、そしてその組み合わせが何を意味するのかについて述べます。

言語要素は一般的な拡張BNF記法を使って説明します。つまり {a} はaの0回以上の繰り返しを表し、 [a] はaが省略可能であることを表します。非終端記号は non-terminal のように表し、キーワードは kword のように表し、それ以外の終端記号は ‘=’ のように表します。 Luaの完全な構文は、このマニュアルの最後 §9 に掲載されています。

3.1 – 字句規約

Luaはフリーフォーマットの言語です。字句要素 (トークン) 間の空白 (改行を含む) は無視されます (ただし名前やキーワードを区切る効果はあります)。

Luaにおける名前 (識別子とも言います) は文字、数字、アンダースコアを組み合わせた任意の文字列です。ただし数字で始まってはいけません。識別子は変数、テーブルフィールド、ラベルに名前を付けるために使われます。

以下のキーワードは予約されており、名前として使うことはできません。

     and       break     do        else      elseif    end
     false     for       function  goto      if        in
     local     nil       not       or        repeat    return
     then      true      until     while

Luaは大文字小文字を区別する言語です。 and は予約語ですが、 And と AND は2つの異なる有効な名前です。慣例により、アンダースコアと大文字で始まる名前 (例えば _VERSION) を作るのは避けるようにしてください。

以下の文字列は、それ以外のトークンです。

     +     -     *     /     %     ^     #
     &     ~     |     <<    >>    //
     ==    ~=    <=    >=    <     >     =
     (     )     {     }     [     ]     ::
     ;     :     ,     .     ..    ...

リテラル文字列は対応するシングルクォートまたはダブルクォートで区切られます。また以下に示すCのようなエスケープシーケンスを使うことができます。

'\a': ベル
'\b': バックスペース
'\f': 改頁
'\n': 改行
'\r': 復帰
'\t': 水平タブ
'\v': 垂直タブ
'\\': バックスラッシュ (円記号)
'\"': 引用符 (ダブルクォート)
'\'': アポストロフィ (シングルクォート)

バックスラッシュに本物の改行が続いたものは文字列中の改行になります。エスケープシーケンス '\z' は後続のホワイトスペース (改行を含む) をスキップします。文字列の中身に改行やスペースを追加せずに長いリテラル文字列を複数行に分割してインデントしたいとき特に便利でしょう。

Luaの文字列は '\0' で表されるゼロを含む任意の8ビット値を持つことができます。より一般的に言えば、数値によってリテラル文字列中の任意のバイトを指定することができます。これはエスケープシーケンス \xXX (XX はちょうど2桁の16進数) やエスケープシーケンス \ddd (ddd は最大3桁の10進数) で行うことができます。 (10進数のエスケープシーケンスに数字が続く場合は、ちょうど3桁を使って表さなければならないことに注意してください。)

エスケープシーケンス \u{XXX} (XXX は文字のコードポイントを表す1桁以上の16進数) を使うと、リテラル文字列にそのUnicode文字のUTF-8エンコーディングを入れることができます (周りの括弧は必須です)。

リテラル文字列は長括弧で囲む長い形式を使って書くこともできます。 n段の開き長括弧は、開き角括弧にn個のイコール記号と、もうひとつ開き角括弧が続いたものです。つまり0段の開き長括弧は [[ と書き、1段の開き長括弧は [=[ と書き、以下同様です。 閉じ長括弧も同様です。例えば4段の閉じ長括弧は ]====] と書きます。 長いリテラルは任意の段数の開き長括弧で始まり、同じ段数の最初の閉じ長括弧で終わります。これには同じ段数の閉じ長括弧以外の任意のテキストを含めることができます。この括弧形式のリテラルは複数行に渡って書くことができ、いかなるエスケープシーケンスも解釈せず、異なる段数の長括弧を無視します。あらゆる種類の改行シーケンス (復帰、改行、復帰+改行、改行+復帰) は単純な改行に変換されます。

ここまで述べたルールに当てはまらないリテラル文字列中のあらゆるバイトは、それ自身を表します。ただし、Luaはファイルをテキストモードで開いて読み込むので、制御文字を使うと場合によっては問題があるかもしれません。そのため、テキストでないデータをリテラル文字列として表現する場合は、テキストでない文字の部分は明示的にエスケープシーケンスを使って記述する方が安全です。

便利なように、開き長括弧の直後に改行がある場合、その改行は文字列に含まれません。例えば、ASCII ('a' が97、改行が10、 '1' が49である文字コード) を使っているシステムでは、以下の5つのリテラル文字列は同じ文字列を表します。

     a = 'alo\n123"'
     a = "alo\n123\""
     a = '\97lo\10\04923"'
     a = [[alo
     123"]]
     a = [==[
     alo
     123"]==]

数値定数 (または数値) には省略可能な小数部と省略可能な10進指数を付けることができます。 10進指数は 'e' または 'E' の文字で示されます。 0x または 0X で始まる16進定数も使うことができます。 16進定数にも省略可能な小数部と省略可能な2進指数を付けることができます。 2進指数は 'p' または 'P' の文字で示されます。数値定数に小数点または指数が付いている場合は浮動小数点数を表し、それ以外の場合は整数を表します。有効な整数定数の例を以下に示します。

     3   345   0xff   0xBEBADA

有効な浮動小数点数定数の例を以下に示します。

     3.0     3.1416     314.16e-2     0.31416E1     34e1
     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1

コメントは2つのハイフン (--) で始まります。ただし文字列中は除きます。 -- の直後のテキストが開き長括弧でなければ、そのコメントは短いコメントで、行の終わりまでです。そうでなければ、それは長いコメントで、対応する閉じ長括弧までです。長いコメントはコードを一時的に無効化するためによく使われます。

3.2 – 変数

変数は値を格納する場所です。 Luaには3種類の変数があります。グローバル変数、ローカル変数、テーブルフィールドです。

単発の名前はグローバル変数かローカル変数です (あるいは関数の仮引数かもしれませんが、それはローカル変数の一種です)。

	var ::= Name

§3.1 で述べたように、名前は識別子を表します。

あらゆる変数名は明示的にローカルと宣言されない限りグローバルとみなされます (§3.3.7 を参照)。ローカル変数はレキシカルスコープを持ちます。つまりローカル変数は、そのスコープ内部で定義された関数から自由にアクセスできます (§3.5 を参照)。

変数に最初の代入が行われるまで、その値は nil です。

角括弧はテーブルのインデックス検索に使われます。

	var ::= prefixexp ‘[’ exp ‘]’

メタテーブルを使うと、テーブルフィールドにアクセスしたときの効果を変更できます。インデックス付き変数 t[i] へのアクセスは gettable_event(t,i) の呼び出しと同等です。 (gettable_event 関数の完全な説明は §2.4 を参照してください。この関数はLuaに定義されておらず、呼ぶことはできません。ここでの説明のために使用しているだけです。)

構文 var.Name は var["Name"] の単なるシンタックスシュガーです。

	var ::= prefixexp ‘.’ Name

グローバル変数 x へのアクセスは、 _ENV.x と同等です。チャンクのコンパイル方法に由来する理由により、 _ENV がグローバル変数になることはありません (§2.2 を参照)。

3.3 – 文

LuaにはPascalやCのものと同様の一般的な文が一通り用意されています。具体的には代入、制御構文、関数呼び出し、変数宣言などがあります。

3.3.1 – ブロック

ブロックは順番に実行される文のリストです。

	block ::= {stat}

Luaには空文があるので、文をセミコロンで区切ったり、ブロックをセミコロンで始めたり、連続して2つのセミコロンを書いたりできます。

	stat ::= ‘;’

関数呼び出しと代入は開き括弧で始めることができます。これによってLuaの文法に曖昧さが生じる場合があります。以下のコード片を考えてみてください。

     a = b + c
     (print or io.write)('done')

これは以下の2通りの解釈が可能です。

     a = b + c(print or io.write)('done')

     a = b + c; (print or io.write)('done')

現在のパーサはこのような構文を常に前者のように扱い、開き括弧は関数呼び出しの引数の始まりであると解釈します。このような曖昧さを回避するために、括弧で始まる文には必ずセミコロンを前置するのが良い習慣です。

     ;(print or io.write)('done')

ブロックは単一の文とするために明示的に区切ることができます。

	stat ::= do block end

明示的なブロックは変数宣言のスコープを制御するのに便利です。また他のブロックの途中に return 文を追加するために使われることもあります (§3.3.4 を参照)。

3.3.2 – チャンク

Luaのコンパイル単位はチャンクと言います。構文的には、チャンクは単なるブロックです。

	chunk ::= block

チャンクは可変長引数を持つ無名関数の本体として扱われます (§3.4.11 を参照)。そのため、チャンクはローカル変数を定義したり、引数を受け取ったり、値を返すことができます。さらに、この無名関数は _ENV という名前の外部ローカル変数のスコープ内にあるかのようにコンパイルされます。その結果となる関数は常に (例え使わなくとも) 唯一の上位値として _ENV を持ちます。

チャンクはファイルやホストプログラム内の文字列に格納しておくことができます。チャンクを実行する場合は、まずそれがロードされます。具体的には、そのチャンクのコードが仮想機械の命令列にコンパイルされます。それから、そのコンパイルされたコードが仮想機械のインタプリタを使って実行されます。

チャンクはコンパイル済みのバイナリ形式にしておくこともできます。詳細は luac プログラムと string.dump 関数を参照してください。ソースプログラムとコンパイル済み形式はどちらでも使用できます。ファイルの形式は自動的に判定され、その結果に応じて適切に動作します (load を参照)。

3.3.3 – 代入

Luaには多重代入があります。そのため、代入の構文は左辺に変数リストがあり、右辺に式リストがあります。どちらのリストもコンマで要素を区切ります。

	stat ::= varlist ‘=’ explist
	varlist ::= var {‘,’ var}
	explist ::= exp {‘,’ exp}

式は §3.4 で議論します。

代入の前に、値リストが変数リストの長さに調節されます。必要な数よりも値が多い場合、余分な値は捨てられます。必要な数よりも値が少ない場合、必要な数だけ nil がリストに追加されます。式リストの最後が関数呼び出しの場合、その呼び出しから返された値がすべて、代入の前に値リストに追加されます (その呼び出しを括弧で囲った場合を除きます。 §3.4 を参照)。

代入文では、まずすべての式が評価され、それから代入が行われます。そのため、以下のコードは

     i = 3
     i, a[i] = i+1, 20

a[3] を20に設定し、 a[4] には影響を与えません。 a[i] の i は、4が代入される前に (3に) 評価されるためです。同様に、以下の行は

     x, y = y, x

x と y を入れ替えます。また、以下の行は

     x, y, z = y, z, x

x、 y、 z の値を巡回置換します。

メタテーブルを使うと、グローバル変数とテーブルフィールドへの代入の効果を変更できます。インデックス付き変数への代入 t[i] = val は settable_event(t,i,val) と同等です。 (settable_event 関数の完全な説明は §2.4 を参照してください。この関数はLuaに定義されておらず、呼ぶことはできません。ここでの説明のために使用しているだけです。)

グローバルな名前への代入 x = val は、代入 _ENV.x = val と同等です (§2.2 を参照)。

3.3.4 – 制御構造

制御構造 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

また2種類の for 文もあります (§3.3.5 を参照)。

制御構造の条件式には任意の値を指定することができます。 false と nil は両方とも偽とみなされます。 nil と false 以外のすべての値は真とみなされます (例えば数値の0や空文字列も真になります)。

repeat–until ループでは、内部のブロックの終わりは until キーワードのところではなく、条件式の後です。そのため、ループブロックの内部で宣言したローカル変数を条件式から参照できます。

goto 文はプログラムの制御をラベルへ移動させます。構文的な理由により、Luaではラベルも文とみなされます。

	stat ::= goto Name
	stat ::= label
	label ::= ‘::’ Name ‘::’

ラベルは、それが定義されたブロック全体において可視です。ただし、同じ名前のラベルが定義されているネストしたブロックの内部とネストした関数の内部は除きます。 gotoは、ローカル変数のスコープの中へ入らない限り、可視なラベルのどれにでも飛べます。

ラベルと空文は無の文と言います。何のアクションも行わないという意味です。

break 文は while、repeat、for ループの実行を終了し、そのループの後の次の文まで飛びます。

	stat ::= break

break はそれを囲んでいる最も内側のループを終了します。

return 文は関数やチャンク (チャンクは無名関数です) から値を返すために使います。関数は2つ以上の値を返すことができます。そのため return 文の構文は以下のようになっています。

	stat ::= return [explist] [‘;’]

return 文はブロックの最後の文としてのみ書くことができます。ブロックの途中で return することが本当に必要であれば、明示的な内部ブロックを使うことができます。つまり、 do return end という慣用句を使えば、 return は (内部) ブロックの最後の文となります。

3.3.5 – for文

for 文には数値用と汎用の2種類の形式があります。

数値用の for ループは、制御変数が等差数列を辿る間、コードブロックを繰り返します。構文は以下の通りです。

	stat ::= for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end

nameが最初のexpの値で始まり、2番目のexpを超えるまで、3番目のexpずつ増えながら、blockが繰り返されます。より正確に言うと、以下のような for 文は、

     for v = 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
       var = var - step
       while true do
         var = var + step
         if (step >= 0 and var > limit) or (step < 0 and var < limit) then
           break
         end
         local v = var
         block
       end
     end

注意点は以下の通りです。

3つの制御式はすべて、ループが始まる前に一度だけ評価されます。これらはすべて、数値に評価されなければなりません。
var、 limit、 step は見えない変数です。ここで示した名前は説明のためだけのものです。
3番目の式 (増分) を指定しなかった場合は1が使われます。
break や goto を使うと for ループを抜けることができます。
ループ変数 v はループ本体にローカルです。ループ終了後にその値が必要な場合は、ループを抜ける前に別の変数に代入しておいてください。

汎用の for 文はイテレータと呼ばれる関数を用いて動作します。繰り返しのたびにイテレータ関数を呼んで新しい値を生成します。この新しい値が nil であれば繰り返しは終了します。汎用 for ループの構文は以下の通りです。

	stat ::= for namelist in explist do block end
	namelist ::= Name {‘,’ Name}

以下のような 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)
         if var_1 == nil then break end
         var = var_1
         block
       end
     end

注意点は以下の通りです。

explist は一度だけ評価されます。戻り値はイテレータ関数、状態、最初のイテレータ変数の初期値です。
f、 s、 var は見えない変数です。この名前はここでの説明のためだけのものです。
break を使うと for ループから抜けることができます。
ループ変数 var_i はループにローカルです。 for の終了後に使うことはできません。値が必要であれば、ループをbreakしたり抜けたりする前に、別の変数に代入しておいてください。

3.3.6 – 文としての関数呼び出し

副作用目的で、関数呼び出しを文として実行することができます。

	stat ::= functioncall

この場合、戻り値はすべて捨てられます。関数呼び出しは §3.4.10 で説明します。

3.3.7 – ローカル宣言

ローカル変数はブロック内のどこでも宣言できます。宣言には初期値の代入を付けることもできます。

	stat ::= local namelist [‘=’ explist]

もしあれば、初期値の代入は多重代入と同じ意味論を持ちます (§3.3.3 を参照)。なければ、すべての変数は nil で初期化されます。

チャンクもブロックであるので (§3.3.2 を参照)、ローカル変数は明示的なブロックの外側のチャンク内でも宣言することができます。

ローカル変数の可視性ルールは §3.5 で説明します。

3.4 – 式

基本的な式には以下のものがあります。

	exp ::= prefixexp
	exp ::= nil | false | true
	exp ::= Numeral
	exp ::= LiteralString
	exp ::= functiondef
	exp ::= tableconstructor
	exp ::= ‘...’
	exp ::= exp binop exp
	exp ::= unop exp
	prefixexp ::= var | functioncall | ‘(’ exp ‘)’

数値とリテラル文字列は §3.1 で説明しました。変数は §3.2 で説明しました。関数定義は §3.4.11 で説明します。関数呼び出しは §3.4.10 で説明します。テーブルコンストラクタは §3.4.9 で説明します。 3つのドット ('...') で表される可変長引数式は、可変長関数の中でだけ使えます。これは §3.4.11 で説明します。

二項演算子には算術演算子 (§3.4.1 を参照)、ビット演算子 (§3.4.2 を参照)、関係演算子 (§3.4.4 を参照)、論理演算子 (§3.4.5 を参照)、連結演算子 (§3.4.6 を参照) があります。単項演算子には単項マイナス (§3.4.1 を参照)、単項ビット否定 (§3.4.2 を参照)、単項論理 not (§3.4.5 を参照)、単項長さ演算子 (§3.4.7 を参照) があります。

関数呼び出しと可変長引数式は両方とも、複数の値を返す場合があります。関数呼び出しが文として使われた場合 (§3.3.6 を参照)、その戻り値リストはゼロ個の要素に調節され、つまりすべての戻り値が捨てられます。式を式リストの最後の (または唯一の) 要素として使った場合、調節は行われません (その式を括弧で囲った場合を除きます)。それ以外のすべての文脈では、戻り値リストは1個の要素に調節され、最初のひとつ以外のすべての値が捨てられるか、値がない場合は nil がひとつ追加されます。

いくつか例を挙げます。

     f()                -- 戻り値は0個に調節される
     g(f(), x)          -- f()の戻り値は1個に調節される
     g(x, f())          -- gは、xに加え、f()からの戻り値をすべて受け取りる
     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)) は必ず1個の値となります。 ((f(x,y,z)) の値は f が返した最初の値になります。 f が何も返さなければ nil になります。)

3.4.1 – 算術演算子

算術演算子には以下のものがあります。

+: 加算
-: 減算
*: 乗算
/: 浮動小数点数除算
//: 切り捨て除算
%: 剰余
^: 累乗
-: 単項マイナス

累乗と浮動小数点数除算以外の算術演算は以下のように動作します。引数が両方とも整数であれば、演算は整数で行われ、結果は整数になります。そうでなければ、引数が両方とも数値であるか、数値に変換可能な文字列であれば (§3.4.3 を参照)、それらは浮動小数点数に変換され、演算は浮動小数点数算術の一般的な規則 (通常はIEEE 754標準規格) に従って行われ、結果は浮動小数点数になります。

累乗と浮動小数点数除算 (/) では、引数は常に浮動小数点数に変換され、結果は必ず浮動小数点数になります。累乗にはISO Cの pow 関数が使用されるため、整数以外の指数に対しても動作します。

切り捨て除算 (//) は商を負の無限大に向かって丸めた除算です。つまり除算の切り捨てです。

剰余は商を負の無限大に向かって丸めた除算 (切り捨て除算) の余りとして定義されています。

整数算術がオーバーフローした場合、すべての演算は2の補数算術の一般的なルールに従ってラップアラウンドします。 (別の言い方をすると、数学的な結果を2⁶⁴で割った余りと等しい一意に表現可能な整数を返します。)

3.4.2 – ビット演算子

ビット演算子には以下のものがあります。

&: ビットごとの論理積
|: ビットごとの論理和
~: ビットごとの排他的論理和
>>: 右シフト
<<: 左シフト
~: 単項ビットごとの否定

ビット演算子はすべて、引数を整数に変換し (§3.4.3 を参照)、その整数の全ビットを演算し、結果を整数で返します。

右シフトと左シフトは両方とも、空いたビットをゼロで埋めます。変位に負の値を指定すると逆方向にシフトします。変位の絶対値が整数のビット数以上であれば結果はゼロになります (すべてのビットが追い出されます)。

3.4.3 – 強制型変換

Luaでは型や表現が実行時に自動的に変換される場合があります。ビット演算では浮動小数点数の引数は常に整数に変換されます。累乗と浮動小数点数除算では整数の引数は常に浮動小数点数に変換されます。それ以外の算術演算はすべて、整数と浮動小数点数の混ざった引数に適用した場合、整数の引数は浮動小数点数に変換されます (これを一般的なルールと言います)。 CのAPIでも、必要に応じて整数が浮動小数点数に変換されたり、浮動小数点数が整数に変換されたりします。さらに、文字列連結では文字列だけでなく数値も引数として受け付けます。

また、数値が期待されるところでは、文字列は数値に変換されます。

整数から浮動小数点数への変換では、その整数の値が浮動小数点数で正確に表現可能であれば、それが結果となります。そうでなければ、その整数より大きな最も近い表現可能な値か、その整数より小さな最も近い表現可能な値に変換されます。この種の変換に失敗することはありません。

浮動小数点数から整数への変換では、その浮動小数点数が整数として正確に表現可能かどうか (つまりその浮動小数点数に小数点以下の端数がないかどうかと、その値が整数表現の範囲内かどうか) がチェックされます。表現可能であればその表現が結果となります。そうでなければ変換は失敗します。

文字列から数値への変換は以下のように行われます。まずその文字列が、Luaの数値構文と字句解析のルールに従って、整数か浮動小数点数に変換されます。 (文字列の前後に空白があってもよく、符号が付いていても構いません。) それから結果の数値 (浮動小数点数または整数) が、文脈 (強制的に変換を行う演算子など) によって要求される型 (浮動小数点数または整数) に変換されます。

数値から文字列への変換では、人間が読める適当な形式が使われます。数値を文字列に変換する方法を完全に制御したい場合は、文字列ライブラリの format 関数を使ってください (string.format を参照)。

3.4.4 – 関係演算子

関係演算子には以下のものがあります。

==: 等しい
~=: 等しくない
<: より小さい
>: より大きい
<=: 小さいまたは等しい
>=: 大きいまたは等しい

これらの演算子は必ず false か true を返します。

等値比較 (==) では、まず引数の型が比較されます。型が異なる場合、結果は false です。そうでなければ引数の値が比較されます。文字列は一般的な方法で比較されます。数値は両辺の数学的な値が同じであれば等しくなります。

テーブル、ユーザーデータ、スレッドの場合は参照が比較されます。つまり、2つのオブジェクトが同じオブジェクトである場合に限り、等しいとみなされます。新しいオブジェクト (テーブル、ユーザーデータ、スレッド) を作成したときは必ず、その新しいオブジェクトは既存のいかなるオブジェクトとも異なります。同じ参照を持つクロージャは必ず等しくなります。検出可能な差異 (異なる動作、異なる定義) を持つクロージャは必ず異なります。

"eq" メタメソッドを使うと、テーブルやユーザーデータの比較方法を変更できます (§2.4 を参照)。

等値比較では、文字列を数値に変換したり、数値を文字列に変換したりしません。そのため "0"==0 は false に評価され、 t[0] と t["0"] はテーブルの異なるエントリを指します。

演算子 ~= は等値比較 (==) の否定です。

順序演算子は以下のように動作します。引数が両方とも数値であれば、その数学的な値に従って (サブタイプに関係なく) 比較されます。そうでなく、引数が両方とも文字列であれば、その値が現在のロケールに従って比較されます。そうでなければ、 "lt" または "le" メタメソッド (§2.4 を参照) が試みられます。比較 a > b は b < a に変換され、 a >= b は b <= a に変換されます。

IEEE 754標準規格に従い、NaNは、いかなる値 (それ自身も含む) と比較しても、小さくなく、等しくなく、大きくもないものとみなされます。

3.4.5 – 論理演算子

論理演算子には and、or、not があります。制御構造と同様に (§3.3.4 を参照)、すべての論理演算子は false と nil を両方とも偽とみなし、それ以外のすべてを真とみなします。

否定演算子 not は必ず false か true を返します。論理積演算子 and は最初の引数が false か nil であればその値を返し、そうでなければ2番目の引数を返します。論理和演算子 or は最初の引数が nil でも false でもなければその値を返し、そうでなければ2番目の引数を返します。 and と or は両方とも短絡評価を行います。つまり2番目の引数は必要な場合にだけ評価されます。いくつか例を挙げます。

     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

(このマニュアルでは --> で式の結果を表します。)

3.4.6 – 連結

文字列連結演算子は2つのドット ('..') で表されます。引数が両方とも文字列か数値であれば、 §3.4.3 で述べたルールに従って文字列に変換されます。そうでなければ __concat メタメソッドが呼ばれます (§2.4 を参照)。

3.4.7 – 長さ演算子

長さ演算子は単項前置演算子 # によって表されます。文字列の長さは、そのバイト数です (つまり、それぞれの文字が1バイトだとしたときの、文字列の長さです)。

__len メタメソッドを使うと、文字列以外の任意の値に対する長さ演算子の動作を変更できます (§2.4 を参照)。

__len メソッドが指定されていない場合、テーブル t の長さは、そのテーブルがシーケンスの場合に限り定義されます。つまり、その正の数値キーの集合が {1..n} (nは何らかの負でない整数) に等しい場合です。この場合、nがその長さになります。ちなみに、以下のようなテーブルは

     {10, 20, nil, 40}

シーケンスではないことに気をつけて下さい。これにはキー 4 はありますが、キー 3 はありません。 (そのため、このテーブルの正の数値キーの集合が {1..n} と等しいようなnが存在しません。) しかし、数値でないキーはテーブルがシーケンスかどうかに影響しないことに注意してください。

3.4.8 – 優先順位

演算子の優先順位は以下の表の通りです。優先順位の低い方から高い方に並べてあります。

     or
     and
     <     >     <=    >=    ~=    ==
     |
     ~
     &
     <<    >>
     ..
     +     -
     *     /     //    %
     単項演算子 (not   #     -     ~)
     ^

一般的な数式と同様に、括弧を使って式の優先度を変えることができます。連結演算子 ('..') と累乗演算子 ('^') は右結合です。それ以外の二項演算子はすべて左結合です。

3.4.9 – テーブルコンストラクタ

テーブルコンストラクタはテーブルを作成する式です。コンストラクタが評価されるたびに新しいテーブルが作成されます。コンストラクタを使うと、空のテーブルを作成したり、テーブルを作成していくつかのフィールドを初期化したりできます。コンストラクタの一般的な構文は以下の通りです。

	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            -- t["x"] = 1
       t[3] = f(x)        -- 3番目のexp
       t[30] = 23
       t[4] = 45          -- 4番目のexp
       a = t
     end

コンストラクタ内の代入の順番は決まっていません。 (この順番は同じキーが複数回出現する場合にだけ意味があります。)

リストの最後のフィールドが exp 形式で、その式が関数呼び出しか可変長引数式であれば、その式が返したすべての値がリストに追加されます (§3.4.10 を参照)。

機械生成コードに便利なように、フィールドのリストには省略可能な区切り文字を付けることができます。

3.4.10 – 関数呼び出し

関数呼び出しの構文は以下の通りです。

	functioncall ::= prefixexp args

関数呼び出しでは、まずprefixexpとargsが評価されます。 prefixexpの値が関数型であれば、その関数が指定された引数で呼ばれます。そうでなければ、prefixexpの "call" メタメソッドが呼ばれます。このとき、prefixexpの値が最初の引数として渡され、その後に元の呼び出しの引数が続きます (§2.4 を参照)。

以下の形式を使って「メソッド」を呼ぶことができます。

	functioncall ::= prefixexp ‘:’ Name args

呼び出し v:name(args) は、 v.name(v,args) のシンタックスシュガーです。ただし v の評価が一度だけである点が異なります。

引数の構文は以下の通りです。

	args ::= ‘(’ [explist] ‘)’
	args ::= tableconstructor
	args ::= LiteralString

すべての引数式は呼び出し前に評価されます。 f{fields} 形式の呼び出しは f({fields}) のシンタックスシュガーであり、引数リストは新しいテーブルひとつです。 f'string' (または f"string" または f[[string]]) 形式の呼び出しは f('string') のシンタックスシュガーであり、引数リストはリテラル文字列ひとつです。

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個に調節している

3.4.11 – 関数定義

関数定義の構文は以下の通りです。

	functiondef ::= function funcbody
	funcbody ::= ‘(’ [parlist] ‘)’ block end

以下のシンタックスシュガーを使うと関数定義が簡単になります。

	stat ::= function funcname funcbody
	stat ::= local function Name funcbody
	funcname ::= Name {‘.’ Name} [‘:’ Name]

以下の文は

     function f () body end

以下のように変換されます。

     f = function () body end

以下の文は

     function t.a.b.c.f () body end

以下のように変換されます。

     t.a.b.c.f = function () body end

以下の文は

     local function f () body end

以下のように変換されます。

     local f; f = function () body end

以下のようにではありません。

     local f = function () body end

(この違いは body から f を参照するときにだけ影響があります。)

関数定義は実行可能な式であり、関数型の値を持ちます。チャンクをコンパイルすると、その関数の本体もすべてコンパイルされます。その後、関数定義を実行すると、その関数がインスタンス化 (またはクローズ) されます。この関数インスタンス (または クロージャ) が、その式の最終的な値になります。

仮引数は、実引数の値で初期化されたローカル変数として振舞います。

	parlist ::= 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 文を使って返します (§3.3.4 を参照)。制御が return 文に出会わず関数の最後に達した場合、関数は戻り値なしでリターンします。

関数が返せる値の数にはシステム依存の制限があります。この制限は1000より大きいことが保証されています。

コロン構文を使ってメソッドを定義することができます。メソッドとは暗黙の引数 self を余分に持つ関数です。例えば、以下の文は

     function t.a.b.c:f (params) body end

以下のシンタックスシュガーです。

     t.a.b.c.f = function (self, params) body end

3.5 – 可視性ルール

Luaはレキシカルスコープを採用した言語です。ローカル変数のスコープは、その宣言の次の文から始まり、その宣言を含む最も内側のブロックの、無でない最後の文で終わります。以下の例を考えてみてください。

     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 はそれぞれ別々のものを持っています。

4 – API

この節ではLuaのためのCのAPI、つまりLuaとやりとりするためにホストプログラムから利用可能なCの関数について説明します。すべてのAPI関数、関連する型、定数は、ヘッダファイル lua.h で宣言されています。

ここでは「関数」という言葉を使いますが、代わりにマクロとして提供されているAPIもあります。特に記載がない限り、そういったマクロは引数を正確にただ一度だけ使用するので、隠れた副作用は発生しません (ただし最初の引数であるLuaステートは除きます)。

ほとんどのCのライブラリと同様に、LuaのAPIでも引数の正当性や一貫性はチェックされません。ただし、マクロ LUA_USE_APICHECK を定義してLuaをコンパイルすると、この動作を変更できます。

4.1 – スタック

Luaでは、Cのコードと値をやりとりするために仮想的なスタックを使用します。スタック内の各要素はLuaの値(nil、数値、文字列など)を表します。

LuaからCを呼んだとき、呼ばれた関数には新しいスタックが用意されます。つまり、以前のスタックや未だアクティブなCの関数が使っているスタックから独立しているということです。初期状態では、このスタックにはそのCの関数に渡された引数がすべて格納されています。また、そのCの関数から呼び出し元に返すための戻り値を置く場所でもあります (lua_CFunction を参照)。

便利なように、ほとんどの取得系APIでは厳密なスタックの規則に従っていません。代わりにスタック内の任意の要素をインデックスで参照することができます。正のインデックスはスタック内の絶対位置を表します (1から始まります)。負のインデックスはスタックトップからの相対位置を表します。より具体的に言うと、スタックにn個の要素があるとき、インデックス1は最初の要素 (つまりスタックに最初に積まれた要素) を表し、インデックスnは最後の要素を表します。またインデックス-1は最後の要素 (つまりスタックトップの要素) を表し、インデックス-nは最初の要素を表します。

4.2 – スタックサイズ

LuaのAPIを使用するときは一貫性を保証する責任があります。特にスタックオーバーフローに対処しなければなりません。関数 lua_checkstack を使うと、新しい要素をスタックに積むのに十分な空き領域があることを保証できます。

LuaからCが呼ばれるとき、スタックには少なくとも LUA_MINSTACK 個の空きスロットがあることが保証されています。 LUA_MINSTACK は20に定義されているので、通常はスタック空間について心配する必要はありません。ただし、ループを使ってスタックにどんどん要素を積むような場合は別です。

戻り値の数を固定せずにLuaの関数を呼んだ場合 (lua_call を参照)、その戻り値を格納するのに十分なスタック空間は保証されますが、余分な空間が残っているかは保証されません。そのため、そのような呼び出しの後でスタックに何らかの値を積む場合は lua_checkstack を使った方がよいでしょう。

4.3 – 有効なインデックスと受け入れ可能なインデックス

スタックインデックスを受け取るAPI関数はすべて、有効なインデックスまたは受け入れ可能なインデックスのみを使うことができます。

有効なインデックスとは変更可能なLuaの値を格納する位置を参照するインデックスです。これには1からスタックトップまで (1 ≤ abs(index) ≤ top) のスタックインデックスと、擬似インデックスがあります。擬似インデックスは、スタック内には無いけれどもCのコードからアクセス可能ないくつかの位置を表します。擬似インデックスはレジストリ (§4.5 を参照) やCの関数の上位値 (§4.4 を参照) にアクセスするために使われます。

特定の変更可能な位置ではなく、値のみが必要な関数 (取得系関数など) では、受け入れ可能なインデックスを使うことができます。有効なインデックスはすべて受け入れ可能なインデックスでもあります。また、スタックトップより後ろの確保済み空間を指す任意の正のインデックス (つまりスタックサイズまでのインデックス) も受け入れ可能なインデックスです。 (0は受け入れ可能なインデックスでないことに注意してください。) 特に記載がない限り、API関数では受け入れ可能なインデックスを使うことができます。

受け入れ可能なインデックスには、スタックから値を取得するとき、スタックトップに対する余分なチェックを回避できる効果があります。例えば、第3引数が存在するかどうかを確認せずに、つまり、3が有効なインデックスかどうかを調べずに、第3引数の値を取得しても構いません。

受け入れ可能なインデックスを指定できる関数では、有効でないインデックスは仮想的な LUA_TNONE 型の値を持つものとみなされます。これはnil値と同様の振る舞いをします。

4.4 – Cのクロージャ

Cの関数を作成するとき、それにいくつかの値を紐付けることができます。つまりCのクロージャを作成できます (lua_pushcclosure を参照)。これらの値は上位値と言い、その関数が呼ばれたときはいつでもアクセスできます。

Cの関数が呼ばれたとき、その上位値が特定の擬似インデックスに配置されます。この擬似インデックスは lua_upvalueindex マクロで生成できます。関数に紐付けられた最初の上位値はインデックス lua_upvalueindex(1) にあり、以下同様です。現在の関数の上位値の個数より大きなn (ただし256以下) を指定して lua_upvalueindex(n) を呼ぶと、受け入れ可能な、しかし無効なインデックスが生成されます。

4.5 – レジストリ

レジストリは、任意のLuaの値を格納するために任意のCのコードから使うことができる、定義済みのテーブルです。レジストリテーブルは常に、擬似インデックス LUA_REGISTRYINDEX の位置に配置されています。あらゆるCのライブラリがこのテーブルにデータを格納できます。ただし、衝突を回避するため、他のライブラリで使われないようなキーを注意深く選ぶ必要があります。一般的には、自分のライブラリの名前を含む文字列や、自分のコード内のCのオブジェクトのアドレスを指すライトユーザーデータ、自分のコード内で作成した任意のLuaオブジェクトなどを、キーとして使うのがよいでしょう。変数名と同様に、アンダースコアと大文字で始まる文字列のキーは、Luaが内部で使用するために予約されています。

整数のキーは、リファレンスの仕組み (luaL_ref を参照) やいくつかの定義済みの値によって使われています。そのため、それ以外の目的で整数のキーを使わないでください。

新しいLuaステートを作成したとき、レジストリにはいくつか定義済みの値が格納されています。これら定義済みの値は lua.h で定数として定義されている整数キーでアクセスできます。以下の定数が定義されています。

LUA_RIDX_MAINTHREAD: レジストリのこのインデックスには、そのステートのメインスレッドが格納されています。 (メインスレッドとは、ステートと一緒に作成されたスレッドのことです。)
LUA_RIDX_GLOBALS: レジストリのこのインデックスには、グローバル環境が格納されています。

4.6 – Cでのエラー処理

Luaではエラーを処理するために、内部的にCの longjmp の機能を使っています。 (LuaをC++としてコンパイルした場合は例外が使われます。詳細はソースコード内の LUAI_THROW を検索してください。) Luaが何らかのエラー (メモリ確保エラー、型エラー、構文エラー、実行時エラーなど) に直面すると、エラーを発生させます。つまりロングジャンプを行います。 保護された環境は setjmp を使って復帰点を設定します。あらゆるエラーは最も最近のアクティブな復帰点にジャンプします。

保護された環境の外でエラーが起きるとパニック関数が呼び出されます (lua_atpanic を参照)。その後、 abort が呼ばれ、ホストアプリケーションが終了します。独自のパニック関数を用意し、その関数から戻らないようにすれば (Luaの外に作った独自の復帰点にロングジャンプするなど)、終了を回避できます。

パニック関数はメッセージハンドラ (§2.3 を参照) であるかのように実行されます。例えば、スタックトップにエラーメッセージが置かれます。しかしスタック空間についての保証はありません。スタックに何かを積む場合、まず利用可能な空き領域をチェックしなければなりません (§4.2 を参照)。

APIのほとんどの関数はエラーを発生する可能性があります。例えばメモリ確保エラーなどです。各関数のドキュメントにエラーが発生する可能性があるかどうかについて記載してあります。

lua_error を呼ぶとCの関数からエラーを発生させることができます。

4.7 – Cでのyield処理

Luaではコルーチンをyieldするために、内部的にCの longjmp の機能を使っています。そのため、例えばCの関数 foo がAPI関数を呼び、そのAPI関数が (直接的に、またはyieldする他の関数を呼ぶことによって間接的に) yieldした場合、 longjmp によってCのスタックフレームが消去されるため、もはや foo に戻ることはできなくなります。

この種の問題を避けるため、API呼び出しを横切ってyieldしようとするとエラーが発生します。ただし以下の3つの関数を除きます。

lua_yieldk
lua_callk
lua_pcallk

これらの関数はすべて、yield後に実行を継続するための継続関数を (kという名前の引数で) 受け取ります。

継続を説明するには、いくつか用語の定義が必要です。 Luaから呼ばれたCの関数は元の関数と言うことにします。この元の関数は上記3つのCのAPI関数のいずれかを呼びます。これを呼び出し先の関数と言うことにします。そして現在のスレッドがyieldされます。 (これが発生するのは、呼び出し先の関数が lua_yieldk である場合か、呼び出し先の関数が lua_callk または lua_pcallk であり、それによって呼ばれた関数がyieldした場合です。)

呼び出し先の関数の実行中に現在のスレッドがyieldされたとしましょう。スレッドの再開後、いずれ呼び出し先の関数は実行を終了します。しかし、呼び出し先の関数は元の関数に戻ることができません。元の関数のCのスタックフレームはyieldによって破壊されているためです。代わりに継続関数が呼ばれます。呼び出し先の関数に引数として渡した関数です。名前が示すように、継続関数は元の関数の作業を継続します。

例えば以下の関数を考えてみてください。

     int original_function (lua_State *L) {
       ...     /* コード1 */
       status = lua_pcall(L, n, m, h);  /* Luaを呼ぶ */
       ...     /* コード2 */
     }

lua_pcall で実行されるLuaのコードからyieldできるようにしたいとします。まず、この関数を以下のように書き換えます。

     int k (lua_State *L, int status, lua_KContext ctx) {
       ...  /* コード2 */
     }

     int original_function (lua_State *L) {
       ...     /* コード1 */
       return k(L, lua_pcall(L, n, m, h), ctx);
     }

上のコードにある新しい関数 k が 継続関数 です (lua_KFunction 型です)。 lua_pcall を呼んだ後に元の関数がしていた処理をすべて引き継ぐ関数です。次に、 lua_pcall で実行されるLuaのコードが割り込み (エラーまたはyield) を受けた場合に k を呼んでほしい旨をLuaに伝えなければなりません。 lua_pcall を lua_pcallk に変更し、コードを以下のように書き換えます。

     int original_function (lua_State *L) {
       ...     /* コード1 */
       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
     }

外側にある明示的な継続関数の呼び出しに注意してください。継続関数は必要な場合にだけ呼び出されます。つまり、エラーやyield後に再開した場合です。呼び出し先の関数が一度もyieldせずに正常終了した場合は lua_pcallk (および lua_callk) も正常に戻ります。 (もちろんその場合、継続関数を呼ぶ代わりに、元の関数の中で同等の処理を直接行っても構いません。)

継続関数はLuaステート以外に2つの引数を取ります。呼び出しの最終状態と lua_pcallk に渡したコンテキスト値 (ctx) です。 (Luaはこのコンテキスト値を使用しません。元の関数から継続関数に値を渡すためだけのものです。) lua_pcallk では、状態は lua_pcall の戻り値と同じですが、yield後に実行された場合は LUA_YIELD になります (LUA_OK の代わりです)。 lua_yieldk および lua_callk では、継続関数が呼ばれたとき、状態は常に LUA_YIELD です。 (これら2つの関数はエラーを処理しないため、エラーの場合には継続関数が呼ばれません。) 同様に、 lua_callk を使う場合は、状態として LUA_OK を継続関数に渡すべきです。 (lua_yieldk では継続関数を直接呼ぶことに大した意味はありません。 lua_yieldk は、通常、戻りません。)

継続関数は元の関数と同様に扱われます。継続関数は元の関数と同じLuaのスタックを、呼び出し先の関数が戻ったばかりかのような状態で受け取ります。 (例えば lua_callk の後、関数とその引数がスタックから削除され、その呼び出しからの戻り値で置き換えられます。) また上位値も同じものが配置されます。戻り値は元の関数から返したかのように処理されます。

4.8 – 関数と型

この節では、CのAPIにあるすべての関数と型の一覧をアルファベット順で掲載しています。各関数には [-o, +p, x] のような表示があります。

最初のフィールド o はスタックから削除される要素の数です。 2番目のフィールド p はスタックに積まれる要素の数です。 (どの関数も必ず、引数を削除してから結果を積みます。) x|y 形式のフィールドは、状況に応じて x 個または y 個の要素が積まれる (または削除される) ことを表します。疑問符 '?' は、引数を見ただけでは積まれる (または削除される) 要素の数がわからないことを表します (例えばスタックに何があるかによって変わるなど)。 3番目のフィールド x は、エラーが発生するかどうかを示します。 '-' はエラーが発生しないことを表します。 'e' はエラーが発生する場合があることを表します。 'v' は意図的にエラーを発生させる場合があることを表します。

`lua_absindex`

[-0, +0, –]

int lua_absindex (lua_State *L, int idx);

受け入れ可能なインデックス idx を、それと同等な絶対インデックス (つまりスタックトップに依存しないインデックス) に変換します。

`lua_Alloc`

typedef void * (*lua_Alloc) (void *ud,
                             void *ptr,
                             size_t osize,
                             size_t nsize);

Luaステートで使われるメモリアロケータ関数の型です。アロケータ関数は realloc に似た機能を提供しなければなりませんが、まったく同じではありません。引数は以下の通りです。

ud: lua_newstate に渡した不透明なポインタ。
ptr: 確保/再確保/解放しようとしているブロックのポインタ。
osize: ブロックの元のサイズ、または確保しようとしているものを表すコード。
nsize: ブロックの新しいサイズ。

ptr が NULL でない場合、 osize は ptr が指しているブロックのサイズです。つまりそのブロックを確保/再確保したときに渡されたサイズです。

ptr が NULL の場合、 osize は確保しようとしているオブジェクトの種類を表すコードで、以下の値になります。

LUA_TSTRING
LUA_TTABLE
LUA_TFUNCTION
LUA_TUSERDATA
LUA_TTHREAD

上記以外の値の場合は上記以外のメモリを確保しようとしていることを表します。

アロケータ関数は以下のように動作するものと想定されます。

nsize がゼロの場合、アロケータは free と同様の動作を行い、 NULL を返さなければなりません。

nsize がゼロでない場合、アロケータは realloc と同様の動作をしなければなりません。要求を満たせない場合、アロケータは NULL を返します。 osize >= nsize の場合、アロケータは失敗しないものと想定されます。

アロケータ関数の単純な実装を以下に示します。これは補助ライブラリの luaL_newstate で使われているものです。

     static void *l_alloc (void *ud, void *ptr, size_t osize,
                                                size_t nsize) {
       (void)ud;  (void)osize;  /* 未使用 */
       if (nsize == 0) {
         free(ptr);
         return NULL;
       }
       else
         return realloc(ptr, nsize);
     }

free(NULL) が何の効果もないことと、 realloc(NULL,size) が malloc(size) と同等であることは、標準規格のCで保証されていることに注意してください。このコードではブロックを縮小するときに realloc が失敗しないものと仮定しています。 (この動作は標準規格のCで保証されていませんが、安全な仮定であろうと思われます。)

`lua_arith`

[-(2|1), +1, e]

void lua_arith (lua_State *L, int op);

スタックトップの2つ (否定の場合は1つ) の値に対して算術演算またはビット演算を行い (トップにある方の値が第2引数になります)、それらの値を削除し、演算の結果を積みます。この関数は、対応するLuaの演算子の意味論に従います (つまりメタメソッドが呼ばれる場合があります)。

op の値は以下の定数のいずれかでなければなりません。

LUA_OPADD: 加算 (+)
LUA_OPSUB: 減算 (-)
LUA_OPMUL: 乗算 (*)
LUA_OPDIV: 浮動小数点数除算 (/)
LUA_OPIDIV: 切り捨て除算 (//)
LUA_OPMOD: 剰余 (%)
LUA_OPPOW: 累乗 (^)
LUA_OPUNM: 反数 (単項の -)
LUA_OPBNOT: ビットごとの否定 (~)
LUA_OPBAND: ビットごとの論理積 (&)
LUA_OPBOR: ビットごとの論理和 (|)
LUA_OPBXOR: ビットごとの排他的論理和 (~)
LUA_OPSHL: 左シフト (<<)
LUA_OPSHR: 右シフト (>>)

`lua_atpanic`

[-0, +0, –]

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

新しいパニック関数を設定し、古いものを返します (§4.6 を参照)。

`lua_call`

[-(nargs+1), +nresults, e]

void lua_call (lua_State *L, int nargs, int nresults);

関数を呼びます。

関数を呼ぶには以下のようにします。まず呼びたい関数をスタックに積みます。次にその関数に渡す引数を順番通りに積みます。つまり最初の引数を最初に積みます。最後に lua_call を呼びます。 nargs はスタックに積んだ引数の数です。関数を呼ぶと、その関数と引数がすべてスタックから削除されます。関数から戻ると、その関数の戻り値がスタックに積まれます。戻り値の数は nresults 個に調節されます。ただし nresults が LUA_MULTRET の場合は除きます。この場合は関数の戻り値がすべて積まれます。スタック空間は戻り値が収まるように必要に応じて伸ばされます。関数の戻り値は順番通りにスタックに積まれます (最初の戻り値が最初に積まれます)。そのため呼び出しの後は最後の戻り値がスタックトップになります。

呼んだ関数の中でエラーが発生すると (longjmp を使って) 上に伝播されます。

このLuaコードと同等のことをホストプログラムで行う方法を以下の例に示します。

     a = f("how", t.x, 14)

Cでは以下のようにします。

     lua_getglobal(L, "f");       /* 呼ぶ関数 */
     lua_pushliteral(L, "how");   /* 第1引数 */
     lua_getglobal(L, "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個の戻り値で 'f' を呼ぶ */
     lua_setglobal(L, "a");       /* グローバル変数 'a' を設定 */

上記のコードは釣り合いが取れていることに注意してください。つまり最終的にスタックが元の状態に戻っています。これは良いプログラミング習慣であると考えられます。

`lua_callk`

[-(nargs + 1), +nresults, e]

void lua_callk (lua_State *L,
                int nargs,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

lua_call とまったく同様の動作をしますが、呼んだ関数がyieldできます (§4.7 を参照)。

`lua_CFunction`

typedef int (*lua_CFunction) (lua_State *L);

Cの関数の型です。

適切にLuaとやりとりするためには、引数と戻り値を以下のように受け渡します。 Cの関数はLuaからの引数をスタックに順番通りに受け取ります (最初の引数が最初に積まれます)。そのため関数が開始したとき lua_gettop(L) はその関数が受け取った引数の数を返します。最初の引数 (もしあれば) はインデックス1で、最後の引数はインデックス lua_gettop(L) です。 Luaに戻り値を返すには、その値を順番通りにスタックに積み (最初の戻り値を最初に積み)、その戻り値の数を返します。戻り値より下にある値はすべて適切に破棄されます。 Luaの関数と同様に、Luaから呼ばれるCの関数も複数の戻り値を返すことができます。

例えば、以下の関数は可変個の数値引数を受け取り、その平均と合計を返します。

     static int foo (lua_State *L) {
       int n = lua_gettop(L);           /* 引数の数 */
       lua_Number sum = 0.0;
       int i;
       for (i = 1; i <= n; i++) {
         if (!lua_isnumber(L, i)) {
           lua_pushliteral(L, "incorrect argument");
           lua_error(L);
         }
         sum += lua_tonumber(L, i);
       }
       lua_pushnumber(L, sum/n);        /* 最初の戻り値 */
       lua_pushnumber(L, sum);          /* 2番目の戻り値 */
       return 2;                        /* 戻り値の数 */
     }

`lua_checkstack`

[-0, +0, –]

int lua_checkstack (lua_State *L, int n);

スタックに少なくとも n 個の空きスロットがあることを保証します。要求を満たせなかった場合は false を返します。これは、スタックを固定の最大サイズ (通常、少なくとも数千個) より大きくしようとしたか、空きスロットのためのメモリを確保できなかったかです。スタックが小さくなることはありません。スタックがすでに新しいサイズよりも大きい場合は何もしません。

`lua_close`

[-0, +0, –]

void lua_close (lua_State *L);

指定されたLuaステートのすべてのオブジェクトを破棄し (もしあればガベージコレクションメタメソッドも呼び)、このステートが使用していた動的メモリをすべて解放します。プラットフォームによっては、ホストプログラムの終了時にすべてのリソースが自動的に解放されるため、この関数を呼ぶ必要がないかもしれません。一方、デーモンやウェブサーバのような複数のステートを作成する実行時間の長いプログラムでは、おそらく必要なくなったステートは直ちに閉じる必要があるでしょう。

`lua_compare`

[-0, +0, e]

int lua_compare (lua_State *L, int index1, int index2, int op);

2つのLuaの値を比較します。インデックス index1 の値とインデックス index2 の値を比較し、 op を満たす場合は1を返します。比較は対応するLuaの演算子の意味論に従います (つまりメタメソッドが呼ばれる場合があります)。それ以外の場合は0を返します。いずれかのインデックスが有効でない場合も0を返します。

op は以下のいずれかの値でなければなりません。

LUA_OPEQ: compares for equality (==)
LUA_OPLT: compares for less than (<)
LUA_OPLE: compares for less or equal (<=)
LUA_OPEQ: 等しい (==)
LUA_OPLT: より小さい (<)
LUA_OPLE: より小さいまたは等しい (<=)

`lua_concat`

[-n, +1, e]

void lua_concat (lua_State *L, int n);

スタックトップにある n 個の値を連結し、それらをスタックから削除し、結果をスタックトップに置きます。 n が1の場合、結果はその1個の値です (つまり何もしません)。 n が0の場合、結果は空文字列です。連結はLuaの通常の意味論に従って行われます (§3.4.6 を参照)。

`lua_copy`

[-0, +0, –]

void lua_copy (lua_State *L, int fromidx, int toidx);

インデックス fromidx の位置にある要素を、有効なインデックス toidx の位置にある要素に上書きコピーします。それ以外の位置の要素には影響しません。

`lua_createtable`

[-0, +1, e]

void lua_createtable (lua_State *L, int narr, int nrec);

新しい空のテーブルを作成し、スタックに積みます。引数 narr は、そのテーブルがシーケンスとして持つ予定の要素数のヒントです。引数 nrec は、そのテーブルが持つ予定のそれ以外の要素数のヒントです。これらのヒントは新しいテーブルのメモリを事前確保するために使われる場合があります。テーブルが持つ予定の要素数があらかじめわかってる場合、この事前確保は性能向上の役に立ちます。そうでない場合は lua_newtable を使っても構いません。

`lua_dump`

[-0, +0, e]

int lua_dump (lua_State *L,
                        lua_Writer writer,
                        void *data,
                        int strip);

関数をバイナリチャンクとしてダンプします。スタックトップにあるLuaの関数を受け取り、バイナリチャンクを生成します。このバイナリチャンクをロードすると、ダンプした関数と同等な関数になります。チャンクの部分部分を書き出すためにライター関数 (lua_Writer を参照) が呼ばれ、その際に data が渡されます。

strip が真であれば、空間を節約するため、そのバイナリ表現には関数に関するすべてのデバッグ情報が含まれない場合があります。

戻り値はライターの最後の呼び出しから返されたエラーコードです。エラーがなければ0です。

ダンプ対象のLuaの関数はスタックから削除されません。

`lua_error`

[-1, +0, v]

int lua_error (lua_State *L);

スタックトップの値をエラーオブジェクトとして使用してLuaのエラーを発生させます。ロングジャンプを行うため、この関数が戻ることはありません (luaL_error を参照)。

`lua_gc`

[-0, +0, e]

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: ガベージコレクションのインクリメンタルステップをひとつ実行します。
LUA_GCSETPAUSE: ガベージコレクタ停止期間 (§2.5 参照) を data に変更し、以前の値を返します。
LUA_GCSETSTEPMUL: ガベージコレクタステップ係数 (§2.5 参照) を data に変更し、以前の値を返します。
LUA_GCISRUNNING: ガベージコレクタが動作中 (つまり停止中でない) かどうかを示すブーリアンを返します。

これらのオプションの詳細は collectgarbage を参照してください。

`lua_getallocf`

[-0, +0, –]

lua_Alloc lua_getallocf (lua_State *L, void **ud);

指定されたステートのメモリアロケータ関数を返します。 ud が NULL でなければ、そのメモリアロケータ関数を設定したときに渡された不透明なポインタが *ud に格納されます。

`lua_getfield`

[-0, +1, e]

int lua_getfield (lua_State *L, int index, const char *k);

t[k] の値をスタックに積みます。ただし t は指定されたインデックスにある値です。 Luaの場合と同様に "index" イベントに対するメタメソッドが呼ばれる場合があります (§2.4 参照)。

積んだ値の型を返します。

`lua_getextraspace`

[-0, +0, –]

void *lua_getextraspace (lua_State *L);

指定されたLuaステートに紐付けられた生のメモリ領域へのポインタを返します。アプリケーションはこの領域をどのような目的で使っても構いません。 Luaはこの領域を一切使いません。

新しいスレッドを作成すると、そのスレッドのメモリ領域はメインスレッドが持つメモリ領域のコピーで初期化されます。

デフォルトでは、この領域はvoidポインタ1個分のサイズです。 Luaをコンパイルし直せばこの領域のサイズを変更できます。 (luaconf.h の LUA_EXTRASPACE を参照。)

`lua_getglobal`

[-0, +1, e]

int lua_getglobal (lua_State *L, const char *name);

グローバル変数 name の値をスタックに積みます。その値の型を返します。

`lua_geti`

[-0, +1, e]

int lua_geti (lua_State *L, int index, lua_Integer i);

t[i] の値をスタックに積みます。ただし t は指定されたインデックスにある値です。 Luaの場合と同様に "index" イベントに対するメタメソッドが呼ばれる場合があります (§2.4 を参照)。

積んだ値の型を返します。

`lua_getmetatable`

[-0, +(0|1), –]

int lua_getmetatable (lua_State *L, int index);

指定されたインデックスの値がメタテーブルを持っていれば、そのメタテーブルをスタックに積み、1を返します。そうでなければ0を返し、スタックに何も積みません。

`lua_gettable`

[-1, +1, e]

int lua_gettable (lua_State *L, int index);

t[k] の値をスタックに積みます。ただし t は指定されたインデックスの値で、 k はスタックトップの値です。

キーはスタックから削除され、結果の値がそこに積まれます。 Luaの場合と同様に "index" イベントに対するメタメソッドが呼ばれる場合があります (§2.4 を参照)。

積んだ値の型を返します。

`lua_gettop`

[-0, +0, –]

int lua_gettop (lua_State *L);

スタックトップのインデックスを返します。インデックスは1から始まるので、この結果はスタックの要素数と等しくなります。ちなみに0はスタックが空であることを表します。

`lua_getuservalue`

[-0, +1, –]

int lua_getuservalue (lua_State *L, int index);

指定されたインデックスのユーザーデータに紐付けられたLuaの値をスタックに積みます。

積んだ値の型を返します。

`lua_insert`

[-1, +1, –]

void lua_insert (lua_State *L, int index);

スタックトップの値を指定された有効なインデックスに移動します。このインデックスより上にある要素は空いた隙間にずらされます。擬似インデックスは実際のスタック位置を表していないため、この関数では使用できません。

`lua_Integer`

typedef ... lua_Integer;

Luaの整数の型です。

デフォルトでは long long (一般的には2の補数表現の64ビット整数) ですが、 long や int (一般的には2の補数表現の32ビット整数) に変えることもできます。 (luaconf.h の LUA_INT_TYPE を参照。)

この型の最小値および最大値を表す定数 LUA_MININTEGER および LUA_MAXINTEGER も定義されています。

`lua_isboolean`

[-0, +0, –]

int lua_isboolean (lua_State *L, int index);

指定されたインデックスの値がブーリアンであれば1を返し、そうでなければ0を返します。

`lua_iscfunction`

[-0, +0, –]

int lua_iscfunction (lua_State *L, int index);

指定されたインデックスの値がCの関数であれば1を返し、そうでなければ0を返します。

`lua_isfunction`

[-0, +0, –]

int lua_isfunction (lua_State *L, int index);

指定されたインデックスの値が関数 (CまたはLuaのいずれか) であれば1を返し、そうでなければ0を返します。

`lua_isinteger`

[-0, +0, –]

int lua_isinteger (lua_State *L, int index);

指定されたインデックスの値が整数 (つまり、その値が数値であって、その表現が整数) であれば1を返し、そうでなければ0を返します。

`lua_islightuserdata`

[-0, +0, –]

int lua_islightuserdata (lua_State *L, int index);

指定されたインデックスの値がライトユーザーデータであれば1を返し、そうでなければ0を返します。

`lua_isnil`

[-0, +0, –]

int lua_isnil (lua_State *L, int index);

指定されたインデックスの値が nil であれば1を返し、そうでなければ0を返します。

`lua_isnone`

[-0, +0, –]

int lua_isnone (lua_State *L, int index);

指定されたインデックスが有効でなければ1を返し、そうでなければ0を返します。

`lua_isnoneornil`

[-0, +0, –]

int lua_isnoneornil (lua_State *L, int index);

指定されたインデックスが有効でないか、その値が nil であれば1を返し、そうでなければ0を返します。

`lua_isnumber`

[-0, +0, –]

int lua_isnumber (lua_State *L, int index);

指定されたインデックスの値が数値であるか、数値に変換可能な文字列であれば1を返し、そうでなければ0を返します。

`lua_isstring`

[-0, +0, –]

int lua_isstring (lua_State *L, int index);

指定されたインデックスの値が文字列または数値 (数値は常に文字列に変換可能) であれば1を返し、そうでなければ0を返します。

`lua_istable`

[-0, +0, –]

int lua_istable (lua_State *L, int index);

指定されたインデックスの値がテーブルであれば1を返し、そうでなければ0を返します。

`lua_isthread`

[-0, +0, –]

int lua_isthread (lua_State *L, int index);

指定されたインデックスの値がスレッドであれば1を返し、そうでなければ0を返します。

`lua_isuserdata`

[-0, +0, –]

int lua_isuserdata (lua_State *L, int index);

指定されたインデックスの値がユーザーデータ (フルはまたはライトのいずれか) であれば1を返し、そうでなければ0を返します。

`lua_isyieldable`

[-0, +0, –]

int lua_isyieldable (lua_State *L);

指定されたコルーチンがyield可能であれば1を返し、そうでなければ0を返します。

`lua_KContext`

typedef ... lua_KContext;

継続関数のコンテキストの型です。数値型でなければなりません。 intptr_t が使用可能な場合は intptr_t として定義されるため、ポインタを格納することもできます。そうでない場合は ptrdiff_t として定義されます。

`lua_KFunction`

typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);

継続関数の型です (§4.7 を参照)。

`lua_len`

[-0, +1, e]

void lua_len (lua_State *L, int index);

指定されたインデックスの値の長さを返します。 Luaの '#' 演算子 (§3.4.7 を参照) と同等であり、 "length" イベントに対するメタメソッドが呼ばれる場合があります (§2.4 を参照)。結果はスタックに積まれます。

`lua_load`

[-0, +1, –]

int lua_load (lua_State *L,
              lua_Reader reader,
              void *data,
              const char *chunkname,
              const char *mode);

Luaのチャンクを実行せずにロードします。エラーがなければ、コンパイルしたチャンクがLuaの関数としてスタックトップに積まれます。

戻り値は以下のいずれかです。

LUA_OK: エラーなし。
LUA_ERRSYNTAX: コンパイル中の構文エラー。
LUA_ERRMEM: メモリ確保エラー。
LUA_ERRGCMM: __gc メタメソッド実行中のエラー。 (このエラーはロード中のチャンクとは関係ありません。ガベージコレクタによって発生します。)

チャンクを読み込むためにユーザー提供の reader 関数が使われます (lua_Reader を参照)。 data 引数はこのリーダー関数に渡される不透明な値です。

chunkname 引数はチャンクの名前で、エラーメッセージやデバッグ情報に使われます (§4.9 で参照)。

チャンクがテキストであるかバイナリであるかは自動的に判定され、その結果に応じて適切にロードされます (luac プログラムを参照)。文字列 mode は load のものと同様です。ただし NULL の場合は文字列 "bt" と同等です。

lua_load の内部でスタックを使用するので、リーダー関数から戻るときは必ずスタックを元の状態に戻さなければなりません。

結果となる関数に上位値がある場合、その最初の上位値はレジストリのインデックス LUA_RIDX_GLOBALS に格納されているグローバル環境の値に設定されます (§4.5 を参照)。メインチャンクをロードするとき、この上位値は _ENV 変数になります (§2.2 を参照)。それ以外の上位値は nil で初期化されます。

`lua_newstate`

[-0, +0, –]

lua_State *lua_newstate (lua_Alloc f, void *ud);

新しい独立したステートで実行される新しいスレッドを作成します。 (メモリ不足により) スレッドかステートを作成できない場合は NULL を返します。引数 f はアロケータ関数です。このステートのためのメモリ確保はすべてこの関数を通して行われます。第2引数 ud はアロケータ関数を呼ぶときに渡される不透明なポインタです。

`lua_newtable`

[-0, +1, e]

void lua_newtable (lua_State *L);

新しい空のテーブルを作成し、スタックに積みます。 lua_createtable(L, 0, 0) と同等です。

`lua_newthread`

[-0, +1, e]

lua_State *lua_newthread (lua_State *L);

新しいスレッドを作成し、それをスタックに積み、その新しいスレッドを表す lua_State へのポインタを返します。この関数から返される新しいスレッドはグローバル環境を元のスレッドと共有しますが、実行スタックは別々です。

スレッドを閉じたり破棄したりする明示的な関数はありません。スレッドは他のLuaオブジェクト同様にガベージコレクションの対象です。

`lua_newuserdata`

[-0, +1, e]

void *lua_newuserdata (lua_State *L, size_t size);

指定されたサイズの新しいメモリブロックを確保し、そのブロックのアドレスを持つ新しいフルユーザーデータをスタックに積み、そのアドレスを返します。このメモリはホストプログラム側で自由に使用できます。

`lua_next`

[-1, +(2|0), e]

int lua_next (lua_State *L, int index);

スタックからキーを削除し、指定されたインデックスのテーブルからキーと値のペア (指定されたキーの「次の」ペア) を積みます。テーブルにそれ以上要素がなければ (何も積まずに) 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 を呼んだときに問題が生じます。

巡回中にテーブルを変更する場合の注意点について next 関数を参照してください。

`lua_Number`

typedef ... lua_Number;

Luaの浮動小数点数の型です。

デフォルトでは double ですが、 float や long double に変更することもできます。 (luaconf.h の LUA_FLOAT_TYPE を参照。)

`lua_numbertointeger`

int lua_numbertointeger (lua_Number n, lua_Integer *p);

Luaの浮動小数点数をLuaの整数に変換します。 n は小数点以下の端数がないものと仮定されます。その値がLuaの整数の範囲内であれば整数に変換され、 *p に代入されます。このマクロは変換が成功したかどうかを表すブーリアン値を返します。 (ちなみに、この範囲チェックをこのマクロを使わずに正しく行うのは、丸めの問題があるため少々トリッキーなものになります。)

このマクロは引数を2回以上評価する場合があります。

`lua_pcall`

[-(nargs + 1), +(nresults|1), –]

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

保護モードで関数を呼びます。

nargs と nresults は両方とも lua_call の場合と同じ意味です。呼び出しの間にエラーが発生しなければ、 lua_pcall は lua_call とまったく同様の動作をします。しかし何らかのエラーが発生した場合、それは lua_pcall によってキャッチされ、ひとつの値 (エラーメッセージ) をスタックに積み、エラーコードを返します。 lua_call と同様に、関数と引数は常にスタックから削除されます。

msgh が0であれば、スタック上に返されるエラーメッセージは元のエラーメッセージそのままです。そうでなければ、 msgh はメッセージハンドラのスタックインデックスです。 (擬似インデックスは使えません。) 実行時エラーが発生すると、エラーメッセージを引数としてその関数が呼ばれ、その戻り値が lua_pcall からスタック上に返されるメッセージになります。

一般的に、メッセージハンドラはエラーメッセージにさらなるデバッグ情報を付加するために使われます。例えばスタックトレースなどです。そういった情報は lua_pcall から戻った後では収集することができません。スタックが巻き戻されるためです。

lua_pcall 関数は以下の定数のいずれかを返します (lua.h で定義されています)。

LUA_OK (0): 成功。
LUA_ERRRUN: 実行時エラー。
LUA_ERRMEM: メモリ確保エラー。このようなエラーの場合、メッセージハンドラは呼ばれません。
LUA_ERRERR: メッセージハンドラ実行中のエラー。
LUA_ERRGCMM: __gc メタメソッド実行中のエラー。 (このエラーは一般的に、呼んだ関数とは関係ありません。)

`lua_pcallk`

[-(nargs + 1), +(nresults|1), –]

int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);

lua_pcall とまったく同様の動作をしますが、呼んだ関数の中でyieldできます (§4.7 を参照)。

`lua_pop`

[-n, +0, –]

void lua_pop (lua_State *L, int n);

スタックから n 個の要素を削除します。

`lua_pushboolean`

[-0, +1, –]

void lua_pushboolean (lua_State *L, int b);

b の値を持つブーリアン値をスタックに積みます。

`lua_pushcclosure`

[-n, +1, e]

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

新しいCのクロージャをスタックに積みます。

Cの関数を作成するとき、それにいくつかの値を紐付けることができます。つまりCのクロージャを作成できます (§4.4 を参照)。その関数が呼ばれたときはいつでもその値にアクセスすることができます。 Cの関数に値を紐付けるには、まずその値をスタックに積みます (値が複数ある場合は、最初の値を最初に積みます)。次に lua_pushcclosure を呼び、Cの関数を作成してスタックに積みます。このとき関数に紐付けたい値の数を引数 n に指定します。これらの値もスタックから削除されます。

n の最大値は255です。

n がゼロの場合は軽量なCの関数が作成されます。これはそのCの関数への単なるポインタです。この場合、メモリエラーが発生することはありません。

`lua_pushcfunction`

[-0, +1, –]

void lua_pushcfunction (lua_State *L, lua_CFunction f);

Cの関数をスタックに積みます。この関数は、Cの関数へのポインタを受け取り、関数型のLuaの値をスタックに積みます。この値が呼ばれると、対応するCの関数が呼ばれます。

Luaから呼ばれる関数はすべて、引数と戻り値の正しい受け渡し方法に従わなければなりません (lua_CFunction を参照)。

`lua_pushfstring`

[-0, +1, e]

const char *lua_pushfstring (lua_State *L, const char *fmt, ...);

書式化した文字列をスタックに積み、その文字列へのポインタを返します。 ISO Cのsprintf関数に似ていますが、重要な違いがいくつかあります。

結果を格納する空間を自分で確保する必要はありません。結果はLuaの文字列であり、Luaがメモリ確保の面倒を見ます (そしてガベージコレクションによって自動的に解放されます)。
変換指定子は非常に制限されています。フラグ、幅、精度はありません。以下変換指定子のみが使用可能です。
- '%%': 文字 '%' を挿入します。
- '%s': ゼロ終端文字列を挿入します。サイズ制限はありません。
- '%f': lua_Number を挿入します。
- '%I': lua_Integer を挿入します。
- '%p': ポインタを16進数として挿入します。
- '%d': int を挿入します。
- '%c': int を1バイト文字として挿入します。
- '%U': long int をUTF-8バイトシーケンスとして挿入します。

`lua_pushglobaltable`

[-0, +1, –]

void lua_pushglobaltable (lua_State *L);

グローバル環境をスタックに積みます。

`lua_pushinteger`

[-0, +1, –]

void lua_pushinteger (lua_State *L, lua_Integer n);

n の値を持つ整数をスタックに積みます。

`lua_pushlightuserdata`

[-0, +1, –]

void lua_pushlightuserdata (lua_State *L, void *p);

ライトユーザーデータをスタックに積みます。

ユーザーデータはCの値をLuaで表現したものです。 ライトユーザーデータはポインタ、つまり void* を表します。これは値です (数値と同様です)。つまり作成する必要はなく、個別のメタテーブルを持たず、 (作成されないため) 回収されません。ライトユーザーデータは同じCのアドレスを持つ「どの」ライトユーザーデータとも等しくなります。

`lua_pushliteral`

[-0, +1, e]

const char *lua_pushliteral (lua_State *L, const char *s);

このマクロは lua_pushstring と同等ですが、 s がリテラル文字列である場合にだけ使うべきです。

`lua_pushlstring`

[-0, +1, e]

const char *lua_pushlstring (lua_State *L, const char *s, size_t len);

s が指しているサイズ len の文字列をスタックに積みます。指定された文字列は内部コピーが作成される (または再利用される) ため、 s が指しているメモリはこの関数から戻った直後に自由に解放したり再利用したりできます。文字列はゼロを含む任意のバイナリを持つことができます。

その文字列の内部コピーを指すポインタを返します。

`lua_pushnil`

[-0, +1, –]

void lua_pushnil (lua_State *L);

nil値をスタックに積みます。

`lua_pushnumber`

[-0, +1, –]

void lua_pushnumber (lua_State *L, lua_Number n);

n の値を持つ浮動小数点数をスタックに積みます。

`lua_pushstring`

[-0, +1, e]

const char *lua_pushstring (lua_State *L, const char *s);

s が指しているゼロ終端文字列をスタックに積みます。指定された文字列は内部コピーが作成される (または再利用される) ため、 s が指しているメモリはこの関数から戻った直後に自由に解放したり再利用したりできます。

その文字列の内部コピーを指すポインタを返します。

s が NULL の場合は nil を積み、 NULL を返します。

`lua_pushthread`

[-0, +1, –]

int lua_pushthread (lua_State *L);

L が表しているスレッドをスタックに積みます。このステートのスレッドがメインスレッドであれば1を返します。

`lua_pushvalue`

[-0, +1, –]

void lua_pushvalue (lua_State *L, int index);

指定されたインデックスの要素のコピーをスタックに積みます。

`lua_pushvfstring`

[-0, +1, e]

const char *lua_pushvfstring (lua_State *L,
                              const char *fmt,
                              va_list argp);

lua_pushfstring と同等ですが、可変長引数の代わりに va_list を取ります。

`lua_rawequal`

[-0, +0, –]

int lua_rawequal (lua_State *L, int index1, int index2);

インデックス index1 と index2 の2つの値が生で (つまりメタメソッドを呼ばずに) 等しければ1を返します。そうでなければ0を返します。いずれかのインデックスが有効でない場合も0を返します。

`lua_rawget`

[-1, +1, –]

int lua_rawget (lua_State *L, int index);

lua_gettable に似ていますが、生のアクセス (つまりメタメソッドなし) を行います。

`lua_rawgeti`

[-0, +1, –]

int lua_rawgeti (lua_State *L, int index, lua_Integer n);

t[n] の値をスタックに積みます。ただし t は指定されたインデックスのテーブルです。アクセスは生です。つまりメタメソッドは呼ばれません。

積んだ値の型を返します。

`lua_rawgetp`

[-0, +1, –]

int lua_rawgetp (lua_State *L, int index, const void *p);

t[k] の値をスタックに積みます。ただし t は指定されたインデックスのテーブルで、 k はポインタ p をライトユーザーデータとして表現したものです。アクセスは生です。つまりメタメソッドは呼ばれません。

積んだ値の型を返します。

`lua_rawlen`

[-0, +0, –]

size_t lua_rawlen (lua_State *L, int index);

指定されたインデックスの値の生の「長さ」を返します。文字列の場合はその文字列の長さです。テーブルの場合は長さ演算子 ('#') の結果です。ただしメタメソッドは呼ばれません。ユーザーデータの場合は、そのユーザーデータに割り当てられたメモリブロックのサイズです。それ以外の場合は0です。

`lua_rawset`

[-2, +0, e]

void lua_rawset (lua_State *L, int index);

lua_settable と似ていますが、生の代入 (つまりメタメソッドなし) を行います。

`lua_rawseti`

[-1, +0, e]

void lua_rawseti (lua_State *L, int index, lua_Integer i);

t[i] = v と同等のことを行います。ただし t は指定されたインデックスのテーブルで、 v はスタックトップの値です。

値はスタックから削除されます。代入は生です。つまりメタメソッドは呼ばれません。

`lua_rawsetp`

[-1, +0, e]

void lua_rawsetp (lua_State *L, int index, const void *p);

t[p] = v と同等のことを行います。ただし t は指定されたインデックスのテーブル、 p はライトユーザーデータとして符号化されたポインタ、 v はスタックトップの値です。

値はスタックから削除されます。代入は生です。つまりメタメソッドは呼ばれません。

`lua_Reader`

typedef const char * (*lua_Reader) (lua_State *L,
                                    void *data,
                                    size_t *size);

lua_load で使われるリーダー関数です。チャンクの新しい断片が必要になるたびに lua_load から呼ばれ、 data 引数が渡されます。リーダー関数は、チャンクの新しい断片を入れたメモリブロックへのポインタを返し、 size にそのブロックのサイズを設定しなければなりません。このブロックはリーダー関数がもう一度呼ばれるまで存在していなければなりません。チャンクの終わりを知らせるには NULL を返すか、 size をゼロに設定しなければなりません。リーダー関数は1以上の任意のサイズの断片を返すことができます。

`lua_register`

[-0, +0, e]

void lua_register (lua_State *L, const char *name, lua_CFunction f);

グローバル変数 name の新しい値として、Cの関数 f を設定します。これは以下のようなマクロとして定義されています。

     #define lua_register(L,n,f) \
            (lua_pushcfunction(L, f), lua_setglobal(L, n))

`lua_remove`

[-1, +0, –]

void lua_remove (lua_State *L, int index);

指定された有効なインデックスの要素を削除し、それより上の要素を隙間を埋めるため下にずらします。この関数では擬似インデックスを使うことはできません。擬似インデックスは実際のスタック位置ではないためです。

`lua_replace`

[-1, +0, –]

void lua_replace (lua_State *L, int index);

スタックトップの要素を指定された有効なインデックスに移動し、そのスタックトップの要素を削除します (それ以外の要素は移動しません。つまり指定されたインデックスの値を置換します)。

`lua_resume`

[-?, +?, –]

int lua_resume (lua_State *L, lua_State *from, int nargs);

指定されたスレッド L のコルーチンを開始および再開させます。

コルーチンを開始するには、メイン関数と引数をスレッドのスタックに積み、 lua_resume を呼びます。 nargs は引数の数です。コルーチンの実行が中断するか終了すると呼び出しから戻ります。戻ったとき、スタックには lua_yield に渡されたすべての値、または本体の関数から返されたすべての値が置かれています。コルーチンがyieldした場合は LUA_YIELD を返します。エラーを発生せずにコルーチンが実行終了した場合は LUA_OK を返します。エラーが発生した場合はエラーコードを返します (lua_pcall を参照)。

エラーが発生した場合、スタックは巻き戻されません。そのためデバッグAPIを使うことができます。スタックトップにエラーメッセージがあります。

コルーチンを再開するには、最後の lua_yield からすべての戻り値を削除し、 yield からの戻り値として渡す値だけをスタックに積み、それから lua_resume を呼びます。

引数 from は L を再開するコルーチンを表します。そのようなコルーチンがない場合は NULL を指定できます。

`lua_rotate`

[-0, +0, –]

void lua_rotate (lua_State *L, int idx, int n);

有効なインデックス idx とスタックトップの間のスタック要素を回転させます。 n が正の場合はトップ方向に n 個分、 n が負の場合はボトム方向に -n 個分回転します。 n の絶対値を回転させる部分のサイズより大きくしてはなりません。この関数では擬似インデックスを使うことはできません。擬似インデックスは実際のスタック位置ではないためです。

`lua_setallocf`

[-0, +0, –]

void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);

指定されたステートのアロケータ関数を f に、そのユーザーデータを ud に変更します。

`lua_setfield`

[-1, +0, e]

void lua_setfield (lua_State *L, int index, const char *k);

t[k] = v と同等のことを行います。ただし t は指定されたインデックスの値で、 v はスタックトップの値です。

値はスタックから削除されます。 Luaの場合と同様に "newindex" イベントのメタメソッドが呼ばれる場合があります (§2.4 を参照)。

`lua_setglobal`

[-1, +0, e]

void lua_setglobal (lua_State *L, const char *name);

スタックから値を削除し、それをグローバル変数 name の新しい値に設定します。

`lua_seti`

[-1, +0, e]

void lua_seti (lua_State *L, int index, lua_Integer n);

t[n] = v と同等のことをします。ただし t は指定されたインデックスの値で、 v はスタックトップの値です。

値はスタックから削除されます。 Lua の場合と同様に "newindex" イベントのメタメソッドが呼ばれる場合があります (§2.4 を参照)。

`lua_setmetatable`

[-1, +0, –]

void lua_setmetatable (lua_State *L, int index);

スタックからテーブルを削除し、そのテーブルを指定されたインデックスの値の新しいメタテーブルとして設定します。

`lua_settable`

[-2, +0, e]

void lua_settable (lua_State *L, int index);

t[k] = v と同等のことをします。ただし t は指定されたインデックスの値、 v はスタックトップの値で、 k はスタックトップのひとつ下の値です。

キーと値は両方ともスタックから削除されます。 Luaの場合と同様に "newindex" イベントのメタメソッドが呼ばれる場合があります (§2.4 を参照)。

`lua_settop`

[-?, +?, –]

void lua_settop (lua_State *L, int index);

任意のインデックスまたは0を受け取り、スタックトップをそのインデックスにします。新しいスタックトップが古いスタックトップより大きい場合、新しい要素は nil で埋められます。 index が0の場合、スタックの要素はすべて削除されます。

`lua_setuservalue`

[-1, +0, –]

void lua_setuservalue (lua_State *L, int index);

値をスタックから削除し、それを指定されたインデックスのユーザーデータに関連付けます。

`lua_State`

typedef struct lua_State lua_State;

スレッドおよび (そのスレッドを通して) 間接的にLuaインタプリタのステート全体を指す不透明な構造体です。 Luaのライブラリは完全に再入可能です。つまりグローバル変数を持ちません。ステートに関する情報はすべて、この構造体を通してアクセスされます。

ライブラリのどの関数にも最初の引数としてこの構造体へのポインタを渡さなければなりません。ただしゼロからLuaステートを作成する lua_newstate は除きます。

`lua_status`

[-0, +0, –]

int lua_status (lua_State *L);

スレッド L の状態を返します。

状態は、通常のスレッドの場合は0 (LUA_OK)、 lua_resume で実行したスレッドがエラー終了した場合はエラーコード、スレッドが中断している場合は LUA_YIELD です。

関数の呼び出しは状態が LUA_OK のスレッドでのみ行うことができます。再開は状態が LUA_OK (新しいコルーチンを再開する場合) または LUA_YIELD (コルーチンを再開する場合) のスレッドに対して行うことができます。

`lua_stringtonumber`

[-0, +1, –]

size_t lua_stringtonumber (lua_State *L, const char *s);

ゼロ終端文字列 s を数値に変換し、その数値をスタックに積み、その文字列の合計サイズ、つまり長さプラス1を返します。変換結果はLuaの字句規約に従って整数か浮動小数点数になります (§3.1 を参照)。文字列の前後に空白があってもよく、符号が付いていても構いません。文字列が有効な数値でなかった場合は0が返され、スタックには何も積まれません。 (この戻り値はブーリアンとみなすことができます。つまり変換が成功した場合は真です。)

`lua_toboolean`

[-0, +0, –]

int lua_toboolean (lua_State *L, int index);

指定されたインデックスのLuaの値をブーリアン値 (0または1) に変換します。 Luaの条件判定と同様に false と nil 以外のすべてのLuaの値に対して真を返し、それ以外は偽を返します。 (実際のブーリアン値のみを受け入れたい場合は lua_isboolean を使ってその値の型をチェックしてください。)

`lua_tocfunction`

[-0, +0, –]

lua_CFunction lua_tocfunction (lua_State *L, int index);

指定されたインデックスの値をCの関数に変換します。この値はCの関数でなければなりません。そうでなければ NULL を返します。

`lua_tointeger`

[-0, +0, –]

lua_Integer lua_tointeger (lua_State *L, int index);

lua_tointegerx の isnum に NULL を渡した場合と同等です。

`lua_tointegerx`

[-0, +0, –]

lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);

指定されたインデックスのLuaの値を符号付き整数型 lua_Integer に変換します。このLuaの値は整数か、整数に変換可能な数値または文字列 (§3.4.3 を参照) でなければなりません。そうでなければ0を返します。

isnum が NULL でなければ、その参照先に操作が成功したかどうかを示すブーリアン値が格納されます。

`lua_tolstring`

[-0, +0, e]

const char *lua_tolstring (lua_State *L, int index, size_t *len);

指定されたインデックスのLuaの値をCの文字列に変換します。 len が NULL でなければ、 *len にその文字列の長さが設定されます。このLuaの値は文字列か数値でなければなりません。そうでなければ NULL を返します。値が数値の場合、そのスタック内の値は実際に文字列に変換されます。 (この変換はテーブル巡回中のキーに対して適用すると lua_next を混乱させます。)

lua_tolstring は、Luaステートの内部の文字列を指す、完全にアラインメントされたポインタを返します。この文字列は (Cのように) 最後の文字の後に必ずゼロ ('\0') を持ちますが、途中にもゼロが含まれる場合があります。

Luaはガベージコレクションを行うため、 lua_tolstring から返されたポインタが、対応するLuaの値がスタックから削除された後も有効かどうかは、保証されていません。

`lua_tonumber`

[-0, +0, –]

lua_Number lua_tonumber (lua_State *L, int index);

lua_tonumberx の isnum に NULL を渡した場合と同等です。

`lua_tonumberx`

[-0, +0, –]

lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);

指定されたインデックスのLuaの値をCの型 lua_Number に変換します。このLuaの値は数値か、数値に変換可能な文字列 (§3.4.3 を参照) でなければなりません。そうでなければ0を返します。

isnum が NULL でなければ、その参照先に操作が成功したかどうかを示すブーリアン値が格納されます。

`lua_topointer`

[-0, +0, –]

const void *lua_topointer (lua_State *L, int index);

指定されたインデックスの値をCの汎用ポインタ (void*) に変換します。この値はユーザーデータ、テーブル、スレッドまたは関数でなければなりません。そうでなければ NULL を返します。異なるオブジェクトには異なるポインタが返されます。このポインタから元の値に戻す方法はありません。

通常、この関数はハッシュとデバッグ情報のためにのみ使われます。

`lua_tostring`

[-0, +0, e]

const char *lua_tostring (lua_State *L, int index);

lua_tolstring で len に NULL を渡した場合と同等です。

`lua_tothread`

[-0, +0, –]

lua_State *lua_tothread (lua_State *L, int index);

指定されたインデックスの値をLuaのスレッドに変換します (lua_State* として表されます)。この値はスレッドでなければなりません。そうでなければ NULL を返します。

`lua_touserdata`

[-0, +0, –]

void *lua_touserdata (lua_State *L, int index);

指定されたインデックスの値がフルユーザーデータであれば、そのブロックアドレスを返します。値がライトユーザーデータであれば、そのポインタを返します。そうでなければ NULL を返します。

`lua_type`

[-0, +0, –]

int lua_type (lua_State *L, int index);

指定されたインデックスの値の型を返します。有効でない (しかし受け入れ可能な) インデックスに対しては LUA_TNONE を返します。 lua_type が返す型は lua.h で定義されている以下の定数で符号化されます。

LUA_TNIL (0)
LUA_TNUMBER
LUA_TBOOLEAN
LUA_TSTRING
LUA_TTABLE
LUA_TFUNCTION
LUA_TUSERDATA
LUA_TTHREAD
LUA_TLIGHTUSERDATA

`lua_typename`

[-0, +0, –]

const char *lua_typename (lua_State *L, int tp);

値 tp に符号化された型の名前を返します。この値は lua_type が返す値のいずれかでなければなりません。

`lua_Unsigned`

typedef ... lua_Unsigned;

lua_Integer の符号なし版です。

`lua_upvalueindex`

[-0, +0, –]

int lua_upvalueindex (int i);

実行中の関数の i 番目の上位値を表す擬似インデックスを返します (§4.4 を参照)。

`lua_version`

[-0, +0, v]

const lua_Number *lua_version (lua_State *L);

Luaのコアに格納されているバージョン番号のアドレスを返します。有効な lua_State を渡した場合は、そのステートを作成するのに使われたバージョンのアドレスを返します。 NULL を渡した場合は、その呼び出しを実行しているバージョンのアドレスを返します。

`lua_Writer`

typedef int (*lua_Writer) (lua_State *L,
                           const void* p,
                           size_t sz,
                           void* ud);

lua_dump で使われるライター関数の型です。新しいチャンクの断片が生成されるたびに lua_dump から呼ばれ、出力されるバッファ (p) とそのサイズ (sz)、および lua_dump に渡した data 引数が渡されます。

ライター関数はエラーコードを返します。 0はエラー無しを表します。それ以外の値はすべてエラーを表し、 lua_dump を停止してライター関数をそれ以上呼ばれなくします。

`lua_xmove`

[-?, +?, –]

void lua_xmove (lua_State *from, lua_State *to, int n);

同じステートの異なるスレッド間で値を交換します。

from のスタックから n 個の値を削除し、 to のスタックにそれらを積みます。

`lua_yield`

[-?, +?, e]

int lua_yield (lua_State *L, int nresults);

lua_yieldk と同等ですが、継続を取りません (§4.7 を参照)。そのためスレッドが再開したときは呼び出し元の関数から再開されます。

`lua_yieldk`

[-?, +?, e]

int lua_yieldk (lua_State *L,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

コルーチン (スレッド) をyieldします。

lua_yieldk を呼ぶと、実行中のコルーチンはその実行を一時停止し、そのコルーチンを開始した lua_resume の呼び出しから戻ります。引数 nresults は lua_resume に戻り値として渡すスタック上の値の数です。

コルーチンが再び再開すると、yieldしたCの関数の実行を続行するために指定された継続関数 k が呼ばれます (§4.7 を参照)。この継続関数は以前の関数と同じスタックを受け取ります。ただし n 個の戻り値は削除され、 lua_resume に渡された引数に置き換えられます。さらに継続関数は lua_yieldk に渡した値 ctx を受け取ります。

通常、この関数は戻りません。コルーチンが再開するときは継続関数から実行が再開されます。ただし特別な場合がひとつあります。それは行フック (§4.9 を参照) の内部で呼ばれたときです。この場合、 lua_yieldk は継続無しで (おそらく lua_yield の形で) 呼ばれるべきであり、そのフックはこの呼び出しの直後に戻るべきです。コルーチンをyieldし、そして再開するとき、そのフックを呼び出した (Luaの) 関数から通常の実行が続行されます。

保留中のCの呼び出しに継続関数が無い場合、またはresumeの内部で実行されていないスレッド (すなわちメインスレッド) から呼ばれた場合は、エラーが発生します。

4.9 – デバッグインタフェース

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 linedefined;            /* (S) */
  int lastlinedefined;        /* (S) */
  unsigned char nups;         /* (u) number of upvalues */
  unsigned char nparams;      /* (u) number of parameters */
  char isvararg;              /* (u) */
  char istailcall;            /* (t) */
  char short_src[LUA_IDSIZE]; /* (S) */
  /* private part */
  other fields
} lua_Debug;

関数またはアクティベーションレコードに関する様々な情報を受け渡すために使われる構造体です。 lua_getstack は、後の利用のために、この構造体のプライベートな部分のみを埋めます。それ以外のフィールドを役に立つ情報で埋めるには lua_getinfo を呼んでください。

lua_Debug の各フィールドの意味は以下の通りです。

source: その関数を作成したチャンクの名前です。 source が '@' で始まっている場合、それは '@' の後の名前のファイルで定義された関数だという意味です。 source が '=' で始まっている場合、その残りの部分はユーザー依存の方法で記述されたソースの説明です。それ以外の場合、その関数は文字列内で定義された関数であり、 source がその文字列です。
short_src: エラーメッセージに使うための、 source の「印刷可能」なバージョンです。
linedefined: その関数の定義が始まる位置の行番号です。
lastlinedefined: その関数の定義が終わる位置の行番号です。
what: その関数がLuaの関数であれば文字列 "Lua"、 Cの関数であれば "C"、チャンクのメイン部分であれば "main" です。
currentline: その関数の現在の実行位置の行です。行番号情報が利用可能でなければ-1に設定されます。
name: その関数に対する適当な名前です。 Luaの関数はファーストクラスの値であるため固定の名前を持ちません。関数によっては複数のグローバル変数に格納されているかもしれません。テーブルフィールドにのみ格納されている関数もあるでしょう。 lua_getinfo 関数は、その関数がどのように呼ばれたのかを調べて、良さそうな名前を探します。名前が見つからなければ NULL に設定されます。
namewhat: name フィールドの説明です。その関数がどのように呼ばれたのかに応じて以下のいずれかの値になります。
- "global"
- "local"
- "method"
- "field"
- "upvalue"
- "" (空文字列)
(適用できそうな選択肢がなければ空文字列になります。)
istailcall: その関数呼び出しが末尾呼び出しであれば真になります。その場合、その呼び出しの呼び出し元はスタックに残っていません。
nups: その関数の上位値の数です。
nparams: その関数の固定引数の数です (Cの関数の場合は必ず0になります)。
isvararg: その関数が可変長引数を持つ場合は真になります。 (Cの関数の場合は必ず真になります)。

`lua_gethook`

[-0, +0, –]

lua_Hook lua_gethook (lua_State *L);

現在のフック関数を返します。

`lua_gethookcount`

[-0, +0, –]

int lua_gethookcount (lua_State *L);

現在のフックカウントを返します。

`lua_gethookmask`

[-0, +0, –]

int lua_gethookmask (lua_State *L);

現在のフックマスクを返します。

`lua_getinfo`

[-(0|1), +(0|1|2), e]

int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);

指定された関数または関数呼び出しに関する情報を取得します。

関数呼び出しに関する情報を取得する場合、引数 ar は、事前に lua_getstack の呼び出しによって埋められたか、フック (lua_Hook を参照) に引数として渡された、有効なアクティベーションレコードでなければなりません。

関数に関する情報を取得する場合は、その関数をスタックに積み、文字列 what の最初の文字を '>' にします。 (この場合、その関数はスタックトップから取り出され、削除されます。) 例えば関数 f が定義された行を知りたい場合、以下のようなコードを書きます。

     lua_Debug ar;
     lua_getglobal(L, "f");  /* グローバル変数 'f' を取得 */
     lua_getinfo(L, ">S", &ar);
     printf("%d\n", ar.linedefined);

文字列 what の各文字により、構造体 ar の埋めるフィールドやスタックに積む値を指定します。

'n': フィールド name、 namewhat を埋めます。
'S': フィールド source、 short_src、 linedefined、 lastlinedefined、 what を埋めます。
'l': フィールド currentline を埋めます。
't': フィールド istailcall を埋めます。
'u': フィールド nups、 nparams、 isvararg を埋めます。
'f': 指定されたレベルで実行中の関数をスタックに積みます。
'L': その関数の有効な行番号をインデックスに持つテーブルをスタックに積みます。 (有効な行とは何らかのコードが関連付けられている行です。つまりブレークポイントを設置することができる行のことです。空行やコメントは有効な行ではありません。)
このオプションがオプション 'f' と一緒に使われた場合、このテーブルは関数の後に積まれます。

この関数はエラーの場合 (例えば what に無効なオプションを指定された場合) 0を返します。

`lua_getlocal`

[-0, +(0|1), –]

const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);

指定されたアクティベーションレコード、または指定された関数の、ローカル変数に関する情報を取得します。

前者の場合、引数 ar は、事前に lua_getstack の呼び出しによって埋められたか、フック (lua_Hook を参照) に引数として渡された、有効なアクティベーションレコードでなければなりません。インデックス n で調査するローカル変数を選びます。変数のインデックスと名前については debug.getlocal を参照してください。

lua_getlocal は、その変数の値をスタックに積み、その名前を返します。

後者の場合、 ar には NULL を指定し、関数はスタックトップに置かなければなりません。この場合はLuaの関数の引数のみを見ることができ (アクティブな変数についての情報はないため)、スタックに積まれる値はありません。

インデックスがアクティブなローカル変数の数より大きい場合は NULL を返します (そして何も積みません)。

`lua_getstack`

[-0, +0, –]

int lua_getstack (lua_State *L, int level, lua_Debug *ar);

インタプリタのランタイムスタックについての情報を取得します。

指定されたレベルで実行中の関数のアクティベーションレコードの識別情報で、 lua_Debug 構造体の一部が埋められます。レベル0は現在実行中の関数、レベルn+1はレベルnの呼び出し元の関数です (スタックに残らない末尾呼び出しは除きます)。エラーがなければ1を返します。スタックの深さよりも大きなレベルが指定された場合は0を返します。

`lua_getupvalue`

[-0, +(0|1), –]

const char *lua_getupvalue (lua_State *L, int funcindex, int n);

インデックス funcindex のクロージャの n 番目の上位値に関する情報を取得します。その上位値の値をスタックに積み、その名前を返します。インデックス n が上位値の数より大きい場合は NULL を返します (そして何も積みません)。

Cの関数の場合は、どの上位値に対しても、名前として空文字列 "" が返されます。 (Luaの関数の場合は、上位値はその関数が使用しているためにクロージャに含まれている外部ローカル変数です。)

上位値は関数全体にわたってアクティブであり、特定の順番はありません。適当な順番で番号付けられます。

`lua_Hook`

typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);

デバッグフック関数の型です。

フックが呼ばれると、引数 ar のフィールド event に、そのフックの原因となったイベントが設定されます。これらのイベントは以下の定数で表されます。

LUA_HOOKCALL
LUA_HOOKRET
LUA_HOOKTAILCALL
LUA_HOOKLINE
LUA_HOOKCOUNT

さらに、lineイベントの場合はフィールド currentline も設定されます。 ar のそれ以外のフィールドの値を取得する場合は lua_getinfo を呼ばなければなりません。

callイベントの場合、 event は LUA_HOOKCALL (通常の値) または LUA_HOOKTAILCALL (末尾呼び出しの場合) です。後者の場合、対応するreturnイベントはありません。

フックを実行中の間、さらなるフックの呼び出しは無効化されます。そのため、フックから関数やチャンクを実行ためにLuaをコールバックすると、それはいかなるフックも呼び出さずに実行されます。

フック関数は継続を持つことができません。そのため lua_yieldk、 lua_pcallk、 lua_callk にnull以外の k を渡すことはできません。

フック関数は以下の状況でyieldすることができます。 countイベントとlineイベントのみyieldできます。 yieldするには、 lua_yield の nresults に0を渡して呼ぶ (つまり値を渡さない) ことによってフック関数の実行を終了しなければなりません。

`lua_sethook`

[-0, +0, –]

void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);

デバッグフック関数を設定します。

引数 f はフック関数です。 mask は、そのフックが呼ばれるイベントを以下の定数のビットごとの論理和で指定します。

LUA_MASKCALL
LUA_MASKRET
LUA_MASKLINE
LUA_MASKCOUNT

count 引数は、マスクに LUA_MASKCOUNT が含まれている場合にだけ意味があります。各イベントについて、フック関数は以下で説明するように呼ばれます。

callフック: 関数を呼んだときに呼ばれます。フックは新しい関数に入った直後、その関数が引数を取得する前に呼ばれます。
returnフック: 関数から戻るときに呼ばれます。フックは関数から離れる直前に呼ばれます。その関数の戻り値にアクセスする標準的な方法はありません。
lineフック: コードの新しい行の実行が開始されるとき、または (同じ行であっても) コード内で逆方向のジャンプが発生したときに呼ばれます。 (このイベントはLuaの関数を実行している間だけ発生します。)
countフック: count 個の命令を実行するごとに呼ばれます。 (このイベントはLuaの関数を実行している間だけ発生します。)

mask をゼロに設定するとフックは無効化されます。

`lua_setlocal`

[-(0|1), +0, –]

const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);

指定されたアクティベーションレコードのローカル変数の値を設定します。スタックトップの値をその変数に代入し、その名前を返します。また、スタックトップからその値を削除します。

インデックスがアクティブなローカル変数の数よりも大きい場合は NULL を返します (そしてスタックの値は削除されません)。

引数 ar および n は関数 lua_getlocal と同様です。

`lua_setupvalue`

[-(0|1), +0, –]

const char *lua_setupvalue (lua_State *L, int funcindex, int n);

クロージャの上位値の値を設定します。スタックトップの値をその上位値に代入し、その名前を返します。また、スタックからその値を削除します。

インデックス n が上位値の数より大きい場合は NULL を返します (そしてスタックの値は削除されません)。

引数 funcindex および n は関数 lua_getupvalue と同様です。

`lua_upvalueid`

[-0, +0, –]

void *lua_upvalueid (lua_State *L, int funcindex, int n);

インデックス funcindex のクロージャの n 番目の上位値の一意な識別子を返します。

この一意な識別子を使うと、異なるクロージャが上位値を共有しているかどうかを確認することができます。ひとつの上位値を共有している (つまり同じ外部ローカル変数にアクセスする) Luaのクロージャは、その上位値のインデックスに対して同一の識別子を返します。

引数 funcindex および n は関数 lua_getupvalue と同様ですが、 n を上位値の数より大きくすることはできません。

`lua_upvaluejoin`

[-0, +0, –]

void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
                                    int funcindex2, int n2);

インデックス funcindex1 にあるLuaのクロージャの n1 番目の上位値が、インデックス funcindex2 にあるLuaのクロージャの n2 番目の上位値を参照するようにします。

5 – 補助ライブラリ

補助ライブラリにはCとLuaの間でやり取りするための便利な関数がいくつか用意されています。基本APIはCとLuaの間でやり取りするために必要な基本的な関数をすべて提供していますが、補助ライブラリはいくつかの一般的な処理のためにより高水準な関数を提供しています。

補助ライブラリの関数と型はすべて、ヘッダファイル lauxlib.h で定義されており、接頭辞 luaL_ が付いています。

補助ライブラリの関数はすべて基本APIの上に構築されているため、基本APIを使ってできないことは何もありません。しかし補助ライブラリを使えばコードの一貫性を高められます。

補助ライブラリの関数にはいくつか追加のスタックスロットを内部的に使用するものがあります。補助ライブラリの関数が使うスロットが5個未満の場合、スタックサイズのチェックは行っていません。単純に十分なスロットがあるものと仮定しています。

補助ライブラリの関数にはCの関数の引数をチェックするためのものがあります。これらの関数は引数用のエラーメッセージを生成するため ("bad argument #1" など)、それ以外の値に対して使うべきではありません。

luaL_check* という名前の関数は、そのチェック内容を満たさなかった場合、常にエラーが発生します。

5.1 – 関数と型

すべての補助ライブラリの関数と型をアルファベット順に掲載します。

`luaL_addchar`

[-?, +?, e]

void luaL_addchar (luaL_Buffer *B, char c);

バイト c をバッファ B に追加します (luaL_Buffer を参照)。

`luaL_addlstring`

[-?, +?, e]

void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);

s の指す長さ l の文字列をバッファ B に追加します (luaL_Buffer を参照)。文字列にはゼロを含めることができます。

`luaL_addsize`

[-?, +?, e]

void luaL_addsize (luaL_Buffer *B, size_t n);

バッファエリア (luaL_prepbuffer を参照) に事前にコピーしておいた長さ n の文字列をバッファ B (luaL_Buffer を参照) に追加します。

`luaL_addstring`

[-?, +?, e]

void luaL_addstring (luaL_Buffer *B, const char *s);

s の指すゼロ終端文字列をバッファ B に追加します (luaL_Buffer を参照)。

`luaL_addvalue`

[-1, +?, e]

void luaL_addvalue (luaL_Buffer *B);

スタックトップの値をバッファ B に追加します (luaL_Buffer を参照)。その値はスタックから削除されます。

これは文字列バッファ系唯一の、追加の要素をスタックから取るタイプの関数です。

`luaL_argcheck`

[-0, +0, v]

void luaL_argcheck (lua_State *L,
                    int cond,
                    int arg,
                    const char *extramsg);

cond が真かどうかを確認します。そうでなければ標準的なエラーメッセージを使ってエラーを発生させます (luaL_argerror を参照)。

`luaL_argerror`

[-0, +0, v]

int luaL_argerror (lua_State *L, int arg, const char *extramsg);

extramsg をコメントとして含む以下のような標準的なエラーメッセージを使って、呼び出し元のCの関数の第 arg 引数の問題を報告するエラーを発生します。

     bad argument #arg to 'funcname' (extramsg)

この関数は戻りません。

`luaL_Buffer`

typedef struct luaL_Buffer luaL_Buffer;

文字列バッファの型です。

文字列バッファを使うとCのコードでLuaの文字列を少しずつ組み立てられます。以下のような形で使います。

まず luaL_Buffer 型の変数 b を宣言します。
次に luaL_buffinit(L, &b) を呼んでそれを初期化します。
そして任意の luaL_add* 関数を呼んで、文字列片をバッファに追加します。
最後に luaL_pushresult(&b) を呼びます。これによりスタックトップに最終的な文字列が残されます。

結果となる文字列の合計サイズが事前に判っているのであれば、バッファを以下のように使うことができます。

まず luaL_Buffer 型の変数 b を宣言します。
次に luaL_buffinitsize(L, &b, sz) を呼んでそれを初期化し、サイズ sz の空間を事前確保します。
そしてその空間に文字列をコピーします。
最後に luaL_pushresultsize(&b, sz) を呼びます。 sz はその空間にコピーされる結果の文字列の合計サイズです。

この操作の間、文字列バッファは不定個のスタックスロットを使います。そのためバッファを使用している間、スタックトップがどこにあるかはわかりません。釣り合いが取れている限り、バッファ操作の呼び出しの合間にスタックを使うことはできます。つまりバッファ操作を呼び出すときは、前回バッファ操作をした直後の状態と同じレベルにスタックを戻す必要があります。 (このルールの唯一の例外は luaL_addvalue です。) luaL_pushresult を呼んだ後、スタックはバッファを初期化したときのレベルに戻り、その上に最終的な文字列が積まれます。

`luaL_buffinit`

[-0, +0, –]

void luaL_buffinit (lua_State *L, luaL_Buffer *B);

バッファ B を初期化します。この関数は空間を一切割り当てません。バッファは変数として宣言していなければなりません (luaL_Buffer を参照)。

`luaL_buffinitsize`

[-?, +?, e]

char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);

luaL_buffinit を呼んだ後に luaL_prepbuffsize を呼ぶのと同等です。

`luaL_callmeta`

[-0, +(0|1), e]

int luaL_callmeta (lua_State *L, int obj, const char *e);

メタメソッドを呼びます。

インデックス obj のオブジェクトがメタテーブルを持っていて、このメタテーブルにフィールド e がある場合、この関数はそのオブジェクトを引数としてそのフィールドを呼びます。その場合、この関数は真に加えて、その呼び出しから返された戻り値をスタックに積みます。メタテーブルがないか、メタメソッドがない場合、この関数は偽を返します (スタックには何も積みません)。

`luaL_checkany`

[-0, +0, v]

void luaL_checkany (lua_State *L, int arg);

arg 番目の引数が存在するかどうか (nil を含む) を確認します。

`luaL_checkinteger`

[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int arg);

arg 番目の引数が整数 (または整数に変換可能な値) かどうかを確認し、その整数を lua_Integer に変換して返します。

`luaL_checklstring`

[-0, +0, v]

const char *luaL_checklstring (lua_State *L, int arg, size_t *l);

arg 番目の引数が文字列かどうかを確認し、その文字列を返します。 l が NULL でなければ、 *l がその文字列の長さで埋められます。

この関数は結果を取得するために lua_tolstring を使います。そのため、その関数の変換と注意点はすべてここでも適用されます。

`luaL_checknumber`

[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int arg);

arg 番目の引数が数値かどうかを確認し、その数値を返します。

`luaL_checkoption`

[-0, +0, v]

int luaL_checkoption (lua_State *L,
                      int arg,
                      const char *def,
                      const char *const lst[]);

arg 番目の引数が文字列かどうかを確認し、その文字列を配列 lst (NULLで終わっていなければなりません) の中から探します。その文字列が見つかれば、その配列内のインデックスを返します。引数が文字列でないか、その文字列が見つからなければ、エラーが発生します。

def が NULL でなければ、 arg 番目の引数が存在しないときやその引数が nil のときに、デフォルト値として def が使われます。

この関数は、文字列をCのenumに対応付けるときに便利です。 (Luaのライブラリの通常の慣習では、オプションの選択に数値ではなく文字列を使います。)

`luaL_checkstack`

[-0, +0, v]

void luaL_checkstack (lua_State *L, int sz, const char *msg);

スタックサイズを top + sz 個分に伸ばします。スタックをそのサイズに伸ばせない場合はエラーが発生します。 msg は、そのエラーメッセージに追加されるテキストです (追加のテキストが不要であれば NULL でも構いません)。

`luaL_checkstring`

[-0, +0, v]

const char *luaL_checkstring (lua_State *L, int arg);

arg 番目の引数が文字列かどうかを確認し、その文字列を返します。

この関数は結果を取得するために lua_tolstring を使います。そのため、その関数の変換と注意点はすべてここでも適用されます。

`luaL_checktype`

[-0, +0, v]

void luaL_checktype (lua_State *L, int arg, int t);

arg 番目の引数が t 型かどうかを確認します。 t の型の符号化については lua_type を参照してください。

`luaL_checkudata`

[-0, +0, v]

void *luaL_checkudata (lua_State *L, int arg, const char *tname);

arg 番目の引数が tname 型のユーザーデータ (luaL_newmetatable を参照) かどうかを確認し、そのユーザーデータのアドレスを返します (lua_touserdata を参照)。

`luaL_checkversion`

[-0, +0, –]

void luaL_checkversion (lua_State *L);

呼び出しを実行しているコア、Luaステートを作成したコア、呼び出しを行ったコードがすべて同じバージョンのLuaを使用しているかどうかを確認します。また、呼び出しを実行しているコアとLuaステートを作成したコアが、同じアドレススペースを使用しているかどうかも確認します。

`luaL_dofile`

[-0, +?, e]

int luaL_dofile (lua_State *L, const char *filename);

指定されたファイルをロードして実行します。これは以下のマクロとして定義されています。

     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))

エラーがなければ偽を返し、エラーの場合は真を返します。

`luaL_dostring`

[-0, +?, –]

int luaL_dostring (lua_State *L, const char *str);

指定された文字列をロードして実行します。これは以下のマクロとして定義されています。

     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))

エラーがなければ偽を返し、エラーの場合は真を返します。

`luaL_error`

[-0, +0, v]

int luaL_error (lua_State *L, const char *fmt, ...);

エラーを発生させます。エラーメッセージの書式は、 fmt と追加の引数で指定されます。これらは lua_pushfstring と同じルールに従います。また、エラーが発生したファイル名と行番号が利用可能であれば、それらがメッセージの先頭に追加されます。

この関数は決して戻りませんが、慣例としてCの関数で return luaL_error(args) のように使います。

`luaL_execresult`

[-0, +3, e]

int luaL_execresult (lua_State *L, int stat);

標準ライブラリのプロセス関係の関数 (os.execute および io.close) のための戻り値を生成します。

`luaL_fileresult`

[-0, +(1|3), e]

int luaL_fileresult (lua_State *L, int stat, const char *fname);

標準ライブラリのファイル関係の関数 (io.open、 os.rename、 file:seek など) のための戻り値を生成します。

`luaL_getmetafield`

[-0, +(0|1), e]

int luaL_getmetafield (lua_State *L, int obj, const char *e);

インデックス obj のオブジェクトのメタテーブルのフィールド e をスタックに積み、その積んだ値の型を返します。そのオブジェクトがメタテーブルを持っていないか、そのメタテーブルがそのフィールドを持っていなければ、何も積まずに LUA_TNIL を返します。

`luaL_getmetatable`

[-0, +1, –]

int luaL_getmetatable (lua_State *L, const char *tname);

レジストリの名前 tname に関連付けられたメタテーブル (luaL_newmetatable を参照) (その名前に関連付けられたメタテーブルがなければ nil) をスタックに積みます。積んだ値の型を返します。

`luaL_getsubtable`

[-0, +1, e]

int luaL_getsubtable (lua_State *L, int idx, const char *fname);

値 t[fname] がテーブルであることを保証し、そのテーブルをスタックに積みます。ただし t はインデックス idx の値です。既存のテーブルが存在した場合は真を返し、新しいテーブルを作成した場合は偽を返します。

`luaL_gsub`

[-0, +1, e]

const char *luaL_gsub (lua_State *L,
                       const char *s,
                       const char *p,
                       const char *r);

文字列 s 内に出現する文字列 p をすべて文字列 r に置き換えた文字列を作成します。その結果の文字列をスタックに積み、それを返します。

`luaL_len`

[-0, +0, e]

lua_Integer luaL_len (lua_State *L, int index);

指定されたインデックスの値の「長さ」を数値として返します。これはLuaの '#' 演算子と同等です (§3.4.7 を参照)。演算の結果が整数でない場合はエラーが発生します。 (これはメタメソッドが呼ばれた場合にのみ発生します。)

`luaL_loadbuffer`

[-0, +1, –]

int luaL_loadbuffer (lua_State *L,
                     const char *buff,
                     size_t sz,
                     const char *name);

luaL_loadbufferx の mode に NULL を渡した場合と同等です。

`luaL_loadbufferx`

[-0, +1, –]

int luaL_loadbufferx (lua_State *L,
                      const char *buff,
                      size_t sz,
                      const char *name,
                      const char *mode);

バッファをLuaのチャンクとしてロードします。この関数は lua_load を使って buff が指すサイズ sz のチャンクをロードします。

この関数は lua_load と同じ結果を返します。 name はチャンクの名前で、デバッグ情報やエラーメッセージに使われます。文字列 mode は関数 lua_load と同様です。

`luaL_loadfile`

[-0, +1, e]

int luaL_loadfile (lua_State *L, const char *filename);

luaL_loadfilex の mode に NULL を渡した場合と同等です。

`luaL_loadfilex`

[-0, +1, e]

int luaL_loadfilex (lua_State *L, const char *filename,
                                            const char *mode);

ファイルをLuaのチャンクとしてロードします。この関数は lua_load を使って filename という名前のファイルからチャンクをロードします。 filename が NULL の場合は標準入力からロードされます。ファイルの最初の行が # で始まっている場合、その行は無視されます。

文字列 mode は関数 lua_load と同様です。

この関数は lua_load と同じ結果を返しますが、ファイルを開けなかったり読み込めなかった場合は追加のエラーコード LUA_ERRFILE を返します。

lua_load と同様に、この関数はチャンクをロードするだけです。実行はしません。

`luaL_loadstring`

[-0, +1, –]

int luaL_loadstring (lua_State *L, const char *s);

文字列をLuaのチャンクとしてロードします。この関数は lua_load を使ってゼロ終端文字列 s からチャンクをロードします。

この関数は lua_load と同じ結果を返します。

lua_load と同様に、この関数はチャンクをロードするだけです。実行はしません。

`luaL_newlib`

[-0, +1, e]

void luaL_newlib (lua_State *L, const luaL_Reg l[]);

新しいテーブルを作成し、リスト l の関数をそこに登録します。

これは以下のようなマクロとして実装されています。

     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))

配列 l はポインタではなく、実際の配列でなければなりません。

`luaL_newlibtable`

[-0, +1, e]

void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);

配列 l のすべてのエントリを格納するのに適したサイズの新しいテーブルを作成します。 (しかし実際にそれらを格納はしません。) これは luaL_setfuncs と共に使われることを意図しています (luaL_newlib を参照)。

これはマクロとして実装されています。配列 l はポインタではなく、実際の配列でなければなりません。

`luaL_newmetatable`

[-0, +1, e]

int luaL_newmetatable (lua_State *L, const char *tname);

レジストリにキー tname がすでにあれば0を返します。そうでなければ、ユーザーデータ用のメタテーブルとして使われる新しいテーブルを作成し、ペア __name = tname をこの新しいテーブルに追加し、ペア [tname] = 新しいテーブル をレジストリに追加し、1を返します。 (エントリ __name はエラー報告関数のいくつかで使われます。)

どちらの場合でも、レジストリの tname に関連付けられた最終的な値がスタックに積まれます。

`luaL_newstate`

[-0, +0, –]

lua_State *luaL_newstate (void);

Luaのステートを作成します。標準規格のCの realloc 関数をベースとしたアロケータを渡して lua_newstate を呼びます。また、致命的なエラーが発生した場合にエラーメッセージを標準エラー出力に表示するパニック関数 (§4.6 を参照) を設定します。

新しいステートを返します。メモリ確保エラーが発生した場合は NULL を返します。

`luaL_openlibs`

[-0, +0, e]

void luaL_openlibs (lua_State *L);

すべての標準Luaライブラリを指定されたステートにオープンします。

`luaL_optinteger`

[-0, +0, v]

lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);

arg 番目の引数が整数 (または整数に変換可能) であれば、その整数を返します。その引数が存在しないか nil であれば d を返します。どちらでもなければエラーが発生します。

`luaL_optlstring`

[-0, +0, v]

const char *luaL_optlstring (lua_State *L,
                             int arg,
                             const char *d,
                             size_t *l);

arg 番目の引数が文字列であれば、その文字列を返します。その引数が存在しないか nil であれば d を返します。どちらでもなければエラーが発生します。

l が NULL でなければ、 *l に結果の長さが格納されます。

`luaL_optnumber`

[-0, +0, v]

lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);

arg 番目の引数が数値であれば、その数値を返します。その引数が存在しないか nil であれば d を返します。どちらでもなければエラーが発生します。

`luaL_optstring`

[-0, +0, v]

const char *luaL_optstring (lua_State *L,
                            int arg,
                            const char *d);

`luaL_prepbuffer`

[-?, +?, e]

char *luaL_prepbuffer (luaL_Buffer *B);

luaL_prepbuffsize に定義済みのサイズ LUAL_BUFFERSIZE を渡した場合と同等です。

`luaL_prepbuffsize`

[-?, +?, e]

char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);

バッファ B に追加したい文字列をコピーすることのできる、サイズ sz の領域のアドレスを返します (luaL_Buffer を参照)。文字列をこの領域にコピーした後、実際にバッファに追加する文字列のサイズを引数に luaL_addsize を呼ばなければなりません。

`luaL_pushresult`

[-?, +1, e]

void luaL_pushresult (luaL_Buffer *B);

バッファ B の使用を終了し、最終的な文字列をスタックトップに置きます。

`luaL_pushresultsize`

[-?, +1, e]

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);

luaL_addsize を呼んだ後に luaL_pushresult を呼ぶのと同等です。

`luaL_ref`

[-1, +0, e]

int luaL_ref (lua_State *L, int t);

スタックトップのオブジェクトに対するリファレンスを、インデックス t のテーブルに作成して返します。 (オブジェクトはスタックから削除されます。)

リファレンスは一意な整数のキーです。テーブル t に手動で整数キーを追加しない限り、返されるキーの一意性が保証されます。 lua_rawgeti(L, t, r) を呼ぶと、リファレンス r の参照するオブジェクトを取得できます。関数 luaL_unref を呼ぶと、リファレンスとそれに関連付けられたオブジェクトを解放できます。

スタックトップのオブジェクトが nil の場合は、定数 LUA_REFNIL を返します。定数 LUA_NOREF は、 luaL_ref が返すいかなるリファレンスとも異なることが保証されています。

`luaL_Reg`

typedef struct luaL_Reg {
  const char *name;
  lua_CFunction func;
} luaL_Reg;

luaL_setfuncs で登録する関数配列の型です。 name は関数の名前で、 func は関数へのポインタです。 luaL_Reg の配列は最後に必ず番兵エントリを置かなければなりません。番兵エントリは name と func が両方とも NULL のエントリです。

`luaL_requiref`

[-0, +1, e]

void luaL_requiref (lua_State *L, const char *modname,
                    lua_CFunction openf, int glb);

modname が package.loaded にまだ存在しなければ、 require を通して呼ばれたかのように文字列 modname を引数として関数 openf を呼び、 package.loaded[modname] にその呼び出しの結果を設定します。

glb が真であれば、グローバル変数 modname にもそのモジュールが格納されます。

そのモジュールをスタックに置きます。

`luaL_setfuncs`

[-nup, +0, e]

void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);

配列 l (luaL_Reg を参照) のすべての関数を、スタックトップのテーブル (ただし上位値がある場合はその下です。下記参照) に登録します。

nup がゼロでなければ、すべての関数は nup 個の上位値を共有した状態で作成されます。これらの上位値は事前にライブラリテーブルの上に積んでおかなければならず、登録後にスタックから削除されます。

`luaL_setmetatable`

[-0, +0, –]

void luaL_setmetatable (lua_State *L, const char *tname);

スタックトップのオブジェクトのメタテーブルを、レジストリの名前 tname に関連付けられたメタテーブルとして設定します。 (luaL_newmetatable を参照)。

`luaL_Stream`

typedef struct luaL_Stream {
  FILE *f;
  lua_CFunction closef;
} luaL_Stream;

標準入出力ライブラリで使われるファイルハンドルの標準的な表現です。

ファイルハンドルは LUA_FILEHANDLE という名前のメタテーブルを持つフルユーザーデータとして実装されています (LUA_FILEHANDLE は実際のメタテーブルの名前に展開されるマクロです)。このメタテーブルは入出力ライブラリによって作成されます (luaL_newmetatable を参照)。

このユーザーデータは先頭に構造体 luaL_Stream が存在しなければなりません。この最初の構造体の後には任意のデータを持つことができます。フィールド f は対応するCのストリームです (不完全に作成されたハンドルを表すために NULL になる場合もあります)。フィールド closef は、ハンドルが閉じられたか回収されたときにストリームを閉じるために呼ばれる、Luaの関数を指します。この関数は唯一の引数としてファイルハンドルを取り、 true (成功の場合) または nil とエラーメッセージ (エラーの場合) を返さなければなりません。ひとたびこのフィールドが呼ばれると、ハンドルが閉じられたことを表すため、このフィールドの値は NULL に変更されます。

`luaL_testudata`

[-0, +0, e]

void *luaL_testudata (lua_State *L, int arg, const char *tname);

この関数は luaL_checkudata と同様に動作します。ただしチェックが失敗した場合は、エラーを発生させる代わりに NULL を返します。

`luaL_tolstring`

[-0, +1, e]

const char *luaL_tolstring (lua_State *L, int idx, size_t *len);

指定されたインデックスの任意のLuaの値を、適当な書式でCの文字列に変換します。結果の文字列はスタックに積まれ、また戻り値としても返されます。 len が NULL でなければ、 *len にその文字列の長さが設定されます。

その値に "__tostring" フィールドを持つメタテーブルがある場合は、その値を引数として対応するメタメソッドが呼ばれ、その呼び出しの戻り値が結果として使われます。

`luaL_traceback`

[-0, +1, e]

void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
                     int level);

L1 のスタックトレースを作成して積みます。 msg が NULL でなければ、スタックトレースの先頭にそれが追加されます。 level 引数はスタックトレースを開始するレベルを指定します。

`luaL_typename`

[-0, +0, –]

const char *luaL_typename (lua_State *L, int index);

指定されたインデックスの値の型の名前を返します。

`luaL_unref`

[-0, +0, –]

void luaL_unref (lua_State *L, int t, int ref);

インデックス t のテーブルからリファレンス ref を解放します (luaL_ref を参照)。対応するエントリがテーブルから削除され、参照されていたオブジェクトが回収可能になります。リファレンス ref もまた、後の再利用のために解放されます。

ref が LUA_NOREF または LUA_REFNIL の場合は、何もしません。

`luaL_where`

[-0, +1, e]

void luaL_where (lua_State *L, int lvl);

コールスタックのレベル lvl の現在の実行位置を表す文字列をスタックに積みます。通常、この文字列は以下のような書式です。

     チャンクの名前:現在の行:

レベル0は実行中の関数、レベル1は実行中の関数の呼び出し元の関数以下同様です。

この関数はエラーメッセージのプレフィックスを作成するために使われます。

6 – 標準ライブラリ

標準LuaライブラリはCのAPIを通して直接実装できる便利な関数を提供しています。これらの関数の中には、基本的な言語機能を提供しているもの (例えば type や getmetatable)、「外部」のサービスへのアクセスを提供しているもの (例えば入出力)、Lua自身で実装可能だけれども非常に便利であるとか重大な性能上の要件のためにCで実装する価値のあるもの (例えば table.sort) などがあります。

すべてのライブラリは公式のCのAPIを使って実装されており、本体とは別のCのモジュールとして提供されています。現在Luaには以下の標準ライブラリがあります。

基本ライブラリ (§6.1);
コルーチンライブラリ (§6.2);
パッケージライブラリ (§6.3);
文字列操作 (§6.4);
基本的なUTF-8のサポート (§6.5);
テーブル操作 (§6.6);
数学関数 (§6.7) (sin, log, etc.);
入出力 (§6.8);
OS機能 (§6.9);
デバッグ機能 (§6.10).

基本ライブラリとパッケージライブラリを除き、各ライブラリのすべての機能はグローバルテーブルのフィールドとして、またはオブジェクトのメソッドとして提供されます。

これらのライブラリにアクセスするには、 luaL_openlibs 関数をCのホストプログラムから呼んでください。これによりすべての標準ライブラリがオープンされます。別の方法として、 luaL_requiref を使って以下の関数を呼ぶことで、個別にオープンすることもできます。

luaopen_base: 基本ライブラリ
luaopen_package: パッケージライブラリ
luaopen_coroutine: コルーチンライブラリ
luaopen_string: 文字列ライブラリ
luaopen_utf8: UTF8ライブラリ
luaopen_table: テーブルライブラリ
luaopen_math: 数学ライブラリ
luaopen_io: 入出力ライブラリ
luaopen_os: OSライブラリ
luaopen_debug: デバッグライブラリ

これらの関数は lualib.h で宣言されています。

6.1 – 基本機能

基本ライブラリはLuaの中核的な機能を提供します。アプリケーションにこのライブラリを含めない場合は、これらの機能の代替品を用意する必要がないか、慎重に検討してください。

`assert (v [, message])`

引数 v の値が偽 (つまり nil または false) であれば error を呼びます。そうでなければその引数をすべて返します。エラーの場合、 message はエラーオブジェクトです。指定しなかった場合はデフォルトの "assertion failed!" が使われます。

`collectgarbage ([opt [, arg]])`

この関数はガベージコレクタへの汎用インタフェースです。第1引数 opt によって様々な機能を実行します。

"collect": 完全なガベージコレクションサイクルを実行します。これはデフォルトのオプションです。
"stop": ガベージコレクタの自動実行を停止します。自動実行を再開するまでの間、ガベージコレクタは明示的に呼び出された場合にのみ動作します。
"restart": ガベージコレクタの自動実行を再開します。
"count": Luaが使用している合計メモリをキロバイト単位で返します。この値には小数部があるので、1024を掛けるとLuaが使用している正確なバイト数になります (オーバーフローした場合を除く)。
"step": ガベージコレクションのステップを実行します。 arg によってそのステップの「サイズ」を制御できます。ゼロの場合、コレクタは基本的な (分割不可能な) ステップをひとつ実行します。ゼロ以外の場合、コレクタはその量のメモリ (キロバイト単位) の確保を行ったかのように動作します。そのステップでコレクションサイクルが完了した場合は true を返します。
"setpause": arg をコレクタの停止値 (§2.5 を参照) の新しい値として設定します。 停止値の以前の値を返します。
"setstepmul": arg をコレクタのステップ係数 (§2.5 を参照) の新しい値として設定します。 ステップ係数の以前の値を返します。
"isrunning": コレクタが実行中 (つまり停止していない) かどうかを表すブーリアン値を返します。

`dofile ([filename])`

指定された名前のファイルを開き、その内容をLuaのチャンクとして実行します。引数なしで呼んだ場合は標準入力 (stdin) の内容を実行します。チャンクから返されたすべての値を返します。エラーの場合は呼び出し元にエラーを伝播させます (つまり保護モードで実行しません)。

`error (message [, level])`

最後の保護された関数呼び出しを終了し、 message をエラーオブジェクトとして返します。関数 error は決して戻りません。

メッセージが文字列の場合は、通常、そのメッセージの先頭に、エラー位置に関する情報が追加されます。 level 引数は、そのエラー位置の取得方法を指定します。レベル1 (デフォルト) の場合、エラー位置は error 関数の呼び出し元で、レベル2は error の呼び出し元の呼び出し元を指し、以下同様です。レベル0を指定すると、エラー位置に関する情報をメッセージに追加しません。

`_G`

グローバル環境 (§2.2 を参照) を保持するグローバル変数です (関数ではありません)。 Lua自身はこの変数を使用しません。この値を変更しても環境には影響しませんし、逆も同様です。

`getmetatable (object)`

object にメタテーブルがなければ nil を返します。そうでなく、そのオブジェクトのメタテーブルに "__metatable" フィールドがあれば、それに関連付けられた値を返します。いずれでもなければ、指定されたオブジェクトのメタテーブルを返します。

`ipairs (t)`

以下の構文

     for i,v in ipairs(t) do body end

でキーと値のペア (1,t[1])、(2,t[2])、··· を最初のnil値まで巡回できるような3つの値 (イテレータ関数、テーブル t、0) を返します。

`load (chunk [, chunkname [, mode [, env]]])`

チャンクをロードします。

chunk が文字列であれば、チャンクはその文字列です。 chunk が関数であれば、チャンク片を取得するためにその関数が繰り返し呼ばれます。 chunk は呼ばれるたびに文字列を返さなければなりません。この文字列は前回の戻り値と連結されます。空文字列または nil を返すか、何も返さなければ、チャンクの終わりになります。

構文エラーがなければ、コンパイルされたチャンクが関数として返されます。そうでなければ、 nil とエラーメッセージが返されます。

結果の関数に上位値がある場合、最初の上位値は env が指定されていればその値に、そうでなければグローバル環境に設定されます。残りの上位値は nil に初期化されます。 (メインチャンクをロードした場合、結果の関数は必ず、ちょうど1個の上位値として _ENV 変数を持ちます (§2.2 を参照)。しかし、関数から作成したバイナリチャンク (string.dump を参照) をロードした場合、結果の関数は任意の個数の上位値を持っている場合があります。) すべての上位値は新しく確保されます。つまり他のいかなる関数とも共有されていません。

chunkname はエラーメッセージやデバッグ情報で使われるチャンクの名前です (§4.9 を参照)。指定しなかった場合、 chunk が文字列であればデフォルトで chunk になり、そうでなければ "=(load)" になります。

文字列 mode は、テキストまたはバイナリ (コンパイル済みチャンク) いずれのチャンクを許可するかを制御します。以下の文字列のいずれかを指定できます。

"b": バイナリチャンクのみ
"t": テキストチャンクのみ
"bt": バイナリとテキスト両方

デフォルトは "bt" です。

バイナリチャンクの一貫性はチェックされません。悪意を持って作られたバイナリチャンクはインタプリタをクラッシュさせる可能性があります。

`loadfile ([filename [, mode [, env]]])`

load に似ていますが、チャンクをファイル filename から取得します。ファイル名を指定しなかった場合は標準入力から取得します。

`next (table [, index])`

テーブルのすべてのフィールドを巡回します。第1引数はテーブルで、第2引数はそのテーブルのインデックスです。 next は、そのテーブルの次のインデックスと、それに関連付けられた値を返します。第2引数に nil を指定して呼ぶと、最初のインデックスと、それに関連付けられた値を返します。最後のインデックスを指定して呼ぶか、空のテーブルに nil を指定して呼ぶと、 nil を返します。第2引数を指定しなかった場合は、 nil を指定したものと解釈されます。例えば、 next(t) でテーブルが空かどうかを調べることができます。

インデックスが列挙される順番は決まっていません。これは数値のインデックスに対しても同様です。 (テーブルを数値順に巡回したい場合は数値用の for を使ってください。)

巡回の途中でテーブル中の元々存在しなかったフィールドに値を代入した場合、 next の動作は未定義です。しかし既存のフィールドは変更しても構いません。また既存のフィールドを削除しても構いません。

`pairs (t)`

t にメタメソッド __pairs があれば、 t を引数としてそれを呼び、その呼び出しの最初の3つの戻り値を返します。

そうでなければ、 next 関数、テーブル t、 nil の3つの値を返します。そのため、以下の構文

     for k,v in pairs(t) do body end

でテーブル t のすべてのキーと値のペアを巡回できます。

巡回中にテーブルを変更する際の注意点については、関数 next を参照してください。

`pcall (f [, arg1, ···])`

指定された引数を渡して関数 f を保護モードで呼びます。つまり f の内部で発生したいかなるエラーも伝播されないという意味です。代わりに pcall がエラーをキャッチし、ステータスコードを返します。最初の戻り値はステータスコード (ブーリアン) で、呼び出しがエラーなく成功した場合は真になります。この場合、その最初の戻り値の後に、その呼び出しからの戻り値もすべて返されます。エラーが発生した場合は false とエラーメッセージを返します。

`print (···)`

任意の個数の引数を受け取り、 tostring を使って各引数を文字列に変換し、それらの値を stdout に表示します。この関数は書式化出力を意図していません。例えばデバッグ用に、値を表示するための簡単な方法として用意されているだけです。出力を完全に制御したい場合は string.format および io.write を使ってください。

`rawequal (v1, v2)`

メタメソッドを呼ばずに、 v1 と v2 が等しいかどうかを確認します。ブーリアンを返します。

`rawget (table, index)`

メタメソッドを呼ばずに、 table[index] の実際の値を取得します。 table はテーブルでなければなりません。 index は任意の値を指定できます。

`rawlen (v)`

メタメソッドを呼ばずに、オブジェクト v の長さを返します。 v はテーブルか文字列でなければなりません。整数を返します。

`rawset (table, index, value)`

メタメソッドを呼ばずに、 table[index] の実際の値を value に設定します。 table はテーブルでなければなりません。 index は nil とNaN以外の任意の値を指定できます。 value は任意のLuaの値を指定できます。

この関数は table を返します。

`select (index, ···)`

index が数値の場合、 index 番目以降の引数をすべて返します。負の数値の場合は最後から数えます (-1が最後の引数です)。そうでなければ、 index は文字列 "#" でなければならず、渡された追加の引数の合計個数を返します。

`setmetatable (table, metatable)`

指定されたテーブルのメタテーブルを設定します。 (それ以外の型のメタテーブルをLuaから変更することはできません。 Cからのみできます。) metatable が nil の場合、指定されたテーブルのメタテーブルは削除されます。元のメタテーブルに "__metatable" フィールドがある場合はエラーが発生します。

この関数は table を返します。

`tonumber (e [, base])`

base を指定せずに呼ぶと、引数を数値に変換しようと試みます。その引数がすでに数値であるか、数値に変換可能な文字列であれば、その数値を返します。そうでなければ nil を返します。

文字列の変換結果はLuaの字句規約 (§3.1 を参照) に従って整数か浮動小数点数になります。 (文字列の前後に空白があってもよく、符号が付いていても構いません。)

base を指定して呼んだ場合、 e はその基数で整数値として解釈可能な文字列でなければなりません。基数には2から36までの任意の整数を指定できます。 10より大きな基数の場合は、 'A' (大文字でも小文字でも構いません) が10を表し、 'B' が11を表し、以下同様で、 'Z' が35を表します。文字列 e が、指定された基数で有効な数値でない場合は、 nil を返します。

`tostring (v)`

任意の型の値を受け取り、それを人間が読める形式の文字列に変換します。 (数値の変換方法を完全に制御したい場合は string.format を使ってください。)

v のメタテーブルに "__tostring" フィールドがあれば、 v を引数としてその対応する値を呼び、その呼び出しの戻り値が結果として使われます。

`type (v)`

引数の型を文字列として返します。戻り値は以下のいずれかになります。

"nil" (という文字列、 nil 値ではなく)
"number"
"string"
"boolean"
"table"
"function"
"thread"
"userdata"

`_VERSION`

現在のインタプリタのバージョン文字列を保持しているグローバル変数です (関数ではありません)。この変数の現在の値は "Lua 5.3" です。

`xpcall (f, msgh [, arg1, ···])`

pcall に似ていますが、新しいメッセージハンドラに msgh を設定します。

6.2 – コルーチン操作

このライブラリはコルーチンを操作する関数から構成されます。このライブラリの関数はすべてテーブル coroutine の中に提供されます。コルーチンの一般的な説明は §2.6 を参照してください。

`coroutine.create (f)`

f を本体に持つ新しいコルーチンを作成します。 f は関数でなければなりません。その新しいコルーチンであるスレッド型のオブジェクトを返します。

`coroutine.isyieldable ()`

実行中のコルーチンがyield可能であれば真を返します。

実行中のコルーチンがメインスレッドでなく、yield可能でないCの関数の内部でなければ、そのコルーチンはyield可能です。

`coroutine.resume (co [, val1, ···])`

コルーチン co の実行を開始または続行します。最初にコルーチンをresumeしたとき、その本体の実行が開始されます。値 val1、··· は、その本体関数に引数として渡されます。そのコルーチンがyieldされていた場合は、それを再開します。値 val1、··· は、yieldからの戻り値として渡されます。

コルーチンをエラーなく実行できた場合は、 true に加え、 yield に渡されたあらゆる値 (コルーチンをyieldした場合) または本体関数から返されたあらゆる値 (コルーチンを終了した場合) を返します。エラーが発生した場合は false とエラーメッセージを返します。

`coroutine.running ()`

実行中のコルーチンとブーリアンを返します。このブーリアンは、そのコルーチンがメインスレッドであれば真です。

`coroutine.status (co)`

コルーチン co の状態を文字列として返します。

"running": コルーチンは実行中 (つまり呼び出し元のコルーチン) である。
"suspended": コルーチンは yield の呼び出しで中断されているか、まだ実行開始していない。
"normal": コルーチンはアクティブであるが、実行中ではない (つまり他のコルーチンを resume した)。
"dead": コルーチンは本体関数を終了したか、エラーで停止した。

`coroutine.wrap (f)`

f を本体に持つ新しいコルーチンを作成します。 f は関数でなければなりません。呼ばれるたびにそのコルーチンをresumeする関数を返します。この関数に渡したあらゆる引数は、 resume に追加の引数として渡したのと同様の動作をします。最初のブーリアンを除き、 resume から返されるものと同じ値を返します。エラーが発生した場合は、そのエラーを伝播します。

`coroutine.yield (···)`

呼び出し元のコルーチンの実行を中断します。 yield に渡したあらゆる引数は、 resume に追加の戻り値として渡されます。

6.3 – モジュール

パッケージライブラリはLuaのモジュールをロードするための基本的な機能を提供します。関数 require はグローバル環境に直接エクスポートされます。それ以外のものはすべてテーブル package の中にエクスポートされます。

`require (modname)`

指定されたモジュールをロードします。まず、 modname がすでにロード済みかどうかを確認するために、テーブル package.loaded が調べられます。もしロード済みであれば、 package.loaded[modname] に格納されている値が返されます。そうでなければ、そのモジュールのためにローダーの検索が試みられます。

ローダーを検索するにあたって、シーケンス package.searchers がガイドとして用いられます。このシーケンスを変更すると、モジュールの検索方法を変えることができます。以下の説明は package.searchers のデフォルトの設定に基づくものです。

まず package.preload[modname] が検索されます。この値が存在すれば、その値 (関数でなければなりません) がローダーになります。そうでなければ、 package.path に格納されているパスを使うLuaのローダーが検索されます。それでも見つからなければ、 package.cpath に格納されているパスを使うCのローダーが検索されます。それでも見つからなければ、オールインワンローダー (package.searchers を参照) が試みられます。

ローダーが見つかると、そのローダーに2個の引数、 modname と、そのローダーをどのように取得したかに依存する追加の値が渡されます。 (ローダーがファイル由来の場合、追加の引数はそのファイル名になります。) そのローダーがnilでない値を返すと、その返された値が package.loaded[modname] に代入されます。ローダーがnilでない値を返さず、 package.loaded[modname] に何の値も代入しなかった場合は、そのエントリに true が代入されます。いずれの場合も、 package.loaded[modname] の最終的な値が require から返されます。

モジュールのロード中または実行中に何らかのエラーが発生したか、そのモジュールのローダーを見つけることができなかった場合、 require はエラーを発生させます。

`package.config`

パッケージのコンパイル時設定を記述した文字列です。この文字列は以下の行の並びです。

1行目はディレクトリ区切り文字列です。デフォルトはWindowsでは '\' で、それ以外のすべてのシステムでは '/' です。
2行目はパス中のテンプレートを区切る文字です。デフォルトは ';' です。
3行目はテンプレート中の置換点を示す文字列です。デフォルトは '?' です。
4行目はWindowsのパス中の、実行可能ファイルのディレクトリに置換される文字列です。デフォルトは '!' です。
5行目は luaopen_ 関数の名前を作成するときに、その後のテキストをすべて無視する印です。デフォルトは '-' です。

`package.cpath`

Cのローダーを検索するために require で使われるパスです。

Cのパス package.cpath は、環境変数 LUA_CPATH_5_3 または環境変数 LUA_CPATH または luaconf.h で定義されているデフォルトのパスを使って、Luaのパス package.path が初期化されるのと同じ方法で初期化されます。

`package.loaded`

モジュールがすでにロード済みかどうかを制御するために require で使われるテーブルです。モジュール modname をrequireしたとき、 package.loaded[modname] が偽でなければ、 require は単にそこに格納されている値を返します。

この変数は実際のテーブルへの参照にすぎません。この変数に代入しても require で使われるテーブルは変わりません。

`package.loadlib (libname, funcname)`

Cのライブラリ libname をダイナミックリンクします。

funcname が "*" であれば、そのライブラリをリンクし、そのライブラリがエクスポートしているシンボルを他のダイナミックリンクライブラリから利用できるようにだけします。そうでなければ、そのライブラリ内の関数 funcname を検索し、その関数をCの関数として返します。そのため、 funcname は lua_CFunction のプロトタイプに従わなければなりません。 (lua_CFunction を参照)。

これは低水準の関数です。パッケージシステムやモジュールシステムを完全に迂回します。 require と異なり、パスを検索することもなく、拡張子を自動的に追加することもありません。 libname Cのライブラリの完全なファイル名でなければならず、必要であればパスや拡張子も含めなければなりません。 funcname はそのCのライブラリがエクスポートしている正確な名前でなければなりません (使用したCコンパイラやリンカに依存します)。

この機能は標準規格のCではサポートされていません。そのため一部のプラットフォーム (Windows、Linux、Mac OS X、Solaris、BSD、および dlfcn 標準をサポートしている各種Unixシステム) でのみ利用可能です。

`package.path`

Luaのローダーを検索するために require で使われるパスです。

この変数はスタートアップ時に環境変数 LUA_PATH_5_3 または環境変数 LUA_PATH の値、またはそれらの環境変数が定義されていない場合は luaconf.h に定義されているデフォルトのパスに初期化されます。環境変数の値の中の ";;" は (もしあれば) デフォルトのパスに置換されます。

`package.preload`

特定のモジュール用のローダーを格納するテーブルです (require を参照)。

この変数は実際のテーブルへの参照にすぎません。この変数に代入しても require で使われるテーブルは変わりません。

`package.searchers`

モジュールのロード方法を制御するために require で使われるテーブルです。

このテーブルの各エントリは検索関数です。モジュールを検索するとき、モジュール名 (require に渡した引数) を唯一の引数としてこれらの各検索関数が昇順で呼ばれます。この関数は、別の関数 (モジュールローダー) と、そのローダーに渡す追加の値を返すことができます。あるいは、モジュールが見つからなかった理由を表す文字列 (あるいは何も言うべきことがなければ nil) を返すこともできます。

このテーブルは4個の検索関数で初期化されます。

1番目の検索関数は単純に package.preload テーブルからローダーを検索します。

2番目の検索関数は package.path に格納されているパスを使ってLuaのライブラリとしてローダーを検索します。検索は関数 package.searchpath で説明されているように行われます。

3番目の検索関数は変数 package.cpath で指定されたパスを使ってCのライブラリとしてローダーを検索します。これも同様に、検索は関数 package.searchpath で説明されているように行われます。例えばCのパスが以下の文字列である場合、

     "./?.so;./?.dll;/usr/local/?/init.so"

モジュール foo の検索は、ファイル ./foo.so、 ./foo.dll、 /usr/local/foo/init.so を、この順番で、開けるかどうか試します。 Cのライブラリが見つかったなら、ダイナミックリンクの機能を使ってそのライブラリをリンクします。次に、ローダーとして使えるCの関数をそのライブラリ内から検索します。 Cの関数の名前は、文字列 "luaopen_" と、モジュール名のドットをアンダースコアで置換した文字列を連結したものです。さらにモジュール名にハイフンが含まれている場合、最初のハイフンとその後の接尾辞は削除されます。例えばモジュール名が a.b.c-v2.1 の場合、関数名は luaopen_a_b_c になります。

4番目の検索関数はオールインワンローダーを試みます。指定されたモジュールのルート名に対してCのパスからライブラリを検索します。例えば a.b.c をrequireすると、 a というCのライブラリが検索されます。見つかれば、そのサブモジュールに対するオープン関数がライブラリ内から検索されます。先程の例では luaopen_a_b_c になります。この機能により、複数のCのサブモジュールを、各サブモジュールの元々のオープン関数を保ったまま、ひとつのライブラリにパッケージ化できます。

1番目 (preload) 以外のすべての検索関数は、 package.searchpath から返されるのと同様に、モジュールが見つかったファイル名を追加の値として返します。 1番目の検索関数は追加の値を返しません。

`package.searchpath (name, path [, sep [, rep]])`

指定された path から指定された name を検索します。

パスは一連のテンプレートをセミコロンで区切った文字列です。各テンプレートに対して、テンプレート中の疑問符 (もしあれば) が name に置換され、 sep (デフォルトはドット) がすべて rep (デフォルトではシステムのディレクトリ区切り文字) に置換され、結果のファイル名が開けるかどうか試みられます。

例えばパスが以下の文字列の場合、

     "./?.lua;./?.lc;/usr/local/?/init.lua"

名前 foo.a を検索すると、ファイル ./foo/a.lua、 ./foo/a.lc、 /usr/local/foo/a/init.lua が、この順番で、開けるかどうか試みられます。

読み込みモードで開くことができた最初のファイル名を返します。開けるファイルが無かった場合は、 nil とエラーメッセージを返します。 (このエラーメッセージには開けるかどうか試みられたすべてのファイル名が記載されます。)

6.4 – 文字列操作

このライブラリは部分文字列の検索、部分文字列の抽出、パターンマッチングなど、文字列操作のための汎用的な機能を提供しています。 Luaでは文字列中のインデックスを指定するとき、最初の文字が1の位置です (Cのように0ではありません)。インデックスには負の値を指定することもでき、文字列の終わりから逆方向のインデックスとして解釈されます。つまり最後の文字は-1の位置で、以下同様です。

文字列ライブラリの関数はすべてテーブル string の中に提供されます。また文字列に対するメタテーブルも設定されます。このメタテーブルは __index フィールドを持ち、 string テーブルを指します。そのため文字列関数をオブジェクト指向スタイルで使うこともできます。例えば string.byte(s,i) は s:byte(i) と書くこともできます。

文字列ライブラリでは1バイト文字のエンコーディングが想定されています。

`string.byte (s [, i [, j]])`

文字 s[i]、s[i+1]、...、s[j] の内部的な文字コードの数値を返します。 i のデフォルト値は1で、 j のデフォルト値は i です。これらのインデックスは関数 string.sub と同じルールに従って修正されます。

文字コードの数値は異なるプラットフォームへの移植性が保証されていません。

`string.char (···)`

ゼロ個以上の整数を受け取り、引数の個数と同じ長さの文字列を返します。この文字列中の各文字は、対応する引数に等しい内部的な文字コードの数値を持ちます。

文字コードの数値は異なるプラットフォームへの移植性が保証されていません。

`string.dump (function [, strip])`

指定された関数のバイナリ表現 (バイナリチャンク) を含む文字列を返します。後にこの文字列を load に渡すと、その関数のコピーを作成できます (ただし上位値は新しいものになります)。 strip が真の値の場合は、空間を節約するため、その関数に関するすべてのデバッグ情報が含まれない場合があります。

上位値を持つ関数は、上位値の個数だけが保存されます。 (再) ロードされたとき、それらの上位値には新しいインスタンスが作成され、 nil に初期化されます。 (デバッグライブラリを使用し、関数の上位値を必要に応じて自分で保存、再ロードすることはできます。)

`string.find (s, pattern [, init [, plain]])`

文字列 s から pattern (§6.4.1 を参照) の最初のマッチを検索します。マッチが見つかれば、その開始位置と終了位置を示す s のインデックスを返します。見つからなければ nil を返します。省略可能な第3引数 init は検索の開始位置を指定する数値です。デフォルト値は1で、負の値も指定できます。省略可能な第4引数 plain は、 true の値を指定するとパターンマッチの機能が無効化され、 pattern のどの文字も魔法扱いしない、ただの「部分文字列検索」処理になります。 plain を指定するときは init も指定しなければならないことに注意してください。

パターンにキャプチャがある場合は、マッチが成功すると、2つのインデックスの後にキャプチャした値も返されます。

`string.format (formatstring, ···)`

最初の引数 (文字列でなければなりません) で指定された記述に従い、可変長引数を書式化して返します。書式文字列はISO Cの関数 sprintf と同じルールに従います。ただしオプションおよび修飾子 *、 h、 L、 l、 n、 p はサポートされず、追加のオプション q があるという点が異なります。 q オプションは二重引用符で囲った文字列を書式化します。このとき、Luaインタプリタで安全に読み戻せることを保証するために、必要に応じてエスケープシーケンスが使われます。例えば以下の呼び出しは

     string.format('%q', 'a string with "quotes" and \n new line')

以下の文字列を生成します。

     "a string with \"quotes\" and \
      new line"

オプション A、 a、 E、 e、 f、 G、 g はすべて引数として数値を期待します。オプション c、 d、 i、 o、 u、 X、 x は整数を期待します。オプション q は文字列を期待します。オプション s はゼロを含まない文字列を期待します。引数が文字列でなければ tostring と同じルールに従って文字列に変換されます。

LuaをC99でないコンパイラでコンパイルした場合、オプション A および a (16進浮動小数点数) ではいかなる修飾子 (フラグ、幅、長さ) もサポートされません。

`string.gmatch (s, pattern)`

呼ばれるたびに文字列 s に対して pattern (§6.4.1 を参照) から次のキャプチャを返すようなイテレータ関数を返します。 pattern にキャプチャが指定されていなければ、呼ばれるたびにマッチ全体が返されます。

例えば以下のループは文字列 s 中のすべての単語を巡回し、それを各行に表示します。

     s = "hello world from Lua"
     for w in string.gmatch(s, "%a+") do
       print(w)
     end

次の例は指定された文字列中の 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])`

s 中のすべて (または指定されていれば最初の n 個) の pattern (§6.4.1 を参照) を repl で指定された置換文字列で置き換えた文字列を返します。 repl には文字列、テーブル、または関数を指定できます。また、2つめの値として出現したマッチの合計数も返します。 gsub という名前は Global SUBstitution から来ています。

repl が文字列の場合はその値が置換に使われます。文字 % はエスケープ文字として動作します。 repl 中の %d (ただし d は1から9) 形式の並びは、d番目のキャプチャした部分文字列の値を表します。並び %0 はマッチ全体を表し、並び %% は単一の % を表します。

repl がテーブルの場合は、各マッチに対し、1番目のキャプチャをキーとして使ってテーブルが検索されます。

repl が関数の場合は、マッチが出現するたびにその関数が呼ばれ、キャプチャした部分文字列が順番通りに引数として渡されます。

どの場合でも、パターンにキャプチャが無ければ、パターン全体が1個のキャプチャ内にあるかのように動作します。

テーブル検索や関数呼び出しの戻り値が文字列または数値であれば、それが置換文字列として使われます。そうでなく、 false または nil であれば、置換は行われません (つまり文字列中の元のマッチがそのまま保たれます)。

いくつか例を挙げます。

     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 load(s)()
         end)
     --> x="4+5 = 9"

     local t = {name="lua", version="5.3"}
     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
     --> x="lua-5.3.tar.gz"

`string.len (s)`

文字列を受け取り、その長さを返します。空文字列 "" の長さは0です。ゼロも数えられるので、 "a\000bc\000" の長さは5です。

`string.lower (s)`

文字列を受け取り、その文字列中の大文字をすべて小文字に変更した文字列を返します。それ以外の文字は変更されません。何が大文字であるかの定義は現在のロケールに依存します。

`string.match (s, pattern [, init])`

文字列 s 中の pattern (§6.4.1 を参照) の最初のマッチを検索します。見つかった場合は、そのパターンのキャプチャを返します。そうでなければ nil を返します。 pattern にキャプチャが無ければ、マッチ全体が返されます。省略可能な第3引数 init は検索の開始位置を指定する数値です。デフォルト値は1で、負の値も指定できます。

`string.pack (fmt, v1, v2, ···)`

書式文字列 fmt (§6.4.2 を参照) に従って、値 v1、v2、··· をバイナリ文字列にパックし、その文字列を返します。

`string.packsize (fmt)`

指定された書式で string.pack から返される文字列のサイズを返します。書式文字列には可変長のオプション 's' および 'z' を含めることはできません (§6.4.2 を参照)。

`string.rep (s, n [, sep])`

文字列 s を文字列 sep で区切って n 個連結した文字列を返します。 sep のデフォルト値は空文字列 (つまり区切り文字なし) です。 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 文字を返します。

負のインデックスを変換した後、 i が1より小さければ1に修正され、 j が文字列の長さより大きければその長さに修正されます。これらの修正の後、 i が j より大きければ空文字列が返されます。

`string.unpack (fmt, s [, pos])`

書式文字列 fmt (§6.4.2 を参照) に従って、文字列 s にパックされた値を返します (string.pack を参照)。省略可能な pos は s の読み込み開始位置を指定します (デフォルトは1です)。値を読み込んだ後、 s の最初の未読バイトのインデックスも返されます。

`string.upper (s)`

文字列を受け取り、その文字列中の小文字をすべて大文字に変更した文字列を返します。それ以外の文字は変更されません。何が小文字であるかの定義は現在のロケールに依存します。

6.4.1 – パターン

Luaのパターンは、パターンマッチ関数 string.find、 string.gmatch、 string.gsub、 string.match によってパターンとして解釈される正規文字列によって記述されます。この節ではこれらの文字列の構文と意味 (つまり何にマッチするのか) を説明します。

文字クラス

文字クラスは文字の集合を表すために使われます。文字クラスの記述では以下の組み合わせが使えます。

x: (ただしxは魔法の文字^$()%.[]*+-?のいずれでもない) 文字x自身を表します。
.: (ドット) すべての文字を表します。
%a: すべての英字を表します。
%c: すべての制御文字を表します。
%d: すべての数字を表します。
%g: 空白以外のすべての印刷可能文字を表します。
%l: すべての小文字を表します。
%p: すべての句読点文字を表します。
%s: すべての空白文字を表します。
%u: すべての大文字を表します。
%w: すべての英数字を表します。
%x: すべての16進数字を表します。
%x: (ただしxは英数以外の任意の文字) 文字xを表します。これは魔法の文字をエスケープする標準的な方法です。英数以外のあらゆる文字 (魔法でない文字も含むすべての句読点文字が含まれます) は、前に '%' を付けることでパターン中でそれ自身を表すことができます。
[set]: setの中のすべての文字の和集合であるクラスを表します。 '-' を使って範囲の終わりの文字を区切ることによって、その範囲の文字を指定することができます。範囲は昇順です。上で説明したすべてのクラス %x はsetの中でも部品として使うことができます。 setの中のそれ以外の文字はすべてそれ自身を表します。例えば [%w_] (または [_%w]) はすべての英数字にアンダースコアを加えたものを表し、 [0-7] は8進数字を表し、 [0-7%l%-] は8進数字に小文字と '-' 文字を加えたものを表します。
範囲とクラスの相互作用は定義されていません。そのため [%a-z] や [a-%%] といったパターンは無意味です。
[^set]: setの補集合を表します。 setは上で述べた通りに解釈されます。

ひとつの文字で表されているクラス (%a、%c など) はすべて、対応する大文字でそのクラスの補集合を表します。例えば %S は空白以外のすべての文字を表します。

英字、空白などの文字グループは現在のロケールに依存します。例えば、クラス [a-z] と %l は同等でない場合があります。

パターン項目

パターン項目は以下のいずれかです。

単一の文字クラス。そのクラス中の任意の1文字にマッチします。
単一の文字クラスに '*' が続いたもの。そのクラス中の文字の0回以上の繰り返しにマッチします。これらの繰り返し項目は必ず最も長いマッチ可能な並びにマッチします。
単一の文字クラスに '+' が続いたもの。そのクラス中の文字の1回以上の繰り返しにマッチします。これらの繰り返し項目は必ず最も長いマッチ可能な並びにマッチします。
単一の文字クラスに '-' が続いたもの。そのクラス中の文字の0回以上の繰り返しにマッチします。 '*' と異なり、これらの繰り返し項目は必ず最も短いマッチ可能な並びにマッチします。
単一の文字クラスに '?' が続いたもの。そのクラス中の文字の0回または1回の出現にマッチします。可能であれば常に1回の出現にマッチします。
%n (ただしnは1から9) この項目はn番目のキャプチャした文字列 (後述) と等しい部分文字列にマッチします。
%bxy (ただしxとyは2つの別々の文字) この項目は、xで始まりyで終わる、xとyの釣り合いが取れている文字列にマッチします。つまり、文字列を左から右に読み進み、xのときに+1、yのときに-1をカウントするとき、最初にカウントが0になったyが終わりのyになります。例えば、項目 %b() は括弧の釣り合いが取れている式にマッチします。
%f[set] (境界パターン) この項目は、次の文字がsetに属し、前の文字がsetに属しない、任意の位置の空文字列にマッチします。集合setは先程説明したように解釈されます。対象の先頭と末尾は文字 '\0' があるかのように処理されます。

パターン

パターンはパターン項目の並びです。パターンの先頭にキャレット '^' があれば、マッチが対象文字列の先頭に固定されます。パターンの最後に '$' があれば、マッチが対象文字列の最後に固定されます。それ以外の場所では、 '^' および '$' は特別な意味を持たず、それ自身を表します。

キャプチャ

パターンには括弧で囲ったサブパターンを含めることができます。これはキャプチャを表します。マッチが成功すると、対象文字列のうちキャプチャにマッチした部分の文字列が、後の使用のために保存されます (キャプチャされます)。キャプチャは、その左括弧によって番号付けされます。例えばパターン "(a*(.)%w(%s*))" の場合、 "a*(.)%w(%s*)" にマッチした部分の文字列が最初のキャプチャ (つまり番号1) として保存され、 "." にマッチした文字が番号2でキャプチャされ、 "%s*" にマッチした部分が番号3になります。

特別な場合として、空のキャプチャ () を使うと現在の文字列位置 (数値) をキャプチャします。例えば、パターン "()aa()" を文字列 "flaaap" に適用すると、2つのキャプチャ3と5が得られます。

6.4.2 – packおよびunpackの書式文字列

string.pack、 string.packsize、 string.unpack の第1引数は書式文字列で、作成する (または読み込む) 構造体のレイアウトを記述します。

書式文字列は変換オプションの並びです。変換オプションは以下のものが指定できます。

<: リトルエンディアンに設定します。
>: ビッグエンディアンに設定します。
=: ネイティブエンディアンに設定します。
![n]: アラインメントを n に設定します (デフォルトはネイティブアラインメント)。
b: 符号付きバイト (char)。
B: 符号無しバイト (char)。
h: 符号付きshort (ネイティブサイズ)。
H: 符号無しshort (ネイティブサイズ)。
l: 符号付きlong (ネイティブサイズ)。
L: 符号無しlong (ネイティブサイズ)。
j: lua_Integer。
J: lua_Unsigned。
T: size_t (ネイティブサイズ)。
i[n]: nバイトの符号付きint (デフォルトはネイティブサイズ)。
I[n]: nバイトの符号無しint (デフォルトはネイティブサイズ)。
f: float (ネイティブサイズ)。
d: double (ネイティブサイズ)。
n: lua_Number。
cn: nバイトの固定長文字列。
z: ゼロ終端文字列。
s[n]: 長さを前置した文字列。長さはnバイトの符号無し整数 (デフォルトはsize_t) として符号化されます。
x: 1バイトのパディング。
Xop: オプションopに従ってアラインメントした空項目 (op はアラインメント以外は無視されます)。
' ': (空白) 無視されます。

("[n]" は省略可能な整数値を表しています。) パディング、空白、設定 (オプション "xX <=>!") を除き、各オプションに引数がひとつずつ (string.pack の場合) または結果がひとつずつ (string.unpack の場合) 対応します。

オプション "!n"、"sn"、"in"、"In" において、 n は1から16までの任意の整数を指定できます。整数オプションはすべてオーバーフローのチェックが行われます。 string.pack では指定した値が指定したサイズに収まるかチェックされ、 string.unpack では読み込んだ値がLuaの整数に収まるかチェックされます。

書式文字列はいずれも先頭に "!1=" が付いているかのように解釈されます。つまり最大アラインメントは1 (アラインメントなし) で、ネイティブエンディアンです。

アラインメントは以下のように動作します。各オプションに対して、そのオプションのサイズと最大アラインメントの間で最小の倍数のオフセットからデータが開始されるまでの間に、パディングが追加されます。この最小は2の乗数でなければなりません。オプション "c" および "z" はアラインメントされません。オプション "s" は最初の整数のアラインメントに従います。

すべてのパディングは string.pack によってゼロで埋められます (そして string.unpack によって無視されます。)

6.5 – UTF-8サポート

このライブラリはUTF-8エンコーディングの基本的なサポートを提供します。このライブラリの関数はすべてテーブル utf8 の中に提供されます。このライブラリにはエンコーディング処理以外のUnicodeに対するサポートはありません。文字の意味が必要な操作、例えば文字の分類などは対象外です。

特に明記されない限り、引数としてバイト位置を受け取る関数はすべて、その位置はバイトシーケンスの開始位置であるか、対象文字列の長さプラス1であるとみなされます。文字列ライブラリと同様に、負のインデックスは文字列の終わりから数えられます。

`utf8.char (···)`

ゼロ個以上の整数を受け取り、それぞれを対応するUTF-8バイトシーケンスに変換し、それらのシーケンスをすべて連結した文字列を返します。

`utf8.charpattern`

対象が有効なUTF-8文字列であると仮定したときの、ちょうどひとつのUTF-8バイトシーケンスにマッチするパターン (§6.4.1 を参照) "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" です (文字列です。関数ではありません)。

`utf8.codes (s)`

以下の構文

     for p, c in utf8.codes(s) do body end

で文字列 s 中のすべての文字を巡回できるような値を返します。ただし p は位置 (バイト単位) で、 c は各文字のコードポイントです。無効なバイトシーケンスに遭遇した場合はエラーが発生します。

`utf8.codepoint (s [, i [, j]])`

バイト位置 i と j の間 (両端を含む) で始まる s 中のすべての文字のコードポイントを (整数として) 返します。 i のデフォルト値は1、 j のデフォルト値は i です。無効なバイトシーケンスに遭遇した場合はエラーが発生します。

`utf8.len (s [, i [, j]])`

バイト位置 i と j の間 (両端を含む) で始まる文字列 s 中のUTF-8文字の数を返します。 i のデフォルト値は1、 j のデフォルト値は-1です。無効なバイトシーケンスが見つかった場合は、偽の値に加えて、最初の無効なバイトの位置を返します。

`utf8.offset (s, n [, i])`

s の n 文字目 (位置 i から数えて) のエンコーディングが始まる位置 (バイト単位) を返します。 n に負の値を指定すると、位置 i より前の文字になります。 i のデフォルト値は、 n が負でなければ1で、負の場合は #s + 1 です。例えば、 utf8.offset(s, -n) はその文字列の終わりから n 文字目のオフセットになります。対象中に指定された文字が無いか、終端の直後の場合は、 nil を返します。

特殊な場合として、 n が0のときは、 s の i 番目のバイトを含む文字のエンコーディング開始位置を返します。

s は有効なUTF-8文字列であると仮定しています。

6.6 – テーブル操作

このライブラリはテーブル操作のための汎用的な機能を提供します。このライブラリの関数はすべてテーブル table の中に提供されます。

操作がテーブルの長さを必要とするときは、テーブルは正規のシーケンスであるか、 __len メタメソッドを持たなければなりません (§3.4.7 を参照)。いずれの関数においても、指定されたテーブル中の数値でないキーは無視されます。

`table.concat (list [, sep [, i [, j]]])`

すべての要素が文字列か数値であるリストを受け取り、文字列 list[i]..sep..list[i+1] ··· sep..list[j] を返します。 sep のデフォルト値は空文字列、 i のデフォルト値は1、 j のデフォルト値は #list です。 i が j より大きい場合は空文字列を返します。

`table.insert (list, [pos,] value)`

要素 list[pos]、list[pos+1]、···、list[#list] を上に移動し、 list の位置 pos に要素 value を挿入します。 pos のデフォルト値は #list+1 なので、 table.insert(t,x) はリスト t の最後に x を挿入します。

`table.move (a1, f, e, t [,a2])`

テーブル a1 の要素をテーブル a2 に移動します。多重代入 a2[t],··· = a1[f],···,a1[e] と同等です。 a2 のデフォルト値は a1 です。移動先の範囲と移動元の範囲は重なっていても構いません。移動する要素の数はLuaの整数に収まらなければなりません。

`table.pack (···)`

すべての引数をキー 1、2、··· に格納し、その引数の合計個数をフィールド "n" に格納した、新しいテーブルを返します。結果のテーブルはシーケンスでない場合があります。

`table.remove (list [, pos])`

list から位置 pos の要素を削除し、その削除した要素の値を返します。 pos が1と #list の間の整数であれば、要素 list[pos+1]、list[pos+2]、···、list[#list] は下へ移動し、要素 list[#list] は消去されます。インデックス pos には #list + 1 も指定でき、また #list が0のときには0も指定できます。これらの場合は要素 list[pos] が消去されます。

pos のデフォルト値は #list なので、呼び出し table.remove(l) はリスト l の最後の要素を削除します。

`table.sort (list [, comp])`

list[1] から list[#list] のリスト要素を、指定した順番にその場でソートします。 comp を指定する場合、それは関数でなければなりません。この関数は、リストの要素を2個受け取り、1番目の要素が2番目の要素より前に来て欲しい場合に真を返さなければなりません (つまりソート後に not comp(list[i+1],list[i]) が真になるようにします)。 comp を指定しない場合は、標準のLuaの演算子 < が代わりに使われます。

ソートのアルゴリズムは安定ではありません。つまり、指定された順序において等しいとみなされる要素は、ソートによってその相対位置が変化する場合があります。

`table.unpack (list [, i [, j]])`

指定されたリストの要素を返します。以下と同等です。

     return list[i], list[i+1], ···, list[j]

デフォルトでは i は1で、 j は #list です。

6.7 – 数学関数

このライブラリは基本的な数学関数を提供します。このライブラリの関数と定数はすべてテーブル math の中に提供されます。 "integer/float" という注釈が付いている関数は、整数の引数には整数の結果を、浮動小数点数の引数 (または両方が混在した引数) には浮動小数点数の結果を返します。丸め関数 (math.ceil、 math.floor、 math.modf) は、結果が整数の範囲に収まる場合は整数を返し、そうでなければ浮動小数点数を返します。

`math.abs (x)`

x の絶対値を返します。 (integer/float)

`math.acos (x)`

x の逆余弦を (ラジアンで) 返します。

`math.asin (x)`

x の逆正弦を (ラジアンで) 返します。

`math.atan (y [, x])`

y/x の逆正接を (ラジアンで) 返します。ただし結果の象限を決めるために両方の引数の符号が使われます。 (x がゼロの場合も正確に処理されます。)

x のデフォルト値は1です。そのため呼び出し math.atan(y) は y の逆正接を返します。

`math.ceil (x)`

x より大きいまたは等しい最小の整数値を返します。

`math.cos (x)`

x (ラジアン) の余弦を返します。

`math.deg (x)`

角度 x をラジアンから度に変換します。

`math.exp (x)`

e^xの値を返します (ただし e は自然対数の底です)。

`math.floor (x)`

x より小さいまたは等しい最大の整数を返します。

`math.fmod (x, y)`

x を y で割った商をゼロに向かって丸めた余りを返します。 (integer/float)

`math.huge`

他のいかなる数値よりも大きな浮動小数点数の値 HUGE_VAL です。

`math.log (x [, base])`

指定されたbaseを底とする x の対数を返します。 base のデフォルト値はeです (つまり x の自然対数を返します)。

`math.max (x, ···)`

Luaの演算子 < に従って最大の値を持つ引数を返します。 (integer/float)

`math.maxinteger`

最も大きな整数です。

`math.min (x, ···)`

Luaの演算子 < に従って最小の値を持つ引数を返します。 (integer/float)

`math.mininteger`

最も小さな整数です。

`math.modf (x)`

x の整数部と x の小数部を返します。 2番目の戻り値は常に浮動小数点数です。

`math.pi`

円周率πの値です。

`math.rad (x)`

角度 x を度からラジアンに変換します。

`math.random ([m [, n]])`

引数を指定せずに呼ぶと、範囲 [0,1) に一様に分布する浮動小数点数の擬似乱数を返します。 2つの整数 m と n を指定して呼ぶと、範囲 [m, n] に一様に分布する整数の擬似乱数を返します。 (m-n の値を負にすることはできず、またLuaの整数に収まらなければなりません。) 呼び出し math.random(n) は math.random(1,n) と同等です。

この関数は基となるCが提供している擬似乱数生成関数へのインタフェースです。統計的な性質については保証されていません。

`math.randomseed (x)`

x を擬似乱数生成器の「種」として設定します。同じ種を指定すると同じ数列が生成されます。

`math.sin (x)`

x (ラジアン) の正弦を返します。

`math.sqrt (x)`

x の平方根を返します。 (この値は式 x^0.5 を使っても計算できます。)

`math.tan (x)`

x (ラジアン) の正接を返します。

`math.tointeger (x)`

値 x が整数に変換可能であれば、その整数を返します。そうでなければ nil を返します。

`math.type (x)`

x が整数であれば "integer" を返し、浮動小数点数であれば "float" を返し、 x が数値でなければ nil を返します。

`math.ult (m, n)`

符号無しとして比較したとき m が n より下であれば真を返します。

6.8 – 入出力機能

入出力ライブラリは2種類のスタイルのファイル操作を提供します。ひとつめは暗黙のファイルハンドルを使うもので、デフォルト入力ファイルとデフォルト出力ファイルを設定し、すべての入出力操作をこのデフォルトファイルに対して行います。ふたつめのスタイルは明示的なファイルハンドルを使うものです。

暗黙のファイルハンドルを使うときは、すべての操作がテーブル io に提供されます。明示的なファイルハンドルを使うときは、 io.open からファイルハンドルが返され、すべての操作はそのファイルハンドルのメソッドとして提供されます。

テーブル io にはCの通常の意味を持つ3つの定義済みファイルハンドル io.stdin、 io.stdout、 io.stderr も提供されています。入出力ライブラリがこれらのファイルを閉じることはありません。

特に明記されない限り、すべての入出力関数は失敗時に nil (に加えて2番目の戻り値としてエラーメッセージと、3番目の戻り値としてシステム依存のエラーコード) を返し、成功時は nil でない値を返します。エラー発生時のエラーメッセージとエラーコードの計算はCのグローバル変数 errno に依存しているため、POSIX以外のシステムではスレッドセーフでない場合があります。

`io.close ([file])`

file:close() と同等です。 file を指定しない場合はデフォルト出力ファイルを閉じます。

`io.flush ()`

io.output():flush() と同等です。

`io.input ([file])`

ファイル名を指定して呼ぶと、その名前のファイルを (テキストモードで) 開き、そのハンドルをデフォルト入力ファイルとして設定します。ファイルハンドルを指定して呼ぶと、単にそのファイルハンドルをデフォルト入力ファイルとして設定します。引数を指定せずに呼ぶと、現在のデフォルト入力ファイルを返します。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

`io.lines ([filename ···])`

指定されたファイル名を読み込みモードで開き、その開いたファイルに対して file:lines(···) のように動作するイテレータ関数を返します。イテレータ関数がファイルの終端を検出すると、 (ループを終えるため) 何の値も返さず、ファイルを自動的に閉じます。

呼び出し io.lines() (ファイル名を指定しない場合) は io.input():lines("*l") と同等です。つまりデフォルト入力ファイルの各行を巡回します。この場合、ループの終了時にファイルを閉じません。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

`io.open (filename [, mode])`

文字列 mode で指定されたモードでファイルを開きます。新しいファイルハンドルを返します。エラーの場合は nil とエラーメッセージを返します。

mode 文字列には以下のいずれかを指定できます。

"r": 読み込みモード (デフォルト)。
"w": 書き込みモード。
"a": 追記モード。
"r+: 更新モード。以前のデータは維持されます。
"w+": 更新モード。以前のデータは消去されます。
"a+": 追記モード。以前のデータは維持されます。ファイルの終端にのみ書き込むことができます。

また mode 文字列の最後に 'b' を付けることもできます。これはシステムによってはバイナリモードでファイルを開く場合に必要です。

`io.output ([file])`

io.input と同様ですが、デフォルト出力ファイルに対して動作します。

`io.popen (prog [, mode])`

この関数はシステム依存であり、プラットフォームによっては利用できません。

別のプロセスでプログラム prog を開始し、そのプログラムからデータを読み込む (mode が "r" の場合、デフォルト) またはそのプログラムにデータを書き込む (mode が "w" の場合) ために使えるファイルハンドルを返します。

`io.read (···)`

io.input():read(···) と同等です。

`io.tmpfile ()`

テンポラリファイルのハンドルを返します。このファイルは更新モードで開かれ、プログラム終了時に自動的に削除されます。

`io.type (obj)`

obj が有効なファイルハンドルであるかどうかを確認します。 obj が開かれているファイルハンドルであれば文字列 "file"、 obj が閉じられたファイルハンドルであれば "closed file"、 obj がファイルハンドルでなければ nil を返します。

`io.write (···)`

io.output():write(···) と同等です。

`file:close ()`

file を閉じます。ハンドルがガベージコレクタに回収されればファイルは自動的に閉じられますが、そうなるまでの時間は予測できないことに注意してください。

io.popen で作成されたファイルハンドルを閉じるとき、 file:close は os.execute が返すのと同じ値を返します。

`file:flush ()`

file に書き込まれたデータを保存します。

`file:lines (···)`

呼ばれるたびに指定された書式に従ってファイルを読み込むイテレータ関数を返します。書式が指定されない場合はデフォルトとして "l" が使われます。例えば以下の構文は

     for c in file:lines(1) do body end

そのファイルの現在の位置から始まるすべての文字を巡回します。 io.lines と異なり、この関数はループ終了時にファイルを閉じません。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

`file:read (···)`

指定された書式に従ってファイル file を読み込みます。書式は読み込む内容を指定します。各書式に対して、読み込んだ内容の文字列または数値を返します。指定された書式でデータを読めなかった場合は nil を返します。 (後者の場合、残りの書式に対する読み込みは実行されません。) 書式を指定せずに読んだ場合はデフォルトの書式 (次の行を読み込む) が使用されます (下記参照)。

以下の書式が利用可能です。

"n": 数値を読み込み、それをLuaの字句規約に従って浮動小数点数または整数として返します。 (数値の前に空白や符号があっても構いません。) この書式は必ず、数値として有効な部分を可能な限り長く読み込みます。それが有効な数値を成していなければ (空文字、"0x"、"3.4e-" など)、それは読み捨てられ、 nil を返します。
"a": 現在の位置から始めてファイル全体を読み込みます。ファイルの終端では空文字列を返します。
"l": 次の行を読み込みますが、行末は読み飛ばします。ファイルの終端では nil を返します。これはデフォルトの書式です。
"L": 行末文字 (もしあれば) を維持したまま次の行を読み込みます。ファイルの終端では nil を返します。
数値: 指定した数値のバイト数 (最大) の文字列を読み込みます。数値がゼロの場合は、何も読み込まず空文字列を返します。いずれの場合もファイルの終端では nil を返します。

書式 "l" および "L" はテキストファイルに対してのみ使うべきです。

`file:seek ([whence [, offset]])`

ファイルの位置を設定および取得します。ファイルの位置はファイルの先頭から測られ、 offset で指定された位置に以下に示す文字列 whence で指定された基準点を加えた位置に設定されます。

"set": 基準は0 (ファイルの先頭)
"cur": 基準は現在位置
"end": 基準はファイルの終端

成功した場合はファイルの先頭からバイト単位で測った最終的なファイルの位置を返します。失敗した場合は nil とエラーを説明する文字列を返します。

whence のデフォルト値は "cur" で、 offset のデフォルト値は0です。例えば、呼び出し file:seek() は現在のファイルの位置を変更せずに返します。呼び出し file:seek("set") は位置をファイルの先頭に設定します (そして0を返します)。また、呼び出し file:seek("end") は位置をファイルの終端に設定し、そのサイズを返します。

`file:setvbuf (mode [, size])`

出力ファイルのバッファリングモードを設定します。以下の3つのモードが利用可能です。

"no": バッファリングなし。いかなる出力操作の結果も直ちに現れます。
"full": 完全バッファリング。出力操作は、バッファが満杯になるか、そのファイルを明示的に flush したときだけ行われます (io.flush を参照)。
"line": 行バッファリング。出力は、改行が出力されるか、何らかのスペシャルファイル (端末デバイスなど) から読み取りを行うまでバッファリングされます。

最後の2つの場合、 size はバッファのサイズ (バイト単位) を指定します。デフォルトは適当なサイズです。

`file:write (···)`

各引数の値を file に出力します。引数は文字列か数値でなければなりません。

成功した場合は file を返します。そうでない場合は nil とエラーを説明する文字列を返します。

6.9 – OS機能

このライブラリはテーブル os を通して実装されています。

`os.clock ()`

プログラムが使用したCPU時間のおよその量を秒単位で返します。

`os.date ([format [, time]])`

指定された文字列 format に従って書式化された日付と時刻を含む文字列またはテーブルを返します。

time 引数を指定した場合はその時刻が書式化されます (この値の説明は os.time 関数を参照)。そうでなければ現在時刻が書式化されます。

format が '!' で始まる場合、日付は協定世界時で書式化されます。このオプション文字の後、 format が文字列 "*t" であれば、以下のフィールドを持つテーブルを返します。

year (4桁)
month (1–12)
day (1–31)
hour (0–23)
min (0–59)
sec (0–61)
wday (曜日、日曜日が1)
yday (通日)
isdst (夏時間フラグ、ブーリアン)

夏時間の情報が利用できない場合、最後のフィールドは存在しません。

format が "*t" でなければ、ISO Cの関数 strftime と同じルールに従って書式化した日付を文字列として返します。

引数を指定せずに呼ぶと、ホストシステムと現在のロケールに依存した適当な日付時刻の表現を返します (つまり os.date() は os.date("%c") と同等です)。

この関数はCの関数 gmtime およびCの関数 localtime に依存しているため、POSIX以外のシステムではスレッドセーフでない場合があります。

`os.difftime (t2, t1)`

時刻 t1 から時刻 t2 までの差を秒単位で返します (ただし時刻の値は os.time から返された値です)。 POSIX、Windows、その他いくつかのシステムでは、この値は正確に t2-t1 です。

`os.execute ([command])`

この関数はISO Cの関数 system と同等です。 OSのシェルによって実行される command を渡します。最初の戻り値は、コマンドが正常終了した場合は true、そうでなければ nil です。この最初の戻り値の後、以下のような文字列と数値が返されます。

"exit": コマンドは正常に終了しました。後の数値はコマンドの終了ステータスです。
"signal": コマンドはシグナルによって終了しました。後の数値はコマンドが終了した原因のシグナルです。

command を指定せずに呼ぶと、シェルが利用可能であれば真を返します。

`os.exit ([code [, close]])`

ISO Cの関数 exit を呼んでホストプログラムを終了させます。 code が true の場合、返されるステータスは EXIT_SUCCESS です。 code が false の場合、返されるステータスは EXIT_FAILURE です。 code が数値の場合、返されるステータスはその数値です。 code のデフォルト値は true です。

省略可能な第2引数 close が真であれば、終了前にLuaのステートが閉じられます。

`os.getenv (varname)`

プロセスの環境変数 varname の値を返します。その変数が定義されていなければ nil を返します。

`os.remove (filename)`

指定した名前のファイル (または空のディレクトリ (POSIXシステムの場合)) を削除します。失敗した場合は nil に加え、エラーを説明する文字列とエラーコードが返されます。

`os.rename (oldname, newname)`

oldname という名前のファイルまたはディレクトリを newname にリネームします。失敗した場合は nil に加え、エラーを説明する文字列とエラーコードが返されます。

`os.setlocale (locale [, category])`

プログラムの現在のロケールを設定します。 locale はロケールを指定するシステム依存の文字列です。 category は変更するカテゴリを指定する省略可能な文字列で、以下のいずれかです。

"all"
"collate"
"ctype"
"monetary"
"numeric"
"time"

デフォルトのカテゴリは "all" です。この関数は新しいロケールの名前を返します。要求に沿えない場合は nil を返します。

locale が空文字列の場合、現在のロケールは実装依存のネイティブなロケールに設定されます。 locale が文字列 "C" の場合、現在のロケールは標準規格のCロケールに設定されます。

最初の引数に nil を指定して呼ぶと、指定したカテゴリに対する現在のロケールの名前を返します。

この関数はCの関数 setlocale に依存しているため、スレッドセーフでない場合があります。

`os.time ([table])`

引数を指定せずに呼ぶと現在時刻を返します。そうでなければ、指定されたテーブルで表されたローカル日時に対応する時刻の値を返します。このテーブルには以下のフィールドが必須です。

year
month
day

以下のフィールドは省略可能です。

hour (デフォルトは 12)
min (デフォルトは 0)
sec (デフォルトは 0)
isdst (デフォルトは nil)

それ以外のフィールドは無視されます。これらのフィールドの説明は os.date 関数を参照してください。

これらのフィールドの値は有効な範囲内である必要はありません。例えば sec が-10であれば、それ以外のフィールドで指定された時刻から-10秒を表します。 hour が1000であれば、それ以外のフィールドで指定された時刻から+1000時間を表します。

戻り値はシステム依存の意味を持つ数値です。 POSIX、Windows、その他いくつかのシステムでは、この数値は特定の開始点 (「エポック」) からの秒数です。それ以外のシステムでは、その意味は規定されておらず、 os.date および os.difftime への引数としてのみ使うことができます。

`os.tmpname ()`

テンポラリファイルとして使うことのできるファイル名を持った文字列を返します。このファイルは使用前に明示的に開かなければならず、必要なくなったときには明示的に削除しなければなりません。

POSIXシステムでは、セキュリティリスクを回避するため、その名前のファイルが作成されます。 (名前取得とファイル作成の間に他の誰かが間違ったパーミッションでファイルを作成する可能性があるためです。) その場合でもやはり使用前にはそのファイルを開く必要があり、 (結局使わなかったとしても) そのファイルを削除する必要があります。

可能であれば io.tmpfile を使う方がよいかもしれません。こちらはプログラム終了時に自動的にファイルが削除されます。

6.10 – デバッグライブラリ

このライブラリはデバッグインタフェース (§4.9) の機能をLuaのプログラムに提供します。このライブラリを使うときは気を付けてください。これらの関数の中には、Luaのコードに関する基本的な想定 (関数ローカルな変数は外側からアクセスできない、ユーザーデータのメタテーブルはLuaのコードから変更できない、Luaのプログラムはクラッシュしない、など) を破るものがあり、安全なはずのコードを破壊する可能性があります。また、このライブラリの関数の中には性能的の良くないものもあります。

このライブラリの関数はすべて debug テーブルの中に提供されます。スレッドに対して動作する関数はすべて、省略可能な最初の引数として操作対象のスレッドを取ります。デフォルトは常に現在のスレッドです。

`debug.debug ()`

ユーザーとの対話モードに入ります。対話モードではユーザーが入力した文字列が実行されます。単純なコマンドや様々なデバッグ機能を使うことで、ユーザーがグローバル変数やローカル変数を調査したり、その値を変更したり、式を評価したりできます。単語 cont だけを含む行を入力するとこの関数を終了し、呼び出し元の実行を続けます。

debug.debug に対するコマンドは、どの関数の内部にも字句的にネストしていないため、ローカル変数に直接アクセスすることはできないことに注意してください。

`debug.gethook ([thread])`

スレッドの現在のフック設定を3つの値、現在のフック関数、現在のフックマスク、現在のフックカウントとして返します (debug.sethook 関数で設定するものと同様です)。

`debug.getinfo ([thread,] f [, what])`

関数に関する情報をテーブルに格納して返します。関数は直接指定するか、 f の値として数値を指定できます。数値の場合は、指定されたスレッドのコールスタックのレベル f で実行中の関数を表します。レベル0は現在の関数 (getinfo 自身)、レベル1は getinfo の呼び出し元の関数 (スタックに残らない末尾呼び出しは除きます)、以下同様です。 f がアクティブな関数の数よりも大きい場合は nil を返します。

戻り値のテーブルには、埋めるフィールドを表す文字列 what に従って、 lua_getinfo が返すフィールドがすべて含まれる可能性があります。 what のデフォルト値は、有効な行番号のテーブル以外の利用可能なすべての情報を取得します。オプション 'f' を指定すると、 func という名前のフィールドにその関数自身が追加されます。オプション 'L' を指定すると、 activelines という名前のフィールドに有効な行番号のテーブルが追加されます。

例えば、式 debug.getinfo(1,"n").name は現在の関数の名前 (もし適当な名前が見つかれば) を返します。式 debug.getinfo(print) は print 関数に関する利用可能なすべての情報を持ったテーブルを返します。

`debug.getlocal ([thread,] f, local)`

スタックのレベル f の関数のインデックス local のローカル変数の名前と値を返します。明示的なローカル変数だけでなく引数や一時変数などもアクセスできます。

最初の引数またはローカル変数はインデックス1で、以下同様です。その関数の現在のスコープで有効な変数のみが数えられ、コード中で宣言された順番に従って番号付けられます。負のインデックスは可変長引数を参照します。 -1は最初の可変長引数です。指定されたインデックスの変数が存在しなければ nil を返します。範囲外のレベルが指定された場合はエラーが発生します。 (レベルが有効かどうかを確認するには debug.getinfo を呼びます。)

'(' (開き括弧) で始まる変数名は名前のわからない変数を表します。ループ制御変数のような内部変数やデバッグ情報が保存されていないチャンクの変数などです。

引数 f には関数も指定できます。この場合は関数の引数の名前のみが返されます。

`debug.getmetatable (value)`

指定された value のメタテーブルを返します。メタテーブルがなければ nil を返します。

`debug.getregistry ()`

レジストリテーブル (§4.5 を参照) を返します。

`debug.getupvalue (f, up)`

関数 f のインデックス up の上位値の名前と値を返します。指定したインデックスの上位値が存在しなければ nil を返します。

'(' (開き括弧) で始まる変数名は名前のわからない変数を表します。デバッグ情報の保存されていないチャンクの変数などです。

`debug.getuservalue (u)`

u に関連付けられているLuaの値を返します。 u がユーザーデータでなければ nil を返します。

`debug.sethook ([thread,] hook, mask [, count])`

指定された関数をフックとして設定します。文字列 mask および数値 count は、いつフックが呼ばれるかを指定します。文字列maskは以下の文字の任意の組み合わせを指定できます。

'c': 関数が呼ばれるたびにフックが呼ばれます。
'r': 関数から戻るたびにフックが呼ばれます。
'l': コードの新しい行に入るたびにフックが呼ばれます。

さらに、 count がゼロでなければ、 count 個の命令を実行するたびにフックが呼ばれます。

引数を指定せずに呼ぶとフックは無効化されます。

フックが呼ばれたとき、最初の引数は呼び出しの原因となったイベントを表す以下の文字列です。

"call" (または "tail call")
"return"
"line"
"count"

lineイベントの場合、フックには第2引数として新しい行番号が渡されます。フック内でレベルに2を指定して getinfo を呼ぶことで、実行中の関数に関する情報をさらに取得できます (レベル0は getinfo で、レベル1はフック関数です)。

`debug.setlocal ([thread,] level, local, value)`

スタックのレベル level の関数のインデックス local のローカル変数の値に value を代入します。指定したインデックスのローカル変数が存在しない場合は nil を返します。 level が範囲外の場合はエラーが発生します。 (レベルが有効かどうかを確認するには getinfo を呼びます。) そうでなければ、そのローカル変数の名前を返します。

変数のインデックスと名前についての詳しい情報は debug.getlocal を参照してください。

`debug.setmetatable (value, table)`

指定された value に対するメタテーブルを指定された table (nil も指定できます) に設定します。 value を返します。

`debug.setupvalue (f, up, value)`

関数 f のインデックス up の上位値に値 value を代入します。指定したインデックスの上位値が存在しない場合は nil を返します。そうでなければ、その上位値の名前を返します。

`debug.setuservalue (udata, value)`

指定された udata に指定されたLuaの値 value を関連付けます。 udata はフルユーザーデータでなければなりません。

udata を返します。

`debug.traceback ([thread,] [message [, level]])`

message が存在し、文字列でも nil でもなければ、 message を返します。この場合はそれ以上何も処理しません。そうでなければ、コールスタックのスタックトレースを表す文字列を返します。省略可能な message 文字列はスタックトレースの先頭に追加されます。省略可能な level の数値はスタックトレースを開始するレベルを表します (デフォルトは1で、 traceback の呼び出し元関数です)。

`debug.upvalueid (f, n)`

指定された関数の n 番目の上位値に対する一意な識別子を (ライトユーザーデータとして) 返します。

`debug.upvaluejoin (f1, n1, f2, n2)`

Luaのクロージャ f1 の n1 番目の上位値がLuaのクロージャ f2 の n2 番目の上位値を参照するようにします。

7 – スタンドアロンの Lua

LuaはCのホストプログラムに組み込まれる拡張言語として設計されていますが、スタンドアロンの言語としても使われています。スタンドアロンのLuaインタプリタは単純に lua という名前で、標準の配布物に含まれています。スタンドアロンのインタプリタには、デバッグライブラリも含めて標準ライブラリがすべて含まれています。使い方は以下の通りです。

     lua [options] [script [args]]

オプションは以下の通りです。

-e stat: 文字列 stat を実行します。
-l mod: mod を "require" します。
-i: スクリプトの実行後に対話モードに入ります。
-v: バージョン情報を表示します。
-E: 環境変数を無視します。
--: オプションの処理を停止します。
-: stdin をファイルとして実行し、オプションの処理を停止します。

オプションを処理した後、指定されたスクリプトが実行されます。引数なしで起動すると、標準入力 (stdin) が端末の場合は lua -v -i のように動作し、そうでなければ lua - のように動作します。

オプション -E を付けずに起動すると、いかなる引数も実行する前に、環境変数 LUA_INIT_5_3 (バージョン名付きの変数が定義されていない場合は LUA_INIT) がチェックされます。この変数の内容が @filename という書式であれば、そのファイルが実行されます。そうでなければ、その文字列自身が実行されます。

オプション -E を付けて実行すると、 LUA_INIT を無視する以外に LUA_PATH および LUA_CPATH の値も無視されます。 package.path および package.cpath の値には、 luaconf.h で定義されているデフォルトのパスが設定されます。

-i と -E を除き、すべてのオプションは順番に処理されます。例えば以下のようなコマンドは

     $ lua -e'a=1' -e 'print(a)' script.lua

まず a を1に設定し、次に a の値を表示し、最後にファイル script.lua を引数なしで実行します。 (ただし $ はシェルプロンプトです。これは環境によって異なる場合があります。)

いかなるコードも実行する前に、 arg という名前のグローバルなテーブルにすべてのコマンドライン引数が集められます。スクリプトの名前がインデックス0に格納され、最初の引数はスクリプト名の後のインデックス1に格納され、以下同様です。スクリプト名より前の引数 (つまりインタプリタ名およびオプション) はすべて負のインデックスに格納されます。例えば以下のコマンドでは

     $ lua -la b.lua t1 t2

このテーブルは以下のようになります。

     arg = { [-2] = "lua", [-1] = "-la",
             [0] = "b.lua",
             [1] = "t1", [2] = "t2" }

スクリプトが指定されていない場合は、インタプリタ名がインデックス0に格納され、残りの引数がそれに続きます。例えば以下のコマンドは

     $ lua -e "print(arg[1])"

"-e" を表示します。スクリプトがある場合、そのスクリプトには引数 arg[1]、···、arg[#arg] が渡されます。 (Luaのすべてのチャンクと同様に、スクリプトは可変長引数の関数としてコンパイルされます。)

対話モードではプロンプトの表示と行の待ち受けが繰り返されます。行を読み込んだ後、その行が式として解釈されます。成功した場合はその値が表示されます。そうでなければその行が文として解釈されます。不完全な文が入力された場合は、異なるプロンプトを表示し、文が完全になるまで待ち受けます。

スクリプト内で保護されていないエラーが発生した場合は、そのエラーが標準エラー出力に報告されます。エラーオブジェクトが文字列でなく、メタメソッド __tostring があれば、そのメタメソッドが呼ばれて最終的なメッセージが生成されます。そうでなければ、そのエラーオブジェクトが文字列に変換され、それにスタックトレースが付け加えられます。

正常に終了するとメインのLuaステートが閉じられます (lua_close を参照)。 os.exit を呼んで終了するとこの処理を回避できます。

LuaをUnixシステムのスクリプトインタプリタとして使用できるように、スタンドアロンのインタプリタはチャンクの最初の行が # で始まる場合、その行を読み飛ばします。つまり、 chmod +x と以下のような #! 形式を使うと、Luaのスクリプトを実行可能なプログラムにすることができます。

     #!/usr/local/bin/lua

(Luaのインタプリタの場所は環境によって異なる場合があります。 lua が PATH の通った場所にあるならば、

     #!/usr/bin/env lua

がより移植性の高い方法です。)

8 – 前バージョンとの非互換な点

この節ではLua 5.2からLua 5.3にプログラムを移植する際に遭遇するかもしれない非互換な点の一覧を掲載しています。非互換のいくつかは、適切なオプション (ファイル luaconf.h を参照) を使ってLuaをコンパイルすると回避できます。しかし、これらの互換オプションは将来のバージョンでは削除される予定です。

LuaのバージョンごとにCのAPIが変更される可能性があります。これはプログラムのソースコードを変更することを暗黙に意味するわけではなく、定数の数値やマクロとして実装された関数なども含まれています。そのため、Luaの異なるバージョン間でのバイナリ互換は仮定するべきではありません。新しいバージョンを使うときは、LuaのAPIを使うプログラムを必ず再コンパイルしてください。

同様に、Luaのバージョンごとにコンパイル済みチャンクの内部表現も変更される可能性があります。コンパイル済みチャンクはLuaの異なるバージョン間での互換性はありません。

公式の配布物の標準のパスはバージョン間で変更される場合があります。

8.1 – 言語の変更

Lua 5.2とLua 5.3の主な違いは、数値のサブタイプである整数の導入です。この変更が「通常の」計算に影響することはないと思われますが、場合によっては (主にオーバーフロー関係の影響で) 異なる結果になることがあります。
この差異は数値を強制的に浮動小数点数にすることで修正できます (Lua 5.2ではすべての数値が浮動小数点数でした)。例えば定数の最後に .0 を付けたり、 x = x + 0.0 で変数を変換したりできます。 (これらは非互換に対応するための臨時的な応急処理にすぎません。良いプログラミングの一般的なガイドラインではありません。良いプログラミングのためには、浮動小数点数が必要なところでは浮動小数点数を使い、整数が必要なところでは整数を使ってください。)
浮動小数点数を文字列に変換するとき、整数のように見える場合は結果に接尾辞 .0 が追加されるようになりました。 (例えば、浮動小数点数の 2.0 は 2 ではなく 2.0 と表示されます。) 数値に対して特定の書式が必要な場合は、必ず明示的な書式を使ってください。
(正確にはこれは非互換ではありません。数値を文字列として書式化する方法は規定されていないためです。しかし特定の書式を想定しているプログラムも存在していました。)
ガベージコレクタの世代別モードは削除されました。 (これはLua 5.2の実験的な機能でした。)

8.2 – ライブラリの変更

bit32 ライブラリは廃止されました。互換性のある外部のライプラリをrequireするか、あるいはより良い方法として、その関数を適切なビット演算子に置き換えてください。 (bit32 は32ビット整数を扱っていましたが、Lua 5.3のビット演算子はLuaの整数 (デフォルトでは64ビット) を扱うことに気を付けてください。)
テーブルライブラリは要素の設定や取得の際にメタメソッドを考慮するようになりました。
ipairs のイテレータはメタメソッドを考慮するようになりました。 __ipairs メタメソッドは廃止されました。
io.read のオプション名の最初の '*' は無くなりました。互換性のため、この文字は引き続き受け付けられます (そして無視されます)。
数学ライブラリの以下の関数は廃止されました。
- atan2
- cosh
- sinh
- tanh
- pow
- frexp
- ldexp
math.pow(x,y) は x^y で置き換えることができます。 math.atan2 は math.atan で置き換えることができます。 math.atan は引数1個と引数2個のどちらでも受け付けるようになりました。 math.ldexp(x,exp) は x * 2.0^exp で置き換えることができます。それ以外の演算については、外部のライブラリを使うかLuaで実装してください。
require で使われるCのローダーの検索関数でバージョン名の処理方法が変わりました。バージョンは (他の多くのツールと同様に) モジュール名の後に来るようになりました。互換性のため、この検索関数は新しい形式に従ったオープン関数が見つからなかった場合、古い書式も試みます。 (Lua 5.2ではすでにそのように動作していましたが、ドキュメントは変更されていませんでした。)
呼び出し collectgarbage("count") の戻り値はひとつだけになりました。 (最初の戻り値の小数部から2番目の戻り値を計算できます。)

8.3 – APIの変更

継続関数は lua_getctx を使って取得する必要があった値を引数として受け取るようになりました。そのため lua_getctx は削除されました。それに合わせてコードを変更してください。
関数 lua_dump に引数 strip が追加されました。以前の動作をするにはこの引数に0を渡してください。
符号無し整数を扱う関数 (lua_pushunsigned、 lua_tounsigned、 lua_tounsignedx、 luaL_checkunsigned、 luaL_optunsigned) は廃止されました。同等の符号付きバージョンを型キャストと共に使ってください。
デフォルトでない整数型を変換するマクロ (luaL_checkint、 luaL_optint、 luaL_checklong、 luaL_optlong) は廃止されました。 lua_Integer に対する同等のものを型キャストと共に使ってください (または、可能であれば、あなたのコードで lua_Integer を使ってください)。

9 – Lua の完全な構文

Luaの完全な構文を拡張BNF記法で以下に掲載します。一般的な拡張BNF記法と同様に、 {A} はAの0回以上の繰り返しを表し、 [A] はAが省略可能であることを表します。 (演算子の優先順位は §3.4.8 を参照。終端記号Name、Numeral、LiteralStringの説明は §3.1 を参照。)


	chunk ::= block

	block ::= {stat} [retstat]

	stat ::=  ‘;’ |
		 varlist ‘=’ explist |
		 functioncall |
		 label |
		 break |
		 goto Name |
		 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 explist do block end |
		 function funcname funcbody |
		 local function Name funcbody |
		 local namelist [‘=’ explist]

	retstat ::= return [explist] [‘;’]

	label ::= ‘::’ Name ‘::’

	funcname ::= Name {‘.’ Name} [‘:’ Name]

	varlist ::= var {‘,’ var}

	var ::=  Name | prefixexp ‘[’ exp ‘]’ | prefixexp ‘.’ Name

	namelist ::= Name {‘,’ Name}

	explist ::= exp {‘,’ exp}

	exp ::=  nil | false | true | Numeral | LiteralString | ‘...’ | functiondef |
		 prefixexp | tableconstructor | exp binop exp | unop exp

	prefixexp ::= var | functioncall | ‘(’ exp ‘)’

	functioncall ::=  prefixexp args | prefixexp ‘:’ Name args

	args ::=  ‘(’ [explist] ‘)’ | tableconstructor | LiteralString

	functiondef ::= function funcbody

	funcbody ::= ‘(’ [parlist] ‘)’ block end

	parlist ::= namelist [‘,’ ‘...’] | ‘...’

	tableconstructor ::= ‘{’ [fieldlist] ‘}’

	fieldlist ::= field {fieldsep field} [fieldsep]

	field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp

	fieldsep ::= ‘,’ | ‘;’

	binop ::=  ‘+’ | ‘-’ | ‘*’ | ‘/’ | ‘//’ | ‘^’ | ‘%’ |
		 ‘&’ | ‘~’ | ‘|’ | ‘>>’ | ‘<<’ | ‘..’ |
		 ‘<’ | ‘<=’ | ‘>’ | ‘>=’ | ‘==’ | ‘~=’ |
		 and | or

	unop ::= ‘-’ | not | ‘#’ | ‘~’