6.2 – 基本関数

基本ライブラリはLuaへ中核となる関数を提供します。このライブラリをアプリケーションに含めない場合、その機能の一部について実装を提供する必要がないか、注意深く確認してください。

`assert (v [, message])`

引数vの値が偽（つまりnilまたはfalse）ならエラーを発生させ、それ以外の場合はすべての引数を返します。エラーの場合、messageがエラーオブジェクトです。省略した場合のデフォルトは”assertion failed!”です。

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

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

“collect”：完全なガベージコレクションサイクルを実行します。これはデフォルトのオプションです。
“stop”：ガベージコレクターの自動実行を停止します。再開する呼び出しがあるまで、明示的に呼び出したときだけコレクターが実行されます。
“restart”：ガベージコレクターの自動実行を再開します。
“count”：Luaが使用中の総メモリ量をKbyte単位で返します。値には小数部分があり、1024を掛けるとLuaが使用中の正確なバイト数になります。
“step”：ガベージコレクションのステップを実行します。このオプションの後には、ステップサイズを示す整数の追加引数を指定できます。サイズが正のnなら、コレクターは新たにnバイトが割り当てられたかのように動作します。サイズが0なら、コレクターは基本ステップを実行します。インクリメンタルモードでは、基本ステップは現在のステップサイズに対応します。世代別モードでは、基本ステップは完全なマイナーコレクションを実行します。コレクターがインクリメンタルステップを予定している場合は、そのステップを実行します。インクリメンタルモードでは、ステップがコレクションサイクルを完了すると関数はtrueを返します。世代別モードでは、ステップがメジャーコレクションを完了するとtrueを返します。
“isrunning”：コレクターが実行中（つまり停止していない）かを示すブール値を返します。
“incremental”：コレクターモードをインクリメンタルへ変更し、以前のモードを返します。
“generational”：コレクターモードを世代別へ変更し、以前のモードを返します。
“param”

：コレクターの引数値を変更または取得します。このオプションの後には1つまたは2つの追加引数、すなわち変更または取得する引数の名前（文字列）と、省略可能なその引数の新しい値（範囲

[0,100000]

の整数）を指定する必要があります。第1引数は次の値のいずれかでなければなりません。
- “minormul”
  
  ：マイナー乗数。
- “majorminor”
  
  ：メジャー・マイナー乗数。
- “minormajor”
  
  ：マイナー・メジャー乗数。
- “pause”
  
  ：ガベージコレクターの一時停止。
- “stepmul”
  
  ：ステップ乗数。
- “stepsize”
  
  ：ステップサイズ。
呼び出しは常に引数の以前の値を返します。新しい値を指定しなければ、値は変更されません。

Luaはこれらの値を圧縮形式で保存するため、以前の値として返される値は最後に設定した値と厳密には一致しない場合があります。

ガベージコレクションとこれらのオプションの一部について詳しくは§2.5を参照してください。

この関数をファイナライザーから呼び出すべきではありません。

`dofile ([filename])`

指定されたファイルを開き、その内容をLuaチャンクとして実行し、チャンクが返すすべての値を返します。引数なしで呼び出すと、

dofile

は標準入力（

stdin

）の内容を実行します。エラーの場合、

dofile

はエラーを呼び出し元へ伝播します。（つまり、

dofile

は保護モードで実行されません。）

`error (message [, level])`

エラーオブジェクトを

message

としてエラー（

§2.3

を参照）を発生させます。この関数が返ることはありません。

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

`_G`

グローバル環境（

§2.2

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

`getmetatable (object)`

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

`ipairs (t)`

次の構文が

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

最初に存在しないインデックスまで、キーと値の組（1,t[1]）、（2,t[2]）、…を反復処理するように、3つの値（イテレーター関数、値t、0）を返します。

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

チャンクを読み込みます。

chunkが文字列なら、その文字列がチャンクです。chunkが関数なら、loadはチャンクの断片を得るために繰り返し呼び出します。chunkの各呼び出しは、それ以前の結果と連結する文字列を返す必要があります。空文字列、nil、または値を返さないことがチャンクの終わりを示します。

構文エラーがなければ、loadはコンパイル済みチャンクを関数として返します。それ以外の場合はfailとエラーメッセージを返します。

メインチャンクを読み込むと、結果の関数は常にちょうど1つの上位値、変数_ENVを持ちます（§2.2を参照）。ただし、関数から作成したバイナリチャンク（string.dumpを参照）を読み込むと、結果の関数は任意の数の上位値を持つ可能性があり、その最初の上位値が変数_ENVである保証はありません。（メインでない関数は_ENV上位値を持たないことさえあります。）

いずれにしても、結果の関数に上位値がある場合、最初の上位値は、引数が指定されていればenvの値に、指定されていなければグローバル環境の値に設定されます。そのほかの上位値はnilで初期化されます。すべての上位値は新しく、ほかのどの関数とも共有されません。

chunknameはエラーメッセージとデバッグ情報でチャンク名として使われます（§4.7を参照）。省略した場合、chunkが文字列ならchunkが、それ以外なら”=(load)”がデフォルトです。

文字列modeは、チャンクがテキストかバイナリ（つまりプリコンパイル済みチャンク）かを制御します。文字列”b”（バイナリチャンクのみ）、“t”（テキストチャンクのみ）、“bt”（バイナリとテキストの両方）のいずれかを指定できます。デフォルトは”bt”です。

Luaはバイナリチャンクの一貫性を検査しません。悪意を持って細工されたバイナリチャンクはインタープリターをクラッシュさせる可能性があります。引数modeを使ってバイナリチャンクの読み込みを防止できます。

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

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

`next (table [, index])`

プログラムがテーブルのすべてのフィールドを走査できるようにします。第1引数はテーブル、第2引数はこのテーブル内のインデックスです。nextを呼び出すと、テーブルの次のインデックスと関連付けられた値を返します。第2引数をnilとして呼び出すと、nextは最初のインデックスと関連付けられた値を返します。最後のインデックスを指定した場合、または空のテーブルでnilを指定した場合、nextはnilを返します。第2引数を省略するとnilとして解釈されます。特に、テーブルが空かどうかを確認するためにnext(t)を使えます。

インデックスが列挙される順序は、数値インデックスであっても規定されていません。（テーブルを数値順に走査するには、数値forを使います。）

テーブルの走査中に、存在しないフィールドへ値を代入してはいけません。ただし、既存のフィールドは変更できます。特に、既存のフィールドをnilに設定できます。

`pairs (t)`

tがメタメソッド__pairsを持つ場合、tを引数としてそのメタメソッドを呼び出し、呼び出しの最初の4つの結果を返します。

それ以外の場合、次の構文が

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

テーブルtのすべてのキーと値の組を反復処理するように、関数next、テーブルt、2つのnil値を返します。

走査の詳細については関数nextを参照してください。

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

指定された引数で関数fを保護モードで呼び出します。これはf内のエラーを伝播させず、代わりにpcallがエラーを捕捉してステータスコードを返すことを意味します。最初の結果はステータスコード（ブール値）で、呼び出しがエラーなく成功すればtrueです。その場合、pcallは最初の結果に続いて呼び出しのすべての結果も返します。エラーの場合、pcallはfalseとエラーオブジェクトを返します。pcallが捕捉したエラーはメッセージハンドラーを呼び出さないことに注意してください。

`print (···)`

任意の数の引数を受け取り、

tostring

と同じ規則で各引数を文字列へ変換し、その値を

stdout

へ表示します。

関数printは整形出力を目的とせず、たとえばデバッグ時に値を示すための簡便な方法にすぎません。出力を完全に制御するにはstring.formatとio.writeを使います。

`rawequal (v1, v2)`

メタメソッド

__eq

を呼び出さず、

v1

が

v2

と等しいかを確認します。ブール値を返します。

`rawget (table, index)`

メタ値

__index

を使わず、

table[index]

の実際の値を取得します。

table

はテーブルでなければなりません。

index

には任意の値を指定できます。

`rawlen (v)`

メタメソッド

__len

を呼び出さず、テーブルまたは文字列でなければならないオブジェクト

v

の長さを返します。整数を返します。

`rawset (table, index, value)`

メタ値

__newindex

を使わず、

table[index]

の実際の値を

value

に設定します。

table

はテーブル、

index

は

nil

およびNaN以外の任意の値、

value

は任意のLua値でなければなりません。

この関数はtableを返します。

`select (index, ···)`

indexが数値なら、引数番号indexより後のすべての引数を返します。負の数値は末尾からインデックスを付けます（-1が最後の引数です）。それ以外の場合、indexは文字列"#"でなければならず、selectは受け取った追加引数の総数を返します。

`setmetatable (table, metatable)`

指定されたテーブルのメタテーブルを設定します。metatableがnilなら、指定されたテーブルのメタテーブルを除去します。元のメタテーブルに__metatableフィールドがある場合は、エラーを発生させます。

この関数はtableを返します。

Luaコードからほかの型のメタテーブルを変更するには、デバッグライブラリ（§6.11）を使う必要があります。

`tonumber (e [, base])`

baseなしで呼び出すと、tonumberは引数を数値へ変換しようとします。引数がすでに数値であるか、数値へ変換できる文字列なら、tonumberはその数値を返します。それ以外の場合はfailを返します。

Luaの字句規則（§3.1を参照）に従い、文字列の変換結果は整数または浮動小数点数になります。文字列の先頭と末尾には空白を含められ、符号も指定できます。

baseを指定して呼び出すと、eはその基数の整数表記として解釈する文字列でなければなりません。基数には2から36までの任意の整数を指定できます。10より大きい基数では、文字’A’（大文字と小文字のどちらでも可）が10、‘B’が11を表し、同様に’Z’が35を表します。文字列eが指定された基数で有効な数値表記でなければ、関数はfailを返します。

`tostring (v)`

任意の型の値を受け取り、人間が読める形式の文字列へ変換します。

vのメタテーブルに__tostringフィールドがある場合、tostringはvを引数として対応する値を呼び出し、呼び出しの結果を自身の結果として使います。それ以外の場合、vのメタテーブルに文字列値を持つ__nameフィールドがあれば、tostringは最終結果にその文字列を使うことがあります。

数値の変換方法を完全に制御するにはstring.formatを使います。

`type (v)`

唯一の引数の型を文字列として返します。この関数が返す可能性のある値は、“nil”（値nilではなく文字列）、“number”、“string”、“boolean”、“table”、“function”、“thread”、“userdata”です。

`_VERSION`

実行中のLuaバージョンを含む文字列を保持するグローバル変数（関数ではありません）です。この変数の現在の値は”Lua 5.5”です。

`warn (msg1, ···)`

すべての引数（文字列であるべきです）を連結して構成したメッセージで警告を発します。

慣例により、‘@’で始まる単一部分のメッセージは、警告システム自体へのメッセージである制御メッセージとして意図されます。特にLuaの標準警告関数は、警告の発行を停止する制御メッセージ”@off”と、発行を（再）開始する”@on”を認識し、不明な制御メッセージは無視します。

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

この関数はpcallと同様ですが、新しいメッセージハンドラーmsghを設定します。