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

このリファレンスマニュアルは Lua 言語の公式の定義です。 Lua プログラミングの完全な導入には Programming in Lua を参照してください。

索引

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

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

目次 · 索引

0 – 日本語訳について

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

1 – 序文

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

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

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

他のどんなリファレンスマニュアルとも同様に、この文章は所々が無味乾燥です。 Lua の設計に関する議論は、 Lua のウェブサイトから入手できる技術論文を参照してください。 Lua プログラミングの詳しい紹介は、 Roberto 著 Programming in Lua を参照してください。

2 – 基本コンセプト

このセクションでは言語のいくつかの基本コンセプトを説明します。

2.1 – 値と型

Lua は 動的型付け言語 です。つまり、変数ではなく、値が型を持ちます。型定義の構文はありません。すべての値は自分自身の型を保持しています。

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

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

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

nil は nil 値の型です。その主な性質は他のいかなる値とも異なることであり、通常、役に立つ値がないことを表します。

ブーリアン は false 値と true 値の型です。 nil と false は両方とも条件式では偽となり、他のすべての値は真となります。

数値は実数 (倍精度浮動小数点) を表します。数値演算は元になっている C の実装と同じ規則で行われ、通常は IEEE 754 標準に従っています。 (数値に他の内部表現、例えば単精度浮動小数点や整数を使う Lua インタプリタをビルドすることも簡単です。ファイル luaconf.h を参照してください。)

文字列 は不変のバイト列を表します。 Lua は 8 ビットクリーンであり、文字列には埋め込まれたゼロ ('\0') を含む、いかなる 8 ビット値でも格納することができます。

Lua は Lua で書かれた関数も C で書かれた関数も呼び出す (および操作する) ことができます (§3.4.9 を参照)。

ユーザーデータ 型は任意の C のデータを Lua の変数に格納するための型です。ユーザーデータは生のメモリブロックへのポインタです。ユーザーデータには 2 種類あります。メモリブロックを Lua が管理するものがフルユーザーデータで、メモリブロックをホストが管理するものがライトユーザーデータです。ユーザーデータは、代入と等値比較を除いて、 Lua による定義済みの演算はありません。 メタテーブル を使うと、フルユーザーデータに対する演算をプログラマが定義することができます (§2.4 を参照)。ユーザーデータは Lua 内で作ったり変更したりすることはできず、 C の API を使う必要があります。これによってホストプログラムが保持するデータの完全性が保証されます。

スレッド 型は独立した実行のスレッドを表し、コルーチンを実装するために使われます (§2.6 を参照)。 Lua のスレッドを OS のスレッドと混同しないでください。スレッドをサポートしていないシステム上でもコルーチンはサポートされています。

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

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

すべての正の整数キーの集合が {1..n} であるようなテーブルを、 シーケンス と呼ぶことにします。整数 n はシーケンスの長さと呼びます (§3.4.6 を参照)。

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

テーブルのインデックス検索は Lua における生の等値の定義に従います。式 a[i] および a[j] は、 i と j が生の等値 (つまりメタメソッドなしで等しい) であるときに限り、同じテーブル要素を指します。

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

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

2.2 – 環境およびグローバル環境

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

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

_ENV の値として使われるテーブルは一般的に環境と呼ばれます。

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

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

レジストリ内のグローバル環境を (C のコードかデバッグライブラリを使って) 変更する場合、変更後にロードしたチャンクはすべて、新しい環境を使います。しかしすでにロード済みのチャンクは影響を受けません。各チャンクは自身の _ENV 変数の環境を参照し続けます。また、変数 _G (元のグローバル環境に格納されているもの) は自動的には更新されません。

2.3 – エラー処理

Lua は組み込み用の拡張言語であるため、すべての Lua の活動はホストプログラム内の C のコードが Lua ライブラリの関数を呼ぶことによって始まります (lua_pcall を参照)。 Lua チャンクのコンパイル中または実行中にエラーが発生すると、制御がホストに戻り、適切な処置を取ることができます (例えばエラーメッセージを表示するなど)。

Lua のコードでは error 関数を呼ぶことで明示的にエラーを発生させることができます。 Lua 内でエラーをキャッチする必要がある場合は、指定した関数を 保護モード で実行する pcall 関数または xpcall 関数を使います。

エラーが発生すると、 エラーオブジェクト (エラーメッセージ とも言う) が、そのエラーに関する情報と共に伝達されます。 Lua 自身がエラーを発生させるときは、エラーオブジェクトは常に文字列ですが、プログラム上では任意の値をエラーオブジェクトとしてエラーを発生させることができます。

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

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

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

メタテーブルのキーは イベント の名前によって決めれられています。キーに対応する値は メタメソッド と呼ばれます。上の例では、イベントは "add" で、メタメソッドは加算を実行する関数です。

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

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

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

メタテーブルは算術演算、順序比較、連結、長さ演算、およびインデックス検索に対するオブジェクトの動作をコントロールします。メタテーブルはユーザーデータまたはテーブルがガベージコレクタに回収される時に呼ばれる関数も定義できます。値に対してこれらのどれかの操作が実行されると、その値のメタテーブルに対応するイベントがあるか調べられます。もしあれば、そのキーに関連付けられた値 (メタメソッド) が演算の実行をコントロールします。

メタテーブルは以下の一覧にある演算をコントロールします。それぞれの演算は対応する名前で区別します。それぞれの演算に対応するキーは、その名前の前に 2 つのアンダースコア '__' を付けた文字列です。例えば、"add" 演算のキーは文字列 "__add" です。

これらの演算の意味は、インタプリタが演算をどのように実行するかを示す Lua の関数で説明するのが良いでしょう。ただし以下の示す Lua で書かれたコードは、単に説明のためだけのものです。実際の動作はインタプリタにハードコーディングされており、ここに示した疑似コードよりも効率的に動作します。この説明に使われているすべての関数 (rawget、 tonumber など) は §6.1 に記載されています。ちなみに、指定したオブジェクトのメタメソッドを取得するために以下の表現を使っていますが、

     metatable(obj)[event]

これは以下のように読み替えてください。

     rawget(getmetatable(obj) or {}, event)

つまり、メタメソッドへのアクセスは他のメタメソッドを呼び出さず、またメタテーブルを持たないオブジェクトにアクセスする場合でもエラーを発生しません (単純に nil を返します)。

単項演算子 - および # については、メタメソッドにはダミーの第 2 引数が渡されます。この余分の引数は Lua の内部構造を簡単化するためだけのもので、将来のバージョンでは削除されるかもしれません。そのため以下のコードでは表していません (ほとんどの場合この余分の引数は無意味です)。

"add": + 演算。

以下の関数 getbinhandler は、二項演算子のハンドラがどのように選択されるかを定義しています。まず第 1 引数を見ます。その型が演算に対するハンドラを定義していなければ、第 2 引数を見ます。

     function getbinhandler (op1, op2, event)
       return metatable(op1)[event] or metatable(op2)[event]
     end

この関数を使うことによって、 op1 + op2 の演算は以下のように書けます。

     function add_event (op1, op2)
       local o1, o2 = tonumber(op1), tonumber(op2)
       if o1 and o2 then  -- 両方の引数が数値か?
         return o1 + o2   -- この '+' はプリミティブの加算
       else  -- 少なくとも片方の引数が数値でない
         local h = getbinhandler(op1, op2, "__add")
         if h then
           -- 両方の引数を渡してハンドラを呼ぶ
           return (h(op1, op2))
         else  -- ハンドラが利用不可能、 デフォルトの動作
           error(···)
         end
       end
     end

"sub": - 演算。 "add" 演算と同様の動作。
"mul": * 演算。 "add" 演算と同様の動作。
"div": / 演算。 "add" 演算と同様の動作。
"mod": % 演算。 "add" 演算と同様の動作。ただしプリミティブの演算は o1 - floor(o1/o2)*o2 のように行われます。
"pow": ^ (累乗) 演算。 "add" 演算と同様の動作。ただしプリミティブの演算には pow 関数 (C の数学ライブラリ) を用います。

"unm": 単項 - 演算。

     function unm_event (op)
       local o = tonumber(op)
       if o then  -- 引数は数値か?
         return -o  -- この '-' はプリミティブの符号反転
       else  -- 引数は数値でない
         -- 引数からハンドラの取得を試みる
         local h = metatable(op).__unm
         if h then
           -- 引数を渡してハンドラを呼ぶ
           return (h(op))
         else  -- ハンドラが利用不可能、 デフォルトの動作
           error(···)
         end
       end
     end

"concat": .. (連結) 演算。

     function concat_event (op1, op2)
       if (type(op1) == "string" or type(op1) == "number") and
          (type(op2) == "string" or type(op2) == "number") then
         return op1 .. op2  -- プリミティブの文字列連結
       else
         local h = getbinhandler(op1, op2, "__concat")
         if h then
           return (h(op1, op2))
         else
           error(···)
         end
       end
     end

"len": # 演算。

     function len_event (op)
       if type(op) == "string" then
         return strlen(op)      -- プリミティブの文字列の長さ
       else
         local h = metatable(op).__len
         if h then
           return (h(op))       -- 引数を渡してハンドラを呼ぶ
         elseif type(op) == "table" then
           return #op              -- プリミティブのテーブルの長さ
         else  -- ハンドラが利用不可能、 エラー
           error(···)
         end
       end
     end

テーブルの長さについての説明は §3.4.6 を参照してください。

"eq": == 演算。関数 getequalhandler は等値比較のメタメソッドがどのように選択されるかを定義しています。メタメソッドは比較しようとする両方の値が同じ型であり、その演算に対するメタメソッドが同じであり、両方の値がテーブルまたはユーザーデータである場合だけ選択されます。

     function getequalhandler (op1, op2)
       if type(op1) ~= type(op2) or
          (type(op1) ~= "table" and type(op1) ~= "userdata") then
         return nil     -- 異なる型
       end
       local mm1 = metatable(op1).__eq
       local mm2 = metatable(op2).__eq
       if mm1 == mm2 then return mm1 else return nil end
     end

"eq" イベントは以下のように定義されます。

     function eq_event (op1, op2)
       if op1 == op2 then   -- プリミティブの等価比較
         return true   -- 値は等しい
       end
       -- メタメソッドを試みる
       local h = getequalhandler(op1, op2)
       if h then
         return not not h(op1, op2)
       else
         return false
       end
     end

ちなみに結果は常にブーリアンです。

"lt": < 演算。

     function lt_event (op1, op2)
       if type(op1) == "number" and type(op2) == "number" then
         return op1 < op2   -- 数値の比較
       elseif type(op1) == "string" and type(op2) == "string" then
         return op1 < op2   -- 辞書順の比較
       else
         local h = getbinhandler(op1, op2, "__lt")
         if h then
           return not not h(op1, op2)
         else
           error(···)
         end
       end
     end

ちなみに結果は常にブーリアンです。

"le": <= 演算。

     function le_event (op1, op2)
       if type(op1) == "number" and type(op2) == "number" then
         return op1 <= op2   -- 数値の比較
       elseif type(op1) == "string" and type(op2) == "string" then
         return op1 <= op2   -- 辞書順の比較
       else
         local h = getbinhandler(op1, op2, "__le")
         if h then
           return not not h(op1, op2)
         else
           h = getbinhandler(op1, op2, "__lt")
           if h then
             return not h(op2, op1)
           else
             error(···)
           end
         end
       end
     end

"le" メタメソッドが無い場合は、 a <= b と not (b < a) が同等であると仮定して "lt" が呼ばれることに注意してください。

他の比較演算子と同じく、結果は常にブーリアンです。

"index": インデックスアクセス table[key]。メタメソッドは table に key が存在しない場合だけ呼ばれることに注意してください。 (table がテーブルでない場合は、キーは決して存在しないため、常にメタメソッドが呼ばれます。)

     function gettable_event (table, key)
       local h
       if type(table) == "table" then
         local v = rawget(table, key)
         -- キーが存在する場合は、 その生の値を返す
         if v ~= nil then return v end
         h = metatable(table).__index
         if h == nil then return nil end
       else
         h = metatable(table).__index
         if h == nil then
           error(···)
         end
       end
       if type(h) == "function" then
         return (h(table, key))     -- ハンドラを呼び出す
       else return h[key]           -- または演算を繰り返す
       end
     end

"newindex": インデックス付き代入 table[key] = value。メタメソッドは table に key が存在しない場合だけ呼ばれることに注意してください。

     function settable_event (table, key, value)
       local h
       if type(table) == "table" then
         local v = rawget(table, key)
         -- キーが存在する場合は、 生の代入を行う
         if v ~= nil then rawset(table, key, value); return end
         h = metatable(table).__newindex
         if h == nil then rawset(table, key, value); return end
       else
         h = metatable(table).__newindex
         if h == nil then
           error(···)
         end
       end
       if type(h) == "function" then
         h(table, key,value)           -- ハンドラを呼び出す
       else h[key] = value             -- または演算を繰り返す
       end
     end

"call": 値が呼ばれたときに呼ばれます。

     function function_event (func, ...)
       if type(func) == "function" then
         return func(...)   -- プリミティブの call
       else
         local h = metatable(func).__call
         if h then
           return h(func, ...)
         else
           error(···)
         end
       end
     end

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

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

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

ガベージコレクタ停止期間は新しいサイクルを開始するまでに待つ時間の長さをコントロールします。大きな値を指定するほどコレクタは消極的になります。 100 より小さな値を指定するとコレクタはすぐに新しいサイクルを開始します。 200 を指定すると 2 倍の合計メモリが使われるまで新しいサイクルを開始しません。

ガベージコレクタステップ係数はメモリ割り当てに対するコレクタの動作速度をコントロールします。大きな値を指定するほどコレクタは積極的になりますが、各インクリメンタルステップのサイズも増加します。 100 より小さな値を指定するとコレクタが非常に遅くなり、コレクタのサイクルが終わらなくなる場合があります。デフォルトは 200 です。これはメモリ割り当ての「2倍」の速度でコレクタが走ることになります。

ステップ係数を非常に大きな数 (プログラムが使う可能性のあるバイト数の最大値より 10% 以上大きな数) にすると、コレクタはストップザワールドコレクタのように動作します。さらに停止期間を 200 にすると、コレクタは毎回の完全なコレクションごとにメモリ使用量を 2 倍にする、前のバージョンの Lua と同じような動作になります。

これらの数値を変更するには、 C で lua_gc を呼ぶか、 Lua で collectgarbage を呼びます。またこれらの関数を使うと、コレクタを直接コントロール (停止したり再開したり) することもできます。

Lua 5.2 における実験的な機能として、コレクタの動作モードをインクリメンタルから 世代別 に変更できます。 世代別コレクタ はほとんどのオブジェクトが若くして死ぬと仮定し、そのため若い (最近作られた) オブジェクトのみを巡回します。この動作はコレクタが使う時間を減らしますが、 (年老いて死んだオブジェクトが溜まる可能性があるため) メモリ使用量は増えます。 2 つめの問題を軽減するため、世代別コレクタは時々フルコレクションを行います。これは実験的な機能であることを忘れないでください。大いに試して頂いて構いませんが、実際に効果があったか確認するようにしてください。

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

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

オブジェクト (テーブルまたはユーザーデータ) を回収時にファイナライズするためには、それをファイナライズ用に マーク しなければなりません。オブジェクトにメタテーブルを設定したとき、そのメタテーブルが文字列 "__gc" のフィールドを持っていれば、そのオブジェクトはファイナライズ用にマークされます。もし設定時にメタテーブルが __gc フィールドを持っていなければ、後でそのメタテーブルにそのフィールドを追加しても、そのオブジェクトはファイナライズ用にマークされません。しかし、オブジェクトがいったんマークされた後でなら、メタテーブルの __gc フィールドは自由に変更できます。

マークしたオブジェクトがガベージになっても、ガベージコレクタはすぐにはそれを回収しません。代わりにそれはリストに格納されます。ガベージコレクションが終わった後、そのリスト中の各オブジェクトについて、以下の関数と同等のことが行われます。

     function gc_event (obj)
       local h = metatable(obj).__gc
       if type(h) == "function" then
         h(obj)
       end
     end

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

回収されたオブジェクト (およびそのオブジェクトを通してアクセス可能なオブジェクト) は、まだファイナライザによって使われるため、 Lua によって蘇生されます。通常、この蘇生は短期的なものであり、そのオブジェクトのメモリは次のガベージコレクションサイクルで解放されます。しかし、ファイナライザがそのオブジェクトをなんらかのグローバルな場所 (グローバル変数など) に格納すると、永続的な蘇生になります。いずれにせよ、オブジェクトのメモリは完全にアクセスできなくなった場合に限り解放されます。またファイナライザは 2 回以上は呼ばれません。

2.5.2 – 弱参照テーブル

弱参照テーブル は要素が 弱参照 であるテーブルです。弱参照はガベージコレクタに無視されます。言い換えると、オブジェクトへの参照が弱参照だけになった場合、ガベージコレクタはそのオブジェクトを回収します。

弱参照テーブルは、弱参照のキー、弱参照の値、またはその両方を持つことができます。弱参照キーを持つテーブルは、キーは回収されますが、値は回収されません。弱参照キーと弱参照値の両方を持つテーブルは、キーと値の両方が回収されます。どの場合でも、キーか値のいずれかが回収されれば、そのペア全体がテーブルから取り除かれます。テーブルの弱参照の性質はメタテーブルの __mode フィールドでコントロールします。 __mode フィールドが文字列で、文字 'k' が含まれていれば、そのテーブルはキーが弱参照になります。 __mode フィールドに 'v' が含まれていれば、そのテーブルは値が弱参照になります。

弱参照のキーと 強参照 の値を持つテーブルは、 短命テーブル と呼ばれます。短命テーブルでは、キーが到達可能な場合だけ、値が到達可能です。具体的に言うと、キーが値を通してのみ参照可能な場合は、そのペアは削除されます。

テーブルの弱参照性の変更は、次のコレクションサイクル以降に限り効果を発揮する可能性があります。特に、弱参照モードから強参照モードに変更する場合、変更が効果を発揮するまでの間に、そのテーブルからいくつかの要素が回収されてしまう場合があります。

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

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

弱参照テーブル自身が蘇生オブジェクトである場合は、次のコレクションサイクルまで適切にクリアされない場合があります。

2.6 – コルーチン

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

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

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

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

coroutine.yield を呼ぶと、コルーチンは中断されます。コルーチンが中断されると、対応する coroutine.resume から直ちに戻ります。たとえ中断がネストした関数呼び出しの中 (つまりメイン関数ではなく、メイン関数から直接または間接的に呼ばれた別の関数の中) で起きた場合でも、同様です。中断した場合、 coroutine.resume は true と coroutine.yield に渡された引数を返します。同じコルーチンをもう一度 resume すると、コルーチンは中断した地点から実行を継続します。そのとき coroutine.yield は coroutine.resume に渡された追加の引数を返します。

coroutine.create と同様に、 coroutine.wrap 関数もコルーチンを作成します。ただしコルーチン自身を返すのではなく、呼ばれるとコルーチンを再開する関数を代わりに返します。この関数に渡した引数はすべて 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) は、 Lua 自身が使用する変数として予約されています。

以下の文字列はその他のトークンです。

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

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

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

バックスラッシュに本物の改行が続いたものは、文字列中で改行になります。

エスケープシーケンス '\z' は、後続のホワイトスペース (改行も含む) をスキップします。文字列中に改行や空白を追加せずに、複数行に渡る長い文字列を分割したりインデントしたりしたいときに、特に便利でしょう。

リテラル文字列中のバイトは、その数値で指定することもできます。これにはエスケープシーケンス \xXX または \ddd を使います。 XX はぴったり 2 桁の 16 進数で、 ddd は最大 3 桁の 10 進数です。 (10 進数のエスケープシーケンスの直後に数字が続くときは、ぴったり 3 桁を使わなければならないことに注意してください。) Lua の文字列には任意の 8 ビット値を入れることができます。 '\0' で表される埋め込まれたゼロも入れることができます。

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

ソース文字列の解析において、上記のルールに明示的な影響のないリテラル文字列内のあらゆるバイトは、それ自身を表現します。しかしながら、解析時はテキストモードでファイルを開くので、いくつかの制御文字について、システムのファイル関数が、何らかの問題を起こす可能性があります。そのため、テキスト以外のデータは、明示的に非テキスト文字用のエスケープシーケンスを使って、引用符を用いたリテラルとして表現する方が安全です。

便利なように、開き長括弧の直後に改行が続く場合は、その改行は文字列に含まれません。例えば、 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     3.0     3.1416     314.16e-2     0.31416E1
     0xff  0x0.1E  0xA23p-4   0X1.921FB54442D18P+1

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

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 ::= ‘;’

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

	stat ::= do block end

明示的なブロックは、変数宣言のスコープをコントロールするのに便利です。明示的なブロックはまた、ブロックの途中に return 文を入れるために使うこともあります (§3.3.4 を参照)。

3.3.2 – チャンク

Lua の実行の単位は チャンク と呼ばれます。構文的には、チャンクは単にブロックです。

	chunk ::= block

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

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

チャンクはバイナリ形式に事前コンパイルしておくこともできます。詳細は luac を参照してください。ソース形式のプログラムとコンパイル済み形式はどちらを使っても構いません。ファイル形式は自動的に判定され、適切に動作します。

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 で始まり、二番目の exp に達するまで、三番目の 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
       while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do
         local v = var
         block
         var = var + step
       end
     end

注意点を以下に示します。

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

汎用 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 は見えない変数です。ここで示した名前は説明のためだけのものです。
for ループを抜けるために break を使うことができます。
ループ変数 var_i はループにローカルです。 for の終了後に使うことはできません。もしこの値が必要なら、ループを break または終了する前に他の変数に代入しておいてください。

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

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

	stat ::= functioncall

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

3.3.7 – ローカル宣言

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

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

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

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

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

3.4 – 式

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

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

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

二項演算子には算術演算子 (§3.4.1 を参照)、関係演算子 (§3.4.3 を参照)、論理演算子 (§3.4.4 を参照)、および連結演算子 (§3.4.5 を参照) があります。単項演算子には単項マイナス (§3.4.1 を参照)、単項 not (§3.4.4 を参照)、および単項 長さ演算子 (§3.4.6 を参照) があります。

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

いくつか例を挙げます。

     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 – 算術演算子

Lua には以下ような一般的な算術演算子があります。

+ (加算)
- (減算)
* (乗算)
/ (除算)
% (剰余)
^ (累乗)
単項の - (符号反転)

引数が数値か、数値に変換できる文字列 (§3.4.2 を参照) であれば、すべての演算は一般的な意味を持ちます。累乗は任意の指数に対して使えます。例えば x^(-0.5) は x の平方根の逆数を計算します。剰余は以下のように定義されます。

     a % b == a - math.floor(a/b)*b

つまり、商を負の無限大に向かって丸めた除算の余りです。

3.4.2 – 強制型変換

文字列と数値は実行時に自動的に変換されます。文字列に対して算術演算が適用されると、その文字列を Lua の字句解析のルールに沿って数値に変換しようと試みます。 (文字列には前後の空白や符号があっても構いません。) 逆に、文字列が期待されるところで数値が使われると、その数値は適当な形式で文字列に変換されます。数値を文字列に変換する方法を完全にコントロールしたい場合は、文字列ライブラリの format 関数を使ってください (string.format を参照)。

3.4.3 – 関係演算子

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

     ==    ~=    <     >     <=    >=

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

等値比較 (==) はまず引数の型を比較します。型が異なっている場合、結果は false です。そうでなければ、引数の値を比較します。数値および文字列の場合は、一般的な方法で比較します。テーブル、ユーザーデータ、スレッドは参照を比較します。つまり、同じオブジェクトである場合だけ、等しいとみなします。新しいオブジェクト (テーブル、ユーザーデータ、スレッド) を作ったときは常に、この新しいオブジェクトはそれまで存在していたオブジェクトとは異なります。同じ参照を持つクロージャは常に等しくなります。観測可能な差異 (異なる動作や異なる定義) を持つクロージャは常に異なります。

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

§3.4.2 の変換規則は等値比較には適用されません。そのため、 "0"==0 は false と評価され、 t[0] と t["0"] は異なるテーブルエントリを指します。

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

順序演算子は以下のように動作します。両方の引数が数値の場合は、それらは普通に比較されます。そうでなく、両方の引数が文字列の場合は、それらは現在のロケールに従って比較されます。そうでなければ、"lt" または "le" メタメソッドを呼び出します (§2.4 を参照)。 a > b は b < a に変換され、 a >= b は b <= a に変換されます。

3.4.4 – 論理演算子

Lua には論理演算子 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.5 – 連結

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

3.4.6 – 長さ演算子

長さ演算子は単項前置演算子 # で表されます。文字列の長さは、そのバイト数です (つまり 1 文字が 1 バイトである場合の文字列の長さです)。

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

__len メタメソッドを設定しない場合、テーブル t の長さは、そのテーブルが シーケンス である場合だけ定義されます。つまり、その正の数値キーの集合が {1..n} と等しい場合です。ここで、整数 n がその長さになります。以下のようなテーブルは

     {10, 20, nil, 40}

シーケンスではないことに注意してください。キー 4 は存在しますが、キー 3 が存在しないためです。 (すなわち、このテーブルには正の数値キーの集合が {1..n} と等しくなるような n がありません。) しかしながら、数値以外のキーは、テーブルがシーケンスであるかどうかには影響しないことも、知っておいてください。

3.4.7 – 優先順位

Lua の演算子の優先順位を低いものから高いものの順に以下の表に示します。

     or
     and
     <     >     <=    >=    ~=    ==
     ..
     +     -
     *     /     %
     not   #     - (単項)
     ^

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

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

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

	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"         -- 1 番目の 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.9 を参照)。

コードを自動生成するときに便利なように、フィールドリストの最後に省略可能なセパレータを付けることができます。

3.4.9 – 関数呼び出し

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

	functioncall ::= prefixexp args

関数呼び出しでは、まず prefixexp および args が評価されます。 prefixexp の値が関数型である場合は、その関数が指定された引数で呼び出されます。そうでない場合は、 prefixexp の "call" メタメソッドが呼ばれ、その最初の引数に prefixexp の値が、 2 番目以降に元の引数が渡されます (§2.4 を参照)。

以下の形式は、

	functioncall ::= prefixexp ‘:’ Name args

「メソッド」を呼ぶために使われます。呼び出し v:name(args) は v.name(v,args) のシンタックスシュガーです。ただし v の評価が一度だけであるという点が異なります。

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

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

呼び出しの前にすべての引数が評価されます。 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.10 – 関数定義

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

	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

(これはこの関数の中から f を参照している場合にだけ差異が生じます。)

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

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

	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 で宣言されています。

「関数」という言葉を使いますが、代わりにマクロとして提供されている機能もあります。特に記載がない限り、そのようなマクロはすべて、引数をそれぞれちょうど 1 回だけ使うので、隠れた副作用は起きません (ただし最初の引数である Lua ステートは除きます)。

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

4.1 – スタック

Lua は C との間で値を受け渡しするために、 仮想的なスタック を使います。スタック中の各要素は Lua の値 (nil、数値、文字列など) を表します。

Lua から 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 が保証します。ただし、それ以上の余分な空間は保証されません。そのため、そのような呼び出しの後は、スタックに値を積む前に lua_checkstack を使う必要があるかもしれません。

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

スタックインデックスを引数に取る API 関数はすべて 有効なインデックス または 受け入れ可能なインデックス のみ使用可能です。

有効なインデックス とは、スタック中の有効な位置を指すインデックスです。つまり、 1 とスタックトップの間 (1 ≤ abs(index) ≤ top) の値です。通常、特定のスタック位置が必要な関数 (例えば lua_remove) は、有効なインデックスを必要とします。

特定のスタック位置ではなくスタック中の値のみが必要な関数 (例えば問い合わせ系の関数) では、受け入れ可能なインデックスを使うことができます。 受け入れ可能なインデックス は、スタックに割り当てられた空間中の位置を参照します。つまり、スタックサイズまでのインデックスです。正式に言うと、受け入れ可能なインデックスは以下のようになります。

     (index < 0 && abs(index) <= top) ||
     (index > 0 && index <= stack size)

(0 は受け入れ可能なインデックスではないことに注意してください。) 関数が呼ばれたときのスタックサイズは top + LUA_MINSTACK です。関数 lua_checkstack を使ってスタックサイズを変えることができます。

受け入れ可能なインデックスは、スタックを問い合わせるときにスタックトップに対する余計なチェックを回避する効果があります。例えば C の関数で、 3 番目の引数が存在するかどうかをチェックすることなく、 3 番目の引数を問い合わせることができます。つまり、 3 が有効なインデックスかどうかを調べなくて良いということです。

受け入れ可能なインデックスを使う関数では、有効でないインデックスは仮想の型 LUA_TNONE の値を持つものとして扱います。

特に記載がない限り、有効なインデックスを受け取る関数はすべて 疑似インデックス も使用できます。これは、スタック中には無いものの、 C のコードからアクセス可能な、いくつかの Lua の値を表しています。疑似インデックスはレジストリや C の関数の上位値 (§4.4 を参照) にアクセスするために使われます。

4.4 – C のクロージャ

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

C の関数が呼ばれると、その上位値が特別な疑似インデックスに配置されます。この疑似インデックスはマクロ lua_upvalueindex で表されます。関数に関連付けられた最初の値は lua_upvalueindex(1) の位置にあり、以下同様です。現在の関数の上位値の数よりも大きな n (ただし 255 以下) で lua_upvalueindex(n) を呼ぶと、受け入れ可能な、ただし有効でないインデックスが生成されます。

4.5 – レジストリ

レジストリ は Lua の値を格納するために C のコードから使うことのできる定義済みのテーブルです。このレジストリテーブルは常に疑似インデックス LUA_REGISTRYINDEX の位置にあります。あらゆる C のライブラリがこのテーブルにデータを格納することができますが、衝突を避けるため、他のライブラリが使わないようなキーを注意深く選ぶべきです。通常は、ライブラリの名前を含む文字列や、ライブラリ内の C のオブジェクトのアドレスに対応するライトユーザーデータをキーとして使うのがよいでしょう。グローバル変数と同様に、アンダースコアと大文字で始まる文字列のキーは Lua 自身が使用するために予約されています。

整数のキーは、補助ライブラリで実装されているリファレンスメカニズムや、定義済みの値として使われています。そのため、それ以外の目的で整数キーを使うべきではありません。

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

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

4.6 – C でのエラー処理

内部的に、 Lua はエラー処理のために C の longjmp の機能を使っています。 (C++を使っている場合は例外を使うこともできます。ファイル luaconf.h を参照してください。) Lua が何らかのエラー (メモリ割り当てエラー、型エラー、構文エラーおよび実行時エラーなど) に直面すると、エラーを発生させ、つまりロングジャンプをします。 保護された環境 は setjmp を使って復帰点を設定します。何らかのエラーが発生すると、最も直近のアクティブな復帰点にジャンプします。

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

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

API のほとんどの関数は、何らかのエラー (例えばメモリ割り当てエラー) が発生する可能性があります。各関数のドキュメントにエラーが発生する可能性について記載されています。

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

4.7 – C での yield 処理

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

この種の問題を避けるため、 API 呼び出しをまたいで yield しようとすると Lua はエラーを発生させます。ただし以下の 3 つの関数は除きます。

lua_yieldk
lua_callk
lua_pcallk

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

継続を説明するために、いくつか用語を決める必要があります。 Lua から呼ばれる C の関数は 元の関数 と呼ぶことにします。この元の関数は、これら 3 つの C の API 関数のうちどれかを呼びます。その関数を 呼び出した関数 と呼ぶことにします。その後、現在のスレッドが中断されます。 (これは呼び出した関数が lua_yieldk であるか、呼び出した関数が lua_callk または lua_pcallk でありその呼ばれた関数が yield した場合のことです。)

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

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

元の関数とその継続関数で、 Lua ステート上唯一異なる点は、 lua_getctx の戻り値です。

4.8 – 関数と型

以下に C の API のすべての関数と型をアルファベット順に掲載します。それぞれの関数には [-o, +p, x] のような印が付いています。

最初のフィールド o は、その関数がスタックから取り除く要素の数です。 2 番目のフィールド p は、その関数がスタックに積む要素の数です。 (どの関数も常に、まず引数を取り除いてから、その後に結果を積みます。) x|y 形式のフィールドは、状況に応じて x 個または y 個の要素を積む (または取り除く) という意味です。疑問符 '?' は、引数を見るだけではその関数が積む (または取り除く) 要素の数がわからないことを表します。 (例えばスタックに何があるかによって変わったりします。)

3 番目のフィールド x は、その関数がエラーを発生するかどうかを表します。

'-': 決してエラーを発生しない関数です。
'm': メモリ割り当てエラーのみ発生する可能性がある関数です。
'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 が割り当てようとしているオブジェクトの種類をコード化しています。文字列、テーブル、関数、ユーザーデータまたはスレッドを作成しようとしている場合は、以下のいずれかになります。

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);
     }

標準 C ライブラリでは、 free(NULL) が何もしないこと、および realloc(NULL, size) が malloc(size) と同等であることを思い出してください。このコードではブロックを縮小するときに realloc が失敗しないと想定しています。 (標準 C はこの動作について保証していませんが、安全な想定であろうと思われます。)

`lua_arith`

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

int lua_arith (lua_State *L, int op);

スタックトップのふたつの値 (符号反転の場合はひとつ) に対して算術演算を行います。トップの値が第 2 引数になります。これらの値を取り除き、演算の結果を積みます。関数は対応する Lua の演算子の意味論に従います (つまりメタメソッドを呼ぶ場合があります)。

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

LUA_OPADD: 加算 (+) を実行します。
LUA_OPSUB: 減算 (-) を実行します。
LUA_OPMUL: 乗算 (*) を実行します。
LUA_OPDIV: 除算 (/) を実行します。
LUA_OPMOD: 剰余 (%) を実行します。
LUA_OPPOW: 累乗 (^) を実行します。
LUA_OPUNM: 符号反転 (単項の -) を実行します。

`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 の場合は除きます。この場合、関数のすべての戻り値が積まれます。戻り値が収まるように Lua がスタック空間の面倒を見てくれます。関数の戻り値は正順にスタックに積まれます。つまり最初の戻り値が最初に積まれます。そのため呼び出し後は最後の戻り値がスタックトップです。

呼び出した関数の内部で発生したエラーは (longjmp によって) 上に伝搬されます。

以下の例は、この Lua のコードと同じことをホストプログラムでどうすればいいかを示します。

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

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

     lua_getglobal(L, "f");           /* 呼ぶ関数 */
     lua_pushstring(L, "how");        /* 最初の引数 */
     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, int ctx,
                lua_CFunction k);

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

`lua_CFunction`

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

C の関数の型です。

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

例として、任意の数の数値引数を受け取り、それらの平均と合計を返す関数を以下に示します。

     static int foo (lua_State *L) {
       int n = lua_gettop(L);            /* 引数の数 */
       lua_Number sum = 0;
       int i;
       for (i = 1; i <= n; i++) {
         if (!lua_isnumber(L, i)) {
           lua_pushstring(L, "引数が正しくありません");
           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 extra);

スタックに extra 個の空きスロットを確保します。要求が満たせない場合は 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 の演算子の意味論に従います (つまりメタメソッドを呼ぶ場合があります)。 op を満たさない場合は 0 を返します。いずれかのインデックスが有効でない場合も 0 を返します。

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

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.5 を参照)。

`lua_copy`

[-0, +0, –]

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

有効なインデックス fromidx の要素を有効なインデックス toidx に移動します。どの要素もずらしません (つまりその位置の値を置き換えます)。

`lua_createtable`

[-0, +1, m]

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

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

`lua_dump`

[-0, +0, m]

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

関数をバイナリチャンクとしてダンプします。スタックトップにある Lua の関数を受け取り、バイナリチャンクを生成します。バイナリチャンクは、再びロードすると、ダンプ元のものと同等の関数が得られます。チャンクの各部を生成するにあたって、 lua_dump は出力関数 writer を呼びます (lua_Writer を参照)。 data は writer に渡されます。

戻り値は writer が最後に返したエラーコードです。 0 はエラーなしを表します。

処理対象の Lua の関数はスタックから取り除かれません。

`lua_error`

[-1, +0, v]

int lua_error (lua_State *L);

Lua のエラーを生成します。エラーメッセージ (実際には 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: ガベージコレクションのインクリメンタルステップを実行します。ステップの「サイズ」は data で制御します。大きな値は大きなステップを表しますが、具体的には決まっていません。ステップサイズを制御したい場合は、 data の値を実験的に調整する必要があります。このステップでガベージコレクションサイクルが終了した場合は 1 を返します。
LUA_GCSETPAUSE: コレクタの 停止期間 の新しい値を data に設定します。 (§2.5 を参照)。停止期間の前の値を返します。
LUA_GCSETSTEPMUL: コレクタの ステップ係数 の新しい値を data に設定します (§2.5 を参照)。ステップ係数の前の値を返します。
LUA_GCISRUNNING: コレクタが実行中かどうか (つまり停止中でないか) を示すブーリアン値を返します。
LUA_GCGEN: コレクタを世代別モードに変更します (§2.5 を参照)。
LUA_GCINC: コレクタをインクリメンタルモードに変更します。これはデフォルトのモードです。

これらのオプションについてのより詳しい情報は collectgarbage を参照してください。

`lua_getallocf`

[-0, +0, –]

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

指定したステートのメモリアロケータ関数を返します。 ud が NULL でない場合は、 lua_newstate に渡された不透明なポインタを *ud に格納します。

`lua_getctx`

[-0, +0, –]

int lua_getctx  (lua_State *L, int *ctx);

スレッドの状態とコンテキスト情報を取得します。この関数は継続関数から呼びます (§4.7 を参照)。

元の関数から呼ばれると、 lua_getctx は常に LUA_OK を返し、引数 ctx の値は変更しません。継続関数から呼ばれると、 lua_getctx は LUA_YIELD を返し、 ctx の値にコンテキスト情報を設定します (呼び出した関数の ctx 引数に継続関数と共に渡した値です)。

呼び出した関数が lua_pcallk の場合、呼び出しの中で発生したエラーを処理するときにも継続関数が呼ばれることがあります。つまり、 lua_pcallk によって呼ばれた関数の中でエラーが発生した場合、 Lua は元の関数に戻らず、代わりに継続関数を呼ぶことがあります。この場合、 lua_getctx を呼び出すと、エラーコード (lua_pcallk が返すはずだった値) を返し、 ctx の値には yield した場合のようにコンテキスト情報が設定されます。

`lua_getfield`

[-0, +1, e]

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

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

`lua_getglobal`

[-0, +1, e]

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

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

`lua_getmetatable`

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

int lua_getmetatable (lua_State *L, int index);

指定した受け入れ可能なインデックスの値のメタテーブルをスタックに積みます。その値がメタテーブルでなければ、 0 を返し、スタックには何も積みません。

`lua_gettable`

[-1, +1, e]

void 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, –]

void lua_getuservalue (lua_State *L, int index);

指定したインデックスのユーザーデータに関連付けられた Lua の値をスタックに積みます。この Lua の値はテーブルまたは nil のいずれかです。

`lua_insert`

[-1, +1, –]

void lua_insert (lua_State *L, int index);

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

`lua_Integer`

typedef ptrdiff_t lua_Integer;

符号付き整数値を表すために Lua の API で使われる型です。

デフォルトではこれは ptrdiff_t です。これは通常そのマシンが「快適に」扱える最も大きな符号付きの型です。

`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_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_len`

[-0, +1, e]

void lua_len (lua_State *L, int index);

指定した受け入れ可能インデックスの値の「長さ」を返します。これは Lua の '#' 演算子と同等です (§3.4.6 を参照)。結果はスタックに積まれます。

`lua_load`

[-0, +1, –]

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

Lua のチャンクをロードします (実行はしません)。エラーがなければ、 lua_load はコンパイルしたチャンクを Lua の関数としてスタックトップに積みます。そうでなければ、エラーメッセージを積みます。

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

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

lua_load 関数はユーザー定義の reader 関数を使ってチャンクを読み込みます (lua_Reader を参照)。 data 引数は reader 関数に渡される不透明な値です。

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

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

戻り値の関数は上位値をひとつ持っています。この上位値はレジストリの LUA_RIDX_GLOBALS インデックスに格納されているグローバル環境の値に設定されます (§4.5 を参照)。メインチャンクをロードするときは、この上位値は _ENV 変数になります (§2.2 を参照)。

`lua_newstate`

[-0, +0, –]

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

新しい独立したステート上で走る、新しいスレッドを作成します。スレッドまたはステートを作成できない (メモリ不足のため) 場合は NULL を返します。引数 f はアロケータ関数です。 Lua はこのステート用のすべてのメモリ割り当てをこの関数を使って行います。 2 番目の引数 ud は、アロケータを呼ぶときに毎回渡される不透明なポインタです。

`lua_newtable`

[-0, +1, m]

void lua_newtable (lua_State *L);

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

`lua_newthread`

[-0, +1, m]

lua_State *lua_newthread (lua_State *L);

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

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

`lua_newuserdata`

[-0, +1, m]

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

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

`lua_next`

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

int lua_next (lua_State *L, int index);

スタックからキーを取り除き、指定したインデックスのテーブルから、取り除いたキーの「次の」ペアを積みます。テーブルにそれ以上要素がない場合、 lua_next は何も積まず、 0 を返します。

通常、テーブルの巡回は以下のように行います。

     /* テーブルはスタックのインデックス 't' にあるとします */
     lua_pushnil(L);  /* 最初のキー */
     while (lua_next(L, t) != 0) {
       /* キー (インデックス -2) と値 (インデックス -1) を使います */
       printf("%s - %s\n",
              lua_typename(L, lua_type(L, -2)),
              lua_typename(L, lua_type(L, -1)));
       /* 値は取り除き、 キーは次の反復のために保持しておきます */
       lua_pop(L, 1);
     }

テーブルを巡回する間、それが実際に文字列であると判っている場合以外は、キーに対して直に lua_tolstring を呼んではいけません。 lua_tolstring は指定したインデックスの値を変更することを思い出してください。これは次の lua_next の呼び出しを混乱させます。

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

`lua_Number`

typedef double lua_Number;

Lua の数値型です。デフォルトではこれは double です。 luaconf.h で変更することもできます。このコンフィグレーションファイルファイルにより、数値を他の型 (float や long など) に変更できます。

`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 と同様に、 lua_pcall は関数と引数を常にスタックから取り除きます。

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 errfunc,
                int ctx,
                lua_CFunction 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, m]

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

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

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

n の最大値は 255 です。

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

`lua_pushcfunction`

[-0, +1, –]

void lua_pushcfunction (lua_State *L, lua_CFunction f);

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

Lua に登録しようとする関数は、引数と戻り値を受け渡す正しい手順に従わなければなりません (lua_CFunction を参照)。

lua_pushcfunction はマクロとして定義されています。

     #define lua_pushcfunction(L,f)  lua_pushcclosure(L,f,0)

ちなみに f は 2 回使われます。

`lua_pushfstring`

[-0, +1, m]

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

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

戻り値を受け取るための空間を確保する必要はありません。戻り値は Lua の文字列であり、 Lua がメモリ割り当て (およびガベージコレクションによる解放) の面倒をみます。
変換指定子は非常に制限されています。フラグや幅、精度はありません。変換指定子は以下のもののみが指定できます。
- '%%' (文字列に '%' を挿入します)
- '%s' (ゼロ終端文字列を挿入します。サイズ制限はありません)
- '%f' (lua_Number を挿入します)
- '%p' (ポインタを 16 進数表記で挿入します)
- '%d' (int を挿入します)
- '%c' (int をバイトとして挿入します)

`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, m]

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

lua_pushlstring と同等のマクロですが、 s がリテラル文字列の場合だけ使用できます。文字列の長さは自動的に計算されます。

`lua_pushlstring`

[-0, +1, m]

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

s が指す長さ len の文字列をスタックに積みます。 Lua は指定された文字列の内部コピーを作る (または再利用する) ため、この関数から戻った直後に 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, m]

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

s が指すゼロ終端文字列をスタックに積みます。 Lua は指定された文字列の内部コピーを作成する (または再利用する) ため、この関数から戻った直後に 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, m]

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, –]

void lua_rawget (lua_State *L, int index);

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

`lua_rawgeti`

[-0, +1, –]

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

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

`lua_rawgetp`

[-0, +1, –]

void 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, m]

void lua_rawset (lua_State *L, int index);

lua_settable と同様ですが、生の代入を行う (つまりメタメソッドを呼ばない) 点が異なります。

`lua_rawseti`

[-1, +0, m]

void lua_rawseti (lua_State *L, int index, int n);

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

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

`lua_rawsetp`

[-1, +0, m]

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

t[k] = v と同等のことを行います。ただし t は指定した有効なインデックスのテーブル、 k はポインタ 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 をゼロに設定してください。リーダー関数はゼロより大きな任意のサイズのチャンク片を返してかまいません。

`lua_register`

[-0, +0, e]

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

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

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

`lua_remove`

[-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 narg);

指定したスレッドのコルーチンを開始または再開します。

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

エラーが発生した場合、スタックは巻き戻されないので、デバッグ API を使って調べることができます。エラーメッセージがスタックトップに置かれています。

コルーチンを再開するには、 yield から返す戻り値の値だけをスタックに積み、 lua_resume を呼びます。

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

`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_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);

テーブルまたは nil をスタックから取り除き、その値を指定したインデックスのユーザーデータに関連付ける新しい値として設定します。

`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_toboolean`

[-0, +0, –]

int lua_toboolean (lua_State *L, int index);

指定した受け入れ可能なインデックスの値を C のブーリアン値 (0 または 1) に変換します。 Lua 内での条件式と同様に、 lua_toboolean は false および nil 以外のすべての値に対して真を返します。そうでなければ偽を返します。インデックスが有効でない場合も偽を返します。 (実際のブーリアン値のみを受け付けたい場合は、 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);

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

`lua_tointegerx`

[-0, +0, –]

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

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

数値が整数でなければ、何らかの適当な方法で丸められます。

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

`lua_tolstring`

[-0, +0, m]

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

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

lua_tolstring は Lua ステート内部の文字列への完全にアラインメントされたポインタを返します。この文字列は (C で行われるように) 最後の文字の後ろに常にゼロ ('\0') が付きますが、途中にゼロを含む場合もあります。 Lua はガベージコレクションを行うため、対応する値をスタックから取り除いた後は lua_tolstring から返されたポインタが有効である保証がなくなります。

`lua_tonumber`

[-0, +0, –]

lua_Number lua_tonumber (lua_State *L, int index);

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

`lua_tonumberx`

[-0, +0, –]

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

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

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

`lua_topointer`

[-0, +0, –]

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

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

この関数は通常、デバッグ情報のためだけに使われます。

`lua_tostring`

[-0, +0, m]

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

len に NULL を指定した場合の lua_tolstring と同等です。

`lua_tothread`

[-0, +0, –]

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

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

`lua_tounsigned`

[-0, +0, –]

lua_Unsigned lua_tounsigned (lua_State *L, int index);

isnum に NULL を指定した場合の lua_tounsignedx と同等です。

`lua_tounsignedx`

[-0, +0, –]

lua_Unsigned lua_tounsignedx (lua_State *L, int index, int *isnum);

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

数値が整数でなければ、何らかの適当な方法で丸められます。数値が表現可能な値の範囲外の場合は、表現可能な最大値+1 で割った余りに正規化されます。

isnum が 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
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 unsigned long lua_Unsigned;

符号無し整数値を表すために Lua の API で使われる型です。少なくとも 32 ビット以上はあります。

デフォルトではこれは unsigned int または unsigned long のどちらか 32 ビットの値を保持できる方です。

`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 で使うライター関数の型です。新しいチャンク片が生成されるたびに書き込むべきバッファ (p) 、そのサイズ (sz)、および lua_dump に指定した data 引数を渡されて lua_dump から呼ばれます。

ライターはエラーコードを返します。 0 はエラーなしを表します。それ以外の値はすべてエラーを表し、 lua_dump がそれ以上ライターを呼ぶのを止させます。

`lua_xmove`

[-?, +?, –]

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

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

from のスタックから n 個の値が取り除かれ、その値が to のスタックに積まれます。

`lua_yield`

[-?, +?, –]

int lua_yield  (lua_State *L, int nresults);

lua_yieldk と同等ですが、継続を取りません (§4.7 を参照)。そのため、スレッドが再開すると lua_yield を呼んだ関数を呼んだ関数に戻ります。

`lua_yieldk`

[-?, +?, –]

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

コルーチンを中断します。

この関数は以下のように C の関数の return 式としてのみ呼ぶべきです。

     return lua_yieldk (L, n, i, k);

この方法で C の関数が lua_yieldk を呼ぶと、実行中のスレッドは実行を中断し、このコルーチンを開始した lua_resume の呼び出しから戻ります。引数 nresults はスタック上の値の数を指定します。これらの値は lua_resume から返される戻り値になります。

コルーチンが再び再開するとき、 Lua は指定した継続関数 k を呼び、中断した C の関数の実行を継続します (§4.7 を参照)。この継続関数は前の関数から同じスタックを受け取ります。ただし戻り値は取り除かれ、 lua_resume に渡された引数に置き換えられます。さらに、継続関数は lua_getctx を呼ぶことによって値 ctx にアクセスできます。

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) */
  /* プライベート部分 */
  その他のフィールド
} lua_Debug;

関数またはアクティベーションレコードに関する様々な情報の断片を保持するために使う構造体です。 lua_getstack 関数は後の利用のためにこの構造体のプライベート部分だけをセットします。 lua_Debug の他の部分に有益な情報をセットするには、 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: この関数が末尾呼び出しによって呼ばれた場合 true になります。この場合、このレベルの呼び出し元はスタックに存在しません。
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), m]

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

特定の関数または関数呼び出しに関する情報を返します。

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

関数に関する情報を得るには、その関数をスタックに積み、 what に '>' で始まる文字列を指定します (この場合、 lua_getinfo はスタックトップからその関数を取り除きます。) 例えば、関数 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': 関数内の有効な行番号のインデックスを持つテーブルをスタックに積みます (有効な行 とは、何らかのコードに関連付いている行のことで、つまり、ブレークポイントを置くことができる場所のことです。有効でない行は、例えば空行やコメントなどです。)

エラーが発生すると 0 を返します (例えば what に無効なオプションを指定した場合)。

`lua_getlocal`

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

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

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

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

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

2 番目のケースでは、 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 を呼んだ関数です (ただし末尾呼び出しを除きます。この場合はスタックをカウントしません。) エラーがない場合は lua_getstack は 1 を返します。指定したレベルがスタックの深さより大きい場合は 0 を返します。

`lua_getupvalue`

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

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

クロージャの上位値に関する情報を取得します。 (Lua の関数では、上位値はその関数が使う外部ローカル変数で、そのためクロージャに取り込まれています。) lua_getupvalue は上位値のインデックス n を取り、その上位値の値をスタックに積み、その名前を返します。 funcindex はスタック中のそのクロージャを指定します (上位値はその関数全体を通してアクティブであり、特定の順番がありません。そのため、アルファベット順に番号が付けられています。)

指定したインデックスが上位値の数よりも大きい場合は NULL を返します (また、何も積みません)。 C の関数に対しては、上位値の名前はすべて空文字列 "" になります。

`lua_Hook`

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

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

フックが呼ばれるとき、引数 ar のフィールド event にフックのきっかけとなったイベントの種類が設定されます。 Lua はこれらのイベントを以下の定数で識別します。

LUA_HOOKCALL
LUA_HOOKRET
LUA_HOOKTAILCALL
LUA_HOOKLINE
LUA_HOOKCOUNT

さらに、 line イベントの場合はフィールド currentline も設定されます。 ar の他のフィールドの値を取得するには、 lua_getinfo を呼んでください。

call イベントの場合、通常は event が LUA_HOOKCALL になり、末尾呼び出しでは LUA_HOOKTAILCALL になります。この場合、対応する return イベントはありません。

フックを実行している間は、他のフックの呼び出しは無効化されます。そのため、フックから関数やチャンクを実行するために Lua を呼ぶと、それは一切フックを呼ばずに実行されます。

`lua_sethook`

[-0, +0, –]

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

mask をゼロに設定するとフックは無効になります。

`lua_setlocal`

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

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

指定したアクティベーションレコードのローカル変数の値を設定します。引数 ar および n は lua_getlocal と同様です (lua_getlocal を参照)。 lua_setlocal はスタックトップの値をその変数に代入し、その名前を返します。スタックトップの値は取り除かれます。

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

`lua_setupvalue`

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

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

クロージャの上位値の値を設定します。スタックトップの値を上位値に代入し、その名前を返します。スタックトップの値は取り除かれます。引数 funcindex および n は lua_getupvalue と同様です (lua_getupvalue を参照)。

インデックスが上位値の数より大きい場合は NULL を返します (また、何も積みません)。

`lua_upvalueid`

[-0, +0, –]

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

インデックス fidx のクロージャの n 番目の上位値に対する一意な ID を返します。引数 funcindex および n は lua_getupvalue と同様です (lua_getupvalue を参照) (ただし n は上位値の数より大きくてはいけません)。

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

`lua_upvaluejoin`

void lua_upvaluejoin (lua_State *L, int fidx1, int n1,
                                    int fidx2, int n2);

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

5 – 補助ライブラリ

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

補助ライブラリの関数と型はすべて、ヘッダファイル lauxlib.h で定義され、プレフィクス luaL_ が付いています。

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

補助ライブラリのいくつかの関数は、いくつか追加のスタックスロットを内部的に使用します。補助ライブラリの関数が使うスロットが 5 個未満のときは、スタックサイズはチェックしていません。充分なスロットがあるだろうと想定しています。

補助ライブラリのいくつかの関数は、 C の関数の引数をチェックするために使うことができます。エラーメッセージは引数によってフォーマットされるため (例えば "bad argument #1")、他のスタックの値をチェックするためにこれらの関数を使うべきではないでしょう。

luaL_check* という名前の関数は、チェック条件が満たされないときは常にエラーを発生させます。

5.1 – 関数と型

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

`luaL_addchar`

[-?, +?, m]

void luaL_addchar (luaL_Buffer *B, char c);

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

`luaL_addlstring`

[-?, +?, m]

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

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

`luaL_addsize`

[-?, +?, m]

void luaL_addsize (luaL_Buffer *B, size_t n);

バッファエリアにあらかじめコピーされた長さ n の文字列をバッファ B に追加します (luaL_prepbuffer を参照)。

`luaL_addstring`

[-?, +?, m]

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

s が指すゼロ終端文字列をバッファ B に追加します (luaL_Buffer を参照)。この文字列は埋め込まれたゼロを含むことができません。

`luaL_addvalue`

[-1, +?, m]

void luaL_addvalue (luaL_Buffer *B);

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

これはスタック上の要素を用いて値をバッファに追加する唯一の文字列バッファ関数です。

`luaL_argcheck`

[-0, +0, v]

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

cond が真かどうか確認します。もしそうでなければ、標準的なメッセージのエラーを発生させます。

`luaL_argerror`

[-0, +0, v]

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

コメントとして extramsg を含む標準的なメッセージのエラーを発生させます。

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

`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_pushresult(&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`

[-?, +?, m]

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 narg);

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

`luaL_checkint`

[-0, +0, v]

int luaL_checkint (lua_State *L, int narg);

narg 番目の引数が数値かどうか確認し、その数値を int にキャストして返します。

`luaL_checkinteger`

[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int narg);

narg 番目の引数が数値かどうか確認し、その数値を lua_Integer にキャストして返します。

`luaL_checklong`

[-0, +0, v]

long luaL_checklong (lua_State *L, int narg);

narg 番目の引数が数値かどうか確認し、その数値を long にキャストして返します。

`luaL_checklstring`

[-0, +0, v]

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

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

結果を得るために lua_tolstring を使うので、この関数が行う変換や問題点はすべてこちらにも適用されます。

`luaL_checknumber`

[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int narg);

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

`luaL_checkoption`

[-0, +0, v]

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

narg 番目の引数が文字列かどうか確認し、この文字列を配列 lst から検索します。 lst は NULL で終わっていなければなりません。文字列が見つかった場合は、その配列のインデックスを返します。引数が文字列でないか、文字列が見つからなかった場合は、エラーを発生させます。

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

この関数は文字列を 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 narg);

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

結果を得るために lua_tolstring を使うので、この関数が行う変換や問題点はすべてこちらにも適用されます。

`luaL_checktype`

[-0, +0, v]

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

narg 番目の引数が型 t かどうか確認します。 t に指定する型コードは lua_type を参照してください。

`luaL_checkudata`

[-0, +0, v]

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

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

`luaL_checkunsigned`

[-0, +0, v]

lua_Unsigned luaL_checkunsigned (lua_State *L, int narg);

narg 番目の引数が数値かどうか確認し、その数値を lua_Unsigned にキャストして返します。

`luaL_checkversion`

[-0, +0, –]

void luaL_checkversion (lua_State *L);

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

`luaL_dofile`

[-0, +?, m]

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, m]

int luaL_execresult (lua_State *L, int stat);

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

`luaL_fileresult`

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

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

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

`luaL_getmetafield`

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

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

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

`luaL_getmetatable`

[-0, +1, –]

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

レジストリ内の名前 tname に関連付けられたメタテーブルをスタックに積みます (luaL_newmetatable を参照)。

`luaL_getsubtable`

[-0, +1, m]

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

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

`luaL_gsub`

[-0, +1, m]

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

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

`luaL_len`

[-0, +1, e]

int luaL_len (lua_State *L, int index);

指定した受け入れ可能なインデックスの値の「長さ」を数値として返します。 Lua の '#' 演算子と同等です (§3.4.6 を参照)。この演算の結果が数値でなければエラーを発生します。 (メタメソッドが使われた場合にのみ発生する可能性があります。)

`luaL_loadbuffer`

[-0, +1, –]

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

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

`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, m]

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

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

`luaL_loadfilex`

[-0, +1, m]

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, m]

int luaL_newlib (lua_State *L, const luaL_Reg *l);

新しいテーブルを作成し、そこにリスト l 内の関数を登録します。以下のようなマクロとして実装されています。

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

`luaL_newlibtable`

[-0, +1, m]

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

配列 l 内のすべてのエントリを格納するために最適化されたサイズの新しいテーブルを作成します (ただしエントリを実際に格納はしません)。これは luaL_setfuncs と一緒に使うことを意図しています (luaL_newlib を参照)。

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

`luaL_newmetatable`

[-0, +1, m]

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

レジストリにキー tname がすでにあれば、 0 を返します。そうでなければ、ユーザーデータのメタテーブルとして使うための新しいテーブルを作成し、レジストリにキー tname でそれを登録し、 1 を返します。

いずれの場合でも、レジストリのキー 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_optint`

[-0, +0, v]

int luaL_optint (lua_State *L, int narg, int d);

narg 番目の引数が数値であれば、それを int にキャストした数値を返します。その引数が存在しないか nil であれば、 d を返します。いずれでもなければエラーを発生します。

`luaL_optinteger`

[-0, +0, v]

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

narg 番目の引数が数値であれば、それを lua_Integer にキャストした数値を返します。その引数が存在しないか nil であれば、 d を返します。いずれでもなければエラーを発生します。

`luaL_optlong`

[-0, +0, v]

long luaL_optlong (lua_State *L, int narg, long d);

narg 番目の引数が数値であれば、それを long にキャストした数値を返します。その引数が存在しないか nil であれば、 d を返します。いずれでもなければエラーを発生します。

`luaL_optlstring`

[-0, +0, v]

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

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

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

`luaL_optnumber`

[-0, +0, v]

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

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

`luaL_optstring`

[-0, +0, v]

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

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

`luaL_optunsigned`

[-0, +0, v]

lua_Unsigned luaL_optunsigned (lua_State *L,
                               int narg,
                               lua_Unsigned u);

narg 番目の引数が数値であれば、それを lua_Unsigned にキャストした数値を返します。その引数が存在しないか nil であれば、 u を返します。どちらでもなければエラーを発生します。

`luaL_prepbuffer`

[-?, +?, m]

char *luaL_prepbuffer (luaL_Buffer *B);

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

`luaL_prepbuffsize`

[-?, +?, m]

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

バッファ B へ追加する文字列を格納できるサイズ sz の空間のアドレスを返します (luaL_Buffer を参照)。文字列を実際にバッファに追加するには、その文字列をこの空間に格納してから、サイズを引数に luaL_addsize を呼んでください。

`luaL_pushresult`

[-?, +1, m]

void luaL_pushresult (luaL_Buffer *B);

バッファ B の使用を終えて、最終文字列をスタックトップに残します。

`luaL_pushresultsize`

[-?, +1, m]

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);

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

`luaL_ref`

[-1, +0, m]

int luaL_ref (lua_State *L, int t);

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

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

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

`luaL_Reg`

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

luaL_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);

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_testudata`

[-0, +0, m]

void *luaL_testudata (lua_State *L, int narg, 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, m]

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, m]

void luaL_where (lua_State *L, int lvl);

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

     chunkname:currentline:

レベル 0 は実行中の関数で、レベル 1 は実行中の関数を呼んだ関数で、以下同様です。

この関数はエラーメッセージのプレフィクスを構築するために使います。

6 – 標準ライブラリ

標準 Lua ライブラリは C の API を使って直接実装されている便利な関数を提供します。これらの関数には言語に必須のサービスを提供するもの (例えば type や getmetatable)、「外部」のサービスへのアクセスを提供するもの (例えば I/O)、 Lua 自身で実装可能ではあるものの非常に有用であるか重大な性能上の理由で C で実装する価値があるもの (例えば table.sort) などがあります。

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

基本ライブラリ (§6.1)
コルーチンライブラリ (§6.2)
パッケージライブラリ (§6.3)
文字列操作 (§6.4)
テーブル操作 (§6.5)
数学関数 (§6.6) (sin、 log など)
ビット演算 (§6.7)
入出力 (§6.8)
OS機能 (§6.9)
デバッグ機能 (§6.10)

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

これらのライブラリにアクセスするためには、 C のホストプログラムで luaL_openlibs 関数を呼ぶ必要があります。これはすべての標準ライブラリを開きます。代わりに、 luaL_requiref を使って以下の関数を呼ぶことで個別にライブラリを開くこともできます。

luaopen_base (基本ライブラリ)
luaopen_package (パッケージライブラリ)
luaopen_coroutine (コルーチンライブラリ)
luaopen_string (文字列ライブラリ)
luaopen_table (テーブルライブラリ)
luaopen_math (数学ライブラリ)
luaopen_bitlib (ビットライブラリ)
luaopen_io (I/O ライブラリ)
luaopen_os (オペレーティングシステムライブラリ)
luaopen_debug (デバッグライブラリ)

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

6.1 – 基本関数

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

`assert (v [, message])`

引数 v の値が偽 (つまり nil または false) の場合、エラーを発生します。そうでなければ、引数をすべて返します。 message はエラーメッセージです。省略した場合は、デフォルトの "assertion failed!" になります。

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

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

"collect": 完全なガベージコレクションサイクルを実行します。これはデフォルトの選択肢です。
"stop": ガベージコレクタの自動実行を停止します。再開するまで、コレクタは明示的に呼んだときだけ実行します。
"restart": ガベージコレクタの自動実行を再開します。
"count": Lua が使用中の合計メモリ (キロバイト) および合計メモリのバイト数を 1024 で割った余りの値を返します。最初の値は小数部を持っているため、以下の等式は常に成り立ちます。
```
     k, b = collectgarbage("count")
     assert(k*1024 == math.floor(k)*1024 + b)
```
(2 番目の戻り値は、数値に浮動小数点以外の型を使って Lua をコンパイルした場合に役に立ちます。)
"step": ガベージコレクションの 1 ステップを実行します。ステップの「サイズ」は arg で制御します。大きな値は大きなステップを意味しますが、具体的には決まっていません。ステップサイズを制御したければ、 arg の値を実験的に調整する必要があります。このステップでコレクションサイクルが終わった場合は true を返します。
"setpause": コレクタの 停止期間 の新しい値を arg に設定します (§2.5 を参照)。前の 停止期間 の値を返します。
"setstepmul": コレクタの ステップ係数 の新しい値を arg に設定します (§2.5 を参照)。前の ステップ の値を返します。
"isrunning": コレクタが実行中 (つまり停止中でない) を示すブーリアンを返します。
"generational": コレクタを世代別モードに変更します。これは実験的な機能です (§2.5 を参照)。
"incremental": コレクタをインクリメンタルモードに変更します。これはデフォルトのモードです。

`dofile ([filename])`

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

`error (message [, level])`

直近の保護されて呼ばれた関数を終了し、エラーメッセージとして message を返します。関数 error は決して戻りません。

通常、メッセージが文字列の場合は、メッセージの先頭にエラーの位置についての何らかの情報が追加されます。引数 level はエラーの位置をどのように得るかを指定します。レベル 1 (デフォルト) の場合、エラーの位置は error 関数を呼んだ場所です。レベル 2 は error を呼んだ関数を呼んだ場所で、以下同様です。レベルに 0 を指定するとエラーの位置情報がメッセージに追加されません。

`_G`

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

`getmetatable (object)`

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

`ipairs (t)`

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

そうでなければ、イテレータ関数、テーブル t、および 0 の 3 つの値を返します。したがって、以下の文は

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

そのテーブルの整数キーが存在しない最初のところまで、ペア (1,t[1])、 (2,t[2])、 ... を巡回します。

`load (ld [, source [, mode [, env]]])`

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

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

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

結果の関数に上位値があれば、その最初の上位値はグローバル環境の値、または引数 env が指定されていれば、その値に設定されます。メインチャンクをロードする場合、最初の上位値は _ENV 変数です。 §2.2 を参照。

source はチャンクのソースとして、エラーメッセージやデバッグ情報のために使われます (§4.9 を参照)。省略した場合、 ld が文字列であれば、デフォルトで ld になります。そうでなければ、"=(load)" になります。

文字列 mode はチャンクにテキストやバイナリ (つまりコンパイル済みのチャンク) を許可するかどうかを指定します。以下のいずれかを指定できます。デフォルトは "bt" です。

文字列 "b" (バイナリチャンクのみ)
文字列 "t" (テキストチャンクのみ)
文字列 "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 がエラーをキャッチし、ステータスコードを返します。最初の戻り値はステータスコード (ブーリアン) で、呼び出しがエラーを起こさずに成功した場合は真を返します。その場合、 pcall は最初の戻り値の後に、その呼び出しからの戻り値をすべて返します。何らかのエラーが発生した場合、 pcall は false とエラーメッセージを返します。

`print (···)`

任意の数の引数を受け取り、それらの値を tostring 関数で文字列に変換して stdout に表示します。 print は書式化出力を意図しておらず、例えばデバッグ用に、値を表示する簡便な方法として用意されているにすぎません。出力を完全に制御するには、 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 は任意の値を指定できます。

table を返します。

`select (index, ···)`

index が数値であれば、 index 番目の引数の後にあるすべての引数を返します。負のインデックスを指定すると後ろから数えます (-1 は最後の引数です)。そうでなければ、 index は文字列 "#" でなければならず、その場合 select は追加の引数の合計数を返します。

`setmetatable (table, metatable)`

指定したテーブルにメタテーブルを設定します。 (それ以外の型のメタテーブルは Lua から変更することはできません。 C からのみできます。) metatable が nil の場合は、指定したテーブルからメタテーブルを取り除きます。元のメタテーブルに "__metatable" フィールドがある場合はエラーが発生します。

table を返します。

`tonumber (e [, base])`

base を指定せずに呼ぶと、引数を数値に変換しようと試みます。引数がすでに数値であるか、数値に変換可能な文字列 (§3.4.2 を参照) であれば、その数値を返します。そうでなければ nil を返します。

base を指定した場合、 e はその基数において整数として解釈可能な文字列でなければなりません。基数には 2 から 36 までの整数を指定できます。 11 以上の基数の場合は、 '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.2" です。

`xpcall (f, msgh [, arg1, ···])`

pcall と同様です。ただし新しいメッセージハンドラ msgh を設定します。

6.2 – コルーチン操作

コルーチンに関する操作は基本ライブラリの一部として提供され、 coroutine テーブルに置かれます。コルーチンの一般的な説明は §2.6 を参照してください。

`coroutine.create (f)`

本体を f とする新しいコルーチンを作成します。 f は Lua の関数でなければなりません。この新しいコルーチンである "thread" 型のオブジェクトを返します。

`coroutine.resume (co [, val1, ···])`

コルーチン co の実行を開始または再開します。コルーチンを初めて resume すると、その本体の実行を開始します。値 val1, ... はその本体の関数に引数として渡されます。コルーチンが中断していた場合は、それを再開します。値 val1, ... は yield からの戻り値として渡されます。

コルーチンがエラーなく実行された場合は、 true および yield に渡されたすべての引数 (コルーチンが中断した場合) または本体の関数から返されたすべての値 (コルーチンが終了した場合) を返します。エラーが発生した場合は、 false およびエラーメッセージを返します。

`coroutine.running ()`

実行中のコルーチンおよびブーリアンを返します。ブーリアンは実行中のコルーチンがメインの場合 true になります。

`coroutine.status (co)`

コルーチン co の状態を文字列として返します。

"running": コルーチンが実行中の場合。
"suspended": コルーチンが yield 呼び出しで中断している場合、またはまだ実行開始していない場合。
"normal": コルーチンはアクティブであるが、実行中ではない場合 (つまり他のコルーチンを再開した場合)。
"dead": コルーチンが本体の実行を終了した場合、またはエラーで停止した場合。

`coroutine.wrap (f)`

本体を f とする新しいコルーチンを作成します。 f は Lua の関数でなければなりません。呼ばれるたびにコルーチンを再開する関数を返します。この関数に渡された引数はすべて、 resume の追加の引数と同様に動作します。最初のブーリアンを除いて、 resume の戻り値と同じ値を返します。エラーが発生した場合はそのエラーを伝搬します。

`coroutine.yield (···)`

呼び出し元のコルーチンの実行を中断します。 yield に渡した引数はすべて、 resume に追加の戻り値として渡されます。

6.3 – モジュール

パッケージライブラリは Lua でモジュールをロードするための基本的な機能を提供します。このパッケージはグローバル環境に直接 require 関数をエクスポートします。他のものはすべて package テーブルに置かれます。

`require (modname)`

指定したモジュールをロードします。 modname がロード済みかどうかを知るために、まずテーブル package.loaded を調べます。もしあれば、 require は package.loaded[modname] に格納されている値を返します。そうでなければ、そのモジュールのための ローダー を探します。

ローダーを探すにあたって、シーケンス package.searchers がガイドとして用いられます。このシーケンスを変更すると、モジュールの探し方を変更できます。以下の説明は package.searchers のデフォルトの構成に基づいています。

まず package.preload[modname] が調べられます。その値があった場合は、その値 (関数であるべきです) がローダーになります。なかった場合は、 package.path に格納されているパスを使って Lua のローダーを探します。それも失敗した場合は、 package.cpath に格納されているパスを使って C のローダーを探します。それも失敗した場合は、 オールインワン ローダーを試みます (package.searchers を参照)。

ローダーが見つかると、 modname とローダーを得た方法に依存する追加の値の 2 つを引数として、そのローダーが呼ばれます (ローダーがファイル由来の場合、この追加の値はそのファイル名です)。ローダーが nil 以外の値を返すと、その戻り値が package.loaded[modname] に代入されます。ローダーが nil 以外の値を返さず、 package.loaded[modname] に何も代入されていなければ、そのエントリに true が代入されます。いずれの場合でも、 require は package.loaded[modname] の最終的な値を返します。

モジュールのロードまたは実行中に何らかのエラーが発生するか、またはそのモジュールのためのローダーが見つからなければ、エラーが発生します。

`package.config`

コンパイル時のパッケージの構成を説明する文字列です。この文字列は以下の一連の行から構成されます。

1 行目はディレクトリ区切り文字列です。デフォルトは、 Windows では '\' で、他のすべてのシステムでは '/' です。
2 行目はパス中のテンプレートを区切る文字です。デフォルトは ';' です。
3 行目はテンプレート中の置換ポイントを示す文字列です。デフォルトは '?' です。
4 行目は実行可能ファイルのディレクトリに置き換えられる、 Windows ではパス中の、文字列です。デフォルトは '!' です。
5 行目は luaopen_ 関数の名前を構築するときにそれより前のテキストをすべて無視する印です。デフォルトは '-' です。

`package.cpath`

C のローダーを探すために require が使用するパスです。

環境変数 LUA_CPATH_5_2 または環境変数 LUA_CPATH または luaconf.h に定義されているデフォルトのパスを使って、 Lua のパス package.path を初期化するのと同じ方法で、 C のパス package.cpath は初期化されます。

`package.loaded`

モジュールがロード済みであるかどうかを制御するために require が使用するテーブルです。モジュール modname が require され、 package.loaded[modname] が偽でなければ、 require は単純にそこに格納されている値を返します。

この変数は実際のテーブルを参照しているだけです。この変数に代入しても require が使用するテーブルは変わりません。

`package.loadlib (libname, funcname)`

ホストプログラムを C のライブラリ libname に動的リンクします。

funcname が "*" の場合は、単にそのライブラリをリンクし、ライブラリがエクスポートしているシンボルを他の動的リンクライブラリから利用できるようにするだけです。そうでなければ、そのライブラリ内の関数 funcname を探し、この関数を C の関数として返します。 (そのため、 funcname は 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_2、または環境変数 LUA_PATH、またはこれらの環境変数が定義されていない場合 luaconf.h に定義されているデフォルトのパスで初期化されます。環境変数の値の中に ";;" があれば、デフォルトのパスで置き換えられます。

`package.preload`

特定のモジュール用のローダーを格納するテーブルです (require を参照)。

この変数は実際のテーブルを参照しているだけです。この変数に代入しても require が使用するテーブルは変わりません。

`package.searchers`

モジュールのロード方法を制御するために require が使用するテーブルです。

このテーブルの各エントリは 検索関数 です。モジュールを検索するとき、 require はモジュール名 (require に指定した引数) を引数にしてこれらの各検索関数を昇順で呼びます。検索関数は別の関数 (モジュールの ローダー) およびそのローダーに渡される追加の引数、またはモジュールを見つけられなかった理由を説明する文字列 (または何も言うべきことがなければ nil) を返すことができます。

このテーブルは 4 つの検索関数で初期化されます。

最初の検索関数は単純に 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.v1-b.c であれば、関数の名前は luaopen_b_c になります。

4 番目の検索関数は オールインワンローダー を試みます。これは指定したモジュールのルート名に対するライブラリを C のパスから探します。例えば、 a.b.c が要求された場合、 a に対する C のライブラリを検索します。それが見つかれば、そのライブラリ内からサブモジュール用のオープン関数を探します。上の例では、 luaopen_a_b_c になります。この機能は、パッケージが複数の C のサブモジュールを、各サブモジュールそれぞれ独自のオープン関数を維持したまま、ひとつのライブラリにパックするために使います。

最初の検索関数 (preload) 以外はすべて、 package.searchpath が返すのと同様に、見つかったモジュールのファイル名を追加の値として返します。最初の検索関数は追加の値を返しません。

`package.searchpath (name, path [, sep [, rep]])`

指定した path から指定した name を検索します。

パスはセミコロン区切りの テンプレート 文字列です。各テンプレートに対して、テンプレート内の疑問符を、 name 内の各 sep (デフォルトはドット) をシステムのディレクトリ区切り文字で置き換えたものに置き換え、そしてその結果のファイル名のオープンを試みます。 sep が空文字列であれば、その置き換えは行われません。

例えば、パスが以下の文字列である場合、

     "./?.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) と書くことができます。

文字列ライブラリはシングルバイトの文字コードを想定しています。

`string.byte (s [, i [, j]])`

文字 s[i]、 s[i+1]、 ...、 s[j] の内部の数値コードを返します。 i のデフォルト値は 1、 j のデフォルト値は i です。

数値コードはプラットフォームを超えられる可搬性があるとは限りません。

`string.char (···)`

0 個以上の整数を受け取り、対応する引数と同じ内部の数値コードを持つ文字からなる、引数の数と等しい長さの文字列を返します。

数値コードはプラットフォームを超えられる可搬性があるとは限りません。

`string.dump (function)`

指定した関数のバイナリ表現の文字列を返します。後にこの文字列に対して load を呼ぶと、その関数のコピー (ただし新しい上位値を持つ) を得ることができます。

`string.find (s, pattern [, init [, plain]])`

文字列 s 中の pattern の最初のマッチを検索します。マッチが見つかった場合、 find はそのマッチした最初と最後を表す s のインデックスを返します。見つからない場合は nil を返します。 3 番目の省略可能な数値引数 init は、検索の開始位置を指定します。デフォルト値は 1 で、負の値を指定することもできます。 4 番目の省略可能な引数 plain に true を指定すると、パターンマッチング機能はオフになり、 pattern 内のいかなる文字も魔法の文字とみなされなくなり、普通の「部分文字列を探す」操作を実行します。 plain を指定する場合は init も指定しなければならないことに注意してください。

パターンにキャプチャがある場合は、マッチに成功したとき、 2 つのインデックスの後にキャプチャした値も返されます。

`string.format (formatstring, ···)`

最初の引数 (文字列でなければならない) で指定した記述に従って、可変長引数を書式化したものを返します。書式文字列は 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 もまた引数として数値を期待しますが、この数値の範囲は基礎となっている C の実装によって制限される場合があります。オプション o、 u、 X および x は負の値は取れません。オプション q は文字列を期待し、オプション s は埋め込まれたを持たない文字列を期待します。オプション s の引数が文字列でない場合は、 tostring と同じルールに従って文字列に変換します。

`string.gmatch (s, pattern)`

呼ばれるたびに文字列 s 中の pattern から次のキャプチャを返すイテレータ関数を返します。 pattern にキャプチャがなければ、呼ぶたびにマッチした全体を返します。

例えば、以下のループは文字列 s 中のすべての単語について巡回し、 1 行に 1 つ表示するループです。

     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 中の pattern の出現をすべて (指定した場合は最初の n 個) repl で指定した置換文字列に置き換えたものを返します。 repl には文字列、テーブル、または関数を指定できます。また gsub は 2 番目の戻り値としてマッチが出現した合計数も返します。 gsub という名前は Global SUBstitution から来ています。

repl が文字列の場合は、その文字列が置換に使われます。文字 % はエスケープ文字として働きます。 repl 中の %d (ただし d は 1 から 9) は d 番目のキャプチャした部分文字列の値 (下を参照) を表します。 %0 はマッチ全体を表し、 %% は単一の % を表します。

repl がテーブルの場合は、各マッチごとに最初のキャプチャをキーとしてテーブルを引きます。パターンにキャプチャがなければ、マッチ全体をキーとして使います。

repl が関数の場合は、その関数はマッチが現れるたびに呼ばれ、すべてのキャプチャされた部分文字列が順番通りに引数として渡されます。パターンにキャプチャがなければ、マッチ全体が単一の引数として渡されます。

テーブル検索または関数呼び出しの戻り値が文字列または数値であれば、それが置換文字列として使われます。そうでなく、 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.2"}
     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
     --> x="lua-5.2.tar.gz"

`string.len (s)`

文字列を受け取り、その長さを返します。空文字列 "" の長さは 0 です。埋め込まれたゼロもカウントされるので、 "a\000bc\000" の長さは 5 です。

`string.lower (s)`

文字列を受け取り、その文字列中の大文字をすべて小文字に変更した文字列を返します。それ以外の文字に対しては何もしません。何が大文字であるかの定義は現在のロケールに依存します。

`string.match (s, pattern [, init])`

文字列 s 中の pattern の最初の マッチ を検索します。見つかった場合は、パターン中のキャプチャを返します。見つからない場合は nil を返します。 pattern にキャプチャがなければ、マッチ全体が返されます。 3 番目の省略可能な引数 init は検索を開始する場所を指定します。デフォルト値は 1 で、負の値も指定できます。

`string.rep (s, n [, sep])`

n 個の文字列 s を区切り文字列 sep で連結した文字列を返します。 sep のデフォルト値は空文字列です (つまり区切り文字列はありません)。

`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 より小さくなる場合、 i は 1 に修正されます。 j が文字列の長さより大きい場合、 j はその長さに修正されます。これらの修正後、 i が j より大きくなった場合は、空文字列を返します。

`string.upper (s)`

文字列を受け取り、その文字列中の小文字をすべて大文字に変更した文字列を返します。それ以外の文字に対しては何もしません。何が小文字であるかの定義は現在のロケールに依存します。

6.4.1 – パターン

文字クラス:

文字クラス は文字の集合を表すために使われます。文字クラスの記述では以下の組み合わせが使用できます。

x: (ただし x は 魔法の文字 ^$()%.[]*+-? 以外の文字) 文字 x 自身を表します。
.: (ドット) すべての文字を表します。
%a: すべてのレターを表します。
%c: すべての制御文字を表します。
%d: すべての数字を表します。
%g: 空白を除くすべての印刷可能文字を表します。
%l: すべての小文字を表します。
%p: すべての句読点を表します。
%s: すべての空白文字を表します。
%u: すべての大文字を表します。
%w: すべての英数字を表します。
%x: すべての 16 進数字を表します。
%x: (ただし x は英数以外の文字) 文字 x を表します。これは魔法の文字をエスケープする標準の方法です。すべての句読点 (魔法でない文字も) は '%' を前置してパターン中でそれ自身を表すことができます。
[set]: set 中のすべての文字の和であるクラスを表します。 '-' を使って文字の範囲を指定することができます。 set 中の部品として上で説明した %x クラスもすべて使うことができます。 set 中のそれ以外の文字はすべてそれ自身を表します。例えば [%w_] (または [_%w]) はすべての英数文字にアンダースコアを加えたものを表し、 [0-7] は 8 進数字を表し、 [0-7%l%-] は 8 進数字に小文字と '-' を加えたものを表します。
範囲とクラスの間の相互作用は定義されていません。そのため [%a-z] や [a-%%] のようなパターンは無意味です。
[^set]: set の補集合を表します。 set は上で呼べたように解釈されます。

単一の文字で表されるクラス (%a、 %c など) はすべて、対応する大文字でそのクラスの補集合を表します。例えば、 %S はすべての非空白文字を表します。

レター、空白、およびその他の文字グループの定義は現在のロケールに依存します。例えば、クラス [a-z] は %l と同等でない場合があります。

パターン項目:

パターン項目 は以下のいずれかです。

単一の文字クラス。そのクラスの任意の文字にマッチします。
単一の文字クラスに '*' が続いたもの。そのクラスの文字の 0 回以上の繰り返しにマッチします。この繰り返し項目は常に最も長い可能なものにマッチします。
単一の文字クラスに '+' が続いたもの。そのクラスの文字の 1 回以上の繰り返しにマッチします。この繰り返し項目は常に最も長い可能なものにマッチします。
単一の文字クラスに '-' が続いたもの。そのクラスの文字の 0 回以上の繰り返しにマッチします。 '*' と異なり、この繰り返し項目は最も短い可能なものにマッチします。
単一の文字クラスに '?' が続いたもの。そのクラスの文字の 0 回または 1 回の出現にマッチします。
%n (ただし n は 1 から 9)。この項目は n 番目のキャプチャされた文字列と等しい部分文字列にマッチします (下を参照)。
%bxy (ただし x および y は 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 になります。

特殊なケースとして、空のキャプチャ () は現在位置 (数値) をキャプチャします。例えば、文字列 "flaaap" にパターン "()aa()" を適用すると、 2 つのキャプチャ 3 および 5 が得られます。

6.5 – テーブル操作

このライブラリはテーブル操作のための汎用の関数を提供します。すべての関数は table テーブルに提供されます。

テーブルの長さを扱う操作では、テーブルは正しいシーケンスであるか、または __len メタメソッド (§3.4.6 を参照) を持っていなければならないことを覚えておいてください。すべての関数は、引数として渡されたテーブル内の、数値以外のキーは無視します。

性能上の理由により、これらの関数によって行われるすべてのテーブルアクセス (get および set) は生です。

`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 に要素 value を挿入し、要素 list[pos], list[pos+1], ···, list[#list] を上へずらします。 pos のデフォルト値は #list+1 です。そのため table.insert(t,x) は x をリスト t の最後に挿入します。

`table.pack (···)`

すべての引数をキー 1、 2、 (以下略) に格納し、引数の数をフィールド "n" に格納したテーブルを返します。返されたテーブルはシーケンスでない場合があります。

`table.remove (list [, pos])`

list から位置 pos の要素を取り除き、要素 list[pos+1], list[pos+2], ···, list[#list] を下へずらし、要素 list[#list] を消し去ります。取り除かれた要素の値を返します。 pos のデフォルト値は #list です。そのため table.remove(t) はリスト t の最後の要素を取り除きます。

`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.6 – 数学関数

このライブラリは標準 C の数学ライブラリへのインタフェイスです。すべての関数は math テーブルに提供されます。

`math.abs (x)`

x の絶対値を返します。

`math.acos (x)`

x の逆余弦を (ラジアンで) 返します。

`math.asin (x)`

x の逆正弦を (ラジアンで) 返します。

`math.atan (x)`

x の逆正接を (ラジアンで) 返します。

`math.atan2 (y, x)`

y/x の逆正接を (ラジアンで) 返します。ただし結果の象限を決めるために両方の引数の符号を使います (また x がゼロの場合も正しく処理します)。

`math.ceil (x)`

x 以上で最も小さい整数を返します。

`math.cos (x)`

x (ラジアンで指定) の余弦を返します。

`math.cosh (x)`

x の双曲線余弦を返します。

`math.deg (x)`

角度 x (ラジアンで指定) を度で返します。

`math.exp (x)`

e^x の値を返します。

`math.floor (x)`

x 以下で最大の整数を返します。

`math.fmod (x, y)`

x を y で割ってゼロに向かって丸めた商の余りを返します。

`math.frexp (x)`

x = m2^e であるような m および e を返します。ただし e は整数で、 m は範囲 [0.5, 1) の絶対値 (x がゼロの場合はゼロ) です。

`math.huge`

HUGE_VAL の値です。他のいかなる数値よりも大きいまたは等しい値です。

`math.ldexp (m, e)`

m2^e を返します (e は整数であるべきです)。

`math.log (x [, base])`

指定した基数における x の対数を返します。 base のデフォルト値は e です (つまり x の自然対数を返します)。

`math.max (x, ···)`

引数の最大値を返します。

`math.min (x, ···)`

引数の最小値を返します。

`math.modf (x)`

2 つの値、 x の整数部および x の指数部を返します。

`math.pi`

円周率の値です。

`math.pow (x, y)`

x^y を返します。 (式 x^y を使ってこの値を計算することもできます。)

`math.rad (x)`

角度 x (度で指定) をラジアンで返します。

`math.random ([m [, n]])`

標準 C が提供している単純な疑似乱数生成関数 rand へのインタフェイスです。 (統計的な性質は保証されません。)

引数なしで呼ぶと、範囲 [0,1) の一様な疑似乱数の実数を返します。ひとつの整数 m を指定して呼ぶと、範囲 [1, m] の一様な疑似乱数の整数を返します。 2 つの整数 m および n を指定して呼ぶと、範囲 [m, n] の一様な疑似乱数の整数を返します。

`math.randomseed (x)`

疑似乱数生成器の「種」として x を設定します。同じ種を与えると同じ数列を生成します。

`math.sin (x)`

x (ラジアンで指定) の正弦を返します。

`math.sinh (x)`

x の双曲線正弦を返します。

`math.sqrt (x)`

x の平方根を返します。 (式 x^0.5 を使ってこの値を計算することもできます。)

`math.tan (x)`

x (ラジアンで指定) の正接を返します。

`math.tanh (x)`

x の双曲線正接を返します。

6.7 – ビット演算

このライブラリはビット演算を提供します。すべての関数は bit32 テーブルに提供されます。

特に記載がない限り、すべての関数は範囲 (-2⁵¹,+2⁵¹) の数値引数を受け付けますが、各引数は 2³² で割った余りに正規化され、 (何らかの適当な方法で) 整数に丸められます。それにより最終的な値は [0,2³² - 1] の範囲になります。同様に、すべての戻り値も [0,2³² - 1] の範囲になります。 bit32.bnot(0) の結果である 0xFFFFFFFF は -1 とは異なることに注意してください。

`bit32.arshift (x, disp)`

x を disp ビット右にシフトした数値を返します。数値 disp は表現可能な任意の整数を指定できます。負の変位を指定すると左へシフトします。

このシフト演算は算術シフトと呼ばれるものです。左端の空きビットは x の最上位ビットのコピーで埋められ、右端の空きビットはゼロで埋められます。ちなみに、変位の絶対値が 31 より大きい場合、結果はゼロか 0xFFFFFFFF になります (元のビットはすべてシフトされ追い出されます)。

`bit32.band (···)`

引数のビットごとの論理積を返します。

`bit32.bnot (x)`

x のビットごとの否定を返します。任意の整数 x について、以下の等式が成り立ちます。

     assert(bit32.bnot(x) == (-1 - x) % 2^32)

`bit32.bor (···)`

引数のビットごとの論理和を返します。

`bit32.btest (···)`

引数のビットごとの論理積がゼロと異なるかどうかを示すブーリアンを返します。

`bit32.bxor (···)`

引数のビットごとの排他的論理和を返します。

`bit32.extract (n, field [, width])`

n の field 番目から field + width - 1 番目のビットからなる符号なし整数を返します。ビットは 0 (最下位ビット) から数え、 31 (最上位ビット) までです。アクセスするすべてのビットは [0, 31] の範囲内でなければなりません。

width のデフォルト値は 1 です。

`bit32.replace (n, v, field [, width])`

n の field 番目から field + width - 1 番目のビットを v で置き換えた値を返します。 field および width の詳細について bit32.extract を参照してください。

`bit32.lrotate (x, disp)`

x を disp ビット左にローテートした数値を返します。数値 disp は任意の表現可能な整数を指定できます。

任意の変位について、以下の等式が成り立ちます。

     assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))

ちなみに、負の変位を指定すると右へローテートします。

`bit32.lshift (x, disp)`

x を disp ビット左へシフトした値を返します。数値 disp は任意の表現可能な整数を指定できます。負の変位を指定すると右へシフトします。いずれの方向でも空きビットはゼロで埋められます。ちなみに、変位の絶対値が 31 より大きい場合、結果はゼロになります (すべてのビットがシフトされ追い出されます)。

正の変位に対しては以下の等式が成り立ちます。

     assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)

`bit32.rrotate (x, disp)`

x を disp ビット右へローテートした数値を返します。数値 disp は任意の表現可能な数値を指定できます。

任意の有効な変位について、以下の等式が成り立ちます。

     assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32))

ちなみに、負の変位を指定すると左へローテートします。

`bit32.rshift (x, disp)`

x を disp ビット右へシフトした数値を返します。数値 disp は任意の表現可能な整数を指定できます。負の変位を指定すると左へシフトします。いずれの方向でも空きビットはゼロで埋められます。ちなみに、変位の絶対値が 31 より大きい場合、結果はゼロになります (すべてのビットがシフトされ追い出されます)。

正の変位に対しては以下の等式が成り立ちます。

     assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))

このシフト演算は論理シフトと呼ばれるものです。

6.8 – 入出力機能

I/O ライブラリはファイル操作のための 2 つの異なったスタイルを提供します。ひとつめは暗黙のファイルディスクリプタを使うものです。つまり、デフォルト入力ファイルとデフォルト出力ファイルを設定し、すべての入出力操作はこれらデフォルトファイルに対して行います。ふたつめは明示的なファイルディスクリプタを使うものです。

暗黙のファイルディスクリプタを使う場合、すべての操作は io テーブルによって提供されます。明示的なファイルディスクリプタを使う場合、 io.open 関数が返すファイルディスクリプタを受け取り、すべての操作をこのファイルディスクリプタのメソッドによって行います。

io テーブルはまた C のものと同様の意味を持つ 3 つの定義済みファイルディスクリプタ io.stdin、 io.stdout および io.stderr を提供しています。 I/O ライブラリはこれらのファイルは決してクローズしません。

特に記載がない限り、すべての I/O 関数は失敗時に nil (と、 2 番目の戻り値としてエラーメッセージ、 3 番目の戻り値としてシステム依存のエラーコード) を返し、成功時は nil 以外の何らかの値を返します。

`io.close ([file])`

file:close() と同等です。 file を省略すると、デフォルト出力ファイルを閉じます。

`io.flush ()`

io.output():flush() と同等です。

`io.input ([file])`

ファイル名を指定して呼ぶと、その名前のファイルを (テキストモードで) 開き、そのハンドルをデフォルト入力ファイルとして設定します。ファイルハンドルを指定して呼ぶと、単純にそのファイルハンドルをデフォルト入力ファイルとして設定します。引数なしで呼ぶと、現在のデフォルト入力ファイルを返します。

エラーの場合は、エラーコードを返す代わりにエラーを発生させます。

`io.lines ([filename] ···)`

指定したファイル名を読み込みモードで開き、その開いたファイルに対して file:lines(···) と同様に動作するイテレータ関数を返します。イテレータ関数がファイルの終わりを検知すると、 (ループを終了するために) nil を返し、自動的にそのファイルを閉じます。

io.lines() (ファイル名なし) の呼び出しは io.input():lines() と同等です。つまり、デフォルト入力ファイルの各行を巡回します。この場合はループ終了時にファイルを閉じません。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

`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": 数値を読み込みます。これは文字列の代わりに数値を返す唯一の書式です。
"*a": 現在の位置から始まって、ファイル全体を読み込みます。ファイルの終わりであれば、空文字列を返します。
"*l": 次の行を読み込みます。改行は飛ばします。ファイルの終わりでは nil を返します。これはデフォルトの書式です。
"*L": 次の行を読み込みます。改行は保持します (もしあれば)。ファイルの終わりでは nil を返します。
数値: 指定した数値のバイト数 (最大) からなる文字列を読み込みます。ファイルの終わりでは nil を返します。数値がゼロの場合は、何も読まずに空文字列を返します。

`file:seek ([whence [, offset]])`

offset で指定した位置に文字列 whence で指定した基準を足した位置にファイルの位置を設定し、先頭から数えたファイルの位置を取得します。 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" でなければ、 C の strftime 関数と同じルールに従って書式化した日付を文字列として返します。

引数なしで呼ぶと、ホストシステムと現在のロケールに依存した適当な日付と時刻の表現を返します (つまり os.date() は os.date("%c") と同等です)。

システムによってはこの関数はスレッドセーフではありません。

`os.difftime (t2, t1)`

時刻 t1 から時刻 t2 までの秒数を返します。 POSIX、 Windows、その他いくつかのシステムでは、この値は t2-t1 です。

`os.execute ([command])`

C の system 関数と同等です。オペレーティングシステムのシェルによって実行される command を指定します。コマンドが正常終了した場合は最初の戻り値が true になり、そうでなければ nil になります。この最初の戻り値に続いて、以下のような文字列と数値を返します。

"exit": コマンドは普通に終了しました。後続の数値はコマンドの終了ステータスです。
"signal": コマンドはシグナルによって終了しました。後続の数値はコマンドを終了させたシグナルです。

command を指定せずに呼ぶと、シェルが利用可能かどうかを示すブーリアンを返します。

`os.exit ([code [, close])`

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 のロケールに設定します。

第 1 引数に nil を指定して呼ぶと、指定したカテゴリの現在のロケールの名前を単に返します。

`os.time ([table])`

引数なしで呼ぶと、現在の時刻を返します。引数を指定すると、そのテーブルで指定した日付と時刻を表現する時刻を返します。このテーブルには以下のフィールドが必須です。

year
month
day

さらに以下のフィールドも指定できます。

hour (デフォルトは 12)
min (デフォルトは 0)
sec (デフォルトは 0)
isdst (デフォルトは nil)

これらのフィールドの説明は os.date 関数を参照してください。

戻り値はシステム依存の意味を持つ数値です。 POSIX、 Windows、その他いくつかのシステムでは、この数値は、ある特定の開始時刻 (「エポック」) からの経過秒数です。それ以外のシステムでは、その意味は決まっていません。 time の戻り値は date および difftime への引数としてのみ使うことができます。

`os.tmpname ()`

テンポラリファイルとして使うことのできるファイル名の文字列を返します。このファイルは使う前に明示的に開かなければならず、使い終わったときに明示的に削除しなければなりません。

POSIX システムでは、セキュリティ上のリスクを避けるために、この関数はその名前のファイルを作成します。 (名前を取得してからファイルを作成するまでの間に他の誰かがまずいパーミッションでそのファイルを作成する可能性があるためです。) その場合でも使うときにはファイルを開かなければならず、また (結局使わなかった場合でも) 削除する必要があります。

可能であれば io.tmpfile を使う方が良いです。プログラムの終了時に自動的にファイルを削除してくれます。

6.10 – デバッグライブラリ

このライブラリは Lua のプログラムにデバッグインタフェイス (§4.9) の機能を提供します。このライブラリを使うときは特に注意してください。この関数のいくつかは 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 を使ってください。)

'(' (開き括弧) で始まる変数名は内部の変数 (ループ制御変数、一時変数、可変長引数、および C の関数のローカル変数) を表します。

引数 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 個の命令を実行するたびにフックが呼ばれます。

引数を指定せずに呼ぶと、フックを無効にします。

フックが呼ばれたとき、第 1 引数にはその呼び出しの原因となったイベントを表す以下の文字列が渡されます。

"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 に設定します (table は nil も指定できます)。 value を返します。

`debug.setupvalue (f, up, value)`

関数 f のインデックス up の上位値に値 value を代入します。指定したインデックスの上位値が存在しない場合は nil を返します。そうでなければその上位値の名前を返します。

`debug.setuservalue (udata, value)`

指定した udata に指定した value を関連付けます。 value はテーブルか nil でなければならず、 udata はフルユーザーデータでなければなりません。

udata を返します。

`debug.traceback ([thread,] [message [, level]])`

message が文字列でも nil でもなければ、それ以上の処理をせずに message を返します。そうでなければ、スタックトレースの文字列を返します。省略可能な文字列 message がトレースの先頭に追加されます。省略可能な数値 level はトレースを開始するレベルを指定します (デフォルトは 1 で、 traceback を呼んだ関数です)。

`debug.upvalueid (f, n)`

指定した関数の n 番目の上位値を表す一意な識別子を (ライトユーザーデータとして) 返します。

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

`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: 環境変数を無視します。
--: オプションの処理を停止します。
-: 標準入力をファイルとして実行し、オプションの処理を停止します。

オプションを処理した後、 lua は指定された args を文字列引数として渡し、指定された script を実行します。引数なしで実行した場合、標準入力が端末であれば lua は lua -v -i のように動作し、そうでなければ lua - のように動作します。

-E を指定せずに呼ぶと、どの引数も処理する前に環境変数 LUA_INIT_5_2 (もし定義されていなければ、代わりに LUA_INIT) がチェックされます。その変数の値が @filename の形式であれば、 lua はそのファイルを実行します。そうでなければ、 lua はその文字列自身を実行します。

オプション -E を指定して呼ぶと、 LUA_INIT に加えて LUA_PATH および LUA_CPATH も無視し、 luaconf.h で定義されているデフォルトのパスを package.path および package.cpath に設定します。

-i および -E 以外のすべてのオプションは指定した順番で処理されます。例えば、以下のようなコマンドは

     $ lua -e'a=1' -e 'print(a)' script.lua

まず a に 1 を設定し、次に a の値を表示し、最後にファイル script.lua を引数なしで実行します。 ($ はシェルプロンプトです。これは使用している環境によって異なる場合があります。)

スクリプトの実行を開始する前に、 lua は arg と呼ばれるグローバルなテーブルにすべてのコマンドライン引数を集めます。スクリプト名はインデックス 0 に格納され、スクリプト名の後の最初の引数はインデックス 1 に格納され、以下同様です。スクリプト名の前の引数 (つまりインタプリタ名とインタプリタへのオプション) は、負のインデックスに格納されます。例えば、

     $ lua -la b.lua t1 t2

は、まずファイル a.lua を実行し、次に以下のようなテーブルを作成し、

     arg = { [-2] = "lua", [-1] = "-la",
             [0] = "b.lua",
             [1] = "t1", [2] = "t2" }

最後にファイル b.lua を実行します。スクリプトは arg[1]、 arg[2]、 ... を引数として呼ばれ、可変長引数式 '...' でこれらの引数にアクセスすることもできます。

対話モードでは、不完全な文を書くと、異なるプロンプトを表示して文が完成するまで待ちます。

スクリプト中で保護されないエラーが発生した場合、インタプリタは標準出力ストリームにエラーを報告します。エラーオブジェクトが文字列であれば、スタックトレースにそれが追加されます。そうでなく、エラーオブジェクトが __tostring メタメソッドを持っていれば、最終的なメッセージを生成するためにそのメタメソッドが呼ばれます。最後に、エラーオブジェクトが nil の場合は、エラーは報告されません。

正常終了すると、インタプリタはメインの Lua ステートを閉じます (see lua_close を参照)。 os.exit を読んで終了すると、このステップを回避できます。

Unix システムで Lua をスクリプトインタプリタとして使えるように、スタンドアロンのインタプリタはチャンクが # で始まっている場合、 1 行目をスキップします。そのため、 chmod +x と #! 形式を使って、 Lua のスクリプトを実行可能プログラムにすることができます。

     #!/usr/local/bin/lua

(Lua インタプリタの場所は環境によって異なる場合があります。 lua が PATH の通っている場所にある場合は、

     #!/usr/bin/env lua

がより移植性の高い方法です。)

8 – 前のバージョンと非互換な点

プログラムを Lua 5.1 から Lua 5.2 に移行するにあたって、直面する可能性のある非互換な点の一覧を記載します。適切なオプションを使って Lua をコンパイルすれば、いくつかの非互換は回避できる場合があります (ファイル luaconf.h を参照)。ただし、これらの互換用オプションはすべて、次のバージョンの Lua では削除される予定です。

8.1 – 言語の変更

環境の概念が変わりました。 Lua の関数のみが環境を持ちます。 Lua の関数の環境を設定するには、変数 _ENV を使うか、関数 load を使います。
C の関数は環境を持たなくなりました。いくつかの C の関数の間で共有の状態を持つ必要があれば、上位値を使ってテーブルを共有してください。 (すべての関数で共通の上位値を共有する C のライブラリを開くために、 luaL_setfuncs を使うのもよいでしょう。)
ユーザーデータの「環境」 (現在は user value と呼ばれています) を操作する場合は、新しい関数 lua_getuservalue および lua_setuservalue を使ってください。
Lua の識別子にロケール依存の文字が使えなくなりました。
ガベージコレクションをステップ実行またはフル実行しても、停止状態のガベージコレクタは再開しなくなりました。
弱参照キーを持つ弱参照テーブルは 短命テーブル として動作するようになりました。
デバッグフックの tail return は削除されました。代わりに、末尾呼び出しは特別な新しいイベント tail call を生成するので、デバッガは対応するリターンイベントが存在しないことを知ることができます。
関数値の等値比較が変更されました。関数定義は新しい値を生成しない場合があるようになりました。新しい関数との間に観測可能な差異が無ければ、以前の値を再利用する場合があります。

8.2 – ライブラリの変更

関数 module は廃止されました。通常の Lua のコードでモジュールをセットアップするのが簡単になりました。モジュールはグローバル変数を設定すると期待されることはなくなりました。
関数 setfenv および getfenv は環境に関する変更によって削除されました。
関数 math.log10 は廃止されました。代わりに math.log を使い、第 2 引数に 10 を指定してください。
関数 loadstring は廃止されました。代わりに load を使ってください。この関数は文字列引数を受け取るようになり、 loadstring とまったく同等になりました。
関数 table.maxn は廃止されました。本当に必要な場合は Lua で書いてください。
関数 os.execute はコマンドが正常終了した場合 true を返し、それ以外の場合は nil とエラー情報を返すようになりました。
関数 unpack はテーブルライブラリに移動され、そのため table.unpack という名前になりました。
パターン中の %z 文字クラスは廃止され、 '\0' が通常の文字としてパターン中で使用できるようになりました。
テーブル package.loaders は package.searchers に改名されました。
Lua はバイトコードの検証を行わなくなりました。そのため、コードをロードするすべての関数 (load および loadfile) は、信頼されていないバイナリデータを読み込む場合、潜在的な危険があります。 (実際のところ、これらの関数は検証アルゴリズムに欠陥があり、元々危険でした。) 疑わしい場合は、これらの関数の引数 mode を使って、ロードするチャンクをテキスト形式に制限してください。

8.3 – API の変更

疑似インデックス LUA_GLOBALSINDEX は削除されました。グローバル環境はレジストリから取得する必要があります (§4.5 を参照)。
C の関数が環境を持たなくなったため、疑似インデックス LUA_ENVIRONINDEX および関数 lua_getfenv/lua_setfenv は削除されました。
関数 luaL_register は廃止されました。 luaL_setfuncs を使ってください。モジュールはグローバル変数を作らなくなります。 (モジュールにグローバル変数を設定すると期待されることはなくなりました。)
新しいブロックを作成するとき、つまり ptr が NULL であるとき、アロケーション関数の osize 引数がゼロであるとは限らなくなりました (lua_Alloc を参照)。ブロックが新規かどうかをチェックするときは、 ptr == NULL だけを使ってください。
ユーザーデータのファイナライザ (__gc メタメソッド) は、作成された順番の逆ではなく、ファイナライズ用にマークされた順番の逆で呼ばれるようになりました (§2.5.1 を参照)。 (ほとんどのユーザーデータは作成直後にマークされます。) また、メタテーブルが設定されたときに __gc フィールドがセットされていなければ、後でセットされても、ファイナライザが呼ばれなくなりました。
luaL_typerror は削除されました。必要なら自分で書いてください。
関数 lua_cpcall は廃止されました。単純に lua_pushcfunction で関数を積み、 lua_pcall で呼ぶことができます。
関数 lua_equal および lua_lessthan は廃止されました。代わりに新しい lua_compare を適切な引数で呼んでください。
関数 lua_objlen は lua_rawlen に改名されました。
関数 lua_load に引数 mode が追加されました。 NULL を渡すと以前と同じ動作になります。
関数 lua_resume に引数 from が追加されました。 NULL または呼び出しを実行しているスレッドを渡してください。

9 – Lua の完全な構文

拡張 BNF 記法で記した Lua の完全な構文を掲載します。 (演算子の優先順位に関しては記述されていません。)


	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 | Number | String | ‘...’ | functiondef |
		 prefixexp | tableconstructor | exp binop exp | unop exp

	prefixexp ::= var | functioncall | ‘(’ exp ‘)’

	functioncall ::=  prefixexp args | prefixexp ‘:’ Name args

	args ::=  ‘(’ [explist] ‘)’ | tableconstructor | String

	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 | ‘#’