6.1 基礎関数

基礎関数ライブラリは Lua でコアとなる関数を提供します。もしこのライブラリをアプリケーションに含めない場合には、機能の一部を自分で実装する必要がないかを慎重に確認する必要があります。

assert (v [, message])

引数 v が偽値 (nil または false) ならエラーを送出し、そうでないなら全ての引数をそのまま返します。エラーが起きた場合には message がエラーオブジェクトとなります。message が与えられないときはデフォルト値 "assertion failed!" が使われます。

collectgarbage ([opt [, arg]])

この関数はガベージコレクタへの一般的なインターフェースです。第一引数 opt に応じて異なる処理が行われます:

GC とそのオプションについて詳しくは § 2.5 を参照してください。

dofile ([filename])

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

error (message [, level])

message をエラーオブジェクトとしてエラーを送出します (§ 2.3)。この関数は返りません。

メッセージを文字列とすると、error 関数はメッセージの先頭にエラーが起きた位置を加えます。引数 level はそのときに表示されるエラー位置の取得方法を指定します。level のデフォルトの値は 1 であり、このときは error 関数が呼ばれた位置がエラーの位置となります。level が 2 のときは error 関数を呼んだ関数が呼ばれた位置がエラーの位置となり、以降同様です。level を 0 とすればエラーの位置情報はメッセージに加えられません。

_G

グローバル環境 (§ 2.2) を保持するグローバル変数です (関数ではありません)。Lua はこの変数を利用しません: この値を変えても環境は影響を受けず、逆も同様です。

getmetatable (object)

object がメタテーブルを持たなければ nil を返し、オブジェクトが __metatable フィールドを持てばその値を返し、それ以外の場合にはオブジェクトのメタテーブルを返します。

ipairs (t)

イテレータ関数・テーブル t・0 という三つの値を返します。この関数の返り値の関数を

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

と使うと、キーとバリューの組 (1, t[1]), ..., (2, t[2]) が最初の存在しないインデックスまでイテレートされます。

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

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

chunk が文字列なら、その文字列が読み込むチャンクとなります。chunk が関数なら、load はその関数を何度も呼んでチャンクの部分を取得します。それぞれの chunk の呼び出しは前回の呼び出しに続く文字列を返す必要があり、空の文字列または nil もしくは返り値が存在しないことがチャンクの終わりを表します。

構文エラーが無ければ load はコンパイルされたチャンクを関数として返し、構文エラーが起きたときには fail とエラーメッセージを返します。

メインチャンクを読み込むときは、返り値の関数は必ずただ一つのアップバリュー _ENV を持ちます (参照: § 2.2)。しかし関数から (string.dump で) 作られたバイナリチャンクを読み込むときには、返り値の関数のアップバリューの数は一つとは限りません。また一つ目のアップバリューが _ENV である保証もありません (メインでない関数は _ENV を持たない可能性さえあります)。

読み込み結果の関数がアップバリューを一つでも持つのなら、一つ目のアップバリューは env パラメータが与えられればその値に、与えられなければグローバル環境の値に設定されます。他のアップバリューは nil で初期化されます。全てのアップバリューは「新しく」作られ、他の関数と共有されることはありません。

chunkname はエラーメッセージとデバッグ情報で使われるチャンクの名前です (参照: § 4.7)。chunkname が与えられないときのデフォルト値は chunk が文字列のとき "chunk" で、それ以外のとき "=(load)" です。

文字列 mode はチャンクがテキストかバイナリ (事前にコンパイルされたチャンク) かを表します。可能な値は次の通りであり、デフォルトは "bt" です:

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

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

load と同様ですが、チャンクをファイル filename または標準入力から受け取ります。標準入力が使われるのは filename が指定されなかったときです。

next (table [, index])

この関数はテーブルの全フィールドを走査するために使われます。第一引数はテーブルで、第二引数はテーブルのインデックスです。next を呼び出すと、テーブルの「次の」インデックスとそれに対応するバリューが返ります。第二引数を nil として呼び出すと、next は「最初の」インデックスとそれに対応するバリューを返します。「最後の」インデックスを渡したとき、および空のテーブルに nil を渡したときは、nil を返します。第二引数を省略すると nil と解釈されます。例えば next(t) でテーブルが空かどうかを判定できます。

インデックスが枚挙される順番は決まっていません。数値のインデックスさえ順番通りに返ることは保証されていません (テーブルを数値の順番通りに走査するときは、数値を使った for を使ってください)。

テーブルの走査中に存在しないフィールドに対して何らかの値を代入した場合、next の振る舞いは未定義となります。ただし既存のフィールドの変更は構いません。特に既存のフィールドに対する nil の代入は許されています。

pairs (t)

t がメタメソッド __pairs を持つなら、t を引数としてそれを呼び、返り値の最初の三つの値を返します。

そうでなければ、この関数は next, テーブル t, nil という三つの値を返します。これにより、

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

というコードでテーブル t に含まれる全てのキーとバリューの組を走査できます。

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

pcall (f [, arg1, ...])

与えられた引数を使って関数 f を保護モードで実行します。これは f で起こった任意のエラーが伝播されないことを意味します。その代わり pcall がエラーを捕捉し、返り値として状態コードを返します。一つ目の返り値は状態コード (真偽値) であり、エラーが起きずに実行が終了すれば true となります。この場合 pcall は呼び出した関数からの返り値を状態コードの後の返り値として返します。エラーが起こった場合には、pcall は false とエラーオブジェクトを返します。pcall では捕捉したエラーに対するメッセージハンドラが呼び出されないことに注意してください。

print (...)

可変個数の引数を受け取り、その値を stdout に出力します。それぞれの引数を文字列に変換する規則は tostring と同様です。

print 関数の目的は整った文字列を出力することではなく、デバッグなどのために値を素早く確認することです。出力を完全に制御したい場合には string.format または io.write を使ってください。

rawequal (v1, v2)

メタメソッド __eq を呼び出さずに v1 が v2 と等しいかを判定します。真偽値を返します。

rawget (table, index)

メタバリュー __index を使わずに table[index] の「真の」値を取得します。table はテーブルである必要があり、index はどんな値でも構いません。

rawlen (v)

メタメソッド __len を呼び出さずにオブジェクト v の長さを返します。v はテーブルまたは文字列である必要があります。返り値は整数です。

rawset (table, index, value)

メタメソッド __newindex を使うことなく table[index] の値を value に設定します。table はテーブル、index は nil と NaN 以外の任意の値、value は任意の Lua 値です。

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

select (index, ...)

index が数値なら、index 番目以降の全ての引数を返します。負の数値は最後から数えたインデックスを表します (-1 なら最後の引数です)。そうでないとき index は "#" でなければならず、そのとき select は index 以外の引数の個数を返します。

setmetatable (table, metatable)

与えられたテーブルのメタテーブルを設定します。metatable が nil なら、与えられたテーブルのメタテーブルを削除します。元々あったメタテーブルが __metatable フィールドを持つならエラーを送出します。

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

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

tonumber (e [, base])

base が指定されない場合には、tonumber は引数を数値へ変換します。引数が最初から数値 (あるいは数値に変換できる文字列) のときはその数値を返し、それ以外のときは fail を返します。

文字列の変換結果は整数か浮動小数点数のどちらかであり、変換では Lua の字句変換規則 (§ 3.1) が使われます。変換する文字列の前後には空白が付いていても構わず、また先頭の符号も許されます。

base があるときは e がその値を底とした数値とみなせる文字列である必要があります。底として使えるのは 2 以上 36 以下の値であり、10 より大きい底では 10 を A で、11 を B でというように表します (大文字と小文字の区別はありません)。Z が 35 となります。e が底 base の数値として正しくない場合には、この関数は fail を返します。

tostring (v)

任意の型の値を受け取り、それを人間が読めるフォーマットの文字列に変換します。

v のメタテーブルに __tostring フィールドがあるなら、tostring はその値を v を引数として呼び出し、結果を返り値とします。それ以外の場合で v のメタテーブルに文字列の __name フィールドがあるなら、tostring はそれを返り値として返す可能性があります1。

数値の変換を細かく制御するには string.format を使ってください。

type (v)

引数の値の型を文字列として返します。受け取る引数は一つだけであり、返り値は "nil", "number", "string", "boolean", "table", "function", "thread" のいずれかです ("nil" は値 nil ではなく文字列です)。

_VERSION

実行中の Lua のバージョンを表す文字列を持つグローバル変数です (関数ではありません)。バージョン 5.4 におけるこの変数の値は "Lua 5.4" です。

warn (msg1, ...)

引数を全て連結したメッセージを持つ警告を発生させます。全ての引数は文字列である必要があります。

慣習により、'@' で始まる単一のメッセージは制御メッセージ (control message) を表します。これは警告システムに対するメッセージであり、Lua 標準の警告関数は "@off" と "@on" を認識します。"@off" を使うと警告が無効になり、"@on" で再度有効にするまで警告が無視されるようになります。この二つ以外の制御メッセージは無視されます。

xpcall (f, msgh [, arg1, ...])

この関数は基本的に pcall と同様ですが、新しいメッセージハンドラ msgh を設定する点が異なります。

  1. 訳注: ソースコードによると、v が数値・文字列・真偽値・nil 以外のとき __name が使われる。[return]

広告