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

Copyright © 2006 Lua.org, PUC-Rio. All rights reserved.

目次

  • 索引

  • Top
  • 0 - 日本語訳について
  • 1 - 概要
  • 2 - 言語
    • 2.1 - 字句の構成
    • 2.2 - 値と型
      • 2.2.1 - 変換
    • 2.3 - 変数
    • 2.4 - 文
      • 2.4.1 - チャンク
      • 2.4.2 - ブロック
      • 2.4.3 - 代入
      • 2.4.4 - 制御構造
      • 2.4.5 - for文
      • 2.4.6 - 文としての関数呼び出し
      • 2.4.7 - ローカル宣言
    • 2.5 - 式
      • 2.5.1 - 算術演算子
      • 2.5.2 - 関係演算子
      • 2.5.3 - 論理演算子
      • 2.5.4 - 連結
      • 2.5.5 - 長さ演算子
      • 2.5.6 - 優先順位
      • 2.5.7 - テーブルコンストラクタ
      • 2.5.8 - 関数呼び出し
      • 2.5.9 - 関数定義
    • 2.6 - 可視ルール
    • 2.7 - エラー処理
    • 2.8 - メタテーブル
    • 2.9 - 環境
    • 2.10 - ガベージコレクション
      • 2.10.1 - ガベージコレクションメタメソッド
      • 2.10.2 - 弱参照テーブル
    • 2.11 - コルーチン
  • 3 - アプリケーションプログラムインタフェイス
    • 3.1 - スタック
    • 3.2 - スタックサイズ
    • 3.3 - 擬似インデックス
    • 3.4 - Cのクロージャ
    • 3.5 - レジストリ
    • 3.6 - Cでのエラー処理
    • 3.7 - 関数と型
    • 3.8 - デバッグインタフェイス
  • 4 - 補助ライブラリ
    • 4.1 - 関数と型
  • 5 - 標準ライブラリ
    • 5.1 - 基本関数
    • 5.2 - コルーチン操作
    • 5.3 - モジュール
    • 5.4 - 文字列操作
    • 5.5 - テーブル操作
    • 5.6 - 数学関数
    • 5.7 - 入出力機能
    • 5.8 - OS機能
    • 5.9 - デバッグライブラリ
  • 6 - スタンドアロンのLua
  • 前バージョンとの非互換
  • Luaの完全な構文

索引

関数

_G
_VERSION
assert
collectgarbage
coroutine.create
coroutine.resume
coroutine.running
coroutine.status
coroutine.wrap
coroutine.yield
debug.debug
debug.getfenv
debug.gethook
debug.getinfo
debug.getlocal
debug.getmetatable
debug.getregistry
debug.getupvalue
debug.setfenv
debug.sethook
debug.setlocal
debug.setmetatable
debug.setupvalue
debug.traceback
dofile
error
file:close
file:flush
file:lines
file:read
file:seek
file:setvbuf
file:write
getfenv
getmetatable
io.close
io.flush
io.input
io.lines
io.open
io.output
io.popen
io.read
io.tmpfile
io.type
io.write
ipairs
load
loadfile
loadstring
math.abs
math.acos
math.asin
math.atan2
math.atan
math.ceil
math.cosh
math.cos
math.deg
math.exp
math.floor
math.fmod
math.frexp
math.ldexp
math.log10
math.log
math.max
math.min
math.modf
math.pow
math.rad
math.random
math.randomseed
math.sinh
math.sin
math.sqrt
math.tanh
math.tan
module
next
os.clock
os.date
os.difftime
os.execute
os.exit
os.getenv
os.remove
os.rename
os.setlocale
os.time
os.tmpname
package.cpath
package.loaded
package.loadlib
package.path
package.preload
package.seeall
pairs
pcall
print
rawequal
rawget
rawset
require
select
setfenv
setmetatable
string.byte
string.char
string.dump
string.find
string.format
string.gmatch
string.gsub
string.len
string.lower
string.match
string.rep
string.reverse
string.sub
string.upper
table.concat
table.insert
table.maxn
table.remove
table.sort
tonumber
tostring
type
unpack
xpcall

API

lua_Alloc
lua_CFunction
lua_Debug
lua_Hook
lua_Integer
lua_Number
lua_Reader
lua_State
lua_Writer
lua_atpanic
lua_call
lua_checkstack
lua_close
lua_concat
lua_cpcall
lua_createtable
lua_dump
lua_equal
lua_error
lua_gc
lua_getallocf
lua_getfenv
lua_getfield
lua_getglobal
lua_gethook
lua_gethookcount
lua_gethookmask
lua_getinfo
lua_getlocal
lua_getmetatable
lua_getstack
lua_gettable
lua_gettop
lua_getupvalue
lua_insert
lua_isboolean
lua_iscfunction
lua_isfunction
lua_islightuserdata
lua_isnil
lua_isnumber
lua_isstring
lua_istable
lua_isthread
lua_isuserdata
lua_lessthan
lua_load
lua_newstate
lua_newtable
lua_newthread
lua_newuserdata
lua_next
lua_objlen
lua_pcall
lua_pop
lua_pushboolean
lua_pushcclosure
lua_pushcfunction
lua_pushfstring
lua_pushinteger
lua_pushlightuserdata
lua_pushlstring
lua_pushnil
lua_pushnumber
lua_pushstring
lua_pushthread
lua_pushvalue
lua_pushvfstring
lua_rawequal
lua_rawget
lua_rawgeti
lua_rawset
lua_rawseti
lua_register
lua_remove
lua_replace
lua_resume
lua_setallocf
lua_setfenv
lua_setfield
lua_setglobal
lua_sethook
lua_setlocal
lua_setmetatable
lua_settable
lua_settop
lua_setupvalue
lua_status
lua_toboolean
lua_tocfunction
lua_tointeger
lua_tolstring
lua_tonumber
lua_topointer
lua_tostring
lua_tothread
lua_touserdata
lua_type
lua_typename
lua_xmove
lua_yield

補助ライブラリ

luaL_Buffer
luaL_Reg
luaL_addchar
luaL_addlstring
luaL_addsize
luaL_addstring
luaL_addvalue
luaL_argcheck
luaL_argerror
luaL_buffinit
luaL_callmeta
luaL_checkany
luaL_checkint
luaL_checkinteger
luaL_checklong
luaL_checklstring
luaL_checknumber
luaL_checkoption
luaL_checkstack
luaL_checkstring
luaL_checktype
luaL_checkudata
luaL_error
luaL_getmetafield
luaL_getmetatable
luaL_gsub
luaL_loadbuffer
luaL_loadfile
luaL_loadstring
luaL_newmetatable
luaL_newstate
luaL_openlibs
luaL_optint
luaL_optinteger
luaL_optlong
luaL_optlstring
luaL_optnumber
luaL_optstring
luaL_prepbuffer
luaL_pushresult
luaL_ref
luaL_register
luaL_typename
luaL_typerror
luaL_unref
luaL_where

最終更新: Fri Feb 10 17:15:37 BRST 2006

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

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

Copyright © 2006 Lua.org, PUC-Rio. All rights reserved.

0 - 日本語訳について

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

1 - 概要

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

拡張言語であるため、Luaは「メイン」プログラムを持たない。 ホストクライアント (エンベッディングプログラム、あるいは単にホスト とも呼ぶ) に 組み込まれて 動くだけである。 このホストプログラムは、Luaコードを実行する関数を呼び出したり、Luaの変数を読み書きしたり、Luaから呼ばれるCの関数を登録したりできる。 Cの関数を使ってカスタマイズすることで、共通の構文を持つプログラミング言語で様々な領域を広範囲にカバーすることができる。 Luaのディストリビューションには lua と呼ばれるサンプルのホストプログラムが含まれている。 これはLuaライブラリを使った完全なスタンドアロンのLuaインタプリタを提供している。

Luaはフリーソフトウェアであり、ライセンスにも書かれているように、いかなる保証もなくあるがまま提供される。 このマニュアルに記述されている実装はLuaの公式ウェブサイト www.lua.org で提供されている。

他のすべてのリファレンスマニュアルと同様、この文書はあちこちが無味乾燥である。 Luaのデザインの背後にある決定についての議論は、Luaのウェブサイトにある技術文書を参照のこと。 Luaによるプログラミングの詳しい紹介は、Roberto著 Programming in Lua を参照。

2 - 言語

このセクションでは、Luaの字句、構文、意味論について記述する。 言い換えると、このセクションでは、どういったトークンが有効か、それらをどう組み合わせられるのか、そしてその組み合わせは何を意味するのかについて記述している。

言語構造は一般的な拡張BNF記法を使って説明する。 {a} は a の0回以上の繰り返し、[a] は a が省略可能であることを表す。 非終端記号は italic で表され、キーワードは bold、他の終端記号はシングルクォートで囲まれた type writer フォントで表現される。 Luaの完全な構文はこのマニュアルの最後にある。

2.1 - 字句の構成

Luaの 名前 (識別子 とも呼ばれる) は、文字、数字、アンダースコアを組み合わせた任意の文字列である。 ただし数字で始まってはならない。 これは多くの言語の名前の定義に一致する。 「文字」の定義は現在のロケールに依存する。 現在のロケールでアルファベットとみなされる文字はどれも識別子に使える。 識別子は名前変数やテーブルフィールドに使われる。

以下の キーワード は予約されており、名前としては使えない。

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

Lua は大文字小文字を区別する言語である。 and は予約語だが、And と AND は、2つの異なった、有効な名前である。 慣習的に、アンダースコアと大文字で始まる名前 (例えば _VERSION) は、 Luaが使う内部のグローバル変数として予約されている。

以下の文字列は、その他のトークンである。

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

文字列リテラル は対になるシングルクォートかダブルクォートで囲まれ、 以下の C のようなエスケープシーケンスを含むことができる。

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

上記に加えて、 `\改行´ (バックスラッシュに本物の改行が続いたもの) を記述して文字列中に改行を含めることができる。 さらに `\ddd´ (dddは最大3桁の10進数) というエスケープシーケンスを使って 文字列中の文字をそのコード値で指定することもできる。 (数値エスケープの後に数字が続く場合は、ぴったり3桁使って表現しなければならない。) Luaの文字列は `\0´ で表されるゼロを含み、いかなる8ビット値も含むことができる。

ダブル(またはシングル)クォートで囲まれた文字列リテラルの中に、 ダブル(またはシングル)クォート、改行、バックスラッシュ、または埋め込まれたゼロを置くためには、 エスケープシーケンスを使わなければならない。 他のすべての文字は直接リテラルの中に入れて構わない (ファイルシステムに対しては制御文字が問題を起こすかもしれないが、Luaは大丈夫である。)

文字列リテラルは 長括弧 で囲む長い形式を使って定義することもできる。 n 段の開き長括弧 は、 開き角括弧に n 個のイコールと、さらに開き角括弧を続けたものである。 つまり、0段の開き長括弧は [[ と書き、 1段の開き長括弧は [=[ と書き、以下同様である。 閉じ長括弧 も同様である。 例えば4段の閉じ長括弧は ]====] と書く。 長い文字列は任意の段数の開き長括弧で始まり、同じ段数の閉じ長括弧で終わる。 この角カッコ形式のリテラルは、複数行に渡って記述できる。 エスケープシーケンスは一切解釈されず、異なる段数の閉じ長括弧は無視する。 これは、正しい段数の閉じ長括弧と埋め込まれたゼロ以外の任意の内容を入れられる。

便利なように、開き長括弧のすぐ後に改行が続いたときは、その改行は文字列に含まれない。 例えば、ASCII (つまり `a´ が97、改行が10、`1´ が49であるような文字コード) が使われているシステムでは、 以下の4つのリテラルは同じ文字列を表現している。

      (1)   'alo\n123"'
      (2)   "alo\n123\""
      (3)   '\97lo\10\04923"'
      (4)   [[alo
            123"]]
      (5)   [==[
            alo
            123"]==]

数値定数 には省略可能な小数部と省略可能な指数部を書くことができる。 Luaは接頭辞 0x を付けた整数の16進定数も受け付ける。 有効な数値定数の例を挙げると

       3       3.0     3.1416  314.16e-2   0.31416E1  0xff  0x56

コメント は文字列の外ならどこでも、二つのハイフン (--) で始めることができる。 もし -- の直後に開き長括弧以外のテキストがあれば、そのコメントは 短いコメント であり、行末まで続く。 そうでなければ、それは 長いコメント であり、対応する閉じ長括弧まで続く。 長いコメントはコードを一時的に無効にするためによく使われる。

2.2 - 値と型

Luaは 動的な型の言語 である。 つまり、変数は型を持たず、値が型を持つ。 型定義の構文はない。 すべての値は自分自身で型を保持している。

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

Luaには8つの基本型がある。 nil、ブーリアン、数値、文字列、関数、ユーザーデータ、スレッド、テーブル である。 nil は nil 値の型である。その主な性質は他のいかなる値とも異なることであり、通常、役に立つ値がないことを表す。 ブーリアン は false と true の値を持つ型である。 nil と false は共に条件判断で偽となり、他の値は真となる。 数値 は実数 (double) を表現する。 (しかし数値の内部表現としてfloatやlongなど他の型を使うようLuaインタプリタをビルドし直すのは簡単である。 ファイル luaconf.h を参照。) 文字列 は文字の配列を表現する。 Luaは8ビットクリーンであり、 文字列にはゼロ (`\0´) を含むいかなる8ビット文字も含むことができる (2.1 を参照)。

LuaはLuaで書かれた関数もCで書かれた関数も呼べる (2.5.8 を参照)。

ユーザーデータ は任意のCのデータをLuaの変数に格納するために用意された。 この型は生のメモリブロックに相当し、代入と等価比較を除いて、Luaでは演算が定義されていない。 しかしながら、メタテーブル を用いることで、 プログラマはユーザーデータに対する演算を定義することができる (2.8 を参照)。 ユーザーデータはLua内で作ったり変更することはできず、CのAPIを通してのみ可能である。 これは完全にホストプログラムに所有されたデータであることを保証する。

スレッド は実行されているそれぞれのスレッドを表現し、コルーチンを実装するために使われる (2.11 を参照)。 LuaのスレッドとOSのスレッドを混同しないように。 Luaはスレッドをサポートしないシステム上でもコルーチンをサポートする。

テーブル は連想配列である。 すなわち数値だけでなく任意の値 (nil を除く) をキーにできる配列である。 テーブルは 異種混合 できる。 つまりあらゆる型の値 (nil を除く) を持つことができる。 テーブルはLuaの唯一のデータ構造であり、 普通の配列の他、記号表、集合、レコード、グラフ、ツリーなどを表現するために使われる。 レコードを表現するときは、フィールド名をインデックスとして使う。 このための a.name という表現が a["name"] のシンタックスシュガーとして用意されている。 また、Luaでテーブルを作るための便利な表現がいくつかある (2.5.7 を参照)。

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

テーブル、関数、スレッド、ユーザーデータの値は オブジェクト である。 変数はこれらの実際の値は持たず、それらを 参照 しているだけである。 代入、引数渡し、関数の戻り値は、常に値への参照を扱い、値のコピーは行われない。

ライブラリ関数 type は与えられた値の型を表す文字列を返す。

2.2.1 - 変換

Luaは文字列と数値を実行時に自動的に変換する。 すべての数学演算は、文字列に適用されると、一般的な変換ルールに基づいてその文字列を数値に変換しようとする。 逆に、文字列が期待されるところで数値が使れると、その数値は一般的な形式の文字列に変換される。 数値が文字列に変換される方法を完璧にコントロールする場合は、 文字列ライブラリの format 関数を使う (string.format を参照)。

2.3 - 変数

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

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

    var ::= Name

(2.1 を参照) で定義されているように、名前は識別子を表す。

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

最初の代入が行われる前の変数の値は nil である。

テーブルをインデックス付けするためには角カッコを使う。

    var ::= prefixexp `[´ exp `]´

最初の式 (prefixexp) はテーブル、 二番目の式 (exp) はテーブル内のエントリを指定する値でなければならない。 テーブルのインデックスを指定する式は限定された構文を持つ。 詳細は 2.5 を参照。

構文 var.Name は var["Name"] の単なるシンタックスシュガーであり、 テーブルフィールドを示すために使う。

    var ::= prefixexp `.´ Name

グローバル変数とテーブルフィールドへアクセスする効果はメタテーブルによって変えられる。 インデックス付き変数 t[i] へのアクセスは gettable_event(t,i) の呼び出しと等価である (gettable_event 関数の完全な説明は 2.8 を参照。 この関数はLuaで定義したり呼ぶことはできず、単に説明のため用いているだけである)。

すべてのグローバル変数は、環境テーブル または単に 環境 (2.9 を参照) と呼ばれる通常のLuaのテーブル内に、フィールドとして存在している。 各関数はそれぞれ独自に環境への参照を持ち、 その関数内でのすべてのグローバル変数は、その環境テーブルを参照する。 関数が作られたとき、関数は、それが作られた関数から見える環境を受け継ぐ。 Luaの関数の環境テーブルを取得するには getfenv を呼ぶ。 変更するには setfenv を呼ぶ。 (Cの関数の環境はデバッグライブラリでのみ操作できる (5.9 を参照)。)

グローバル変数 x へのアクセスは _env.x と等価であり、 以下と等価である。

       gettable_event(_env, "x")

ただし、_env は関数が実行されている環境を表す (gettable_event 関数の完全な説明は 2.8 を参照。 この関数はLuaで定義したり読んだりできない。 同様に変数 _env はLuaで定義されていない。 これはただ説明のために用いているだけである)。

2.4 - 文

LuaはPascalやCと同じように一般的な文のセットをサポートしている。 代入、制御構造、関数呼び出し、テーブルコンストラクタや変数の宣言などである。

2.4.1 - チャンク

Luaの実行の単位は チャンク と呼ばれる。 チャンクは、単純に、順番に実行される文の連なりである。 それぞれの文末には省略可能なセミコロンを置いても良い。

    chunk ::= {stat [`;´]}
空文は存在しないため、`;;´ は許されていない。

Luaはチャンクを、可変個の引数を持つ無名関数の本体として扱っている (2.5.9 を参照)。 従って、チャンクはローカル変数を宣言でき、引数を受け取ることができ、戻り値を返せる。

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

チャンクはバイナリ形式のコンパイル済みコードであっても良い。 詳細は luac プログラムを参照。 ソースプログラムとコンパイル済み形式はどちらを用いても良い。 Luaは自動的にファイル形式を検出し、適切に振る舞う。

2.4.2 - ブロック

文の列はブロックである。 構文的には、ブロックはチャンクと等しい。

    block ::= chunk

ブロックは明示的に単一の文とすることもある。

    stat ::= do block end

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

2.4.3 - 代入

Luaは多重代入を許している。 だから、代入文では左辺に変数リスト、右辺に式リストを書く。 どちらのリストもそれぞれの要素をカンマで区切る。

    stat ::= varlist1 `=´ explist1
    varlist1 ::= var {`,´ var}
    explist1 ::= exp {`,´ exp}

式については 2.5 で議論する。

代入の前に、値リストは変数リストの長さに調節される。 もし必要な数よりも値が多ければ、余分な値は捨てられる。 もし必要な数よりも値が少なければ、必要なだけ nil が追加される。 もし式リストの最後が関数呼び出しなら、調節の前に、その関数のすべての戻り値が値リストに追加される (ただし呼び出しをカッコで囲った場合を除く、2.5 を参照)。

代入文は、まずすべての式を評価し、それから、代入が行われる。 だから、このコード

       i = 3
       i, a[i] = i+1, 20
は、i に4が代入される前に a[i] の i が (3に) 評価されるため、 a[3] に20が代入される。 a[4] は何の影響もない。 同様に、
       x, y = y, x
は x と y の値を交換する。

グローバル変数とテーブルフィールドへの代入の効果は、メタテーブルによって変えられる。 インデックス付き変数への代入 t[i] = val は settable_event(t,i,val) と等価である (settable_event 関数の完全な記述は 2.8 を参照。 この関数はLuaで定義したり呼ぶことはできず、 ただ説明のため用いているだけである)。

グローバル変数への代入 x = val は代入 _env.x = val と等価であり、 以下と等価である。

       settable_event(_env, "x", val)

ただし、_env は関数が実行されている環境を表す (変数 _env はLuaに定義されていない。 これはただ説明のために用いているだけである)。

2.4.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

Luaには for 文もある。 これは2つの種類がある (2.4.5 を参照)。

制御構造の条件式は任意の値をとれる。 false と nil は共に偽である。 nil と false 以外のすべての値は真になる (特に、数値の0や空文字列は真であることに注意)。

repeat--until ループでは、 内側のブロックは until キーワードのところではなく条件式の後に終わる。 つまり、条件式はループブロックの内側で宣言されたローカル変数を参照できる。

return 文は関数やチャンク (これはただの関数である) から値を返すために使う。 関数やチャンクは1個以上の値を返すことができる。 return 文の構文は以下の通り。

    stat ::= return [explist1]

break 文は while、repeat、for ループの実行を終了し、 ループの次までスキップする。

    stat ::= break

break は最も内側のループを終わらせる。

return 文と break 文はブロックの 最後 の文としてのみ書くことが許される。 return や break をブロックの途中で使うことが本当に必要なら、 明示的な内部ブロックを使う次のような慣用句を使えば良い。

    do return end
    do break end
これで return も break も (内部) ブロックの最後の文になる。

2.4.5 - for文

for 文には、数値用と汎用の2つの形式がある。

数値用 for ループは制御変数が等差数列を辿ってコードブロックを繰り返す。 以下がその構文である。

    stat ::= for Name `=´ exp `,´ exp [`,´ exp] do block end

block は name が最初の exp で始まって二番目のexp に達するまで、 三番目の exp ずつ進む間、繰り返される。 より正確には、次のような for 文

       for var = e1, e2, e3 do block end
は次のコードに等しい。
       do
         local _var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3)
         if not (_var and _limit and _step) then error() end
         while (_step>0 and _var<=_limit) or (_step<=0 and _var>=_limit) do
           local var = _var
           block
           _var = _var + _step
         end
       end

以下の点に注意:

  • 3つの制御式はループが始まる前に一度だけ評価される。これらは数値でなければならない。
  • _var、_limit、_step は見えない変数である。 この名前は説明のために用いられているだけである。
  • もし三番目の式 (ステップ) が省略されたら、1が使われる。
  • for ループを脱出するためには break を使う。
  • ループ変数 var はループ内でローカルである。 for 文の外側でその値を使うことはできない。 もしループ変数 var の値が必要なら、 ループを出る前に別の変数に代入する必要がある。

汎用 for 文は イテレータ と呼ばれる関数を通して働く。 それぞれの繰り返しについて、新しい値を生成するためにイテレータ関数が呼ばれ、nil になったところで止まる。 汎用 for ループは以下の構文である。

    stat ::= for Name {`,´ Name} in explist1 do block end

次のような for 文

       for var_1, ..., var_n in explist do block end
は次のコードと等価である。
       do
         local _f, _s, _var = explist
         while true do
           local var_1, ... , var_n = _f(_s, _var)
           _var = var_1
           if _var == nil then break end
           block
         end
       end

以下の点に注意:

  • explist は一度だけ評価され、 イテレータ 関数、状態、繰り返し変数 の初期値、でなければならない。
  • _f、_s、_var は見えない変数である。 この名前は説明のために用いられているだけである。
  • for ループを脱出するためには break を使う。
  • ループ変数 var はループ内でローカルである。 for 文の外側でその値を使うことはできない。 もしループ変数 var の値が必要なら、 ループを出る前に別の変数に代入する必要がある。

2.4.6 - 文としての関数呼び出し

副作用を許しているため、関数呼び出しは文として実行できる。

    stat ::= functioncall

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

2.4.7 - ローカル宣言

ローカル変数はブロックの中どこででも宣言できる。 宣言は初期値の代入を伴ってもよい。

    stat ::= local namelist [`=´ explist1]

もしあれば、多重代入と同じ構文で初期値が代入される (2.4.3 を参照)。 そうでなければ、変数はすべて nil で初期化される。

チャンクもまたブロックであるから (2.4.1 を参照)、 明示的なブロックの外側のチャンクでもローカル変数を宣言できる。 そのようなローカル変数のスコープはチャンクの終わりまで続く。

ローカル変数の可視ルールは 2.6 で説明する。

2.5 - 式

Luaの基本の式を以下に示す。

    exp ::= prefixexp
    exp ::= nil | false | true
    exp ::= Number
    exp ::= String
    exp ::= function
    exp ::= tableconstructor
    exp ::= `...´
    exp ::= exp binop exp
    exp ::= unop exp
    prefixexp ::= var | functioncall | `(´ exp `)´

数値と文字列リテラルは 2.1 で説明した。 変数は 2.3 で説明した。 関数定義は 2.5.9 で説明する。 関数呼び出しは 2.5.8 で説明する。 テーブルコンストラクタは 2.5.7 で説明する。 3つのドットで表される可変引数式は、可変引数関数の中でだけ使える。 これは 2.5.9 で説明する。

二項演算子は算術演算子 (2.5.1 を参照)、 関係演算子 (2.5.2 を参照)、 論理演算子 (2.5.3 を参照) がある。 単項演算子は単項マイナス (2.5.1 を参照)、 単項 not (2.5.3 を参照)、 そして単項 長さ演算子 (2.5.5 を参照) がある。

関数呼び出しと可変引数式は複数の値を返す。 式が文として使われた場合 (2.4.6 を参照) (関数呼び出しに対してのみ可能)、 結果のリストはゼロ個に調節され、つまりすべての戻り値が捨てられる。 他の式の中やリストの途中で使われた場合は、 結果のリストは1個に調節され、残りはすべて捨てられる。 式がリストの最後の要素として使われた場合は、 調節は行われない (カッコで囲った場合を除く)。

いくつか例を挙げる。

       f()                -- 戻り値は0個に調節される
       g(f(), x)          -- f()の戻り値は1個に調節される
       g(x, f())          -- xに加えてf()のすべての戻り値をgに渡す
       a,b,c = f(), x     -- f()の戻り値は1個に調節される (そしてcにはnilが入る)
       a,b = ...          -- aに可変引数の最初の値、bに2番目の値が入る
                          -- (対応する引数がなかった場合、a、bにはnilが入る)
       a,b,c = x, f()     -- f()の戻り値は2個に調節される
       a,b,c = f()        -- f()の戻り値は3個に調節される
       return f()         -- f()の戻り値をすべて返す
       return ...         -- 渡された可変引数をすべて返す
       return x,y,f()     -- x、yとf()のすべての戻り値を返す
       {f()}              -- f()のすべての戻り値からなるリストを作る
       {...}              -- 渡された可変引数すべての値からなるリストを作る
       {f(), nil}         -- f()の戻り値が1個に調節される

カッコに囲まれた式は常にただ1つの値を返す。 つまり、たとえ f が複数の値を返しても、(f(x,y,z)) は常に単一の値となる。 (f(x,y,z)) の値は、f が返す最初の値である。 あるいは f が何も返さなければ、nil となる。

2.5.1 - 算術演算子

Luaは一般的な算術演算子をサポートしている。 + (加算)、 - (減算)、* (乗算)、 / (除算)、% (剰余)、^ (累乗)、 および単項の - (符号反転)。 もしオペランドが数値、あるいは数値に変換できる文字列 (2.2.1を参照) なら、すべての演算は通常の意味を持つ。 累乗は任意の指数に対して動作する。 例えば、x^(-0.5) は x の平方根の逆数を計算する。 剰余は以下のように定義されている。

       a % b == a - math.floor(a/b)*b
つまり、負の無限大に向かって丸められた割り算の余りである。

2.5.2 - 関係演算子

Luaの関係演算子は以下の通りである。

       ==    ~=    <     >     <=    >=

これらの演算子は常に false か true いずれかの結果を返す。

等価 (==) はまずオペランドの型を比較する。 もし型が異なっていたら、結果は false である。 そうでなければ、オペランドの値が比較される。 数値と文字列は一般的な方法で比較する。 オブジェクト (テーブル、ユーザーデータ、スレッド、関数) は 参照 を比較し、 2つのオブジェクトが 同じ オブジェクトである場合だけを等しいとみなす。 新しいオブジェクト (テーブル、ユーザーデータ、関数) を作ったときは常に、 この新しいオブジェクトは、以前に存在していたオブジェクトと異なる。

"eq"メタメソッドを使って、テーブルやユーザーデータをLuaが比較する方法を変えられる (2.8 を参照)。

2.2.1 の変換ルールは等価比較には適用されない。 そのため、"0"==0 は false に評価され、 t[0] と t["0"] は異なったテーブルエントリを示す。

演算子 ~= は正確に等価 (==) の否定である。

関係演算子は次のように働く。 引数が両方数値ならば、それらは適切に比較される。 もし両方の引数が文字列ならば、現在のロケールに従ってその値が比較される。そうでなければ、Luaは"lt"または"le"メタメソッドを試みる (2.8 を参照)。

2.5.3 - 論理演算子

Luaの論理演算子は次の通りである。

       and   or    not

制御構造 (2.4.4 を参照) と同じく、 すべての論理演算子は false と nil の両方を偽、それ以外のすべてを真とみなす。

否定演算子 not は常に false か true を返す。 論理積演算子 and は、最初の引数が false か nil ならその値を返し、そうでなければ二番目の引数を返す。 論理和演算子 or は最初の引数が false か nil 以外ならその値を返し、そうでなければ二番目の引数を返す。 and と or は共にショートカット評価を行う。 つまり、二番目のオペランドは、それが必要なときだけ評価される。 いくつかの例を示す。

       10 or 20            --> 10
       10 or error()       --> 10
       nil or "a"          --> "a"
       nil and 10          --> nil
       false and error()   --> false
       false and nil       --> false
       false or nil        --> nil
       10 and 20           --> 20
(このマニュアルでは `-->´ で式の結果を示す。)

2.5.4 - 連結

Luaの文字列連結演算子はふたつのドット (`..´) で表す。 もし両方のオペランドが文字列か数値なら、それらは 2.2.1 で述べたルールに従って文字列に変換される。 そうでなければ、"concat"メタメソッドが呼ばれる (2.8 を参照)。

2.5.5 - 長さ演算子

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

テーブル t の長さは、 t[n] が nil でなく t[n+1] が nil であるような整数 n と定義されている。 また、t[1] が nil なら n はゼロになりうる。 nil でない値が1から n まで格納されている普通の配列では、 その長さは最後のインデックス n を正しく返す。 配列に「穴」がある場合 (つまり間に nil がある場合)、 #t はどれかの nil のひとつ前を返すかもしれない (つまり、その nil が配列の終わりであるように見えるのだ)。

2.5.6 - 優先順位

Luaでの演算子の優先順位を以下の表に示す。 優先順位は低い方から順に

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

普通通りに、カッコを使って式の優先順位を変えることができる。 連結 (`..´) と累乗 (`^´) は右結合である。 他の二項演算子はすべて左結合である。

2.5.7 - テーブルコンストラクタ

テーブルコンストラクタはテーブルを作る式である。 コンストラクタが評価されるたびに新しいテーブルが作られる。 空のテーブルを作ることも、いくつかのフィールドに初期値を持ったテーブルを作ることもできる。 コンストラクタの構文は以下の通りである。

    tableconstructor ::= `{´ [fieldlist] `}´
    fieldlist ::= field {fieldsep field} [fieldsep]
    field ::= `[´ exp `]´ `=´ exp | Name `=´ exp | exp
    fieldsep ::= `,´ | `;´

[exp1] = exp2 形式のフィールドは、 キー exp1 と値 exp2 を持つエントリをテーブルに追加する。 name = exp 形式のフィールドは ["name"] = exp と等価である。 最後の exp 形式のフィールドは、[i] = exp と同じである。 ここで i は1から始まる連続した整数であり、他の形式のフィールドはこのカウンタに影響を与えない。 例えば

       a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
は以下と等価である。
       do
         local t = {}
         t[f(1)] = g
         t[1] = "x"         -- 最初のexp
         t[2] = "y"         -- 2番目のexp
         t.x = 1            -- temp["x"] = 1
         t[3] = f(x)        -- 3番目のexp
         t[30] = 23
         t[4] = 45          -- 4番目のexp
         a = t
       end

もし最後のフィールドが exp 形式で、その式が関数呼び出しか可変引数式であれば、 その戻り値がすべてリストに追加される (2.5.8 を参照)。 これを避けるには、関数呼び出し(あるいは可変引数式)をカッコで囲む (2.5 を参照)。

自動生成コードに便利なように、各フィールドの終わりに省略可能なセミコロンを付けても良い。

2.5.8 - 関数呼び出し

Luaの関数呼び出しは以下の構文である。

    functioncall ::= prefixexp args

関数呼び出しでは、 まず prefixexp と args が評価される。 もし prefixexp の値が 関数 であれば、与えられた引数でその関数が呼ばれる。 そうでなければ、prefixexp の "call" メタメソッドが呼ばれる。 そのとき prefixexp が最初の引数として渡され、二番目以降に元々の引数が続く (2.8 を参照)。

書式

    functioncall ::= prefixexp `:´ Name args
は「メソッド」と呼ばれる。 呼び出し v:name(...) は v.name(v, ...) のシンタックスシュガーであり、 v の評価がただ一度である点だけが異なる。

引数は以下の構文を持つ。

    args ::= `(´ [explist1] `)´
    args ::= tableconstructor
    args ::= String

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

Luaのフリーフォーマット構文の例外として、 関数呼び出しの `(´ の直前で改行することはできない。 この制限によって言語の曖昧さが避けられる。 つまり、この制限がなかった場合、もし次のように書くと

       a = f
       (g).x(a)

Luaは単一の式 a = f(g).x(a) と解釈したかもしれない。 この場合、2つの文にしたければ間にセミコロンが必要である。 だか実際には、f を呼びたければ (g) の前の改行を取り除かなければならない。

return functioncall のような呼び出し形式は 終端呼び出し と呼ばれる。 Luaは 終端呼び出し最適化 (または 終端再帰最適化) を実装している。 終端呼び出しでは、呼び出された関数は呼び出し側関数のスタックエントリを再利用する。 その結果、終端呼び出しのネスト数の制限なしに (無限に再帰呼び出しして) プログラムを実行できる。 しかしながら、終端呼び出しは呼び出し側関数に関するデバッグ情報を消してしまう。 終端呼び出しは、単一の関数呼び出しで return するという特別な状況でのみ起こることに注意。 この構文では、呼び出した関数の戻り値がそのまま呼び出し側関数の戻り値になる。 よって、以下の例はどれも終端呼び出しではない。

       return (f(x))        -- 戻り値が1個に調節されている
       return 2 * f(x)      -- 戻り値が加工されている
       return x, f(x)       -- 戻り値が追加されている
       f(x); return         -- 戻り値が捨てられている
       return x or f(x)     -- 戻り値が1個に調節されている

2.5.9 - 関数定義

関数定義の構文を以下に示す。

    function ::= function funcbody
    funcbody ::= `(´ [parlist1] `)´ block end

以下のシンタックスシュガーは関数定義を単純化する。

    stat ::= function funcname funcbody
    stat ::= local function Name funcbody
    funcname ::= Name {`.´ Name} [`:´ Name]

以下の文

       function f () ... end
は次のように変換される。
       f = function () ... end

以下の文

       function t.a.b.c.f () ... end
は次のように変換される。
       t.a.b.c.f = function () ... end

以下の文

       local function f () ... end
は次のように変換される。
       local f; f = function () ... end
次のようにではない。
       local f = function () ... end
(この違いは、関数の中で f を参照できるかどうかである。)

関数定義は実行可能な式であり、関数 型の値を持つ。 Luaがチャンクをコンパイルすると、 その中にある関数の本体もコンパイルされる。 そして、Luaが関数定義を実行したとき、 関数は インスタンス化 (または クローズ) される。 この関数インスタンス (または クロージャ) は式の最終的な値である。 同じ関数の異なるインスタンスは異なるローカル変数と異なる環境テーブルを参照する場合がある。

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

    parlist1 ::= namelist [`,´ `...´]  |  `...´

関数が呼ばれると、実引数リストは仮引数リストの長さに調節される。 ただし、仮引数リストの最後が3つのドット (`...´) である 可変引数 の場合を除く。 可変引数では実引数が調節されず、 代わりに余分の実引数はすべて 可変引数式 によって関数に渡される。 可変引数式もまた3つのドットで書く。 この式の値は、すべての余分の実引数からなるリストである。 これは複数の戻り値を持つ関数に似ている。 可変引数式が他の式の中やリストの途中で使われた場合は、 結果のリストは要素が1個に調節される。 リストの最後の要素で使われた場合は、 調節は行われない(カッコで囲った場合を除く)。

例として、以下の定義を考える。

       function f(a, b) end
       function g(a, b, ...) end
       function r() return 1,2,3 end

この場合、実引数から仮引数と可変引数式へ以下のようにマッピングされる。

       呼び出し         仮引数

       f(3)             a=3, b=nil
       f(3, 4)          a=3, b=4
       f(3, 4, 5)       a=3, b=4
       f(r(), 10)       a=1, b=10
       f(r())           a=1, b=2

       g(3)             a=3, b=nil, ... -->  (なし)
       g(3, 4)          a=3, b=4,   ... -->  (なし)
       g(3, 4, 5, 8)    a=3, b=4,   ... -->  5  8
       g(5, r())        a=5, b=1,   ... -->  2  3

関数の結果を返すには return 文を使う (2.4.4 を参照)。 return 文に出会わずに制御が関数の終わりまで達したら、関数は何も返さない。

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

       function t.a.b.c:f (...) ... end
は、以下の文のシンタックスシュガーである。
       t.a.b.c.f = function (self, ...) ... end

2.6 - 可視ルール

Luaはレキシカルスコープを持つ言語である。 変数のスコープは、それが宣言された文の 次 から始まり、 その宣言を含む最も内側のブロックのendで終わる。 以下の例を考えよう。

  x = 10                -- グローバル変数
  do                    -- 新しいブロック
    local x = x         -- 新しい変数 `x'、値は 10
    print(x)            --> 10
    x = x+1
    do                  -- 別のブロック
      local x = x+1     -- 別の新しい `x'
      print(x)          --> 12
    end
    print(x)            --> 11
  end
  print(x)              --> 10  (グローバル変数)

local x = x のような宣言に注意。 新しく定義された x はまだスコープに入っていないので、 右辺の x は外側の変数を参照する。

レキシカルスコープのルールにより、 ローカル変数はそのスコープの内側に定義された関数から自由にアクセスできる。 内部関数から使われるローカル変数は、 内部関数の中では 上位値 または 外部ローカル変数 と呼ばれる。

local 文を実行するたびに新しいローカル変数が宣言されることに注意。 以下の例を考えよ。

  a = {}
  local x = 20
  for i=1,10 do
    local y = 0
    a[i] = function () y=y+1; return x+y end
  end

このループは10個のクロージャ (つまり匿名関数の10個のインスタンス) を作る。 クロージャはすべて同じ x を共有するが、 それぞれ異なった y を持つ。

2.7 - エラー処理

Luaは組み込み拡張言語であるから、 すべてのLuaアクションはホストプログラムのCのコードがLuaライブラリの関数を呼ぶことによってスタートする (lua_pcall を参照)。 Luaのコンパイル中や実行中でエラーが起きたときは、制御がCに返され、 適切な動作を行うことができる (例えばエラーメッセージを出すとか)。

Luaコードは error 関数を呼ぶことで明示的にエラーを起こすことができる。 もしLua内でエラーを捕らえる必要があれば、 pcall 関数を使えばよい。

2.8 - メタテーブル

Luaのどの値も メタテーブル を持つことができる。 メタテーブル はLuaの通常のテーブルであるが、 その値に対して特殊な演算をしたときの挙動を定義する。 メタテーブルのフィールドを設定することで、オブジェクトの動作をいくつかの面で変えることができる。 例えば、数値以外の値が加算のオペランドになったとき、 Luaはメタテーブルの "__add" フィールドをチェックする。 もしそれが見つかれば、加算を行うためにその関数が呼ばれる。

メタテーブルのキーを イベント、値を メタメソッド と呼ぶ。 前の例でいうと、"add" がイベントで、加算を行う関数がメタメソッドである。

getmetatable 関数で任意の値のメタテーブルを取り出すことができる。

テーブルのメタテーブルは setmetatable 関数で変更できる。 他の型のメタテーブルをLuaで変えることはできない (デバッグライブラリを除く)。 そのためにはCのAPIを使わなければならない。

テーブルとユーザーデータは独立したメタテーブルを持つことができる (複数のテーブルやユーザーデータが同じメタテーブルを共有することもできる)。 他の型の値は、型ごとに単一のメタテーブルを共有する。 つまりすべての数値に対してひとつだけメタテーブルが存在し、 すべての文字列に対してひとつだけメタテーブルが存在し、 以下同様である。

メタテーブルは、算術演算、関係比較、連結、長さ演算子、インデックス付けについて、オブジェクトがどう振る舞うかを制御する。 また、ユーザーオブジェクトに関しては、オブジェクトがガベージコレクトされたときに呼ばれる関数も定義できる。 各演算には イベント と呼ばれる特殊なキーが関連付けられている。 Luaが値に対してこれらの演算を行うとき、 その値がメタテーブルを持っていてイベントが設定されているかチェックされる。 キーに割り当てられた値 (メタメソッド) はLuaがその演算をどう行うかをコントロールする。

メタテーブルがコントロールできる演算を以下に示す。 各演算は関連付けられた名前で区別される。 各演算のキーは、その名前の前に2つのアンダースコア `__´ が付く文字列である。 例えば、"add"演算のキーは、文字列 "__add" である。 これらの演算の効果は、いかに演算が実行されるかを記述したLuaの関数で説明する。

ここにLuaのコードを示しているのは、単に説明のためである。 実際はインタプリタにハードコードされており、この擬似コードよりも効率的に動作する。 ここで使われている関数 (rawget、tonumber など) は 5.1 に記述されている。 与えられたオブジェクトのメタメソッドを取り出すコードとして、以下の表現を用いているが、

  metatable(obj)[event]
これは次のように読んでもらいたい。
  rawget(metatable(obj) or {}, event)

つまり、メタメソッドへのアクセスで他のメタメソッドを呼び出すことはなく、 オブジェクトがメタメソッドを持っていなくてもエラーを起こすことはない (その場合は単に nil を返す)。

  • "add": + 演算。

    以下の getbinhandler 関数は二項演算でLuaがどのようにハンドラを選ぶかを定義する。 まずLuaは最初のオペランドについて試みる。 もしその型が、その演算についてハンドラを定義していなければ、 二番目のオペランドを試みる。

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

    この関数を使って op1 + op2 の挙動を示すと、

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

  • "sub": - 演算。 "add"演算と同じように動作する。

  • "mul": * 演算。 "add"演算と同じように動作する。

  • "div": * 演算。 "add"演算と同じように動作する。

  • "mod": % 演算。 "add"演算と同じように動作する。 Behavior similar to the "add" operation, プリミティブ演算として 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)         -- プリミティブの文字列長
   elseif type(op) == "table" then
     return #op                -- プリミティブのテーブル長
   else
     local h = metatable(op).__len
     if h then
       -- オペランドに対してハンドラを呼ぶ
       return h(op)
     else  -- ハンドラがない、デフォルトの動作
       error("...")
     end
   end
 end
    テーブルの長さの説明は 2.5.5 を参照。

  • "eq": == 演算。 関数 getcomphandler は、比較演算子のメタメソッドをLuaがどのように選ぶかを定義する。 両方のオブジェクトが同じ型で、その演算に対して同じメタメソッドを持つ場合だけ、 メタメソッドが選択される。
     function getcomphandler (op1, op2, event)
   if type(op1) ~= type(op2) then return nil end
   local mm1 = metatable(op1)[event]
   local mm2 = metatable(op2)[event]
   if mm1 == mm2 then return mm1 else return nil end
 end
    "eq"イベントは次のように定義される。
     function eq_event (op1, op2)
   if type(op1) ~= type(op2) then  -- 型が異なるか?
     return false   -- 異なるオブジェクト
   end
   if op1 == op2 then   -- プリミティブのイコール
     return true   -- オブジェクトは等しい
   end
   -- メタメソッドを試す
   local h = getcomphandler(op1, op2, "__eq")
   if h then
     return h(op1, op2)
   else
     return false
   end
 end
    a ~= b は not (a == b) と等価である。

  • "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 = getcomphandler(op1, op2, "__lt")
     if h then
       return h(op1, op2)
     else
       error("...");
     end
   end
 end
    a > b は b < a と等価である.

  • "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 = getcomphandler(op1, op2, "__le")
     if h then
       return h(op1, op2)
     else
       h = getcomphandler(op1, op2, "__lt")
       if h then
         return not h(op2, op1)
       else
         error("...");
       end
     end
   end
 end
    a >= b は b <= a と等価である。 "le"メタメソッドがなければ、 Luaは a <= b を not (b < a) とみなして"lt"を試みることに注意。

  • "index": table[key] インデックスアクセス。
     function gettable_event (table, key)
   local h
   if type(table) == "table" then
     local v = rawget(table, key)
     if v ~= nil then return v end
     h = metatable(table).__index
     if h == nil then return nil end
   else
     h = metatable(table).__index
     if h == nil then
       error("...");
     end
   end
   if type(h) == "function" then
     return h(table, key)      -- ハンドラを呼ぶか、
   else return h[key]          -- 演算を繰り返す
   end
 end

  • "newindex": table[key] = value インデックス代入。
     function settable_event (table, key, value)
   local h
   if type(table) == "table" then
     local v = rawget(table, key)
     if v ~= nil then rawset(table, key, value); return end
     h = metatable(table).__newindex
     if h == nil then rawset(table, key, value); return end
   else
     h = metatable(table).__newindex
     if h == nil then
       error("...");
     end
   end
   if type(h) == "function" then
     return h(table, key,value)    -- ハンドラを呼ぶか、
   else h[key] = value             -- 演算を繰り返す。
   end
 end

  • "call": 値を関数呼び出ししたときに呼ばれる。
     function function_event (func, ...)
   if type(func) == "function" then
     return func(...)   -- プリミティブの関数呼び出し
   else
     local h = metatable(func).__call
     if h then
       return h(func, ...)
     else
       error("...")
     end
   end
 end

2.9 - 環境

スレッド、関数、ユーザーデータ型のオブジェクトは、 メタテーブルに加えてもうひとつ、 関連付けれられたテーブルを持つ。 これを 環境 と呼ぶ。 メタテーブル同様、環境も普通のテーブルである。

ユーザーデータに関連付けられた環境はLuaにとっては意味を持たない。 これはプログラマのために、 ユーザーデータにテーブルを関連付ける機能として存在するだけである。

スレッドに関連付けられた環境は グローバル環境 と呼ぶ。 これは、スレッドと、スレッドが作成した (loadfile、loadstring または load を使って) ネストされていない関数のデフォルトの環境として使われ、 Cのコードで直接アクセスできる (3.3 を参照)。

Cの関数に関連付けられた環境はCのコードで直接アクセスできる (3.3 を参照)。 またその関数で作成する他のCの関数のデフォルトの環境として使われる。

Luaの関数に関連付けられた環境は、 その関数の中でアクセスするグローバル変数を解決するために使われる (2.3 を参照)。 またその関数で作成する他のLuaの関数のデフォルトの環境として使われる。

setfenv を呼ぶと走行中のスレッドや Lua の関数の環境を変更できる。 getfenv を呼ぶと走行中のスレッドや Lua の関数の環境を取得できる。 他のオブジェクト (ユーザーデータ、Cの関数、他のスレッド) の環境を操作するには、CのAPIを使わなければならない。

2.10 - ガベージコレクション

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

Luaはインクリメンタルマークアンドスイープコレクタを実装している。 ガベージコレクションの周期を制御するために2つの数値、 ガベージコレクタ停止値 と ガベージコレクタステップ係数 を使うことができる。

ガベージコレクタ停止値は、 どれだけ経ったら新しいサイクルを開始するかを制御する。 値が大きいほどコレクタが消極的になる。 1より小さな値にすると、コレクタがすぐに新しいサイクルを開始する。 2にすると、使われているメモリの合計が2倍になったらコレクタが新しいサイクルを開始する。

ステップ係数は、メモリ確保に対するコレクタの相対速度を制御する。 値が大きいほどコレクタは積極的になるが、 各インクリメンタルステップのサイズが大きくなる。 1より小さな値にすると、コレクタは非常に遅くなり、結果としてサイクルが終わらないかもしれない。 デフォルトの2では、メモリ確保の「2倍」の速度でコレクタが動作する。

Cの lua_gc か Luaの collectgarbage を呼ぶと、これらの値を変更できる。 いずれもパーセント値で引数を取る (従って 100 を渡すと 1.00 を意味する)。 これらの関数でコレクタを直接制御できる (停止させたり再開させたり)。

2.10.1 - ガベージコレクションメタメソッド

CのAPIを使う場合、ユーザーデータにガベージコレクタメタメソッドを設定できる (2.8を参照)。 このメタメソッドは ファイナライザ と呼ばれることもある。 ファイナライザはLuaのガベージコレクタを外部リソースと共に使えるようにする (ファイルやネットワーク接続、データベース接続などを閉じたり、独自に確保したメモリを解放するとか)。

メタテーブルに __gc フィールドを持つユーザーデータがガベージになっても、ガベージコレクタはそれをすぐには回収しない。 その代わり、Luaはそれをリストに入れる。 他のオブジェクトの回収が終わったあと、Luaはリスト内のユーザーデータに対して以下の関数と同等のことを行う。

 function gc_event (udata)
   local h = metatable(udata).__gc
   if h then
     h(udata)
   end
 end

各ガベージコレクションサイクルの終わりに、 作られたときと 逆の順番で ユーザーデータのファイナライザが呼ばれる。 つまり、最初に呼ばれるファイナライザは、一番最近に作られたユーザーデータのものである。

2.10.2 - 弱参照テーブル

弱参照テーブル は 弱参照 な要素を持つテーブルである。 弱参照はガベージコレクタに無視される。 言い換えると、オブジェクトへの参照が弱参照のみであれば、ガベージコレクタはそのオブジェクトを回収してしまう。

弱参照テーブルは、キー、値、あるいはその両方が弱参照である。 弱参照キーを持つテーブルは、キーは回収されるが、その値は回収されない。 弱参照キーと弱参照値の両方を持つテーブルでは、キーも値も回収の対象になる。 キーと値のどちらか一方が回収されると、キーと値のペア全体がテーブルから除去される。 テーブルの弱参照の性質は、メタテーブルの __mode フィールドで制御できる。 もし __mode フィールドが文字列で、文字 `k´ が含まれていたら、テーブルのキーが弱参照となる。 もし __mode フィールドが文字 `v´ を含んでいたら、テーブルの値が弱参照となる。

メタテーブルとして使った後に、そのテーブルの __mode フィールドの値を変更するべきではない。 このメタテーブルで制御されているテーブルの弱参照の挙動が未定義となる。

2.11 - コルーチン

Luaはコルーチンをサポートしている。 協調的マルチスレッド と呼ばれることもある。 Luaのコルーチンは独立に実行されるスレッドを表現している。 マルチスレッドシステムのスレッドとは違って、 コルーチンはyield関数を呼んで明示的に実行を中断しなければならない。

コルーチンを作るには coroutine.create を呼ぶ。 これはひとつだけ引数をとり、それにコルーチンのメイン関数を渡す。 create 関数は新しいコルーチンを作成し、その スレッド オブジェクトを返す。 コルーチンはすぐには実行されない。

coroutine.create から返されたスレッドを最初の引数に渡して最初に coroutine.resume を呼んだとき、 そのメイン関数の最初の行からコルーチンの実行が始まる。 coroutine.resume に余分の引数を指定すると、それらはコルーチンのメイン関数に渡される。 コルーチンが開始されたら、終わりに達するか yield を呼ぶまで実行される。

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

コルーチンは coroutine.yield を呼ぶことで中断される。 コルーチンが中断されると、対応する coroutine.resume からすぐに戻る。 コルーチンの中で呼ばれた関数の中で中断されても同様である (つまり、メイン関数から直接的/間接的に呼ばれた、メイン関数以外の関数の中でも)。 この場合も、coroutine.resume は true を返す。 coroutine.yield に引数が渡されていれば、それも返される。 次に同じコルーチンをresumeすると、中断した場所から実行が再開される。 coroutine.resume に余分な引数を渡すと、coroutine.yield からそれらが返される。

coroutine.wrap 関数は coroutine.create と同様にコルーチンを作成するが、 コルーチン自身を返すのではなく、コルーチンをresumeする関数を返す。 その関数に渡された引数は coroutine.resume に追加の引数として渡される。 coroutine.resume からの戻り値は、最初のひとつ (ブーリアン型のエラーコード) を除いた残りが返される。 coroutine.resume と違って、 この関数はエラーを捕らえることはなく、内部で起きたエラーは呼び出した側に伝搬する。

例として、次のコードを考える。

function foo (a)
  print("foo", a)
  return coroutine.yield(2*a)
end

co = coroutine.create(function (a,b)
      print("co-body", a, b)
      local r = foo(a+1)
      print("co-body", r)
      local r, s = coroutine.yield(a+b, a-b)
      print("co-body", r, s)
      return b, "end"
end)

print("main", coroutine.resume(co, 1, 10))
print("main", coroutine.resume(co, "r"))
print("main", coroutine.resume(co, "x", "y"))
print("main", coroutine.resume(co, "x", "y"))
これを実行すると、以下の出力を得る。
co-body 1       10
foo     2
main    true    4
co-body r
main    true    11      -9
co-body x       y
main    true    10      end
main    false   cannot resume dead coroutine

3 - アプリケーションプログラムインタフェイス

このセクションではLuaのためのCのAPIを説明する。 これは、ホストプログラムがLuaに働きかけるためのCの関数のセットである。 すべてのAPI関数と、関連する型、定数は、ヘッダーファイル lua.h で定義されている。

このマニュアルでは「関数」という言葉を使うが、代わりにマクロとして提供されているものもある。 そのようなマクロはすべて、各引数がちょうど一度だけ評価され、いかなる隠れた副作用も発生しない (ただし最初の引数を除く。ここには常にLuaステートを渡す)。

ほとんどのCのライブラリと同様に、 LuaのAPI関数は引数の妥当性や一貫性をチェックしない。 しかし、ファイル luaconf.h の中のマクロ luai_apicheck を適切に定義してLuaを再コンパイルすると、この動作を変更できる。

3.1 - スタック

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

LuaがCを呼ぶときは、以前のスタックの状態やまだアクティブなCの関数が使っているスタックに影響されないように、新しいスタックを用意する。 このスタックはCの関数に渡された引数が格納されており、 Cの関数から呼び出し側に返す戻り値を格納するためにも使われる (lua_CFunction を参照)。

利便性のため、ほとんどの問い合わせ用API関数は厳密なスタックの規則に従っていない。 代わりに、インデックス を使って、スタック内の任意の要素にアクセスできる。 プラスのインデックスはスタック内の 絶対 位置を表し (1 から始まる)、 マイナスのインデックスはスタックトップからの相対 オフセット を表す。 具体的に言うと、スタックに n 個の要素があるとして、 インデックス1は最初の要素 (つまり、空のスタックに最初に積まれた要素) を表し、 インデックス n は最後の要素を表す。 インデックス-1も最後の要素 (つまりスタックトップにある要素) を表し、 インデックス -n は最初の要素を表す。 有効な インデックスは1からスタックトップの間だけである (つまり 1 <= abs(index) <= top)。

3.2 - スタックサイズ

LuaのAPIを使うときは、一貫性を保証する責任がある。 特に、スタックオーバーフローに気を付けなければならない。 スタックサイズを伸ばすためには関数 lua_checkstack を使う。

LuaがCを呼ぶときは、 最低でも全体で LUA_MINSTACK 個のスタック要素が利用可能である。 LUA_MINSTACK は20に定義されており、 スタックにどんどん要素を積むようなループがあったりしなければ、 普通はスタック空間を気にしなくても良い。

多くの問い合わせ関数には、スタック空間内で利用可能な任意のインデックス値を使える。 つまり、lua_checkstack を使って設定できる最大スタックの長さまでのインデックスである。 このようなインデックスは 受け入れ可能なインデックス と呼ぶ。 もっと正確には、受け入れ可能なインデックス は以下のように定義される。

     (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace)
0は決して受け入れ可能なインデックスにならない。

3.3 - 擬似インデックス

特に明記されていなければ、 どの関数も 疑似インデックス と呼ばれる有効なインデックスを受け付ける。 これはスタック内に無いいくつかのLuaの値にCのコードからアクセスするためのものである。 疑似インデックスは、スレッドの環境、関数の環境、レジストリ、Cの関数の上位値にアクセスするために使う (3.4 を参照)。

スレッドの環境 (グローバル変数がある場所) は常に擬似インデックス LUA_GLOBALSINDEX の位置にある。 走行中のCの関数の環境は常に擬似インデックス LUA_ENVIRONINDEX の位置にある。

グローバル変数の値にアクセスしたり変更するためには、 環境テーブルに対して普通のテーブル操作を行う。 例えば、グローバル変数の値にアクセスするには以下を行う。

       lua_getfield(L, LUA_GLOBALSINDEX, varname);

3.4 - Cのクロージャ

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

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

3.5 - レジストリ

Luaはレジストリを提供している。 これは定義済みのテーブルで、好きなLuaの値を格納するためにCのコードから使うことができる。 このテーブルは常に疑似インデックス LUA_REGISTRYINDEX に置かれている。 どのCのライブラリもデータを保持するためにこのテーブルを使えるが、 衝突を避けるため他のライブラリが使っていないキーを選ぶ必要がある。 典型的には、ライブラリ名を含む文字列とか、自分のコードで使っているCオブジェクトのアドレスを持つライトユーザーデータを、キーとして使うと良い。

レジストリ内の整数キーは、補助ライブラリで実装されているリファレンスメカニズムで使われており、それゆえ他の目的に使うべきでない。

3.6 - Cでのエラー処理

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

APIのほとんどの関数はエラー、例えばメモリ確保エラーなどを起こす可能性がある。 以下の関数は保護モード (つまり、実行するために保護された環境を作る) で実行するため、決してエラーを起こさない。 lua_newstate, lua_close, lua_load, lua_pcall, and lua_cpcall。

lua_error を呼ぶと、CのコードからLuaのエラーを発生させることが出来る。

3.7 - 関数と型

以下にCのAPIのすべての関数と型をアルファベット順に示す。

lua_Alloc

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

Luaステートが使うメモリアロケータ関数の型である。 メモリアロケータ関数は realloc に似た機能を提供しなければならないが、 まったく同じではない。 引数は以下の通り。 ud: lua_newstate に渡されたポインタ。 ptr: 割り当て/再割り当て/解放するブロックへのポインタ。 osize: 元のブロックサイズ。 nsize: 新しいブロックサイズ。 osize がゼロの場合、またその場合に限り、ptr は NULLになる。 nsize がゼロの場合、アロケータは NULL を返さなければならない。 osize がゼロでない場合、ptr が指すメモリブロックを解放すべきである。 nsize がゼロでない場合、要求を満たせなければアロケータは NULL を返す。 nsize がゼロでなく osize がゼロの場合、アロケータは malloc のように振る舞うべきである。 nsize と osize が共にゼロでない場合、 osize >=nsize であれば、Luaはアロケータが決して失敗しないものと仮定している。

アロケータ関数の簡単な実装を示そう。 これは lua_newstate が補助ライブラリで使っている。

static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {
  (void)ud;     /* not used */
  (void)osize;  /* not used */
  if (nsize == 0) {
    free(ptr);  /* ANSIはfree(NULL)は効果がないと規定している */
    return NULL;
  }
  else
    /* ANSIはrealloc(NULL, size)はmalloc(size)と同じと規定している */
    return realloc(ptr, nsize);
}

lua_atpanic

          lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

新しいパニック関数を設定し、古いものを返す。

保護された環境の外側でエラーが起きると、Luaは パニック関数 を呼び、それから exit(EXIT_FAILURE) を呼んでホストアプリケーションを終了する。 パニック関数が戻らなければ(例えばロングジャンプするとかで)、終了しないようにできる。

パニック関数はスタックの一番上にあるエラーメッセージにアクセスできる。

lua_call

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

関数を呼ぶ。

関数を呼ぶには、以下の手順に従わなければならない。 まず、呼びたい関数をスタックに積む。 次に、その関数に渡す引数を順番通りに積む。 つまり最初の引数を最初に積む。 最後に、lua_call を呼ぶ。 nargs はスタックに積んだ引数の数である。 すべての引数と関数の値は関数を呼んだときにスタックから取り除かれる。 関数が戻るとき、スタックに戻り値が積まれる。 戻り値の数は nresults 個に調節される。 ただし nresults が LUA_MULTRET の場合は調節されない。 この場合、関数の すべての 戻り値が積まれる。 Luaは戻り値をスタック空間に合うようにする。 関数の戻り値は順番通りに (最初の戻り値が最初に) スタックに積まれる。 従って呼び出し後のスタックの一番上は、その最後の戻り値である。

呼び出した関数の中で起きたエラーは上に伝搬される(longjmpを使って)。

以下のLuaコードと等価なことをホストプログラムからはどうすれば良いのかの例を示す。

       a = f("how", t.x, 14)
これをCで書くと:
    lua_getfield(L, LUA_GLOBALSINDEX, "f");          /* 呼ぶ関数 */
    lua_pushstring(L, "how");                                 /* 最初の引数 */
    lua_getfield(L, LUA_GLOBALSINDEX, "t");            /* テーブル`t' */
    lua_getfield(L, -1, "x");                 /* t.xの結果(2番目の引数)を積む */
    lua_remove(L, -2);                           /* スタックから `t' を取り除く */
    lua_pushinteger(L, 14);                                   /* 3番目の引数 */
    lua_call(L, 3, 1);         /* 3個の引数と1個の戻り値で関数を呼ぶ */
    lua_setfield(L, LUA_GLOBALSINDEX, "a");        /* グローバル変数 `a' に代入 */
上のコードは「整合が取れている」ことに注目。 最終的にスタックは元の状態に戻っている。 これは良いプログラミング作法であると考えられる。

lua_CFunction

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

Cの関数の型。

適切にLuaとやりとりするに、Cの関数は、 引数と戻り値の受け渡し方法を定義する以下の手順に従わなければならない。 Cの関数はLuaからの引数をスタックに順番通り受け取る (最初の引数が最初に積まれる)。 つまり、関数の開始時点では、 lua_gettop(L) は関数が受け取った引数の数を返す。 最初の引数(もしあれば)はインデックス1で、最後の引数はインデックス lua_gettop(L) である。 Luaに値を返すには、Cの関数は単にスタックにその値を順番通り (最初の戻り値を最初に) 積み、戻り値の数を返すだけで良い。 戻り値より下のスタックにある余計な値はすべてLuaによって捨てられる。 Luaの関数と同様、Luaから呼ばれるCの関数でも、たくさんの戻り値を返すことができる。

例として、可変個の数値の引数を取り、その平均と合計を返す関数を以下に示す。

       static int foo (lua_State *L) {
         int n = lua_gettop(L);    /* 引数の数 */
         lua_Number sum = 0;
         int i;
         for (i = 1; i <= n; i++) {
           if (!lua_isnumber(L, i)) {
             lua_pushstring(L, "関数 `average' の引数が正しくありません");
             lua_error(L);
           }
           sum += lua_tonumber(L, i);
         }
         lua_pushnumber(L, sum/n);        /* 最初の戻り値 */
         lua_pushnumber(L, sum);         /* 2番目の戻り値 */
         return 2;                   /* 戻り値の数 */
       }

lua_checkstack

          int lua_checkstack (lua_State *L, int extra);

スタックに少なくとも extra 個の空きスロットがあることを保証する。 もしスタックをそのサイズまで伸ばせなければ false を返す。 スタックがすでに指定された長さよりも長ければ、 わざわざスタックを縮めたりせず、何も変えない。

lua_close

          void lua_close (lua_State *L);

渡されたLuaステート内のすべてのオブジェクトを破棄し (もしあればガベージコレクションメタメソッドも呼び)、 ステート内で使われていたすべての動的メモリを解放する。 プラットフォームによっては、 ホストプログラムが終了するときにすべてのリソースが自動的に解放されるため、 この関数を呼ぶ必要がないかもしれない。 一方、デーモンやウェブサーバのような長時間実行するプログラムでは、 消費リソースが増大するのを避けるために、 必要なくなったステートはすぐに解放する必要があるだろう。

lua_concat

          void lua_concat (lua_State *L, int n);

スタックトップから n 個の値を連結し、それらを取り除き、結果をスタックトップに載せる。 もし n が1ならは、結果はその1つの文字列である (要するに何もしない)。 もし n が0ならば、結果は空文字列である。 連結は通常のLuaの意味論に従って行われる (2.5.4 を参照)。

lua_cpcall

          int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);

Cの関数 func を保護モードで呼ぶ。 func はスタックに1個の引数、ud を持つライトユーザーデータが載った状態で開始する。 エラーが起こった場合、 lua_cpcall は lua_pcall と同じエラーコードを返し、エラーオブジェクトをスタックトップに置く。 そうでなければ0を返し、スタックは何も変えない。 func から返される値はすべて捨てられる。

lua_createtable

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

新しい空のテーブルを作り、スタックに積む。 この新しいテーブルは narr 個の配列要素と nrec 個の非配列要素のための割り当て済み空間を持っている。 この事前割り当ては、そのテーブルがたくさんの要素を持つであろうとわかっている場合に役に立つ。 それ以外の場合は、関数 lua_newtable を使っても良い。

lua_dump

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

関数をバイナリチャンクとしてダンプする。 スタックトップにLuaの関数を1つ受け取り、1つのバイナリチャンクを生成する。 これは、再びロードされたとき、ダンプされたものと同等の関数を作る。 チャンクの各部を生成するとき、 lua_dump はそれらを書き込むために関数 writer (lua_Writer を参照) を、data を与えて呼ぶ。

戻り値は writer の最後の呼び出しが返したエラーコードである。 0はエラーなしを表す。

この関数はスタックからLuaの関数を取り除かない。

lua_equal

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

受け入れ可能なインデックス index1 と index2 の位置にある2つの値が等しければ1を返す。 そうでなければ0を返す。 どちらかのインデックスが有効でないときも0を返す。 比較はLuaの == 演算子の意味論に従って行われる (つまり、メタメソッドを呼ぶ場合がある)。

lua_error

          int lua_error (lua_State *L);

Luaエラーを生成する。 呼ぶ前に、エラーメッセージ (実際にはどんな型の値でも良い) をスタックトップに置かなければならない。 この関数はロングジャンプを行うので、決して戻ってこない (luaL_error を参照)。

lua_gc

          int lua_gc (lua_State *L, int what, int data);

ガベージコレクタを制御する。

この関数は引数 what の値に応じていくつかの仕事を行う。

  • LUA_GCSTOP--- ガベージコレクタを停止させる。
  • LUA_GCRESTART--- ガベージコレクタを再開させる。
  • LUA_GCCOLLECT--- フルガベージコレクションサイクルを実行する。
  • LUA_GCCOUNT--- Luaが使っている現在のメモリ量を (キロバイトで) 返す。
  • LUA_GCCOUNTB--- Luaが使っている現在のメモリ量のバイト数を1024で割った余りを返す。
  • LUA_GCSTEP--- ガベージコレクションのインクリメンタルステップひとつを実行する。 ステップの「サイズ」は data で制御する。 大きな値は大きなステップを意味するが、具体的には定まっていない。 ステップサイズを制御したければ、 data の値を実験的に調整しなければならない。 そのステップでガベージコレクションサイクルが終われば、この関数は1を返す。
  • LUA_GCSETPAUSE--- コレクタの 停止値 (see 2.10 を参照) の新しい値として data ÷100を設定する。 関数は以前の停止値を返す。
  • LUA_GCSETSTEPMUL--- コレクタの ステップ係数 (2.10 を参照) の新しい値として 引数 ÷100を設定する。 関数は以前のステップ係数の値を返す。

lua_getallocf

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

渡されたステートのメモリアロケータ関数を返す。 ud が NULL でなければ、 Luaは lua_newstate に渡されたポインタを *ud に格納する。

lua_getfenv

          void lua_getfenv (lua_State *L, int index);

指定したインデックスの値の環境テーブルをスタックに積む。

lua_getfield

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

値 t[k] をスタックに積む。 ただし t は指定した有効なインデックス index の値である。 Luaの中でと同様に、この関数は "index" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。

lua_getglobal

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

グローバル変数 name の値をスタックに積む。 これはマクロとして定義されている。

#define lua_getglobal(L,s)  lua_getfield(L, LUA_GLOBALSINDEX, s)

lua_getmetatable

          int lua_getmetatable (lua_State *L, int index);

指定した受け入れ可能なインデックスの値のメタテーブルをスタックに積む。 インデックスが有効でないか、その値がメタテーブルを持っていなければ、 この関数は0を返し、スタックには何も積まない。

lua_gettable

          void lua_gettable (lua_State *L, int index);

値 t[k] をスタックに積む。 ただし t は渡された有効なインデックス index の値で、 k はスタックトップの値である。

この関数はスタックからキーを (そこに結果を置く前に) 取り除く。 Luaの中でと同様に、この関数は "index" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。

lua_gettop

          int lua_gettop (lua_State *L);

スタックトップの要素のインデックスを返す。 インデックスは1から始まるので、この戻り値はスタックの要素数と等しい (そしてゼロはスタックが空であることを意味する)。

lua_insert

          void lua_insert (lua_State *L, int index);

指定した位置より上の要素をずらして空きスペースを作り、スタックトップの要素をその位置に移動する。 疑似インデックスは、実際のスタック位置ではないため、指定できない。

lua_Integer

          typedef ptrdiff_t lua_Integer;

整数値を表現するための、Lua APIで使われる型。

デフォルトでは ptrdiff_t である。 これは通常、マシンが「快適に」扱える最大の整数型である。

lua_isboolean

          int lua_isboolean (lua_State *L, int index);

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

lua_iscfunction

          int lua_iscfunction (lua_State *L, int index);

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

lua_isfunction

          int lua_isfunction (lua_State *L, int index);

指定した受け入れ可能なインデックスの値が関数 (CかLuaどちらかの) であれば1、そうでなければ0を返す。

lua_islightuserdata

          int lua_islightuserdata (lua_State *L, int index);

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

lua_isnil

          int lua_isnil (lua_State *L, int index);

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

lua_isnumber

          int lua_isnumber (lua_State *L, int index);

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

lua_isstring

          int lua_isstring (lua_State *L, int index);

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

lua_istable

          int lua_istable (lua_State *L, int index);

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

lua_isthread

          int lua_isthread (lua_State *L, int index);

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

lua_isuserdata

          int lua_isuserdata (lua_State *L, int index);

指定した受け入れ可能なインデックスの値がユーザーデータ (フルかライトどちらかの) であれば1、そうでなければ0を返す。

lua_lessthan

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

受け入れ可能なインデックス index1 の値が受け入れ可能なインデックス index2 の値よりも小さければ1、そうでなければ0を返す。 どちらかのインデックスが有効でない場合も0を返す。 比較はLuaの < 演算子の意味論に従って行われる (つまり、メタメソッドを呼ぶ場合がある)。

lua_load

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

Luaチャンクをロードする。 エラーがなければ、 lua_load はコンパイルしたチャンクをLuaの関数としてスタックトップに積む。 そうでなければ、エラーメッセージを積む。 lua_load の戻り値は以下の通り。

  • 0 --- エラーなし。
  • LUA_ERRSYNTAX --- コンパイル時に構文エラーが発生。
  • LUA_ERRMEM --- メモリ割り当てエラー。

lua_load はチャンクがテキストかバイナリかを自動的に検出し、それに応じてチャンクをロードする (プログラム luac を参照)。

lua_load はチャンクを読み込むためにユーザが提供する reader 関数を使う (see lua_Reader を参照)。 data 引数はそのリーダ関数に渡される値である。

chunkname 引数はチャンクに名前を与える。 これはエラーメッセージやデバッグ情報で使われる (3.8 を参照)。

lua_newstate

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

新しい独立したステートを作る。 ステートを作れなければ (メモリ不足のために)、NULL を返す。 引数 f はアロケータ関数である。 Luaはこのステートのためのすべてのメモリ確保をこの関数を使って行う。 2番目の引数 ud は、そのアロケータに毎回渡されるポインタである。

lua_newtable

          void lua_newtable (lua_State *L);

新しい空のテーブルを作ってスタックに積む。 lua_createtable(L, 0, 0) と同等である。

lua_newthread

          lua_State *lua_newthread (lua_State *L);

新しいスレッドを作ってスタックに積み、 その新しいスレッドを表す lua_State へのポインタを返す。 この関数が返した新しいステートは元のステートとすべてのグローバルオブジェクト (テーブルとか) を共有するが、独立した実行スタックを持つ。

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

lua_newuserdata

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

この関数は指定されたサイズのメモリブロックを割り当て、 そのアドレスを持つ新しいフルユーザーデータをスタックに積み、 そのアドレスを返す。

ユーザーデータはLua内でCの値を表現する。 フルユーザーデータ はメモリブロックを表す。 これは (テーブルと同じように) オブジェクトである。 作成する必要があり、独自のメタテーブルを持つことができ、 ガベージコレクションされるのを検出できる。 フルユーザーデータは (rawequalの下では) それ自身と比較したときだけ等しい。

Luaが gc メタメソッドを持つフルユーザーデータを回収するとき、 Luaはメタメソッドを呼び、ユーザーデータにファイナライズ済みの印を付ける。 このユーザーデータがもう一度回収されると、Luaは対応するメモリを解放する。

lua_next

          int lua_next (lua_State *L, int index);

スタックからキーを取り出し。 指定したインデックスのテーブルからキー・値のペア (取り出したキーの「次」のペア) を積む。 これ以上要素がなければ、 lua_next は (何も積まずに) 0を返す。

典型的な巡回は次のようになる。

       /* テーブルはスタックの `t' の位置にあるとする */
       lua_pushnil(L);  /* 最初のキー */
       while (lua_next(L, t) != 0) {
         /* 「キー」インデックス-2、「値」はインデックス-1の位置にある */
         printf("%s - %s\n",
           lua_typename(L, lua_type(L, -2)), lua_typename(L, lua_type(L, -1)));
         lua_pop(L, 1);  /* 「値」を除去し、「キー」は次の繰り返しのために残す */
       }

テーブルを巡回する間、 キーが本物の文字列であるかどうか判らないなら、キーに対して直接 lua_tolstring を呼んではならない。 lua_tolstring は指定したインデックスにある値を 変える ため、次の lua_next の呼び出しを混乱させることを覚えておくように。

lua_Number

          typedef double lua_Number;

Luaの数値の型。 デフォルトでは、これはdoubleであるが、 luaconf.h で変えることができる。

コンフィギュレーションファイルを変更することで、 Luaが数値に対して他の型 (floatやlongなど) を使うようにできる。

lua_objlen

          size_t lua_objlen (lua_State *L, int index);

指定した受け入れ可能なインデックスの値の「長さ」を返す。 文字列の場合はその文字列の長さ、 テーブルの場合は長さ演算子 (`#´) の結果、 ユーザーデータの場合は割り当てられたメモリブロックのサイズ、 それ以外の場合は0を返す。

lua_pcall

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

関数を保護モードで呼ぶ。

nargs と nresults は lua_call と同じである。 もしエラーがなければ lua_pcall は lua_call とまったく同じように動作する。 しかし、何かエラーが起きた場合は、 lua_pcall はそれを捕らえて、 1つの値 (エラーメッセージ) をスタックに積んでエラーコードを返す。 lua_call 同様、 lua_pcall は常に関数とその引数をスタックから取り除く。

もし errfunc が0であれば、スタックに返されたエラーメッセージは正確に元のエラーメッセージである。 そうでなければ、errfunc は エラーハンドラ関数 のスタックインデックスを指定する (現在の実装では、疑似インデックスは指定できない)。 実行時エラーが起きると、エラーメッセージを引数としてこの関数が呼ばれ、 その戻り値が lua_pcall から返されるエラーメッセージとなる。

典型的には、エラーハンドラ関数は、エラーメッセージにスタックトレースのようなデバッグ情報を付け加えるのに使う。 そういった情報は lua_pcall から戻った後にはもうスタックから除去されているため、集めることができない。

lua_pcall 関数は成功時は0を返し、 エラーの場合は以下のエラーコードのいずれかを返す (lua.h で定義されている)。

  • LUA_ERRRUN --- 実行時エラー。
  • LUA_ERRMEM --- メモリ確保エラー。 このようなエラーでは、Luaはエラーハンドラ関数を呼ばない。
  • LUA_ERRERR --- エラーハンドラ関数実行中のエラー。

lua_pop

          void lua_pop (lua_State *L, int n);

スタックから n 個の要素を取り除く。

lua_pushboolean

          void lua_pushboolean (lua_State *L, int b);

値 b のブーリアン値をスタックに積む。

lua_pushcclosure

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

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

Cの関数を作るとき、いくつかの値を関連付けて Cのクロージャ を作ることができる (see 3.4)。 これらの値はその関数が呼ばれたときにいつでもアクセスできる。 Cの関数に値を関連付けるには、 まずそれらの値をスタックに積む (複数の値がある場合は、最初の値を最初に積む)。 次に lua_pushcclosureを呼び、 Cの関数を作ってスタックにプッシュする。 引数 n は関数に関連付ける値の数を示す。 lua_pushcclosure はスタックからそれらの値を取り除く。

lua_pushcfunction

          void lua_pushcfunction (lua_State *L, lua_CFunction f);

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

Luaに登録する関数は引数と戻り値を受け渡すために、 正しい手順に従わなければ鳴らない (lua_CFunction を参照)。

lua_pushcfunction(L, f) の呼び出しは lua_pushcclosure(L, f, 0) と同等である。

lua_pushfstring

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

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

  • 結果を格納する空間を割り当てる必要がない。 結果はLuaの文字列であり、Luaはメモリの確保を (そしてガベージコレクションによる解放も) 自分で行う。
  • 変換指定子はかなり制限されている。 フラグや幅、精度は指定できない。 変換師は単純な
    `%%´ (文字 `%´)
`%s´ (長さ制限のないゼロ終端文字列)
`%f´ (lua_Number)
`%p´ (16進数としてのポインタ)
`%d´ (int)
`%c´ (文字としての int)
    だけが使える。

lua_pushinteger

          void lua_pushinteger (lua_State *L, lua_Integer n);

値 n を持つ数値をスタックに積む。

lua_pushlightuserdata

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

ライトユーザーデータをスタックに積む。

ユーザーデータはLua内でCの値を表現する。 ライトユーザーデータ はポインタを表す。 それは (数値と同じように) 値である。 作成はせず、メタテーブルも持たず、(作成しないので) 回収もされない。 ライトユーザーデータは、同じCのアドレスを持つ「どの」ライトユーザーデータとも等しい。

lua_pushlstring

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

s が指すサイズ len の文字列をスタックに積む。 Luaは与えられた文字列を内部的にコピーする (または再利用する) ため、 sが指すメモリは関数が戻ったあとすぐに解放あるいは再利用してよい。 文字列は埋め込まれたゼロを含んでいても良い。

lua_pushnil

          void lua_pushnil (lua_State *L);

nil値をスタックに積む。

lua_pushnumber

          void lua_pushnumber (lua_State *L, lua_Number n);

値 n を持つ数値をスタックに積む。

lua_pushstring

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

sが指すゼロ終端文字列をスタックに積む。 Luaは与えられた文字列を内部的にコピーする (または再利用する) ため、 s が指すメモリを関数が戻ったあとすぐに解放あるいは再利用してよい。 文字列は埋め込まれたゼロを含むことができない。 最初のゼロで終端するものと仮定される。

lua_pushthread

          void lua_pushthread (lua_State *L);

Lが表すスレッドをスタックに積む。

lua_pushvalue

          void lua_pushvalue (lua_State *L, int index);

指定した有効なインデックスにある要素のコピーをスタックに積む。

lua_pushvfstring

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

lua_pushfstring と同じであるが、 可変引数の代わりに va_list を渡す点が異なる。

lua_rawequal

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

受け入れ可能なインデックス index1 と index2 が プリミティブに等しい (つまりメタメソッドを呼ばない) とき1を返す。 そうでなければ0を返す。 どちらかのインデックスが有効でないときも0を返す。

lua_rawget

          void lua_rawget (lua_State *L, int index);

lua_gettable と同じであるが、 生のアクセスを行う (つまりメタメソッドを呼ばない) 点が異なる。

lua_rawgeti

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

値 t[n] をスタックに積む。 ただし t は指定した有効なインデックス index の値である。 これは生のアクセスを行う。 つまりメタメソッドを呼ばない。

lua_rawset

          void lua_rawset (lua_State *L, int index);

lua_settable と同じであるが、 生の代入である点が異なる (メタメソッドを呼ばない)。

lua_rawseti

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

t[n] = v と同じことを行う。 ただし t は指定した有効なインデックス index の値で、 v はスタックトップの値である。

この関数は値をスタックから取り除く。 これは生の代入を行う。 つまりメタメソッドを呼ばない。

lua_Reader

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

lua_load で使うリーダー関数。 チャンクの新たなピースが必要になるたびに、data 引数を付けてリーダーが呼ばれる。 リーダーはチャンクの新たなピースを埋めたメモリブロックを指すポインタを返し、 その長さを size にセットしなければならない。 ブロックはリーダー関数がもう一度呼ばれるまで存在しなければならない。 チャンクの最後に達したことを伝えるには NULL を返す。 リーダー関数は1以上の任意のサイズのピースを返すことができる。

lua_register

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

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

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

lua_remove

          void lua_remove (lua_State *L, int index);

指定した有効なインデックスの要素を取り除き、 上の要素をずらして隙間を埋める。 疑似インデックスは、実際のスタック位置でないため、指定できない。

lua_replace

          void lua_replace (lua_State *L, int index);

スタックトップの要素を指定した位置へ移動する。 スタックトップの値は取り除く。 他のどの要素もずらさない。 つまり指定した位置の値を置き換える。

lua_resume

          int lua_resume (lua_State *L, int narg);

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

コルーチンを開始するためには、まず新しいスレッドを作る (lua_newthread を参照)。 次にメイン関数と任意個の引数をスタックに積み、 nargs に引数の数を渡して。 lua_resume を呼ぶ。 コルーチンが中断されたり実行終了したら、呼び出しから戻る。 戻ってきたとき、スタックには lua_yield に渡された値か、本体の関数から返された値がすべて積まれている。 コルーチンがyieldした場合、lua_resume は LUA_YIELD を返す。 コルーチンがエラーなく実行終了した場合は0を返す。 エラーが起きた場合はエラーコードを返す (lua_pcall を参照)。 エラーの場合、スタックは巻き戻されておらず、従ってその上でデバッグAPIを使うことができる。 スタックトップにエラーメッセージが置かれる。 コルーチンを再開するには、yied から返される結果として渡す値だけをスタックに起き、 lua_resume を呼ぶ。

lua_setallocf

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

指定されたステートのアロケータ関数を f と ud に変更する。

lua_setfenv

          int lua_setfenv (lua_State *L, int index);

スタックからテーブルを取り除き、指定したインデックスの値の新しい環境として設定する。 指定したインデックスの値が関数、スレッド、ユーザーデータのどれでもなければ、 lua_setfenv は0を返す。 そうでなければ1を返す。

lua_setfield

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

t[k] = v を実行する。 ただし t は指定した有効なインデックス index の値で、 v はスタックトップの値である。

この関数は値をスタックから除去する。 Luaの中でのように、この関数は "newindex" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。

lua_setglobal

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

スタックから値を取り除き、それをグローバル変数 name の新しい値として設定する。 これはマクロとして定義されている。

#define lua_setglobal(L,s)   lua_setfield(L, LUA_GLOBALSINDEX, s)

lua_setmetatable

          int lua_setmetatable (lua_State *L, int index);

スタックからテーブルを取り除き、それを指定した受け入れ可能なインデックスの値の新しいメタテーブルとして設定する。

lua_settable

          void lua_settable (lua_State *L, int index);

t[k] = v を実行する。 ただし t は指定した有効なインデックス index の値で、 v はスタックトップの値で、 k はそのひとつ下の値である。

この関数はキーと値の両方をスタックから取り除く。 Luaの中でのように、この関数は "newindex" イベントのメタメソッドを呼ぶ場合がある (2.8 を参照)。

lua_settop

          void lua_settop (lua_State *L, int index);

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

lua_State

          typedef struct lua_State lua_State;

Luaインタプリタの状態全体を保持する不透明な構造体。 Luaライブラリはグローバル変数を使っていないので、完全に再入可能である。 ステートに関するすべての情報はこの構造体に保持されている。

このステートへのポインタは、 無からLuaステートを作成する lua_newstate を除いて、 ライブラリのすべての関数で最初の引数として渡さなければならない。

lua_status

          int lua_status (lua_State *L);

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

通常のスレッドの状態は0である。 スレッドがエラー終了していればエラーコード、 スレッドが中断していれば LUA_YIELD を返す。

lua_toboolean

          int lua_toboolean (lua_State *L, int index);

指定した受け入れ可能なインデックスの値をCのブーリアン値 (0または1) に変換する。 Luaでの条件判断と同様に、 lua_toboolean は false と nil 以外のすべての値に対して1を返し、 そうでなければ0を返す。 有効でないインデックスを指定した場合も0を返す。 もし本当のブーリアン値だけを調べたい場合は、 lua_isboolean で値の型を判定すること。

lua_tocfunction

          lua_CFunction lua_tocfunction (lua_State *L, int index);

指定した受け入れ可能なインデックスの値をCの関数に変換する。 この値はCの関数でなければならなず、それ以外では NULL を返す。

lua_tointeger

          lua_Integer lua_tointeger (lua_State *L, int idx);

指定した受け入れ可能なインデックスのLuaの値を符号付き整数型 lua_Integer に変換する。 このLuaの値は数値か、数値に変換できる文字列でなければならない (2.2.1 を参照)。 それ以外の場合、lua_tointeger は0を返す。

数値が整数でなければ、何らかの未規定な方法で整数に丸める。

lua_tolstring

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

指定した受け入れ可能なインデックスのLuaの値を文字列 (const char*) に変換する。 もし len が NULL でなければ、 *len に文字列の長さも設定される。 このLuaの値は文字列か数値でなければならず、 それ以外の場合、この関数は NULL を返す。 もしその値が数値であれば、 lua_tolstring はスタック内のその実際の値を文字列に 変換する (この変換はテーブル巡回中のキーに対して lua_tolstring を使ったときに lua_next を混乱させる)。

lua_tolstring はLuaステート内部の文字列を指す、完全にアラインメントされたポインタを返す。 この文字列は、その最後に必ずゼロ (`\0´) を持つ (Cでよくやるように) が、 その途中にもゼロを含むことがある。 Luaはガベージコレクションを持っているため、 lua_tolstring の返したポインタが、その値がスタックから取り除かれた後も有効であり続けるという保証はない。

lua_tonumber

          lua_Number lua_tonumber (lua_State *L, int index);

指定した受け入れ可能なインデックスにあるLuaの値を数値に変換する (lua_Number を参照)。 このLuaの値は数値か、数値に変換できる文字列でなければならない (2.2.1 を参照)。 それ以外の場合、lua_tonumber は0を返す。

lua_topointer

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

指定した受け入れ可能なインデックスの値をCの汎用ポインタ (void*) に変換する。 この値は、ユーザーデータ、テーブル、スレッド、関数のいずれかである。 それ以外なら lua_topointer は NULL を返す。 Luaは異なるオブジェクトに対しては異なるポインタを返すことを保証する。 ポインタからその元の値に変換する直接的な方法は無い。

典型的には、この関数はデバッグ情報のためにだけ使われる。

lua_tostring

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

len に NULL を渡して lua_tolstring を呼ぶのと同じ。

lua_tothread

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

指定した受け入れ可能なインデックスの値をLuaのスレッド (lua_State* で表される) に変換する。 この値はスレッドでなければならず、それ以外では NULL を返す。

lua_touserdata

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

指定した受け入れ可能なインデックスの値がフルユーザーデータであれば、そのブロックのアドレスを返す。 ライトユーザーデータであれば、そのポインタを返す。 どちらでもなければ NULL を返す。

lua_type

          int lua_type (lua_State *L, int index);

指定した受け入れ可能なインデックスの値の型を返す。 有効でないインデックス (つまりその位置に要素がない) の場合は LUA_TNONE を返す。 lua_type が返す型は lua.h で定義されている以下の定数である。

LUA_TNIL
LUA_TNUMBER
LUA_TBOOLEAN
LUA_TSTRING
LUA_TTABLE
LUA_TFUNCTION
LUA_TUSERDATA
LUA_TTHREAD
LUA_TLIGHTUSERDATA

lua_typename

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

tp が示す型の名前を返す。 tp は lua_type が返す値のいずれかでなければならない。

lua_Writer

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

lua_dump で使うライター関数。 新しいチャンクのピースが生成されるたびに、 書き込みバッファ (p)、そのサイズ (sz)、 および lua_dump に渡した data 引数を渡して lua_dump がライターを呼ぶ。

ライターはエラーコードを返す。 0はエラーなしを意味する。 それ以外の値はエラーを意味し、 lua_dump にそれ以上ライターを呼ぶのをやめさせる。

lua_xmove

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

同じ グローバルステートの異なるスレッド間で値を交換する。

この関数は from のスタックから n 個の値を取り出し、 それらを to のスタックに積む。

lua_yield

          int lua_yield  (lua_State *L, int nresults);

コルーチンを中断する。

この関数は以下のようにCの関数のreturn式でだけ呼べる。

       return lua_yield (L, nresults);
Cの関数がこの方法で lua_yield を呼ぶとコルーチンの実行は中断され、 このコルーチンを開始した lua_resume の呼び出しから戻る。 引数 nresults は lua_resume から返したいスタック上の値の数である。

3.8 - デバッグインタフェイス

Luaは組み込みのデバッグ機能を持っていない。 代わりに、そのための関数と フック による特殊なインタフェイスを提供している。 このインタフェイスで、様々な種類のデバッガ、プロファイラ、およびインタプリタの「内部情報」を必要とするその他のツールを作れるようになっている。

lua_Debug

          typedef struct lua_Debug {
            int event;
            const char *name;           /* (n) */
            const char *namewhat;       /* (n) */
            const char *what;           /* (S) */
            const char *source;         /* (S) */
            int currentline;            /* (l) */
            int nups;                   /* (u) 上位値の数 */
            int linedefined;            /* (S) */
            int lastlinedefined;        /* (S) */
            char short_src[LUA_IDSIZE]; /* (S) */
            /* private part */
            ...
          } lua_Debug;

アクティブな関数に関する色々な情報を格納するのに使う構造体。 lua_getstack は後で使うために、この構造体の内部用メンバだけを埋める。 lua_Debug の他のフィールドを役に立つ情報で埋めるには、lua_getinfo を呼ぶ。

lua_Debug の各フィールドは以下のような意味を持っている。

  • source --- 関数が文字列中で定義されたならば、その文字列である。 関数がファイル中で定義されたならば、`@´ で始まり、その後にファイル名が続く。

  • short_src --- エラーメッセージに使う「可読」バージョンの source。

  • linedefined --- 関数定義の開始位置の行番号。

  • lastlinedefined --- 関数定義の終了位置の行番号。

  • what --- Luaの関数なら "Lua"、 Cの関数なら "C"、 チャンクのメイン部であれば "main"、 関数が終端呼び出ししたならば "tail"。 最後のケースでは、Luaはこの関数について他に何の情報も持っていない。

  • currentline --- 現在実行中の行番号。 この情報が利用可能でなければ、currentline は -1 に設定される。

  • name --- その関数に対する適当な名前。 Luaの関数はファーストクラスの値であるため、固定の名前は持っていない。 複数のグローバル変数に格納されている関数もあれば、テーブルフィールドにのみ格納されているものもある。 lua_getinfo は、その関数がどのように呼ばれたかを調べ、良さそうな名前を探す。 名前が見つからなければ、name は NULL に設定される。

  • namewhat --- name フィールドを説明する。 namewhat は、どのように関数が呼ばれたかによって、以下のいずれかになる。 "global", "local", "method", "field", "upvalue", or "" (空文字列。他に適当なものがなければこれを使う)。

  • nups --- その関数の上位値の数。

lua_gethook

          lua_Hook lua_gethook (lua_State *L);

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

lua_gethookcount

          int lua_gethookcount (lua_State *L);

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

lua_gethookmask

          int lua_gethookmask (lua_State *L);

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

lua_getinfo

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

lua_Debug の各フィールドを役に立つ情報で埋める。

エラー (例えば what に不正なを指定したとか) のときは0を返す。 文字列 what の各文字は、構造体 ar のどのフィールドを埋めるかを選択する。 これは lua_Debug の定義で括弧内に書かれた文字で指示する。 `S´ はフィールド source, linedefined, lastlinedefined, what を埋め、 `l´ はフィールド currentline を埋め、以下同様。 さらに、`f´ を指定すると、指定されたレベルで走っている関数をスタックに積む。

アクティブでない (スタック中にない) 関数の情報を得るには、 それをスタックに積んで what を文字 '>' で始まる文字列にする。 例えば、関数 f が定義された行番号を知りたい場合は、次のように書く。

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

lua_getlocal

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

指定したアクティベーションレコードのローカル変数についての情報を得る。 引数 ar には、事前に lua_getstack を呼んで埋めるか、フック (lua_Hook を参照) に渡された引数を使うかして、有効なアクティベーションレコードを与えなければならない。 インデックス n は調べるローカル変数を指定する (1が最初の引数か最初のアクティブなローカル変数で、最後のアクティブなローカル変数まである)。 lua_getlocal はその変数の値をスタックに積み、その名前を返す。

`(´ (開き括弧) で始まる変数名は内部変数を表している (ループ制御変数、テンポラリ変数、Cの関数のローカル変数など)。

インデックスがアクティブなローカル変数の数より大きいときは、(何も積まずに) NULL を返す。

lua_getstack

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

インタプリタランタイムスタックに関する情報を取得する。

この関数は lua_Debug の一部を、 指定したレベルで実行中の関数の アクティベーションレコード で埋める。 レベル0は現在走っている関数で、レベル n+1 はレベル n の呼び出し元の関数である。 エラーがなければ lua_getstack は1を返す。 スタックの深さよりも大きいレベルが指定された場合は0を返す。

lua_getupvalue

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

クロージャの上位値に関する情報を取得する。 (Luaの関数の上位値は、その関数が使っている外部ローカル変数で、クロージャに取り込まれたもの。) lua_getupvalue はインデックス n の上位値を取得し、その値をスタックに積み、その名前を返す。 funcindex はスタック中のそのクロージャを指す。 (上位値は関数全体に渡って有効であり、特定の順序も持たない。そのため不定の順序で番号付けられている。)

インデックスが上位値の数より大きい場合は、(何も積まずに) NULL を返す。 Cの関数では、どの上位値に対してもその名前に空文字列 "" を返す。

lua_Hook

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

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

フックが呼ばれたとき、ar 引数の event フィールドに フックを起動したイベントが格納されている。 Luaはこれらのイベントを以下の定数で識別する。 LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILRET, LUA_HOOKLINE, LUA_HOOKCOUNT。 さらにlineイベントでは、フィールド currentline も設定される。 ar の他のフィールドを得るには、 lua_getinfo を呼ぶ必要がある。 returnイベントでは、event は通常の LUA_HOOKRET の他に LUA_HOOKTAILRET が設定される場合がある。 後者はLuaが終端呼び出しした関数からの復帰をシミュレートしたもので、 この場合 lua_getinfo は役に立たない。

Luaがフックを実行している間、他のフック呼び出しは向こうになる。 従って、フック内でLuaの関数やチャンクを呼び出した場合、フックを呼ばずに実行される。

lua_sethook

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

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

func はフック関数を指定する。 mask はどのイベントでフックが呼ばれるかを定数 LUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE, LUA_MASKCOUNT の論理和で指定する。 count 引数はmaskが LUA_MASKCOUNT を含むときだけ意味を持つ。 それぞれのイベントについて以下の状況でフックが呼ばれる。

  • callフック は関数を呼ぶときに呼ばれる。 フックは新しい関数に入った直後、その関数が引数を取得する前に呼ばれる。
  • returnフック は関数から戻るときに呼ばれる。 フックは関数から離れる直後に呼ばれる。 戻り値にはアクセスできない。
  • lineフック はインタプリタが新しい行のコードの実行を開始しようとしているとき、 および同じ行内でもジャンプが行われたときに呼ばれる (このイベントはLuaの関数を実行している間だけ起こる)。
  • countフック はインタプリタが count 命令を実行した直後に呼ばれる (このイベントはLuaの関数を実行している間だけ起こる)。

mask にゼロを設定すればフックが無効になる。

lua_setlocal

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

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

インデックスがアクティブなローカル変数の数よりも大きければ、(何も取り除かずに) NULL を返す。

lua_setupvalue

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

クロージャの上位値の値を設定する。 引数 funcindex および n は lua_getupvalue と同じである (lua_getupvalue を参照)。 この関数はスタックトップの値をその上位値に格納し、その名前を返す。 またその値をスタックから取り除く。

インデックスが上位値の数よりも大きければ、(何も取り除かずに) NULL を返す。

4 - 補助ライブラリ

補助ライブラリ はCとLuaのインタフェイスとなるいくつかの便利な関数を提供する。 基本APIはCとLuaの対話の基本的な関数を提供するが、補助ライブラリはいくつかの共通の作業をする高レベルな関数を提供する。

補助ライブラリのすべての関数はヘッダーファイル lauxlib.h に定義され、接頭語 luaL_ が付いている。

補助ライブラリのすべての関数は基本APIの上に構築されており、そのためこのAPIでできないことは何も提供していない。

補助ライブラリにはCの関数の引数をチェックするための関数がいくつかある。 これらは常に luaL_check* または luaL_opt* という名前である。 これらの関数はチェックが妥当(satisfied?)でなかったときエラーを生成する。 エラーメッセージは引数で書式化される ("bad argument #1" など) ため、 他のスタック値に対してこれらの関数を使うべきではない。

4.1 - 関数と型

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

luaL_addchar

          void luaL_addchar (luaL_Buffer B, char c);

文字 c をバッファ B に追加する (luaL_Buffer を参照)。

luaL_addlstring

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

s が指す長さ l の文字列をバッファ B に追加する。 (luaL_Buffer を参照)。 文字列は埋め込まれたゼロを含んでいても良い。

luaL_addsize

          void luaL_addsize (luaL_Buffer B, size_t n);

バッファエリア (luaL_prepbuffer を参照) に前回コピーされた長さ n の文字列をバッファ B に追加する。 (luaL_Buffer を参照)。

luaL_addstring

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

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

luaL_addvalue

          void luaL_addvalue (luaL_Buffer *B);

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

これはバッファに追加する値をスタックから取る唯一の文字列バッファ用関数である。

luaL_argcheck

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

cond が真であることを確認する。 もし違ったら、メッセージ "bad argument #<numarg> to <func> (<extramsg>)" のエラーを生成する。 ただし func はコールスタックから取得する。

luaL_argerror

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

メッセージ "bad argument #<numarg> to <func> (<extramsg>)" のエラーを生成する。 ただし func はコールスタックから取得する。

この関数は決して戻らないが、 Cの関数で return luaL_argerror ... として使うのが慣習である。

luaL_Buffer

          typedef struct luaL_Buffer luaL_Buffer;

文字列バッファ の型。

文字列バッファはCのコードでLuaの文字列片(strings piecemeal)を組み立てるのに使う。 これは以下のように使用する。

  • まず luaL_Buffer 型の変数 b を宣言する。
  • 次に luaL_buffinit(L, &b) を呼んでそれを初期化する。
  • そして luaL_add* 関数のどれかを使ってバッファに文字列片を追加する。
  • 最後に luaL_pushresult(&b) を呼ぶ。 これは最終的な文字列をスタックトップに残す。

通常の操作をしている間、 文字列バッファはいくつかのスタックスロットを使う。 従ってバッファを使っている間は、スタックトップがどこにあるか判っていると仮定できない。 バッファ操作の正しい(successive)呼び出しの間、整合が取れている限りはスタックを使うことができる。 つまり、バッファ操作を呼び出すときは、 スタックが前回バッファ操作した直後と同じ高さでなければならない。 (luaL_addvalue はこのルールの唯一の例外である。) luaL_pushresult を呼んだあと、 スタックはバッファが初期化される前の高さに戻り、その上に最終的な文字列が積まれる。

luaL_buffinit

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

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

luaL_callmeta

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

メタメソッドを呼ぶ。

インデックス obj のオブジェクトがメタテーブルを持っていて、 このメタテーブルがフィールド e を持っていれば、 この関数はこのフィールドを呼び出し、引数としてそのオブジェクトを渡す。 この場合、この関数は1を返し、呼び出しの戻り値をスタックに積む。 メタテーブルがないかメタメソッドがない場合、 この関数は (スタックに何も積まずに) 0を返す。

luaL_checkany

          void luaL_checkany (lua_State *L, int narg);

関数が位置 arg に任意の型 (nil を含む) の引数を持つかチェックする。

luaL_checkint

          int luaL_checkint (lua_State *L, int narg);

関数の第 narg 引数が数値であるかをチェックし、 その値を int にキャストして返す。

luaL_checkinteger

          lua_Integer luaL_checkinteger (lua_State *L, int narg);

関数の第 narg 引数が数値であるかをチェックし、 その値を lua_Integer にキャストして返す。

luaL_checklong

          long luaL_checklong (lua_State *L, int narg);

関数の第 narg 引数が数値であるかをチェックし、 その値を long にキャストして返す。

luaL_checklstring

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

関数の第 narg 引数が文字列であるかをチェックし、その文字列を返す。 l が NULL でなければ、 *l に文字列の長さを格納する。

luaL_checknumber

          lua_Number luaL_checknumber (lua_State *L, int narg);

関数の第 narg 引数が数値であるかをチェックし、 その数値を返す。

luaL_checkoption

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

関数の第 narg 引数が文字列であるかチェックし、 配列 lst (NULL終端でなければならない) からその文字列を検索する。 def が NULL でなければ、 関数が第 narg 引数を持たないかその引数が nil であった場合のデフォルト値として使う。

文字列が見つかった配列インデックスを返す。 引数が文字列でないか文字列が見つからなければエラーを発生する。

この関数は文字列をCの列挙型に変換するのに役に立つ。 Luaのライブラリにおける通常の慣例では、オプションを選択するのに、数値でなく文字列を使う。

luaL_checkstack

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

スタックサイズを top + sz 個の要素に伸ばす。 スタックがそのサイズに伸ばせなければエラーを発生する。 msg はそのエラーメッセージに入れる追加の文字列である。

luaL_checkstring

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

関数の第 narg 引数が文字列であるかチェックし、その文字列を返す。

luaL_checktype

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

関数の第 narg 引数が型 t であるかチェックする。

luaL_checkudata

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

関数の第 narg 引数が型 tname のユーザーデータであるかチェックする (luaL_newmetatable を参照)。

luaL_error

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

エラーを発生させる。 エラーメッセージの書式は fmt と追加の引数で与えられる。 これは lua_pushfstring のと同じルールに従う。 また、メッセージの最初にエラーが発生したファイル名と行番号を、それらの情報が利用可能ならば、追加する。

この関数は決して戻らないが、 Cの関数で return luaL_error ... のように使うのが慣例である。

luaL_getmetafield

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

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

luaL_getmetatable

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

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

luaL_gsub

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

文字列 s 中の文字列 p をすべて文字列 r で置換したコピーを作る。 その結果の文字列をスタックに積み、それを返す。

luaL_loadbuffer

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

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

この関数は lua_load と同じ結果を返す。 name はデバッグ情報やエラーメッセージで使うチャンク名である。

luaL_loadfile

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

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

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

luaL_loadstring

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

Luaのチャンクとして文字列をロードする。 この関数は lua_load を使ってゼロ終端文字列 s に格納されているチャンクをロードする。

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

luaL_newmetatable

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

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

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

luaL_newstate

          lua_State *luaL_newstate (void);

標準のCの realloc 関数をベースにしたアロケータ関数を使って lua_newstate を呼び、新しいLuaステートを作成する。 また、致命的エラーの場合に標準エラー出力にエラーメッセージを出力するパニック関数 (lua_atpanic を参照) を設定する。

新しいステートを返す。 メモリ確保エラーの場合は NULL を返す。

luaL_openlibs

          void luaL_openlibs (lua_State *L);

指定したステートにすべての標準Luaライブラリを開く。

luaL_optint

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

関数の第 narg 引数が数値であれば、その数値を int にキャストして返す。 その引数が存在しないか nil であれば、d を返す。 さもなくばエラーを発生する。

luaL_optinteger

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

関数の第 narg 引数が数値であれば、 その数値を lua_Integer にキャストして返す。 その引数が存在しないか nil であれば、d を返す。 さもなくばエラーを発生する。

luaL_optlong

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

関数の第 narg 引数が数値であれば、その数値を long にキャストして返す。 その引数が存在しないか nil であれば、d を返す。 さもなくばエラーを発生する。

luaL_optlstring

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

関数の第 narg 引数が文字列であれば、その文字列を返す。 引数が存在しないか nil であれば、d を返す。 さもなくばエラーを発生する。

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

luaL_optnumber

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

関数の第 narg 引数が数値であれば、その数値を返す。 その引数が存在しないか nil であれば、d を返す。 さもなくばエラーを発生する。

luaL_optstring

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

関数の第 narg 引数が文字列であれば、その文字列を返す。 その引数が存在しないか nil であれば、d を返す。 さもなくばエラーを発生する。

luaL_prepbuffer

          char *luaL_prepbuffer (luaL_Buffer *B);

バッファ B に追加するための文字列を格納できる、 サイズ LUAL_BUFFERSIZE の領域のアドレスを返す (luaL_Buffer を参照)。 文字列をこの領域に格納したあと、文字列のサイズを渡して luaL_addsize を呼び、実際にバッファに追加しなければならない。

luaL_pushresult

          void luaL_pushresult (luaL_Buffer *B);

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

luaL_ref

          int luaL_ref (lua_State *L, int t);

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

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

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

luaL_Reg

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

luaL_register が登録する関数の配列の型。 name は関数の名前で、func は関数へのポインタである。 luaL_Reg の配列は name と func が共に NULL である番兵エントリで終わらなければならない。

luaL_register

          void luaL_register (lua_State *L, const char *libname,
                              const luaL_Reg *l);

ライブラリを開く。

libname に NULL を渡して呼ぶと、 単純にリスト l (luaL_Reg を参照) の関数をすべてスタックトップのテーブルに登録する。

libname がNULLでなければ、 新しいテーブル t を作成し、 それをグローバル変数 libname の値として設定し、 package.loaded[libname] の値として設定し、 そしてリスト l の関数をすべてそこに登録する。 もし package.loaded[libname] か変数 libname にテーブルが存在すれば、 新しいテーブルを作る代わりにそれを再利用する。

いずれの場合も、この関数はスタックトップにそのテーブルを置く。

luaL_typename

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

インデックス idx の値の型の名前を返す。

luaL_typerror

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

<location>: bad argument <narg> to <function> (<tname> expected, got <realt>)
のようなメッセージのエラーを生成する。 ただし <location> は luaL_where によって生成されたもので、 <function> は現在の関数の名前、 and <realt> は実引数の型名である。

luaL_unref

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

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

ref が LUA_NOREF または LUA_REFNIL の場合、 luaL_unref は何もしない。

luaL_where

          void luaL_where (lua_State *L, int lvl);

コールスタックのレベル lvl の制御の現在位置を識別する文字列をスタックに積む。 典型的にこの文字列は <chunkname>:<currentline>: のような書式になっている。 レベル0は実行中の関数、 レベル1は実行中の関数の呼び出し元の関数、 以下同様である。

この関数はエラーメッセージの接頭辞を構築するために使う。

5 - 標準ライブラリ

Lua標準ライブラリは、CのAPIを使って直接実装された便利な関数を提供する。 いくつかは言語の本質的なサービスを提供するものであり (例えば type や getmetatable)、 残りは「外部の」サービスへのアクセスを提供するものである (例えば I/O)。 また、Lua自身で実装可能であるが、便利さやパフォーマンス要求のためにCで実装されたものもある (例えば sort)。

すべてのライブラリは公開されているCのAPIを使って実装されており、独立したCのモジュールで提供されている。 現在、Luaには以下の標準ライブラリがある。

  • 基本ライブラリ
  • パッケージライブラリ
  • 文字列操作
  • テーブル操作
  • 数学関数 (sin、logなど)
  • 入出力
  • OS機能
  • デバッグ機能
基本ライブラリとパッケージライブラリ以外は、 それぞれのライブラリが、 グローバルテーブルのフィールドか、そのオブジェクトのメソッドとして、そのすべての関数を提供している。

これらのライブラリを使うには、Cのホストプログラムで すべての標準ライブラリを開く luaL_openlibs を呼ばなければならない。 代わりに、 luaopen_base (基本ライブラリ用)、 luaopen_package (パッケージライブラリ用)、 luaopen_string (文字列ライブラリ用)、 luaopen_table (テーブルライブラリ用)、 luaopen_math (数学ライブラリ用)、 luaopen_io (I/OライブラリとOSライブラリ用)、 luaopen_debug (デバッグライブラリ用) を呼んで個別に開くこともできる。 これらは lualib.h に定義されているが、 直接呼ぶべきではなく、他のLuaのC関数と同様に ---- 例えば lua_call を使って ---- 呼ばなければならない。

5.1 - 基本関数

基本ライブラリはLuaへのコアな機能を提供する。 アプリケーションにこのライブラリを含めない場合は、その機能を提供する代わりの実装を用意する必要があるか慎重に調べるべきである。

assert (v [, message])

引数 v が偽 (すなわち nil または false) であればエラーを発生させる。 そうでなければ、そのすべての引数を返す。 message はエラーメッセージを指定する。 省略された場合は "assertion failed!" である。

collectgarbage (opt [, arg])

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

  • "stop" --- ガベージコレクタを停止する。
  • "restart" --- ガベージコレクタを再開する。
  • "collect" --- フルガベージコレクションサイクルを実行する。
  • "count" --- Luaが使っているメモリの合計を(キロバイトで)返す。
  • "step" --- ガベージコレクションステップひとつを実行する。 ステップの「サイズ」は arg で制御する。 大きな値は大きなステップを意味するが、具体的には定まっていない。 ステップサイズを制御したければ、 arg の値を実験的に調整しなければならない。 このステップでコレクションサイクルが終わった場合は true を返す。
  • "steppause" --- コレクタの停止値 (2.10 を参照) の新しい値を arg÷100に設定する。
  • "setstepmul" --- コレクタの ステップ係数 の新しい値を arg÷100に設定する (2.10 を参照)。

dofile (filename)

ファイルを開き、その内容をLuaチャンクとして実行する。 引数が指定されなければ、標準入力 (stdin) から読み取って実行する。 dofileはチャンクから返されたすべての値をそのまま返す。 エラーが起きた場合は、呼び出し側に伝搬される (つまり dofile は保護モードで動くのではない)。

error (message [, level])

最後に保護された関数呼び出しを終了し、message をエラーメッセージとして返す。 関数 error は戻らない。

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

_G

グローバル環境を保持するグローバル変数である (関数ではない)。 つまり、_G._G = _G である。 Lua自身はこの変数を使用しないので、この値を変更しても環境には何の影響もなく、逆もまた同じである (環境を変えるには setfenv を使う)。

getfenv (f)

関数の現在の環境を返す。 f はLuaの関数か、関数のスタックレベルを示す数値である。 レベル1はgetfenvを呼んだ関数である。 もし与えられた関数がLuaの関数でなかったり、fが0の場合は、getfenv はグローバル環境を返す。 f のデフォルト値は1である。

getmetatable (object)

もし object がメタテーブルを持っていなければ nil を返す。 もしobjectのメタテーブルが "__metatable" フィールドを持っていれば、その値を返す。 そうでなければobjectのメタテーブルを返す。

ipairs (t)

3つの値、イテレータ関数、テーブル t、および0を返す。

       for i,v in ipairs(t) do ... end
は (1,t[1])、(2,t[2])、…のペアを、最初に値にnilが現れるまで繰り返す。

巡回中にテーブルを変更する際の注意は next を参照。

load (func [, chunkname])

そのピースを取得する関数 func を使ってチャンクをロードする。 func は前回の戻り値と連結する文字列を返さなければならない。 nil を返す (または戻り値なし) とチャンクの終わりを知らせる。

エラーがなければ、コンパイルされたチャンクが関数として返され、 そうでなければ nil とエラーメッセージが返される。 返された関数の環境はグローバル環境である。

chunkname はエラーメッセージやデバッグ情報のためのチャンク名を指定する。

loadfile ([filename])

load と同じであるが、 ファイル filename からチャンクを読み込む。 ファイル名を与えなければ標準入力から読み込む。

loadstring (string [, chunkname])

load と同じであるが、 指定した文字列からチャンクを読み込む。

与えられた文字列をロードして実行するには、以下の慣用句を使う。

      assert(loadstring(s))()

next (table [, index])

テーブルの全フィールドを巡回するための関数である。 最初の引数はテーブルを、二番目の引数はこのテーブルのインデックスを渡す。 next はテーブル内の次のインデックスと、その値を返す。 二番目の引数に nil を渡すと、初期インデックスとその値が返される。 最後のインデックスで呼び出すか、空のテーブルに対して nil で呼び出すと、 next は nil を返す。 二番目の引数が省略された場合は nil と解釈される。 特に、next(t) を使うとテーブルが空かどうか調べることができる。

Luaにはフィールドの宣言がない。 テーブル内にフィールドが存在しないのと、nil 値が格納されたフィールドには、何の違いも無い。 ゆえに、next は nil でない値を持つフィールドのみを考慮する。 インデックスが列挙される順番は、数値のインデックスに対しても、不定である (数値順にテーブルを巡回するには、数値用の for 文や ipairs 関数を使う)。

テーブルの巡回中に、もし存在していないフィールドに新たに値が割り当てられたら、next の動作は 未定義 である。 しかし既存のフィールドは変更してもよい。 特に、既存のフィールドを消去するのは構わない。

pairs (t)

3つの値、next 関数、テーブル t、nil を返す。

       for k,v in pairs(t) do ... end
はテーブル t のすべてのキー・値ペアについて繰り返す。

巡回中にテーブルを変更する際の注意は next を参照。 +

pcall (f, arg1, arg2, ...)

保護モードで、与えられた引数で f を呼び出す。 つまり f の内部で発生したエラーは伝搬されず、 代わりに pcall がエラーを捕らえ、ステータスコードを返す。 最初の引数はステータスコード (ブーリアン型) で、エラーなしに呼び出しが成功したときは真を返す。 その場合、f の戻り値もすべて、最初の戻り値に続いて返される。 エラーが起こった場合、pcall は false とエラーメッセージを返す。

print (e1, e2, ...)

引数をいくつでも取ることができ、それらの値を tostring で文字列に変換してから標準出力 (stdout) に表示する。 print は書式化出力を意図したものではなく、 典型的にはデバッグのために、値を表示する簡単な方法として用意されているだけである。 書式化出力には string.format を使う。

rawequal (v1, v2)

メタメソッドを呼ぶことなしに v1 と v2 が等しいかどうか調べる。 ブーリアンを返す。

rawget (table, index)

メタメソッドを呼ぶことなしに table[index] の本当の値を得る。 table はテーブルでなければならない。 index は nil 以外のどんな値でも良い。

rawset (table, index, value)

メタメソッドを呼ぶことなしに table[index] に value をセットする。 table はテーブルでなければならない。 index は nil 以外のどんな値でも良い。 value はどんなLuaの値でも良い。

select (index, ...)

index が数値であれば、 index 番目以降の引数をすべて返す。 そうでなければ、index は文字列 "#" でなければならない。 この場合 select は受け取った余分の引数の合計数を返す。

setfenv (f, table)

指定された関数で使われる環境を変更する。 f はLuaの関数か、関数のスタックレベルを指定する数値である。 レベル1は setfenv を呼び出した関数を示す。 setfenv は与えられた関数を返す。

特殊なケースとして、fに0が与えられると、setfenv は走行中のスレッドの環境を変える。 この場合、setfenv は何も返さない。

setmetatable (table, metatable)

table のメタテーブルを変更する (Luaから他の型のメタテーブルを変更することはできない。Cからのみ可能である)。 もし metatable が nil であれば、table のメタテーブルは除去される。 元のメタテーブルが "__metatable" フィールドを持っていると、エラーを発する。

この関数は table を返す。

tonumber (e [, base])

引数を数値に変換しようとする。 もし引数がすでに数値だったり、数値に変換可能な文字列であれば、tonumber は数値を返す。 そうでなければ nil を返す。

省略可能な引数は数値を解釈する際の基数を指定する。 基数は2から36の整数を指定できる。 10より大きい基数では、`A´が10を表し、`B´が11を表し、 以下同様に続き、`Z´が35を表す (大文字でも小文字でも良い)。 基数が10 (デフォルト) の場合 は、数値に小数部や指数部を付けることができる (2.1 を参照)。 他の基数では、符号なしの整数のみを受け付ける。

tostring (e)

任意の型の引数を受け取り、理解しやすい形式の文字列に変換する。 数値が変換される方法を完全にコントロールする場合は string.format を使う。

もし e のメタテーブルが "__tostring" フィールドを持っていたら、 e を引数に、その関連付けられた値が呼び出され、その戻り値が結果として使われる。

type (v)

値の型を文字列で返す。 この関数が返す値は以下のいずれかである。
    "nil" (という文字列。nil 値ではなく。)
    "number"
    "string"
    "boolean"
    "table"
    "function"
    "thread"
    "userdata"

unpack (list [, i [, j]])

与えられたテーブルの要素を返す。 この関数は、以下のコードには固定の要素数しか書けないことを除いて、以下のコードと等価である。
  return list[i], list[i+1], ..., list[j]
デフォルトでは、i は1で j は長さ演算子 (2.5.5 を参照) 定義されているリストの長さである。

_VERSION

現在のインタプリタのバージョン文字列を保持しているグローバル変数 (関数ではない)。 この変数の現在の内容は "Lua 5.1" である。

xpcall (f, err)

この関数は pcall に似ているが、エラーハンドラを指定できる点が異なる。

xpcall は保護モードで f を呼び出し、 err をエラーハンドラとして使う。 f の内部で発生したエラーは伝搬されない。 代わりに、xpcall がエラーを捕らえ、エラーオブジェクトを引数に err を呼ぶ。 最初の戻り値はステータスコード (ブーリアン型) で、 エラーが起きなかった場合は true を返す。 その場合、最初の戻り値に続いて f の戻り値もすべて返される。 エラーが起きた場合、xpcall は false と err の戻り値を返す。

5.2 - コルーチン操作

コルーチン関連の操作は基本ライブラリのサブライブラリであり、テーブル coroutine 内に置かれている。 コルーチンに関する一般的な説明は 2.11 を参照。

coroutine.create (f)

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

coroutine.resume (co [, val1, ..., valn])

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

コルーチンがエラー無く実行されれば、 resume は true に加えて yield に渡された値 (コルーチンが中断された場合)、 もしくは本体の関数から返された値 (コルーチンが終了した場合) を返す。 エラーが起きたら、resume は false とエラーメッセージを返す。

coroutine.running ()

走行中のコルーチンを返す。 メインスレッドで呼ばれた場合は nil を返す。

coroutine.status (co)

コルーチン co の状態を文字列で返す。

"running" ... コルーチンは走行中。 "suspended" ... コルーチンは yield の呼び出しで中断されているが、まだ実行中である。 "normal" ... コルーチンはアクティブであるが走行中でない(つまり他のコルーチンをresumeしている)。 "dead" ... コルーチンの本体の関数が終了したか、エラーで停止した。

coroutine.wrap (f)

f を本体とする新しいコルーチンを作成する。 f はLuaの関数でなければならない。 coroutine.wrap は、呼ばれるたびにコルーチンを再開する関数を返す。 関数に渡された引数は resume に余分に渡される引数と同じ動作をし、 戻り値は resume から最初のブーリアンを除いた値と同じである。 もしエラーが起きた場合、エラーは伝搬する。

coroutine.yield ([val1, ..., valn])

呼ばれたコルーチンの実行を中断する。 コルーチンは、Cの関数やメタメソッド、イテレータを中断することはできない。 yield に渡された引数は resume から追加の戻り値として返される。

5.3 - モジュール

Luaでモジュールを構築したりロードしたりする基本的な機能を提供する。 2つの関数 require および module はグローバル環境に直接エクスポートされる。 それ以外はすべてテーブル package にエクスポートされる。

module (name [, ...])

モジュールを作成する。 package.loaded[name] にテーブルがあれば、 このテーブルがモジュールである。 そうでなければ、指定した名前のグローバルなテーブル t があれば、 このテーブルがモジュールである。 そうでなければ、新しいテーブル t を作成し、 グローバル変数 name の値と package.loaded[name] の値にそれを設定する。 またこの関数は指定された名前で t._NAME を、 モジュール (t それ自身) で t._M を、 パッケージ名 (完全なモジュール名から最後の部分を除いたもの、下記参照) で t_PACKAGE を初期化する。 最後に、module は現在の関数の新しい環境および package.loaded[name] の新しい値として t を設定する。 従って require は t を返す。

もし name が複合名 (つまり、ドットで各部が区切られたもの) であれば、 module はそれぞれの部分についてテーブルを作る (または、すでに存在すれば再利用する)。 例えば、name が a.b.c の場合、 module はグローバル変数 a のフィールド b のフィールド c にモジュールテーブルを格納する。

この関数はモジュール名の後に省略可能な オプション を渡すことができる。 この各オプションはモジュール全体に適用される関数である。

require (modname)

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

ローダを探すために、 require はまず package.preload[modname] を問い合わせる。 もしそこに値があれば、この値 (関数であるべきである) がローダである。 そうでなければ、require は package.path に格納されているパスを使う Luaのローダを探す。 それも失敗したら、package.cpath に格納されているパスを使うCのローダを探す。 それもまた失敗したら、オールインワンローダ (下記参照) を試す。

Cのライブラリをロードする場合、 require はまずアプリケーションをそのライブラリとリンクするためのダイナミックリンク機能を使う。 次にこのライブラリ内からローダとして使うためのCの関数を探す。 このCの関数は "luaopen_" にモジュール名を付けた名前であるが、 ドットはアンダースコアに置換する。 さらに、モジュール名にハイフンが含まれていれば、 その最初のハイフンまでの接頭辞は (ハイフンも含めて) 取り除かれる。 例えば、モジュール名が a.v1-b.c の場合、関数名は luaopen_b_c となる。

require がLuaのライブラリにもCのライブラリにもモジュールを見つけられなければ、 オールインワンローダ を呼ぶ。 このローダはCのパスを見て、指定したモジュールのルート名に対するライブラリを探す。 例えば a.b.c が要求された場合、a というCのライブラリを探す。 もし見つかれば、そのサブモジュールに対するオープン関数をその中から探す。 先の例でいうと、luaopen_a_b_c となる。 この機能により、いくつものCのサブモジュールをひとつのライブラリに納めることができる。 その場合でも各サブモジュールは、それぞれ独自のオープン関数を持つ。

ローダが見つかれば、 require は単一の引数 modname を渡してローダを呼ぶ。 ローダが何らかの値を返すと、 require はそれを package.loaded[modname] に格納する。 ローダが値を返さず、package.loaded[modname] に何の値も格納されていなければ、 require はこのエントリに true を格納する。 いずれにせよ、require は最終的な package.loaded[modname] の値を返す。

モジュールのロードまたは実行でエラーがあったり、そのモジュールのローダが見つからなければ、 require はエラーを発生する。

package.cpath

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

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

package.loaded

すでにロードされたモジュールを管理するために require が使うテーブル。 モジュール modname が要求され、 package.loaded[modname] が偽でなければ、 require は単に、そこに格納されている値を返す。

package.loadlib (libname, funcname)

ホストプログラムをCのライブラリ libname と動的リンクする。 このライブラリの中で関数 funcname を探し、その関数をCの関数として返す (従って、funcname は呼び出し規約 (lua_CFunction を参照) に従わなければならない)。

これは低レベルな関数であり、パッケージシステムやモジュールシステムを完全に迂回する。 require と異なり、 パス探索を行ったり拡張子を自動的に付加したりしない。 libname はCのライブラリの完全なファイル名でなければならず、 必要ならパスや拡張子も含めなければならない。 funcname はCのライブラリがエクスポートしている完全な名前でなければならない (使っているCコンパイラやリンカに依存するであろう)。

この関数はANSI Cのサポート範囲外である。 従って、これはいくつかのプラットフォーム (Windows, Linux, Mac OS X, Solaris, BSD, および dlfcn 標準をサポートする他のUnixシステム) でしか利用できない。

package.path

Luaのローダを探すために require が使うパス。

起動時にLuaは環境変数 LUA_PATH の値、 またはその環境変数が定義されていなければ luaconf.h で定義されているデフォルトパスで、この変数を初期化する。 環境変数の値に ";;" があれば、それをデフォルトパスで置換する。

パスはセミコロンで区切られた一連の テンプレート である。 各テンプレートについて、 require は テンプレート内の疑問符 (interrogation mark) を ファイル名 に置換し、 結果のファイル名をロードしようと試みる。 このファイル名は、モジュール名のドットを 「ディレクトリ区切り文字」 (Unixの "/" のような) で置き換えたものである。 例えば、Luaのパスが

  "./?.lua;./?.lc;/usr/local/?/init.lua"
であった場合、モジュール foo のLuaのローダの検索は、 ファイル ./foo.lua、./foo.lc、 /usr/local/foo/init.lua のロードをこの順序で試みる。

package.preload

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

package.seeall (module)

__index フィールドがグローバル環境を参照するメタテーブルを module にセットする。 従ってこのモジュールはグローバル環境から値を継承する。 関数 module へのオプションとして使われる。

5.4 - 文字列操作

このライブラリは、検索や部分文字列の抽出、パターンマッチングといった、文字列操作のための一般的な機能を提供する。 Luaの文字列のインデックス付けは、最初の文字が1の位置である (Cのように0ではない)。 文字列の末尾から逆方向にマイナス値で指定することもできる。 つまり、最後の文字は -1 の位置で示される。

文字列ライブラリはすべて、テーブル string 内の関数として提供される。 また、__index フィールドが自身を指す文字列用メタテーブルをセットする。 従って、文字列関数はオブジェクト指向スタイルで使うことができる。 例えば、string.bytes(s, i) は s:byte(i) と書くこともできる。

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

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

文字コードの数値は、プラットフォームを超えての可搬性がないことに注意。

string.char (i1, i2, ...)

0個以上の整数を指定できる。 各文字が与えられた引数と等しい内部コードを持ち、長さが引数の数に等しい、文字列を返す。

文字コードの数値は、プラットフォームを超えての可搬性がないことに注意。

string.dump (function)

指定された関数のバイナリ表現を保持する文字列を返す。 loadstring にこの文字列を渡すことで、関数のコピーを作ることができる。 function は上位値を持たないLua関数でなければならない。

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

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

もしパターン内にキャプチャが指定されていれば、 マッチ成功時にキャプチャされた文字列が2つのインデックスの後に返される。

string.format (formatstring, e1, e2, ...)

最初の引数 (文字列でなければならない) で指定された記述に従い、残りの可変個の引数を書式化して返す。 書式文字列は標準C関数のprintfファミリーと同じルールに従う。 ただし、 *、l、L、n、p、h はサポートされてなくて、追加の q がある点だけが異なる。 q オプションは、Luaインタプリタで安全に読み戻せる適切な形式の文字列に書式化する。 その文字列はダブルクォートの間に書かれ、 文字列中のダブルクォート、改行、埋め込まれたゼロ、バックスラッシュは正しくエスケープされる。 例えば、
       string.format('%q', 'a string with "quotes" and \n new line')
は次のような文字列を生成する。
"a string with \"quotes\" and \
 new line"

c、d、E、e、f, g、G、i、o、u, X、x はすべて数値の引数を期待し、 q と s は文字列を期待する。

この関数は埋め込まれたゼロを含む文字列を受け付けない。

string.gmatch (s, pattern)

呼ばれるたびに文字列 s から pattern でキャプチャされた部分を次々と返すような、イテレータ関数を返す。

pattern にキャプチャが指定されていなければ、それぞれの呼び出しごとに、マッチした文字列全体を返す。

例えば、以下のループでは

  s = "hello world from Lua"
  for w in string.gmatch(s, "%a+") do
    print(w)
  end
文字列 s のすべての単語について繰り返し、それぞれを別々の行に出力する。 次の例は、与えられた文字列から key=value のペアを集めてテーブルへ入れる。
  t = {}
  s = "from=world, to=Lua"
  for k, v in string.gmatch(s, "(%w+)=(%w+)") do
    t[k] = v
  end

string.gsub (s, pattern, repl [, n])

パターン pattern をすべて repl によって指定された置換文字列に置き換えた s のコピーを返す。 repl は文字列、テーブル、または関数でもよい。 gsub は二番目の値として、置換が行われた回数も返す。

repl が文字列であれば、その値が置換に使われる。 文字 % はエスケープ文字として機能する。 repl 内に現れる %n は (n は1から9)、 n 番目にキャプチャされた部分文字列を表す (以下を見よ)。 シーケンス %0 はマッチ全体を表す。 シーケンス %% は1個の % を表す。

repl がテーブルであれば、 そのテーブルは最初のキャプチャをキーとしてマッチのたびに問い合わせられる。 パターンにキャプチャがなければ、マッチ全体がキーとして使われる。

repl が関数であれば、マッチが現れるたびにこの関数が呼ばれる。 関数にはキャプチャされた部分文字列が順番にすべて渡される。 パターンにキャプチャが指定されていなければ、マッチした全体が唯一の引数として渡される。 テーブル問い合わせまたは関数呼び出しから返された値が文字列か数値であれば、 それが置換文字列として使われる。 そうでなくて false か nil であれば、置換は行われない (つまり、文字列中の元のマッチが維持される)。

省略可能な最後の引数 n は置換が行われる最大回数を制限する。 例えば、n が1なら最初に現れる pattern だけが置換される。

いくつか例を示す。

   x = string.gsub("hello world", "(%w+)", "%1 %1")
   --> x="hello hello world world"

   x = string.gsub("hello world", "%w+", "%0 %0", 1)
   --> x="hello hello world"

   x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
   --> x="world hello Lua from"

   x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
   --> x="home = /home/roberto, user = roberto"

   x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
         return loadstring(s)()
       end)
   --> x="4+5 = 9"

   local t = {name="lua", version="5.1"}
   x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t)
   --> x="lua-5.1.tar.gz"

string.len (s)

文字列を受け取り、その長さを返す。 空文字列 "" の長さは0である。 文字列中のゼロも数えるので、"a\000b\000c" の長さは5である。

string.lower (s)

文字列を受け取り、その中の大文字をすべて小文字に変えた文字列のコピーを返す。 それ以外の文字は変化しない。 何が大文字であるかは現在のロケールに依存する。

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

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

string.rep (s, n)

文字列 s のコピーを n 個連結した文字列を返す。

string.reverse (s)

文字列 s を反転した文字列を返す。

string.sub (s, i [, j])

文字列 s の、位置 i から位置 j までの部分文字列を返す。 i にも j にも、負の値を使える。 j が省略されたときは -1 とみなされる (つまり文字列の長さと同じ)。 特に、string.sub(s,1,j) は s の先頭から j 文字を取り出し、 string.sub(s, -i) は s の最後の i 文字を取り出す。

string.upper (s)

文字列を受け取り、その中の小文字をすべて大文字に変えた文字列のコピーを返す。 それ以外の文字は変化しない。 何が小文字であるかは現在のロケールに依存する。

Patterns

文字クラス は文字の集合を表す。 以下の組み合わせを文字クラスの指定に使うことができる。

  • x (x は 魔法の文字 ^$()%.[]*+-? 以外の文字) --- 文字 x それ自身を表す。
  • . --- (ドット) すべての文字を表す。
  • %a --- すべてのletterを表す。
  • %c --- すべての制御文字を表す。
  • %d --- すべての数字を表す。
  • %l --- すべての小文字を表す。
  • %p --- すべての区切り記号を表す。
  • %s --- すべての空白文字を表す。
  • %u --- すべての大文字を表す。
  • %w --- すべての英数文字を表す。
  • %x --- すべての十六進数字を表す。
  • %z --- 0として表現される文字を表す。
  • %x (x は英数文字以外) --- 文字 x 自身を表す。 これは魔法の文字をエスケープする標準的な方法である。 いかなる区切り文字 (魔法の文字でなくても) は前に `%´ を付けることでそれ自身を表すことができる。

  • [set] --- set 内のすべての文字の和からなるクラスを表す。 終わりの文字と `-´ で繋げることで、文字の範囲を表す。 上で挙げた %x 形式のすべてのクラスも、set の中で使うことができる。 それ以外の set 内の文字は、それ自身を表す。 例えば、[%w_] (または [_%w]) は、すべての英数にアンダースコアを加えたものを表す。 [0-7] は八進数字を表し、 [0-7%l%-] は八進数字と小文字と `-´ を表す。

    範囲とクラスの相互作用は未定義である。 つまり、[%a-z] や [a-%%] のようなパターンは意味を持たない。

  • [^set] --- set の補集合を表す。 set の内容は上で説明したものと同じである。
ひとつの文字で表現されるクラス (%a、%cなど) はすべて、対応する大文字は補集合を表す。 例えば %S は空白以外のすべての文字を表す。

文字、空白、その他の文字のグループの定義については、現在のロケールに依存する。 特に、クラス [a-z] は %l と等価ではないかもしれない。

パターンの要素 は以下のいずれかである。

  • 単一の文字クラス。そのクラス内の文字ひとつにマッチする。
  • 単一の文字クラスに `*´ が続いたもの。 そのクラスの文字の0回以上の繰り返しにマッチする。 この繰り返し要素は、可能な限り長いシーケンスにマッチする。
  • 単一の文字クラスに `+´ が続いたもの。 そのクラスの文字の1回以上の繰り返しにマッチする。 この繰り返し要素は、可能な限り長いシーケンスにマッチする。
  • 単一の文字クラスに `-´ が続いたもの。 そのクラスの文字の0回以上の繰り返しにマッチする。 `*´ と異なり、この繰り返し要素は可能な限り 短い シーケンスにマッチする。
  • 単一の文字クラスに `?´ が続いたもの。 そのクラスの文字の0回または1回の出現にマッチする。
  • %n (n は1から9)。 これは、n 番目にキャプチャされた文字列にマッチするような要素である (下の説明を参照)。
  • %b xy (x と y は異なる文字)。 これは x で始まって y で終わる文字列にマッチするような要素である。 x と y は 対応が取れる。 つまり、文字列を左から右に読んでいって、 x が現れるたびにカウントを +1 し、y では -1 したとき、 最後の y はカウントが0になる最初の y である。 例えば、要素 %b() はカッコの対応が取れた式にマッチする。

pattern はパターン要素の列である。 パターンの最初に現れる `^´ は対象文字列の先頭にマッチを固定する。 パターンの最後に現れる `$´ は対象文字列の最後にマッチを固定する。 他の位置では、`^´ や `$´ は特別な意味を持たず、それ自身を表す。

パターンはカッコで囲まれたサブパターンを持つことができ、それらは キャプチャ と呼ばれる。 マッチが成功したとき、対象文字列の中でキャプチャにマッチした部分が保存 (キャプチャ) され、後で使うことができる。 キャプチャはその左カッコによって番号付けされる。 例えば、パターン "(a*(.)%w(%s*))" では、 "a*(.)%w(%s*)" にマッチする部分が最初のキャプチャとして保存され (だから1番になる)、 "." にマッチする文字が2番にキャプチャされ、 "%s*" にマッチする部分が3番になる。

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

パターンには途中にゼロを含むことができない。代わりに %z を使う。

5.5 - テーブル操作

このライブラリはテーブル操作のための一般的な機能を提供する。 テーブル table 内にすべての関数が提供される。 これらの関数でテーブルの「長さ」について言及するときは、 それは長さ演算子の結果を意味している。

table.concat (table [, sep [, i [, j]]])

table[i]..sep..table[i+1] ... sep..table[j] を返す。 sep のデフォルト値は空文字列で、 i のデフォルト値は1、 j のデフォルト値はテーブルの長さである。 i が j よりも大きい場合は空文字列を返す。

table.insert (table, [pos,] value)

table の位置 pos に要素 value を挿入する。 空きスペースが必要なら、他の要素を上にずらす。 pos のデフォルト値は n+1 である。 n はテーブルの長さである (2.5.5 を参照)。 table.insert(t,x) の呼び出しは、テーブル t の最後に x を挿入する。

table.maxn (table)

指定したテーブルの最大の正の数値インデックスを返す。 テーブルが正の数値インデックスを持たなければゼロを返す。 (結果を得るために、この関数はテーブル全体を線形に巡回する。)

table.remove (table [, pos])

table から位置 pos の要素を取り除き、 必要なら他の要素を下にずらして空白を埋める。 取り除かれた要素の値が返される。 pos のデフォルト値は n である。 n はテーブルの長さである。 table.remove(t) の呼び出しは、テーブル t の最後の要素を取り除く。

table.sort (table [, comp])

table[1] から table[n] までのテーブル要素を、指定された順序で その場で ソートする。 n はテーブルの長さである。 comp を与える場合、それは関数でなくてはならず、テーブルの要素を2つ受け取り、最初の要素が二番目よりも小さいときに真を返さなければならない (ソート後、not comp(a[i+1],a[i]) が真になる)。 comp が与えられなければ、標準のLuaの演算子 < が代わりに使われる。

ソートのアルゴリズムは安定でない。 つまり、指定された順序において等しいと考えられる要素は、ソートによってその相対位置が変わるかもしれない。

5.6 - 数学関数

このライブラリは標準C数学ライブラリへのインタフェイスである。 math テーブルの中にすべての関数が提供される。 このライブラリは以下の関数を提供する:

       math.abs     math.acos    math.asin    math.atan    math.atan2
       math.ceil    math.cos     math.cosh    math.deg     math.exp
       math.floor   math.fmod    math.frexp   math.ldexp   math.log
       math.log10   math.max     math.min     math.modf    math.pow
       math.rad     math.random  math.randomseed           math.sin
       math.sinh    math.sqrt    math.tan     math.tanh
加えて、変数 math.pi と、値 HUGE_VAL を持つ変数 math.huge も提供される。 これらのほとんどは、Cライブラリの対応する関数への単なるインタフェイスである。 すべての三角関数はラジアンを使う。 関数 math.deg と math.rad はラジアンと度を変換する。

関数 math.max は引数の中の最大値を返す。 同様に math.min は最小値を求める。 共に1つ、2つ、あるいはもっとたくさんの引数を渡すことができる。

関数 math.modf はCの関数 modf に対応する。 これは2つの値、引数の整数部と小数部を返す。 関数 math.frexp も2つの値、 引数の正規化した小数部と指数部を返す。

関数 math.random と math.randomseed は ANSI C で提供される単純なランダム生成関数 rand と srand へのインタフェイスである (統計的な性質は保証されない)。 引数無しで呼ばれると、math.random は [0,1) の範囲の実数の疑似乱数を返す。 数値 n を渡すと、math.random は [1,n] の範囲の整数の疑似乱数を返す。 2つの引数 l と u を渡して呼んだときは、 math.random は [l,u] の範囲の整数の疑似乱数を返す。 math.randomseed 関数は疑似乱数発生器の「シード値」を設定する。 同じシード値からは同じ数列が生成される。

5.7 - 入出力機能

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

暗黙のファイルディスクリプタを使う場合は、すべての操作はテーブル io で提供される。 明示的なファイルディスクリプタを使う場合は、 すべての操作は io.open が返すファイルディスクリプタのメソッドとして提供される。

テーブル io は、 Cで使われる意味と同じの3つの定義済みファイルディスクリプタ io.stdin、io.stdout、io.stderr も提供する。

例外なく、すべてのI/O関数は失敗時に nil (および二番目の戻り値としてエラーメッセージ) を返し、 成功時は nil 以外の何らかの値を返す。

io.close ([file])

file:close() と等価である。 file が省略されると、デフォルト出力ファイルを閉じる。

io.flush ()

デフォルト出力ファイルに対する file:flush と等価である。

io.input ([file])

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

エラーが起きた場合、この関数はエラーコードを返す変わりにエラーを発する。

io.lines ([filename])

指定されたファイル名を読み込みモードで開き、 呼ばれるたびにファイルから1行ずつ返すイテレータ関数を返す。 つまり、

       for line in io.lines(filename) do ... end
はファイルのすべての行について繰り返す。 イテレータ関数は、ファイルの終わりを検出すると nil を返し (ループを終えるため)、自動的にファイルを閉じる。

io.lines() (ファイル名を渡さない) は io.input():lines() と等価である。 すなわち、デフォルト入力ファイルの各行について繰り返す。 この場合は、ループが終わってもファイルを閉じない。

io.open (filename [, mode])

この関数は mode で指定されたモードでファイルを開く。 新しいファイルハンドルを返すか、エラーの場合は nil とエラーメッセージを返す。

mode 文字列は以下のいずれかである。

  • "r" --- 読み込みモード (デフォルト)
  • "w" --- 書き込みモード
  • "a" --- 追記モード
  • "r+" --- 更新モード (以前のデータは消えない)
  • "w+" --- 更新モード (以前のデータはすべて消える)
  • "a+" --- 追記更新モード (以前のデータは消えない) ファイルの最後のだけ書き込みが許される。
mode 文字列は最後に `b´ も付けることができ、 システムによってはバイナリモードでファイルを開くために必要である。 この文字列は標準Cの関数 fopen で使われるのと同じである。

io.output ([file])

io.input と同じであるが、デフォルト出力ファイルに対する操作である。

io.popen ([prog [, mode]])

分離されたプロセスの中でプログラム prog を開始し、 このプログラムからのデータを読み込む (デフォルトの、mode が "r" の場合) ためか、このプログラムにデータを書き込む (mode が "w" の場合) ためのファイルハンドルを返す。

この関数はシステム依存であり、すべてのプラットフォームで利用可能なわけではない。

io.read (format1, ...)

io.input():read と等価である。

io.tmpfile ()

テンポラリファイルのハンドルを返す。 このファイルは更新モードでオープンされ、プログラムの終了時に自動的に削除される。

io.type (obj)

obj が有効なファイルハンドルかどうかチェックする。 obj がオープンされているファイルハンドルなら、文字列 "file" を返す。 obj がクローズされたファイルハンドルなら、文字列 "closed file" を返す。 obj がファイルハンドルでなければ nil を返す。

io.write (value1, ...)

io.output():write と等価である。

file:close ()

file を閉じる。 ファイルハンドルがガベージコレクトされたときはそのファイルは自動的に閉じられるが、 それがいつ起きるかは予測不能であることに注意せよ。

file:flush ()

file に書き込まれたデータを保存する。

file:lines ()

呼ばれるたびにファイルから新しい行を返すイテレータ関数を返す。 つまり、

       for line in file:lines() do ... end
はファイルのすべての行に対して繰り返す (io.lines と異なり、この関数はループの終わりでファイルを閉じない)。

file:read (format1, ...)

何を読むかを指定する書式に従って、ファイル file から読み込む。 各書式について、読み込んだ文字を文字列 (または数値) として返し、 指定された書式でデータを読めなければ nil を返す。 書式を指定せずに呼ばれた場合は、次の行全体を読むデフォルトの書式が使われる (以下を参照)。

利用可能なフォーマットは次の通り。

  • "*n" は数値を読み込む。 これは文字列の変わりに数値を読み込む唯一の書式である。
  • "*a" は現在の位置から、残りのファイル全体を読み込む。 ファイルの終わりでは、空文字列を返す。
  • "*l" は次の行を読み込む (行末文字は飛ばす)。 ファイルの終わりでは nil を返す。これはデフォルトの書式である。
  • 数値 はその文字数からなる文字列を読み込む。 ファイルの終わりでは空文字列を返す。 数値がゼロの場合は、何も読み込まず、空文字列を返す。 ファイルの終わりでは nil を返す。

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

ファイルの先頭から計ったファイル位置を設定/取得する。 位置は文字列 whence で指定された基準位置に offset を加えた値で示す。 whence は以下のいずれかである。

  • "set" --- 基準位置は0 (ファイルの先頭)
  • "cur" --- 基準位置は現在の位置
  • "end" --- 基準位置はファイルの終わり
成功すると、関数 seek はファイル先頭からのバイト数で最終的なファイル位置を返す。 この関数が失敗すると nil とエラー文字列を返す。

whence のデフォルト値は "cur" で、
offset は0である。
つまり、file:seek() の呼び出しは、何も変化させずに、現在の位置を返す。
file:seek("set") はファイルの先頭に位置を変更する (そして0を返す)。
file:seek("end") はファイルの終わりに位置を変更し、ファイルの長さを返す。

file:setvbuf (mode [, size])

出力ファイルのバッファリングモードを設定する。 設定可能なモードは3つある。

  • "no" --- バッファリングなし。出力操作の結果はすべて即座に現れる。
  • "full" --- 完全バッファリング。出力操作はバッファが満杯の場合 (または明示的にそのファイルを flush した場合 (5.7 を参照)) だけ行われる。
  • "line" --- 行バッファリング。出力は改行を出力するか、いくつかのスペシャルファイル (端末デバイスとか) から入力するまでバッファされる。
下の2つの場合では、 sizes でバッファのサイズをバイト単位で指定できる。 デフォルトのサイズは適当である。

file:write (value1, ...)

引数のそれぞれの値を file に書き込む。 引数は文字列か数字でなければならない。 それ以外の値を書き込むには、 write の前に tostring か string.format を使う。

5.8 - OS機能

このライブラリはテーブル os を通して提供される。

os.clock ()

プログラムが使ったCPU時間の概算値を秒で返す。

os.date ([format [, time]])

与えられた文字列 format に従って書式化した日付と時刻を含む文字列、またはテーブルを返す。

time 引数が存在すれば、それが書式化される時刻となる (この値の説明は os.time 関数を参照)。 そうでなければ、date は現在時刻を書式化する。

format が `!´ で始まっていたら、 日付は世界時 (Universal Time) で書式化される。 このオプション文字の後、 format が *t であれば、 date は以下のフィールドを持つテーブルを返す。

  • year (4桁の数値)
  • month (1--12)
  • day (1--31)
  • hour (0--23)
  • min (0--59)
  • sec (0--61)
  • wday (曜日、日曜日が1)
  • yday (1月1日から数えた日数)
  • isdst (夏時間を示すフラグ、ブーリアン)

format が *t でなければ、 date は日付を文字列として返す。 Cの関数 strftime と同じルールに従って書式化される。

引数なしで呼ばれた場合、 date はホストシステムと現在のロケールに依存する一般的な日付と時刻の表現を返す。 (つまり、os.date() は os.date("%c") と等価である)。

os.difftime (t2, t1)

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

os.execute ([command])

この関数はCの関数 system と等価である。 command はOSのシェルによって実行されるコマンドを渡す。 システムに依存するステータスコードを返す。 command を省略すると、シェルが利用可能ならゼロ以外を返し、そうでなければゼロを返す。

os.exit ([code])

省略可能な code でCの関数 exit を呼んでホストプログラムを終了させる。 code のデフォルト値は成功を表すコードである。

os.getenv (varname)

プロセスの環境変数 varname の値を返す。 変数が未定義なら nil を返す。

os.remove (filename)

指定された名前のファイルまたはディレクトリを消す。 消すディレクトリは空でなければならない。 この関数が失敗した場合は nil とエラーメッセージを返す。

os.rename (oldname, newname)

oldname という名前のファイルまたはディレクトリを newname にリネームする。 この関数が失敗した場合は nil とエラーメッセージを返す。

os.setlocale (locale [, category])

プログラムの現在のロケールを設定する。 locale はロケールを表す文字列である。 category は変更したいカテゴリを表す省略可能な文字列で、以下のいずれかである。 "all", "collate", "ctype", "monetary", "numeric", or "time"。 デフォルトのカテゴリは "all" である。 この関数は新しいロケールの名前を返す。 あるいは要求が受け付けられなければ nil を返す。

os.time ([table])

引数無しで呼ばれたときは現在の時刻を返し、 引数がある場合は、与えられたテーブルで指定された日付と時刻を表す時刻を返す。 このテーブルはフィールド year, month, and day を持たなければならず、 省略可能だがフィールド hour, min, sec, and isdst があっても良い (これらのフィールドの説明は os.date 関数を参照).

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

os.tmpname ()

テンポラリファイルとして使えるファイル名を返す。 このファイルは使う前に明示的にオープンする必要があり、 要らなくなったら明示的に削さなければならない。

5.9 - デバッグライブラリ

このライブラリはLuaプログラムへのデバッグインタフェイスの機能を提供する。 このライブラリを使うときは注意すべきである。 ここで提供される関数はデバッグやそれに似たプロファイリングのようなタスクにのみ使うべきである。 普通のプログラミングツールとしてこれらを使う誘惑に抵抗するように。 これらは非常に遅い。 さらに言えば、いくつかの関数はLuaコードについてのいくつかの仮定 (関数のローカル変数は他の関数からアクセスできないとか、ユーザーデータのメタテーブルはLuaから変更できないとか) を侵害し、安全なコードを危うくする恐れがある。

このライブラリのすべての関数は debug テーブル内に提供される。

debug.debug ()

ユーザーとの対話モードに入り、ユーザーが入力した文字列を実行する。 単純なコマンドや他のデバッグ機能を使って、 ユーザーはグローバル変数やローカル変数を調べたり値を変更したり式を評価したりその他ができる。 ユーザーが cont だけの行を入力すると対話モードを終えて実行を継続する。

debug.debug で実行されるコマンドは、 どの関数のレキシカルスコープにも入っていないので、 ローカル変数へは直接アクセスできないことに注意。

debug.getfenv (o)

オブジェクト o の環境を返す。

debug.gethook ()

現在のフック関数、フックマスク、フックカウント (debug.sethook 関数で設定されたもの) を返す。

debug.getinfo (function [, what])

関数に関する情報をテーブルに入れて返す。 関数を直接指定するか数値を指定することができる。 数値は、関数が走っているコールスタックのレベルを意味し、 レベル0は現在の関数 (getinfo 自身)、 レベル1は getinfo を呼び出した関数で、以下同様。 function がアクティブな関数の数よりも大きい数値であれば getinfo は nil を返す。

what はどのフィールドを埋めるかを記述する文字列で、 戻り値のテーブルには lua_getinfo から返されるフィールドがすべて含まれている。 what のデフォルト値では有効なすべての情報を取得する。 もし存在すれば、`f´ オプションは func という名前のフィールドにその関数自身を入れる。

例えば、式 debug.getinfo(1,"n").name は現在の関数の名前を返す (もし適当な名前があれば)。 debug.getinfo(print) は print 関数に関するすべての利用可能な情報を持つテーブルを返す。

debug.getlocal (level, local)

スタックレベル level の関数の、インデックス local のローカル変数の、名前と値を返す。 最初の引数かローカル変数がインデックス1で、以下同様に最後の有効なローカル変数まで続く。 もし指定されたインデックスのローカル変数がなければ nil を返し、 level が範囲外であればエラーを発する (debug.getinfo を使ってレベルが有効かどうかチェックできる)。

`(´ (開き括弧) で始まる変数名は内部的な変数 (ループ制御変数、一時変数、Cの関数のローカルなど) を表している。

debug.getmetatable (object)

指定した object のメタテーブルを返す。 メタテーブルを持っていなければ nil を返す。

debug.getregistry ()

レジストリテーブル (3.5 を参照) を返す。

debug.getupvalue (func, up)

関数 func の、インデックス up の上位値の、名前と値を返す。 指定されたインデックスの上位値が存在しなければ nil を返す。

debug.setfenv (object, table)

指定した object の環境を指定した table にする。

debug.sethook (hook, mask [, count])

指定された関数をフックに設定する。 文字列 mask と数値 count は、いつフックが呼ばれるかを記述する。 文字列maskは以下の文字からなる。

  • "c" --- フックはLuaが関数を呼ぶたびに呼ばれる。
  • "r" --- フックはLuaが関数から戻るたびに呼ばれる。
  • "l" --- フックはLuaがコードの新しい行に入るたびに呼ばれる。
count がゼロでなければ、フックは count 命令が実行されるたびに、その直後に呼ばれる。

引数なしで呼ぶとフックは無効になる。

フックが呼ばれたとき、最初の引数はフックを起動したイベントを示す以下のいずれかの文字列である。 "call", "return" "tail return", "line", "count"。 lineイベントの場合、フックは二番目の引数に新しい行番号が得られる。 "tail return" を除いて、 フックの内部でレベル2の getinfo を呼べば、実行中の関数に関する情報をもっと得られる (レベル0は getinfo 関数自身で、レベル1はフック関数である)。 "tail return" はLuaが復帰をシミュレートしているだけであり、 getinfo は正しくないデータを返すだろう。

debug.setlocal (level, local, value)

スタックレベル level の関数の、インデックス local のローカル変数に、値 value を格納する。 指定されたインデックスのローカル変数が存在しなければ nil を返し、 level が範囲外であればエラーを発する (getinfo を使ってレベルが有効かどうかチェックできる)。 そうでなければ、ローカル変数の名前を返す。

debug.setmetatable (object, table)

指定した object のメタテーブルを指定した table (nil でも良い) にする。

debug.setupvalue (func, up, value)

関数 func の、インデックス up の上位値に、値 value を格納する。 指定されたインデックスの上位値が存在しなければ nil を返す。 そうでなければ、上位値の名前を返す。

debug.traceback ([message])

コールスタックのトレースバックを出力した文字列を返す。 省略可能な message 文字列は、トレースバックの最初に付け加えられる。 この関数は典型的には、より良いエラーメッセージを生成するために xpcall と一緒に使われる。

6 - スタンドアロンのLua

LuaはCのホストプログラムに組み込まれる拡張言語としてデザインされたにも関わらず、 スタンドアロンの言語としてもよく使われる。 スタンドアロンの言語としてのLuaインタプリタは、単純に lua と呼ばれ、 標準のディストリビューションと共に提供されている。 スタンドアロンのインタプリタは、 デバッグライブラリを含むすべての標準ライブラリを持っている。 使い方は以下の通り。

      lua [options] [script [args]]
オプションは以下の通り。
  • - ファイルの代わりに stdin から実行する。
  • -e stat 文字列 stat を実行する。
  • -l mod mod を "requires" する。
  • -i script を実行した後、対話モードに入る。
  • -v バージョン情報を出力する。
  • -- オプションの処理を止める。
  • - オプションの処理を止め、stdin をファイルとして実行する。
これらのオプションが処理されたあと、lua は指定された script に args を文字列として渡して実行する。 引数なしで呼ばれた場合、 stdin (標準入力) が端末であれば lua -v -i、 そうでなければ lua - として振る舞う。

どの引数も適用される前に、 インタプリタは環境変数 LUA_INIT を調べる。 その書式が @filename であれば、そのファイルを実行する。 そうでなければ、その文字列自身を実行する。

-i 以外のすべてのオプションは順番に処理される。 例えば、以下のようなコマンドは

       $ lua -e'a=1' -e 'print(a)' script.lua
まず a に1を代入し、それから a の値 (つまり `1´) を表示し、最後にファイル script.lua を実行する (ここで、$ はシェルプロンプトである。キミのシェルプロンプトは違うかもしれない)。

スクリプトを実行する前に、lua はコマンドライン引数を arg という名前のグローバルなテーブルに格納する。 スクリプト名がインデックス0に格納され、 最初のｈきすうがスクリプト名の後のインデックス1に格納され、以下同様である。 スクリプト名の前のすべての引数 (つまり、インタプリタの名前やオプション) は負のインデックスに割り当てられる。 つまり、次のような場合

       $ lua -la b.lua t1 t2
インタプリタはまずファイル a.lua を実行し、 次に以下のようなテーブルを作る。
       arg = { [-2] = "lua", [-1] = "-la",
               [0] = "b.lua",
               [1] = "t1", [2] = "t2" }
そして最後にファイル b.lua を実行する。 スクリプトは引数として arg[1], arg[2], ... が渡されて呼ばれる。 可変引数式 `...´ を使って引数にアクセスすることもできる。

対話モードでは、不完全な文を書いたときは、それが完全な文になるまで待つ。

グローバル変数 _PROMPT が文字列を持っていれば、 その値がプロンプトに使われる。 同様に、グローバル変数 _PROMPT2 が文字列を持っていれば、 その値が第二プロンプトに使われる (不完全な文である間使われる)。 つまり、プロンプトはコマンドラインから直に変更できる。

       $ lua -e"_PROMPT='myprompt> '" -i
(外側のクォート対はシェルのための、内側はLuaのためのもの。) また、_PROMPT に代入することで、Luaのプログラムからも変更できる。 対話モードに入るには -i が要ることに注意。 そうでなければ、プログラムは _PROMPT に代入した直後に何も出力せず終わるであろう。

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

#!/usr/local/bin/lua
(もちろん、キミのマシンではLuaインタプリタは違う場所にあるかもしれない。 もし PATH の通るところに lua があれば、
#!/usr/bin/env lua
がより移植性の高い解決法である)。

前バージョンとの非互換

プログラムをLua5.0からLua5.1に移行する際に見つかるかもしれない非互換の一覧を示す。 ほとんどの非互換は適切なオプションを使ってコンパイルすることで避けられる (ファイル luaconf.h を参照)。 しかしながら、これらの互換用オプションはすべて次のバージョンのLuaでは削除される予定である。

バージョン5.0との非互換

言語の変更

  • 可変引数システムは、余分の引数を持つテーブルの疑似引数 arg から 可変引数式に変更された。 (luaconf.h のオプション LUA_COMPAT_VARARG)

  • for 文と repeat 文の暗黙の変数のスコープが微妙に変更された。

  • 長い文字列と長いコメントの構文 ([[...]]) はネストできなくなった。 この場合、新しい構文 ([=[...]=]) を使うことができる。 (luaconf.h のオプション LUA_COMPAT_LSTR)

ライブラリの変更

  • 関数 string.gfind は string.gmatch に名前が変更された。 (オプション LUA_COMPAT_GFIND)

  • string.gsub の3番目の引数に関数を渡した場合、 この関数が nil または false を返すと、 空文字列でなくマッチした文字列全体に置換するようになった。

  • 関数 table.setn は廃止された。 関数 table.getn は新しい長さ演算子 (#) が対応する。 関数の代わりに演算子を使う。 (オプション LUA_COMPAT_GETN)

  • 関数 loadlib は package.loadlib に名前が変更された。 (オプション LUA_COMPAT_LOADLIB)

  • 関数 math.mod は math.fmod に名前が変更された。 (オプション LUA_COMPAT_MOD)

  • 関数 table.foreach および table.foreachi は廃止された。 ループには代わりに pairs または ipairs を使う。

  • 新しいモジュールシステムを導入したため、 関数 require に大幅な変更が行われた。 しかしながら、新しい動作は以前とほぼ互換性がある。 ただし require は LUA_PATH の代わりに package.path からパスを取得する。

  • 関数 collectgarbage の引数が変更された。 関数 gcinfo は廃止された。 代わりに collectgarbage("count") を使う。

APIの変更

  • ライブラリを開く luaopen_* 関数は通常のCの関数のようには直接は呼べなくなった。 これらはLuaの関数のようにLuaを通して呼ばなければならない。

  • 関数 lua_open は、ユーザ独自のメモリ確保関数を指定できる lua_newstate に置き換えられた。 標準のメモリ確保関数 (realloc をベースとする) を使ってステートを作るには、 標準ライブラリの luaL_newstate を使う。

  • 関数 luaL_getn および luaL_setn (補助ライブラリにあった) は廃止された。 luaL_getn の代わりに lua_objlen を使う。 luaL_setn の代わりは存在しない。

  • 関数 luaL_openlib は luaL_register に置き換えられた。

Luaの完全な構文

Luaの完全な構文を拡張BNF記法で示す。 これは演算子の優先順位や、 return および break 文がブロックの 最後の 文としてしか使えないといった いくつかの構文的制限は記述していない。

    chunk ::= {stat [`;´]} [laststat[`;´]]

    block ::= chunk

    stat ::=  varlist1 `=´ explist1  |
         functioncall  |
         do block end  |
         while exp do block end  |
         repeat block until exp  |
         if exp then block {elseif exp then block} [else block] end  |
         for Name `=´ exp `,´ exp [`,´ exp] do block end  |
         for namelist in explist1 do block end  |
         function funcname funcbody  |
         local function Name funcbody  |
         local namelist [`=´ explist1]

    laststat ::= return [explist1]  |  break

    funcname ::= Name {`.´ Name} [`:´ Name]

    varlist1 ::= var {`,´ var}

    var ::=  Name  |  prefixexp `[´ exp `]´  |  prefixexp `.´ Name

    namelist ::= Name {`,´ Name}

    explist1 ::= {exp `,´} exp

    exp ::=  nil  |  false  |  true  |  Number  |  String  |  `...´  |
         function  |  prefixexp  |  tableconstructor  |  exp binop exp  |  unop exp

    prefixexp ::= var  |  functioncall  |  `(´ exp `)´

    functioncall ::=  prefixexp args  |  prefixexp `:´ Name args

    args ::=  `(´ [explist1] `)´  |  tableconstructor  |  String

    function ::= function funcbody

    funcbody ::= `(´ [parlist1] `)´ block end

    parlist1 ::= namelist [`,´ `...´]  |  `...´

    tableconstructor ::= `{´ [fieldlist] `}´

    fieldlist ::= field {fieldsep field} [fieldsep]

    field ::= `[´ exp `]´ `=´ exp  |  Name `=´ exp  |  exp

    fieldsep ::= `,´  |  `;´

    binop ::= `+´  |  `-´  |  `*´  |  `/´  |  `^´  |  `%´  |  `..´  |
         `<´  |  `<=´  |  `>´  |  `>=´  |  `==´  |  `~=´  |
         and  |  or

    unop ::= `-´  |  not  |  `#´


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

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

スタート · 目次 · 索引

Copyright © 2011 Lua.org, PUC-Rio. Freely available under the terms of the Lua license.

目次

  • 0 – 日本語訳について

  • 1 – 序文

  • 2 – 基本コンセプト
    • 2.1 – 値と型
    • 2.2 – 環境とグローバル環境
    • 2.3 – エラー処理
    • 2.4 – メタテーブルとメタメソッド
    • 2.5 – ガベージコレクション
      • 2.5.1 – ガベージコレクションメタメソッド
      • 2.5.2 – 弱参照テーブル
    • 2.6 – コルーチン

  • 3 – 言語
    • 3.1 – 字句構造
    • 3.2 – 変数
    • 3.3 – 文
      • 3.3.1 – ブロック
      • 3.3.2 – チャンク
      • 3.3.3 – 代入
      • 3.3.4 – 制御構造
      • 3.3.5 – for 文
      • 3.3.6 – 文としての関数呼び出し
      • 3.3.7 – ローカル宣言
    • 3.4 – 式
      • 3.4.1 – 算術演算子
      • 3.4.2 – 強制型変換
      • 3.4.3 – 関係演算子
      • 3.4.4 – 論理演算子
      • 3.4.5 – 連結
      • 3.4.6 – 長さ演算子
      • 3.4.7 – 優先順位
      • 3.4.8 – テーブルコンストラクタ
      • 3.4.9 – 関数呼び出し
      • 3.4.10 – 関数定義
    • 3.5 – 可視性ルール

  • 4 – API
    • 4.1 – スタック
    • 4.2 – スタックサイズ
    • 4.3 – 有効なおよび受け入れ可能なインデックス
    • 4.4 – C のクロージャ
    • 4.5 – レジストリ
    • 4.6 – C でのエラー処理
    • 4.7 – C での yield 処理
    • 4.8 – 関数と型
    • 4.9 – デバッグインタフェイス

  • 5 – 補助ライブラリ
    • 5.1 – 関数と型

  • 6 – 標準ライブラリ
    • 6.1 – 基本関数
    • 6.2 – コルーチン操作
    • 6.3 – モジュール
    • 6.4 – 文字列操作
      • 6.4.1 – パターン
    • 6.5 – テーブル操作
    • 6.6 – 数学関数
    • 6.7 – ビット演算
    • 6.8 – 入出力機能
    • 6.9 – OS機能
    • 6.10 – デバッグライブラリ

  • 7 – スタンドアロンの Lua

  • 8 – 前のバージョンと非互換な点
    • 8.1 – 言語の変更
    • 8.2 – ライブラリの変更
    • 8.3 – API の変更

  • 9 – Lua の完全な構文

索引

Lua の関数

_G
_VERSION

assert
collectgarbage
dofile
error
getmetatable
ipairs
loadfile
load
next
pairs
pcall
print
rawequal
rawget
rawlen
rawset
require
select
setmetatable
tonumber
tostring
type
xpcall

bit32.arshift
bit32.band
bit32.bnot
bit32.bor
bit32.btest
bit32.bxor
bit32.extract
bit32.lrotate
bit32.lshift
bit32.replace
bit32.rrotate
bit32.rshift

coroutine.create
coroutine.resume
coroutine.running
coroutine.status
coroutine.wrap
coroutine.yield

debug.debug
debug.getuservalue
debug.gethook
debug.getinfo
debug.getlocal
debug.getmetatable
debug.getregistry
debug.getupvalue
debug.setuservalue
debug.sethook
debug.setlocal
debug.setmetatable
debug.setupvalue
debug.traceback
debug.upvalueid
debug.upvaluejoin

file:close
file:flush
file:lines
file:read
file:seek
file:setvbuf
file:write

io.close
io.flush
io.input
io.lines
io.open
io.output
io.popen
io.read
io.stderr
io.stdin
io.stdout
io.tmpfile
io.type
io.write

math.abs
math.acos
math.asin
math.atan
math.atan2
math.ceil
math.cos
math.cosh
math.deg
math.exp
math.floor
math.fmod
math.frexp
math.huge
math.ldexp
math.log
math.max
math.min
math.modf
math.pi
math.pow
math.rad
math.random
math.randomseed
math.sin
math.sinh
math.sqrt
math.tan
math.tanh

os.clock
os.date
os.difftime
os.execute
os.exit
os.getenv
os.remove
os.rename
os.setlocale
os.time
os.tmpname

package.config
package.cpath
package.loaded
package.loadlib
package.path
package.preload
package.searchers
package.searchpath

string.byte
string.char
string.dump
string.find
string.format
string.gmatch
string.gsub
string.len
string.lower
string.match
string.rep
string.reverse
string.sub
string.upper

table.concat
table.insert
table.pack
table.remove
table.sort
table.unpack

C の API

lua_Alloc
lua_CFunction
lua_Debug
lua_Hook
lua_Integer
lua_Number
lua_Reader
lua_State
lua_Unsigned
lua_Writer

lua_absindex
lua_arith
lua_atpanic
lua_call
lua_callk
lua_checkstack
lua_close
lua_compare
lua_concat
lua_copy
lua_createtable
lua_dump
lua_error
lua_gc
lua_getallocf
lua_getctx
lua_getfield
lua_getglobal
lua_gethook
lua_gethookcount
lua_gethookmask
lua_getinfo
lua_getlocal
lua_getmetatable
lua_getstack
lua_gettable
lua_gettop
lua_getupvalue
lua_getuservalue
lua_insert
lua_isboolean
lua_iscfunction
lua_isfunction
lua_islightuserdata
lua_isnil
lua_isnone
lua_isnoneornil
lua_isnumber
lua_isstring
lua_istable
lua_isthread
lua_isuserdata
lua_len
lua_load
lua_newstate
lua_newtable
lua_newthread
lua_newuserdata
lua_next
lua_pcall
lua_pcallk
lua_pop
lua_pushboolean
lua_pushcclosure
lua_pushcfunction
lua_pushfstring
lua_pushinteger
lua_pushlightuserdata
lua_pushliteral
lua_pushlstring
lua_pushnil
lua_pushnumber
lua_pushstring
lua_pushthread
lua_pushvalue
lua_pushvfstring
lua_rawequal
lua_rawget
lua_rawgeti
lua_rawlen
lua_rawset
lua_rawseti
lua_rawgetp
lua_rawsetp
lua_register
lua_remove
lua_replace
lua_resume
lua_setallocf
lua_setfield
lua_setglobal
lua_sethook
lua_setlocal
lua_setmetatable
lua_settable
lua_settop
lua_setupvalue
lua_setuservalue
lua_status
lua_toboolean
lua_tocfunction
lua_tointeger
lua_tointegerx
lua_tolstring
lua_tonumber
lua_tonumberx
lua_topointer
lua_tostring
lua_tothread
lua_tounsigned
lua_tounsignedx
lua_touserdata
lua_type
lua_typename
lua_upvalueid
lua_upvalueindex
lua_upvaluejoin
lua_version
lua_xmove
lua_yield
lua_yieldk

補助ライブラリ

luaL_Buffer
luaL_Reg

luaL_addchar
luaL_addlstring
luaL_addsize
luaL_addstring
luaL_addvalue
luaL_argcheck
luaL_argerror
luaL_buffinit
luaL_buffinitsize
luaL_callmeta
luaL_checkany
luaL_checkinteger
luaL_checkint
luaL_checklong
luaL_checklstring
luaL_checknumber
luaL_checkoption
luaL_checkstack
luaL_checkstring
luaL_checktype
luaL_checkudata
luaL_checkunsigned
luaL_checkversion
luaL_dofile
luaL_dostring
luaL_error
luaL_execresult
luaL_fileresult
luaL_getmetafield
luaL_getmetatable
luaL_getsubtable
luaL_gsub
luaL_len
luaL_loadbuffer
luaL_loadbufferx
luaL_loadfile
luaL_loadfilex
luaL_loadstring
luaL_newlib
luaL_newlibtable
luaL_newmetatable
luaL_newstate
luaL_openlibs
luaL_optinteger
luaL_optint
luaL_optlong
luaL_optlstring
luaL_optnumber
luaL_optstring
luaL_optunsigned
luaL_prepbuffer
luaL_prepbuffsize
luaL_pushresult
luaL_pushresultsize
luaL_ref
luaL_requiref
luaL_setfuncs
luaL_setmetatable
luaL_testudata
luaL_tolstring
luaL_traceback
luaL_typename
luaL_unref
luaL_where
Last update: Tue Nov 29 22:30:23 BRST 2011

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

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

Copyright © 2011 Lua.org, PUC-Rio. Freely available under the terms of the Lua license.

目次 · 索引

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)

ex の値を返します。

math.floor (x)

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

math.fmod (x, y)

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

math.frexp (x)

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

math.huge

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

math.ldexp (m, e)

m2e を返します (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)

xy を返します。 (式 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 テーブルに提供されます。

特に記載がない限り、 すべての関数は範囲 (-251,+251) の数値引数を受け付けますが、 各引数は 232 で割った余りに正規化され、 (何らかの適当な方法で) 整数に丸められます。 それにより最終的な値は [0,232 - 1] の範囲になります。 同様に、 すべての戻り値も [0,232 - 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 | ‘#’


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

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

スタート · 目次 · 索引 · 他のバージョン

Copyright © 2015 Lua.org, PUC-Rio. Freely available under the terms of the Lua license.

目次

  • 0 – 日本語訳について

  • 1 – 序文

  • 2 – 基本コンセプト
    • 2.1 – 値と型
    • 2.2 – 環境とグローバル環境
    • 2.3 – エラー処理
    • 2.4 – メタテーブルとメタメソッド
    • 2.5 – ガベージコレクション
      • 2.5.1 – ガベージコレクションメタメソッド
      • 2.5.2 – 弱参照テーブル
    • 2.6 – コルーチン

  • 3 – 言語
    • 3.1 – 字句規約
    • 3.2 – 変数
    • 3.3 – 文
      • 3.3.1 – ブロック
      • 3.3.2 – チャンク
      • 3.3.3 – 代入
      • 3.3.4 – 制御構造
      • 3.3.5 – for文
      • 3.3.6 – 文としての関数呼び出し
      • 3.3.7 – ローカル宣言
    • 3.4 – 式
      • 3.4.1 – 算術演算子
      • 3.4.2 – ビット演算子
      • 3.4.3 – 強制型変換
      • 3.4.4 – 関係演算子
      • 3.4.5 – 論理演算子
      • 3.4.6 – 連結
      • 3.4.7 – 長さ演算子
      • 3.4.8 – 優先順位
      • 3.4.9 – テーブルコンストラクタ
      • 3.4.10 – 関数呼び出し
      • 3.4.11 – 関数定義
    • 3.5 – 可視性ルール

  • 4 – API
    • 4.1 – スタック
    • 4.2 – スタックサイズ
    • 4.3 – 有効なインデックスと受け入れ可能なインデックス
    • 4.4 – Cのクロージャ
    • 4.5 – レジストリ
    • 4.6 – Cでのエラー処理
    • 4.7 – Cでのyield処理
    • 4.8 – 関数と型
    • 4.9 – デバッグインタフェース

  • 5 – 補助ライブラリ
    • 5.1 – 関数と型

  • 6 – 標準ライブラリ
    • 6.1 – 基本機能
    • 6.2 – コルーチン操作
    • 6.3 – モジュール
    • 6.4 – 文字列操作
      • 6.4.1 – パターン
      • 6.4.2 – packとunpackの書式文字列
    • 6.5 – UTF-8サポート
    • 6.6 – テーブル操作
    • 6.7 – 数学関数
    • 6.8 – 入出力機能
    • 6.9 – OS機能
    • 6.10 – デバッグライブラリ

  • 7 – スタンドアロンのLua

  • 8 – 前バージョンとの非互換な点
    • 8.1 – 言語の変更
    • 8.2 – ライブラリの変更
    • 8.3 – APIの変更

  • 9 – Luaの完全な構文

索引

Lua の関数

基本
_G
_VERSION
assert
collectgarbage
dofile
error
getmetatable
ipairs
load
loadfile
next
pairs
pcall
print
rawequal
rawget
rawlen
rawset
require
select
setmetatable
tonumber
tostring
type
xpcall

コルーチン
coroutine.create
coroutine.isyieldable
coroutine.resume
coroutine.running
coroutine.status
coroutine.wrap
coroutine.yield

デバッグ
debug.debug
debug.gethook
debug.getinfo
debug.getlocal
debug.getmetatable
debug.getregistry
debug.getupvalue
debug.getuservalue
debug.sethook
debug.setlocal
debug.setmetatable
debug.setupvalue
debug.setuservalue
debug.traceback
debug.upvalueid
debug.upvaluejoin

入出力
io.close
io.flush
io.input
io.lines
io.open
io.output
io.popen
io.read
io.stderr
io.stdin
io.stdout
io.tmpfile
io.type
io.write
file:close
file:flush
file:lines
file:read
file:seek
file:setvbuf
file:write

数学
math.abs
math.acos
math.asin
math.atan
math.ceil
math.cos
math.deg
math.exp
math.floor
math.fmod
math.huge
math.log
math.max
math.maxinteger
math.min
math.mininteger
math.modf
math.pi
math.rad
math.random
math.randomseed
math.sin
math.sqrt
math.tan
math.tointeger
math.type
math.ult

OS
os.clock
os.date
os.difftime
os.execute
os.exit
os.getenv
os.remove
os.rename
os.setlocale
os.time
os.tmpname

パッケージ
package.config
package.cpath
package.loaded
package.loadlib
package.path
package.preload
package.searchers
package.searchpath

文字列
string.byte
string.char
string.dump
string.find
string.format
string.gmatch
string.gsub
string.len
string.lower
string.match
string.pack
string.packsize
string.rep
string.reverse
string.sub
string.unpack
string.upper

テーブル
table.concat
table.insert
table.move
table.pack
table.remove
table.sort
table.unpack

UTF-8
utf8.char
utf8.charpattern
utf8.codepoint
utf8.codes
utf8.len
utf8.offset

環境変数

LUA_CPATH
LUA_CPATH_5_3
LUA_INIT
LUA_INIT_5_3
LUA_PATH
LUA_PATH_5_3

C の API

lua_Alloc
lua_CFunction
lua_Debug
lua_Hook
lua_Integer
lua_KContext
lua_KFunction
lua_Number
lua_Reader
lua_State
lua_Unsigned
lua_Writer

lua_absindex
lua_arith
lua_atpanic
lua_call
lua_callk
lua_checkstack
lua_close
lua_compare
lua_concat
lua_copy
lua_createtable
lua_dump
lua_error
lua_gc
lua_getallocf
lua_getextraspace
lua_getfield
lua_getglobal
lua_gethook
lua_gethookcount
lua_gethookmask
lua_geti
lua_getinfo
lua_getlocal
lua_getmetatable
lua_getstack
lua_gettable
lua_gettop
lua_getupvalue
lua_getuservalue
lua_insert
lua_isboolean
lua_iscfunction
lua_isfunction
lua_isinteger
lua_islightuserdata
lua_isnil
lua_isnone
lua_isnoneornil
lua_isnumber
lua_isstring
lua_istable
lua_isthread
lua_isuserdata
lua_isyieldable
lua_len
lua_load
lua_newstate
lua_newtable
lua_newthread
lua_newuserdata
lua_next
lua_numbertointeger
lua_pcall
lua_pcallk
lua_pop
lua_pushboolean
lua_pushcclosure
lua_pushcfunction
lua_pushfstring
lua_pushglobaltable
lua_pushinteger
lua_pushlightuserdata
lua_pushliteral
lua_pushlstring
lua_pushnil
lua_pushnumber
lua_pushstring
lua_pushthread
lua_pushvalue
lua_pushvfstring
lua_rawequal
lua_rawget
lua_rawgeti
lua_rawgetp
lua_rawlen
lua_rawset
lua_rawseti
lua_rawsetp
lua_register
lua_remove
lua_replace
lua_resume
lua_rotate
lua_setallocf
lua_setfield
lua_setglobal
lua_sethook
lua_seti
lua_setlocal
lua_setmetatable
lua_settable
lua_settop
lua_setupvalue
lua_setuservalue
lua_status
lua_stringtonumber
lua_toboolean
lua_tocfunction
lua_tointeger
lua_tointegerx
lua_tolstring
lua_tonumber
lua_tonumberx
lua_topointer
lua_tostring
lua_tothread
lua_touserdata
lua_type
lua_typename
lua_upvalueid
lua_upvalueindex
lua_upvaluejoin
lua_version
lua_xmove
lua_yield
lua_yieldk

補助ライブラリ

luaL_Buffer
luaL_Reg
luaL_Stream

luaL_addchar
luaL_addlstring
luaL_addsize
luaL_addstring
luaL_addvalue
luaL_argcheck
luaL_argerror
luaL_buffinit
luaL_buffinitsize
luaL_callmeta
luaL_checkany
luaL_checkinteger
luaL_checklstring
luaL_checknumber
luaL_checkoption
luaL_checkstack
luaL_checkstring
luaL_checktype
luaL_checkudata
luaL_checkversion
luaL_dofile
luaL_dostring
luaL_error
luaL_execresult
luaL_fileresult
luaL_getmetafield
luaL_getmetatable
luaL_getsubtable
luaL_gsub
luaL_len
luaL_loadbuffer
luaL_loadbufferx
luaL_loadfile
luaL_loadfilex
luaL_loadstring
luaL_newlib
luaL_newlibtable
luaL_newmetatable
luaL_newstate
luaL_openlibs
luaL_optinteger
luaL_optlstring
luaL_optnumber
luaL_optstring
luaL_prepbuffer
luaL_prepbuffsize
luaL_pushresult
luaL_pushresultsize
luaL_ref
luaL_requiref
luaL_setfuncs
luaL_setmetatable
luaL_testudata
luaL_tolstring
luaL_traceback
luaL_typename
luaL_unref
luaL_where

標準ライブラリ

luaopen_base
luaopen_coroutine
luaopen_debug
luaopen_io
luaopen_math
luaopen_os
luaopen_package
luaopen_string
luaopen_table
luaopen_utf8

定数

LUA_ERRERR
LUA_ERRFILE
LUA_ERRGCMM
LUA_ERRMEM
LUA_ERRRUN
LUA_ERRSYNTAX
LUA_HOOKCALL
LUA_HOOKCOUNT
LUA_HOOKLINE
LUA_HOOKRET
LUA_HOOKTAILCALL
LUA_MASKCALL
LUA_MASKCOUNT
LUA_MASKLINE
LUA_MASKRET
LUA_MAXINTEGER
LUA_MININTEGER
LUA_MINSTACK
LUA_MULTRET
LUA_NOREF
LUA_OK
LUA_OPADD
LUA_OPBAND
LUA_OPBNOT
LUA_OPBOR
LUA_OPBXOR
LUA_OPDIV
LUA_OPEQ
LUA_OPIDIV
LUA_OPLE
LUA_OPLT
LUA_OPMOD
LUA_OPMUL
LUA_OPPOW
LUA_OPSHL
LUA_OPSHR
LUA_OPSUB
LUA_OPUNM
LUA_REFNIL
LUA_REGISTRYINDEX
LUA_RIDX_GLOBALS
LUA_RIDX_MAINTHREAD
LUA_TBOOLEAN
LUA_TFUNCTION
LUA_TLIGHTUSERDATA
LUA_TNIL
LUA_TNONE
LUA_TNUMBER
LUA_TSTRING
LUA_TTABLE
LUA_TTHREAD
LUA_TUSERDATA
LUA_USE_APICHECK
LUA_YIELD
LUAL_BUFFERSIZE

Last update: Wed Jun 17 08:30:41 BRT 2015

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

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

Copyright © 2015 Lua.org, PUC-Rio. Freely available under the terms of the Lua license.

目次 · 索引 · 他のバージョン

0 – 日本語訳について

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

1 – 序文

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

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

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

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

2 – 基本コンセプト

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

2.1 – 値と型

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2.3 – エラー処理

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    このイベントのメタメソッドは、メタメソッドという名前にもかかわらず、テーブルであっても構いません。 メタメソッドが関数であれば、 table と key を引数としてその関数が呼ばれます。 メタメソッドがテーブルであれば、そのテーブルを key で検索した結果が最終結果になります。 (この検索は生ではなく正規のものであり、さらなるメタメソッドが呼ばれる場合があります。)

  • "newindex": インデックス付き代入 table[key] = value。 indexイベント同様、このイベントは table がテーブルでないか、 table に key が存在しない場合に発生します。 メタメソッドは table に対して検索されます。

    indexイベント同様、このイベントのメタメソッドは関数とテーブルのどちらでも構いません。 メタメソッドが関数であれば、 table、 key、 value を引数としてその関数が呼ばれます。 メタメソッドがテーブルであれば、そのテーブルに対して同じ key と value でインデックス付き代入を行います。 (この代入は生ではなく正規のものであり、さらなるメタメソッドが呼ばれる場合があります。)

    "newindex" メタメソッドが存在する場合、本来の代入は実行されません (もし必要であれば、メタメソッド内で rawset を呼んで自分で代入を実行してください。)

  • "call": 呼び出し演算 func(args)。 このイベントは関数でない値を呼ぼうとしたときに発生します (つまり func が関数でない場合です)。 メタメソッドは func に対して検索されます。 もしあれば、そのメタメソッドが呼ばれます。 そのとき第1引数に func が渡され、第2引数以降に元の呼び出しの引数 (args) が渡されます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2.5.2 – 弱参照テーブル

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

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

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

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

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

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

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

2.6 – コルーチン

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

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

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

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

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

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

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

     function foo (a)
       print("foo", a)
       return coroutine.yield(2*a)
     end

     co = coroutine.create(function (a,b)
           print("co-body", a, b)
           local r = foo(a+1)
           print("co-body", r)
           local r, s = coroutine.yield(a+b, a-b)
           print("co-body", r, s)
           return b, "end"
     end)

     print("main", coroutine.resume(co, 1, 10))
     print("main", coroutine.resume(co, "r"))
     print("main", coroutine.resume(co, "x", "y"))
     print("main", coroutine.resume(co, "x", "y"))

実行すると以下のように出力されます。

     co-body 1       10
     foo     2
     main    true    4
     co-body r
     main    true    11      -9
     co-body x       y
     main    true    10      end
     main    false   cannot resume dead coroutine

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

3 – 言語

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

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

3.1 – 字句規約

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     3   345   0xff   0xBEBADA

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

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

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

3.2 – 変数

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

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

    var ::= Name

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

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

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

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

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

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

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

    var ::= prefixexp ‘.’ Name

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

3.3 – 文

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

3.3.1 – ブロック

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

    block ::= {stat}

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

    stat ::= ‘;’

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

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

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

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

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

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

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

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

    stat ::= do block end

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

3.3.2 – チャンク

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

    chunk ::= block

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

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

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

3.3.3 – 代入

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

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

式は §3.4 で議論します。

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

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

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

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

     x, y = y, x

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

     x, y, z = y, z, x

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

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

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

3.3.4 – 制御構造

制御構造 if、while、repeat は一般的な意味と馴染み深い構文を持っています。

    stat ::= while exp do block end
    stat ::= repeat block until exp
    stat ::= if exp then block {elseif exp then block} [else block] end

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

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

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

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

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

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

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

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

    stat ::= break

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

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

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

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

3.3.5 – for文

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

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

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

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

     for v = e1, e2, e3 do block end

以下のコードと同等です。

     do
       local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
       if not (var and limit and step) then error() end
       var = var - step
       while true do
         var = var + step
         if (step >= 0 and var > limit) or (step < 0 and var < limit) then
           break
         end
         local v = var
         block
       end
     end

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

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

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

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

以下のような for 文は、

     for var_1, ···, var_n in explist do block end

以下のコードと同等です。

     do
       local f, s, var = explist
       while true do
         local var_1, ···, var_n = f(s, var)
         if var_1 == nil then break end
         var = var_1
         block
       end
     end

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

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

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

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

    stat ::= functioncall

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

3.3.7 – ローカル宣言

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

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

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

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

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

3.4 – 式

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

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

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

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

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

いくつか例を挙げます。

     f()                -- 戻り値は0個に調節される
     g(f(), x)          -- f()の戻り値は1個に調節される
     g(x, f())          -- gは、xに加え、f()からの戻り値をすべて受け取りる
     a,b,c = f(), x     -- f()の戻り値は1個に調節される (cはnilになる)
     a,b = ...          -- aは可変長引数の最初の値を受け取り、
                        -- bは2番目の値を受け取る
                        -- (aもbも、対応する値がなければnilを受け取る)

     a,b,c = x, f()     -- f()の戻り値は2個に調節される
     a,b,c = f()        -- f()の戻り値は3個に調節される
     return f()         -- f()の戻り値をすべて返す
     return ...         -- 受け取った可変長引数をすべて返す
     return x,y,f()     -- x、y、およびf()のすべての戻り値を返す
     {f()}              -- f()のすべての戻り値を持つリストを作る
     {...}              -- すべての可変長引数を持つリストを作る
     {f(), nil}         -- f()の戻り値は1個に調節される

括弧で囲まれたあらゆる式は、常に1個だけの値を返します。 例えば、 f が複数の値を返す場合でも、 (f(x,y,z)) は必ず1個の値となります。 ((f(x,y,z)) の値は f が返した最初の値になります。 f が何も返さなければ nil になります。)

3.4.1 – 算術演算子

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

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

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

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

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

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

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

3.4.2 – ビット演算子

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

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

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

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

3.4.3 – 強制型変換

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

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

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

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

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

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

3.4.4 – 関係演算子

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

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

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

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

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

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

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

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

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

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

3.4.5 – 論理演算子

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

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

     10 or 20            --> 10
     10 or error()       --> 10
     nil or "a"          --> "a"
     nil and 10          --> nil
     false and error()   --> false
     false and nil       --> false
     false or nil        --> nil
     10 and 20           --> 20

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

3.4.6 – 連結

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

3.4.7 – 長さ演算子

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

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

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

     {10, 20, nil, 40}

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

3.4.8 – 優先順位

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

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

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

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

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

    tableconstructor ::= ‘{’ [fieldlist] ‘}’
    fieldlist ::= field {fieldsep field} [fieldsep]
    field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp
    fieldsep ::= ‘,’ | ‘;’

[exp1] = exp2 形式のフィールドは、それぞれキー exp1 と値 exp2 を持つエントリを、その新しいテーブルに追加します。 name = exp 形式のフィールドは ["name"] = exp と同等です。 最後に、 exp 形式のフィールドは [i] = exp と同等です。 ただし i は1から始まる連番の整数です。 他の形式のフィールドは、この連番に影響しません。 例えば、

     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }

これは以下と同等です。

     do
       local t = {}
       t[f(1)] = g
       t[1] = "x"         -- 最初のexp
       t[2] = "y"         -- 2番目のexp
       t.x = 1            -- t["x"] = 1
       t[3] = f(x)        -- 3番目のexp
       t[30] = 23
       t[4] = 45          -- 4番目のexp
       a = t
     end

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

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

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

3.4.10 – 関数呼び出し

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

    functioncall ::= prefixexp args

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

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

    functioncall ::= prefixexp ‘:’ Name args

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

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

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

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

return functioncall 形式の呼び出しは末尾呼び出しと言います。 Luaには真正末尾呼び出し (または真正末尾再帰) が実装されています。 つまり、末尾呼び出しでは呼び出し先の関数が呼び出し元の関数のスタックエントリを再利用します。 そのため、末尾呼び出しをネストできる数に制限がありません。 ただし、末尾呼び出しは呼び出し元の関数に関するデバッグ情報をすべて消去してしまいます。 末尾呼び出しは特定の構文においてのみ起きることに注意してください。 その構文とは、関数呼び出しひとつを引数として持つ return です。 つまり、呼び出し元の関数は呼び出し先の関数の戻り値をそのまま返します。 そのため、以下の例はいずれも末尾呼び出しではありません。

     return (f(x))        -- 戻り値を1個に調節している
     return 2 * f(x)      -- 戻り値を加工している
     return x, f(x)       -- 戻り値を追加している
     f(x); return         -- 戻り値を破棄している
     return x or f(x)     -- 戻り値を1個に調節している

3.4.11 – 関数定義

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

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

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

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

以下の文は

     function f () body end

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

     f = function () body end

以下の文は

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

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

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

以下の文は

     local function f () body end

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

     local f; f = function () body end

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

     local f = function () body end

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

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

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

    parlist ::= namelist [‘,’ ‘...’] | ‘...’

関数が呼ばれると、実引数リストが仮引数リストの長さに調節されます。 ただし、その関数が可変長引数関数の場合は除きます。 可変長引数関数は仮引数リストの最後の3つのドット ('...') で表されます。 可変長引数関数では実引数リストが調節されません。 代わりに余分な引数がすべて集められ、可変長引数式としてその関数に渡されます。 可変長引数式もまた3つのドットで表されます。 この式の値は余分な実引数すべてのリストであり、複数の戻り値を持つ関数に似たものです。 可変長引数式を他の式の内部や式リストの途中で使った場合、その戻り値リストは1個の要素に調節されます。 式リストの最後の要素として使った場合、調節は行われません (その最後の式を括弧で囲った場合を除きます)。

例えば以下の定義を考えてみてください。

     function f(a, b) end
     function g(a, b, ...) end
     function r() return 1,2,3 end

この場合、実引数から仮引数と可変長引数式への対応関係は以下のようになります。

     呼び出し          仮引数

     f(3)             a=3, b=nil
     f(3, 4)          a=3, b=4
     f(3, 4, 5)       a=3, b=4
     f(r(), 10)       a=1, b=10
     f(r())           a=1, b=2

     g(3)             a=3, b=nil, ... -->  (なし)
     g(3, 4)          a=3, b=4,   ... -->  (なし)
     g(3, 4, 5, 8)    a=3, b=4,   ... -->  5  8
     g(5, r())        a=5, b=1,   ... -->  2  3

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

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

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

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

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

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

3.5 – 可視性ルール

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

     x = 10                -- グローバル変数
     do                    -- 新しいブロック
       local x = x         -- 新しい'x'、値は10
       print(x)            --> 10
       x = x+1
       do                  -- 別の新しいブロック
         local x = x+1     -- 別の新しい'x'
         print(x)          --> 12
       end
       print(x)            --> 11
     end
     print(x)              --> 10  (グローバル変数)

local x = x のような宣言の場合、右辺の x は外側の変数を参照することに注意してください。 いま宣言している新しい x はまだスコープに入っていないためです。

レキシカルスコープのルールにより、ローカル変数はそのスコープ内で定義した関数から自由にアクセスできます。 内部関数から使われるローカル変数は、その内部関数からは上位値または外部ローカル変数と言います。

local 文を実行するたびに新しいローカル変数が定義されることに注意してください。 以下の例を考えてみてください。

     a = {}
     local x = 20
     for i=1,10 do
       local y = 0
       a[i] = function () y=y+1; return x+y end
     end

このループはクロージャを10個 (つまり、無名関数のインスタンスを10個) 作成します。 これらのクロージャは、 x は同じものを共有していますが、 y はそれぞれ別々のものを持っています。

4 – API

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

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

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

4.1 – スタック

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

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

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

4.2 – スタックサイズ

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

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

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

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

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

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

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

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

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

4.4 – Cのクロージャ

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

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

4.5 – レジストリ

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

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

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

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

4.6 – Cでのエラー処理

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

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

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

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

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

4.7 – Cでのyield処理

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.8 – 関数と型

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

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

lua_absindex

[-0, +0, –]

int lua_absindex (lua_State *L, int idx);

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

lua_Alloc

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

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

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

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

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

  • LUA_TSTRING
  • LUA_TTABLE
  • LUA_TFUNCTION
  • LUA_TUSERDATA
  • LUA_TTHREAD

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

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

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

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

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

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

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

lua_arith

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

void lua_arith (lua_State *L, int op);

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

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

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

lua_atpanic

[-0, +0, –]

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

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

lua_call

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

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

関数を呼びます。

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

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

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

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

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

     lua_getglobal(L, "f");       /* 呼ぶ関数 */
     lua_pushliteral(L, "how");   /* 第1引数 */
     lua_getglobal(L, "t");       /* 検索するテーブル */
     lua_getfield(L, -1, "x");    /* t.x の結果を積む (第2引数) */
     lua_remove(L, -2);           /* 't' をスタックから削除 */
     lua_pushinteger(L, 14);      /* 第3引数 */
     lua_call(L, 3, 1);           /* 3個の引数と1個の戻り値で 'f' を呼ぶ */
     lua_setglobal(L, "a");       /* グローバル変数 'a' を設定 */

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

lua_callk

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

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

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

lua_CFunction

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

Cの関数の型です。

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

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

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

lua_checkstack

[-0, +0, –]

int lua_checkstack (lua_State *L, int n);

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

lua_close

[-0, +0, –]

void lua_close (lua_State *L);

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

lua_compare

[-0, +0, e]

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

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

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

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

lua_concat

[-n, +1, e]

void lua_concat (lua_State *L, int n);

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

lua_copy

[-0, +0, –]

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

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

lua_createtable

[-0, +1, e]

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

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

lua_dump

[-0, +0, e]

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

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

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

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

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

lua_error

[-1, +0, v]

int lua_error (lua_State *L);

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

lua_gc

[-0, +0, e]

int lua_gc (lua_State *L, int what, int data);

ガベージコレクタを制御します。

この関数は引数 what の値によっていくつかの処理を行います。

  • LUA_GCSTOP: ガベージコレクタを停止させます。
  • LUA_GCRESTART: ガベージコレクタを再開させます。
  • LUA_GCCOLLECT: 完全なガベージコレクションサイクルを実行します。
  • LUA_GCCOUNT: Luaが使用している現在のメモリ量を (キロバイト単位で) 返します。
  • LUA_GCCOUNTB: Luaが使用しているメモリの現在のバイト数を1024で割った余りを返します。
  • LUA_GCSTEP: ガベージコレクションのインクリメンタルステップをひとつ実行します。
  • LUA_GCSETPAUSE: ガベージコレクタ停止期間 (§2.5 参照) を data に変更し、以前の値を返します。
  • LUA_GCSETSTEPMUL: ガベージコレクタステップ係数 (§2.5 参照) を data に変更し、以前の値を返します。
  • LUA_GCISRUNNING: ガベージコレクタが動作中 (つまり停止中でない) かどうかを示すブーリアンを返します。

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

lua_getallocf

[-0, +0, –]

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

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

lua_getfield

[-0, +1, e]

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

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

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

lua_getextraspace

[-0, +0, –]

void *lua_getextraspace (lua_State *L);

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

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

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

lua_getglobal

[-0, +1, e]

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

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

lua_geti

[-0, +1, e]

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

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

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

lua_getmetatable

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

int lua_getmetatable (lua_State *L, int index);

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

lua_gettable

[-1, +1, e]

int lua_gettable (lua_State *L, int index);

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

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

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

lua_gettop

[-0, +0, –]

int lua_gettop (lua_State *L);

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

lua_getuservalue

[-0, +1, –]

int lua_getuservalue (lua_State *L, int index);

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

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

lua_insert

[-1, +1, –]

void lua_insert (lua_State *L, int index);

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

lua_Integer

typedef ... lua_Integer;

Luaの整数の型です。

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

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

lua_isboolean

[-0, +0, –]

int lua_isboolean (lua_State *L, int index);

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

lua_iscfunction

[-0, +0, –]

int lua_iscfunction (lua_State *L, int index);

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

lua_isfunction

[-0, +0, –]

int lua_isfunction (lua_State *L, int index);

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

lua_isinteger

[-0, +0, –]

int lua_isinteger (lua_State *L, int index);

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

lua_islightuserdata

[-0, +0, –]

int lua_islightuserdata (lua_State *L, int index);

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

lua_isnil

[-0, +0, –]

int lua_isnil (lua_State *L, int index);

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

lua_isnone

[-0, +0, –]

int lua_isnone (lua_State *L, int index);

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

lua_isnoneornil

[-0, +0, –]

int lua_isnoneornil (lua_State *L, int index);

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

lua_isnumber

[-0, +0, –]

int lua_isnumber (lua_State *L, int index);

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

lua_isstring

[-0, +0, –]

int lua_isstring (lua_State *L, int index);

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

lua_istable

[-0, +0, –]

int lua_istable (lua_State *L, int index);

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

lua_isthread

[-0, +0, –]

int lua_isthread (lua_State *L, int index);

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

lua_isuserdata

[-0, +0, –]

int lua_isuserdata (lua_State *L, int index);

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

lua_isyieldable

[-0, +0, –]

int lua_isyieldable (lua_State *L);

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

lua_KContext

typedef ... lua_KContext;

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

lua_KFunction

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

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

lua_len

[-0, +1, e]

void lua_len (lua_State *L, int index);

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

lua_load

[-0, +1, –]

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

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

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

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

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

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

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

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

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

lua_newstate

[-0, +0, –]

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

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

lua_newtable

[-0, +1, e]

void lua_newtable (lua_State *L);

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

lua_newthread

[-0, +1, e]

lua_State *lua_newthread (lua_State *L);

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

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

lua_newuserdata

[-0, +1, e]

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

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

lua_next

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

int lua_next (lua_State *L, int index);

スタックからキーを削除し、指定されたインデックスのテーブルからキーと値のペア (指定されたキーの「次の」ペア) を積みます。 テーブルにそれ以上要素がなければ (何も積まずに) 0を返します。

一般的な使い方は以下のようなものです。

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

テーブルを巡回している間、キーに対して直接 lua_tolstring を呼ばないでください (そのキーが実際に文字列であるとわかっている場合は除きます)。 lua_tolstring は指定されたインデックスの値を変更する場合があるため、次に lua_next を呼んだときに問題が生じます。

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

lua_Number

typedef ... lua_Number;

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

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

lua_numbertointeger

int lua_numbertointeger (lua_Number n, lua_Integer *p);

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

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

lua_pcall

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

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

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

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

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

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

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

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

lua_pcallk

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

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

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

lua_pop

[-n, +0, –]

void lua_pop (lua_State *L, int n);

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

lua_pushboolean

[-0, +1, –]

void lua_pushboolean (lua_State *L, int b);

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

lua_pushcclosure

[-n, +1, e]

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

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

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

n の最大値は255です。

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

lua_pushcfunction

[-0, +1, –]

void lua_pushcfunction (lua_State *L, lua_CFunction f);

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

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

lua_pushfstring

[-0, +1, e]

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

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

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

lua_pushglobaltable

[-0, +1, –]

void lua_pushglobaltable (lua_State *L);

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

lua_pushinteger

[-0, +1, –]

void lua_pushinteger (lua_State *L, lua_Integer n);

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

lua_pushlightuserdata

[-0, +1, –]

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

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

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

lua_pushliteral

[-0, +1, e]

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

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

lua_pushlstring

[-0, +1, e]

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

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

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

lua_pushnil

[-0, +1, –]

void lua_pushnil (lua_State *L);

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

lua_pushnumber

[-0, +1, –]

void lua_pushnumber (lua_State *L, lua_Number n);

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

lua_pushstring

[-0, +1, e]

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

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

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

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

lua_pushthread

[-0, +1, –]

int lua_pushthread (lua_State *L);

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

lua_pushvalue

[-0, +1, –]

void lua_pushvalue (lua_State *L, int index);

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

lua_pushvfstring

[-0, +1, e]

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

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

lua_rawequal

[-0, +0, –]

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

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

lua_rawget

[-1, +1, –]

int lua_rawget (lua_State *L, int index);

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

lua_rawgeti

[-0, +1, –]

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

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

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

lua_rawgetp

[-0, +1, –]

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

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

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

lua_rawlen

[-0, +0, –]

size_t lua_rawlen (lua_State *L, int index);

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

lua_rawset

[-2, +0, e]

void lua_rawset (lua_State *L, int index);

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

lua_rawseti

[-1, +0, e]

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

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

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

lua_rawsetp

[-1, +0, e]

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

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

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

lua_Reader

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

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

lua_register

[-0, +0, e]

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

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

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

lua_remove

[-1, +0, –]

void lua_remove (lua_State *L, int index);

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

lua_replace

[-1, +0, –]

void lua_replace (lua_State *L, int index);

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

lua_resume

[-?, +?, –]

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

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

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

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

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

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

lua_rotate

[-0, +0, –]

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

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

lua_setallocf

[-0, +0, –]

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

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

lua_setfield

[-1, +0, e]

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

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

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

lua_setglobal

[-1, +0, e]

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

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

lua_seti

[-1, +0, e]

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

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

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

lua_setmetatable

[-1, +0, –]

void lua_setmetatable (lua_State *L, int index);

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

lua_settable

[-2, +0, e]

void lua_settable (lua_State *L, int index);

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

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

lua_settop

[-?, +?, –]

void lua_settop (lua_State *L, int index);

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

lua_setuservalue

[-1, +0, –]

void lua_setuservalue (lua_State *L, int index);

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

lua_State

typedef struct lua_State lua_State;

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

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

lua_status

[-0, +0, –]

int lua_status (lua_State *L);

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

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

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

lua_stringtonumber

[-0, +1, –]

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

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

lua_toboolean

[-0, +0, –]

int lua_toboolean (lua_State *L, int index);

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

lua_tocfunction

[-0, +0, –]

lua_CFunction lua_tocfunction (lua_State *L, int index);

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

lua_tointeger

[-0, +0, –]

lua_Integer lua_tointeger (lua_State *L, int index);

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

lua_tointegerx

[-0, +0, –]

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

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

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

lua_tolstring

[-0, +0, e]

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

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

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

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

lua_tonumber

[-0, +0, –]

lua_Number lua_tonumber (lua_State *L, int index);

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

lua_tonumberx

[-0, +0, –]

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

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

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

lua_topointer

[-0, +0, –]

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

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

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

lua_tostring

[-0, +0, e]

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

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

lua_tothread

[-0, +0, –]

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

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

lua_touserdata

[-0, +0, –]

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

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

lua_type

[-0, +0, –]

int lua_type (lua_State *L, int index);

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

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

lua_typename

[-0, +0, –]

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

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

lua_Unsigned

typedef ... lua_Unsigned;

lua_Integer の符号なし版です。

lua_upvalueindex

[-0, +0, –]

int lua_upvalueindex (int i);

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

lua_version

[-0, +0, v]

const lua_Number *lua_version (lua_State *L);

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

lua_Writer

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

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

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

lua_xmove

[-?, +?, –]

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

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

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

lua_yield

[-?, +?, e]

int lua_yield (lua_State *L, int nresults);

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

lua_yieldk

[-?, +?, e]

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

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

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

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

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

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

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

Luaには組み込みのデバッグ機能がありません。 代わりに関数およびフックの形で特別なインタフェースが用意されています。 このインタフェースを使うと、デバッガやプロファイラなど、インタプリタの「内部情報」を必要とする様々な種類のツールを作ることができます。

lua_Debug

typedef struct lua_Debug {
  int event;
  const char *name;           /* (n) */
  const char *namewhat;       /* (n) */
  const char *what;           /* (S) */
  const char *source;         /* (S) */
  int currentline;            /* (l) */
  int linedefined;            /* (S) */
  int lastlinedefined;        /* (S) */
  unsigned char nups;         /* (u) number of upvalues */
  unsigned char nparams;      /* (u) number of parameters */
  char isvararg;              /* (u) */
  char istailcall;            /* (t) */
  char short_src[LUA_IDSIZE]; /* (S) */
  /* private part */
  other fields
} lua_Debug;

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

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

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

lua_gethook

[-0, +0, –]

lua_Hook lua_gethook (lua_State *L);

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

lua_gethookcount

[-0, +0, –]

int lua_gethookcount (lua_State *L);

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

lua_gethookmask

[-0, +0, –]

int lua_gethookmask (lua_State *L);

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

lua_getinfo

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

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

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

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

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

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

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

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

    このオプションがオプション 'f' と一緒に使われた場合、 このテーブルは関数の後に積まれます。

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

lua_getlocal

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

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

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

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

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

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

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

lua_getstack

[-0, +0, –]

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

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

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

lua_getupvalue

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

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

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

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

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

lua_Hook

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

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

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

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

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

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

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

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

lua_sethook

[-0, +0, –]

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

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

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

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

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

lua_setlocal

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

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

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

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

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

lua_setupvalue

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

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

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

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

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

lua_upvalueid

[-0, +0, –]

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

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

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

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

lua_upvaluejoin

[-0, +0, –]

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

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

5 – 補助ライブラリ

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

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

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

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

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

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

5.1 – 関数と型

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

luaL_addchar

[-?, +?, e]

void luaL_addchar (luaL_Buffer *B, char c);

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

luaL_addlstring

[-?, +?, e]

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

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

luaL_addsize

[-?, +?, e]

void luaL_addsize (luaL_Buffer *B, size_t n);

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

luaL_addstring

[-?, +?, e]

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

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

luaL_addvalue

[-1, +?, e]

void luaL_addvalue (luaL_Buffer *B);

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

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

luaL_argcheck

[-0, +0, v]

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

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

luaL_argerror

[-0, +0, v]

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

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

     bad argument #arg to 'funcname' (extramsg)

この関数は戻りません。

luaL_Buffer

typedef struct luaL_Buffer luaL_Buffer;

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

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

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

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

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

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

luaL_buffinit

[-0, +0, –]

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

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

luaL_buffinitsize

[-?, +?, e]

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

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

luaL_callmeta

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

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

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

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

luaL_checkany

[-0, +0, v]

void luaL_checkany (lua_State *L, int arg);

arg 番目の引数が存在するかどうか (nil を含む) を確認します。

luaL_checkinteger

[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int arg);

arg 番目の引数が整数 (または整数に変換可能な値) かどうかを確認し、その整数を lua_Integer に変換して返します。

luaL_checklstring

[-0, +0, v]

const char *luaL_checklstring (lua_State *L, int arg, size_t *l);

arg 番目の引数が文字列かどうかを確認し、その文字列を返します。 l が NULL でなければ、 *l がその文字列の長さで埋められます。

この関数は結果を取得するために lua_tolstring を使います。 そのため、その関数の変換と注意点はすべてここでも適用されます。

luaL_checknumber

[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int arg);

arg 番目の引数が数値かどうかを確認し、その数値を返します。

luaL_checkoption

[-0, +0, v]

int luaL_checkoption (lua_State *L,
                      int arg,
                      const char *def,
                      const char *const lst[]);

arg 番目の引数が文字列かどうかを確認し、その文字列を配列 lst (NULLで終わっていなければなりません) の中から探します。 その文字列が見つかれば、その配列内のインデックスを返します。 引数が文字列でないか、その文字列が見つからなければ、エラーが発生します。

def が NULL でなければ、 arg 番目の引数が存在しないときやその引数が nil のときに、デフォルト値として def が使われます。

この関数は、文字列をCのenumに対応付けるときに便利です。 (Luaのライブラリの通常の慣習では、オプションの選択に数値ではなく文字列を使います。)

luaL_checkstack

[-0, +0, v]

void luaL_checkstack (lua_State *L, int sz, const char *msg);

スタックサイズを top + sz 個分に伸ばします。 スタックをそのサイズに伸ばせない場合はエラーが発生します。 msg は、そのエラーメッセージに追加されるテキストです (追加のテキストが不要であれば NULL でも構いません)。

luaL_checkstring

[-0, +0, v]

const char *luaL_checkstring (lua_State *L, int arg);

arg 番目の引数が文字列かどうかを確認し、その文字列を返します。

この関数は結果を取得するために lua_tolstring を使います。 そのため、その関数の変換と注意点はすべてここでも適用されます。

luaL_checktype

[-0, +0, v]

void luaL_checktype (lua_State *L, int arg, int t);

arg 番目の引数が t 型かどうかを確認します。 t の型の符号化については lua_type を参照してください。

luaL_checkudata

[-0, +0, v]

void *luaL_checkudata (lua_State *L, int arg, const char *tname);

arg 番目の引数が tname 型のユーザーデータ (luaL_newmetatable を参照) かどうかを確認し、そのユーザーデータのアドレスを返します (lua_touserdata を参照)。

luaL_checkversion

[-0, +0, –]

void luaL_checkversion (lua_State *L);

呼び出しを実行しているコア、Luaステートを作成したコア、呼び出しを行ったコードがすべて同じバージョンのLuaを使用しているかどうかを確認します。 また、呼び出しを実行しているコアとLuaステートを作成したコアが、同じアドレススペースを使用しているかどうかも確認します。

luaL_dofile

[-0, +?, e]

int luaL_dofile (lua_State *L, const char *filename);

指定されたファイルをロードして実行します。 これは以下のマクロとして定義されています。

     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))

エラーがなければ偽を返し、エラーの場合は真を返します。

luaL_dostring

[-0, +?, –]

int luaL_dostring (lua_State *L, const char *str);

指定された文字列をロードして実行します。 これは以下のマクロとして定義されています。

     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))

エラーがなければ偽を返し、エラーの場合は真を返します。

luaL_error

[-0, +0, v]

int luaL_error (lua_State *L, const char *fmt, ...);

エラーを発生させます。 エラーメッセージの書式は、 fmt と追加の引数で指定されます。 これらは lua_pushfstring と同じルールに従います。 また、エラーが発生したファイル名と行番号が利用可能であれば、それらがメッセージの先頭に追加されます。

この関数は決して戻りませんが、慣例としてCの関数で return luaL_error(args) のように使います。

luaL_execresult

[-0, +3, e]

int luaL_execresult (lua_State *L, int stat);

標準ライブラリのプロセス関係の関数 (os.execute および io.close) のための戻り値を生成します。

luaL_fileresult

[-0, +(1|3), e]

int luaL_fileresult (lua_State *L, int stat, const char *fname);

標準ライブラリのファイル関係の関数 (io.open、 os.rename、 file:seek など) のための戻り値を生成します。

luaL_getmetafield

[-0, +(0|1), e]

int luaL_getmetafield (lua_State *L, int obj, const char *e);

インデックス obj のオブジェクトのメタテーブルのフィールド e をスタックに積み、その積んだ値の型を返します。 そのオブジェクトがメタテーブルを持っていないか、そのメタテーブルがそのフィールドを持っていなければ、何も積まずに LUA_TNIL を返します。

luaL_getmetatable

[-0, +1, –]

int luaL_getmetatable (lua_State *L, const char *tname);

レジストリの名前 tname に関連付けられたメタテーブル (luaL_newmetatable を参照) (その名前に関連付けられたメタテーブルがなければ nil) をスタックに積みます。 積んだ値の型を返します。

luaL_getsubtable

[-0, +1, e]

int luaL_getsubtable (lua_State *L, int idx, const char *fname);

値 t[fname] がテーブルであることを保証し、そのテーブルをスタックに積みます。 ただし t はインデックス idx の値です。 既存のテーブルが存在した場合は真を返し、新しいテーブルを作成した場合は偽を返します。

luaL_gsub

[-0, +1, e]

const char *luaL_gsub (lua_State *L,
                       const char *s,
                       const char *p,
                       const char *r);

文字列 s 内に出現する文字列 p をすべて文字列 r に置き換えた文字列を作成します。 その結果の文字列をスタックに積み、それを返します。

luaL_len

[-0, +0, e]

lua_Integer luaL_len (lua_State *L, int index);

指定されたインデックスの値の「長さ」を数値として返します。 これはLuaの '#' 演算子と同等です (§3.4.7 を参照)。 演算の結果が整数でない場合はエラーが発生します。 (これはメタメソッドが呼ばれた場合にのみ発生します。)

luaL_loadbuffer

[-0, +1, –]

int luaL_loadbuffer (lua_State *L,
                     const char *buff,
                     size_t sz,
                     const char *name);

luaL_loadbufferx の mode に NULL を渡した場合と同等です。

luaL_loadbufferx

[-0, +1, –]

int luaL_loadbufferx (lua_State *L,
                      const char *buff,
                      size_t sz,
                      const char *name,
                      const char *mode);

バッファをLuaのチャンクとしてロードします。 この関数は lua_load を使って buff が指すサイズ sz のチャンクをロードします。

この関数は lua_load と同じ結果を返します。 name はチャンクの名前で、デバッグ情報やエラーメッセージに使われます。 文字列 mode は関数 lua_load と同様です。

luaL_loadfile

[-0, +1, e]

int luaL_loadfile (lua_State *L, const char *filename);

luaL_loadfilex の mode に NULL を渡した場合と同等です。

luaL_loadfilex

[-0, +1, e]

int luaL_loadfilex (lua_State *L, const char *filename,
                                            const char *mode);

ファイルをLuaのチャンクとしてロードします。 この関数は lua_load を使って filename という名前のファイルからチャンクをロードします。 filename が NULL の場合は標準入力からロードされます。 ファイルの最初の行が # で始まっている場合、 その行は無視されます。

文字列 mode は関数 lua_load と同様です。

この関数は lua_load と同じ結果を返しますが、ファイルを開けなかったり読み込めなかった場合は追加のエラーコード LUA_ERRFILE を返します。

lua_load と同様に、この関数はチャンクをロードするだけです。 実行はしません。

luaL_loadstring

[-0, +1, –]

int luaL_loadstring (lua_State *L, const char *s);

文字列をLuaのチャンクとしてロードします。 この関数は lua_load を使ってゼロ終端文字列 s からチャンクをロードします。

この関数は lua_load と同じ結果を返します。

lua_load と同様に、この関数はチャンクをロードするだけです。 実行はしません。

luaL_newlib

[-0, +1, e]

void luaL_newlib (lua_State *L, const luaL_Reg l[]);

新しいテーブルを作成し、リスト l の関数をそこに登録します。

これは以下のようなマクロとして実装されています。

     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))

配列 l はポインタではなく、実際の配列でなければなりません。

luaL_newlibtable

[-0, +1, e]

void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);

配列 l のすべてのエントリを格納するのに適したサイズの新しいテーブルを作成します。 (しかし実際にそれらを格納はしません。) これは luaL_setfuncs と共に使われることを意図しています (luaL_newlib を参照)。

これはマクロとして実装されています。 配列 l はポインタではなく、実際の配列でなければなりません。

luaL_newmetatable

[-0, +1, e]

int luaL_newmetatable (lua_State *L, const char *tname);

レジストリにキー tname がすでにあれば0を返します。 そうでなければ、ユーザーデータ用のメタテーブルとして使われる新しいテーブルを作成し、ペア __name = tname をこの新しいテーブルに追加し、ペア [tname] = 新しいテーブル をレジストリに追加し、1を返します。 (エントリ __name はエラー報告関数のいくつかで使われます。)

どちらの場合でも、レジストリの tname に関連付けられた最終的な値がスタックに積まれます。

luaL_newstate

[-0, +0, –]

lua_State *luaL_newstate (void);

Luaのステートを作成します。 標準規格のCの realloc 関数をベースとしたアロケータを渡して lua_newstate を呼びます。 また、致命的なエラーが発生した場合にエラーメッセージを標準エラー出力に表示するパニック関数 (§4.6 を参照) を設定します。

新しいステートを返します。 メモリ確保エラーが発生した場合は NULL を返します。

luaL_openlibs

[-0, +0, e]

void luaL_openlibs (lua_State *L);

すべての標準Luaライブラリを指定されたステートにオープンします。

luaL_optinteger

[-0, +0, v]

lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);

arg 番目の引数が整数 (または整数に変換可能) であれば、その整数を返します。 その引数が存在しないか nil であれば d を返します。 どちらでもなければエラーが発生します。

luaL_optlstring

[-0, +0, v]

const char *luaL_optlstring (lua_State *L,
                             int arg,
                             const char *d,
                             size_t *l);

arg 番目の引数が文字列であれば、その文字列を返します。 その引数が存在しないか nil であれば d を返します。 どちらでもなければエラーが発生します。

l が NULL でなければ、 *l に結果の長さが格納されます。

luaL_optnumber

[-0, +0, v]

lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);

arg 番目の引数が数値であれば、その数値を返します。 その引数が存在しないか nil であれば d を返します。 どちらでもなければエラーが発生します。

luaL_optstring

[-0, +0, v]

const char *luaL_optstring (lua_State *L,
                            int arg,
                            const char *d);

arg 番目の引数が文字列であれば、その文字列を返します。 その引数が存在しないか nil であれば d を返します。 どちらでもなければエラーが発生します。

luaL_prepbuffer

[-?, +?, e]

char *luaL_prepbuffer (luaL_Buffer *B);

luaL_prepbuffsize に定義済みのサイズ LUAL_BUFFERSIZE を渡した場合と同等です。

luaL_prepbuffsize

[-?, +?, e]

char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);

バッファ B に追加したい文字列をコピーすることのできる、サイズ sz の領域のアドレスを返します (luaL_Buffer を参照)。 文字列をこの領域にコピーした後、実際にバッファに追加する文字列のサイズを引数に luaL_addsize を呼ばなければなりません。

luaL_pushresult

[-?, +1, e]

void luaL_pushresult (luaL_Buffer *B);

バッファ B の使用を終了し、最終的な文字列をスタックトップに置きます。

luaL_pushresultsize

[-?, +1, e]

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);

luaL_addsize を呼んだ後に luaL_pushresult を呼ぶのと同等です。

luaL_ref

[-1, +0, e]

int luaL_ref (lua_State *L, int t);

スタックトップのオブジェクトに対するリファレンスを、インデックス t のテーブルに作成して返します。 (オブジェクトはスタックから削除されます。)

リファレンスは一意な整数のキーです。 テーブル t に手動で整数キーを追加しない限り、返されるキーの一意性が保証されます。 lua_rawgeti(L, t, r) を呼ぶと、リファレンス r の参照するオブジェクトを取得できます。 関数 luaL_unref を呼ぶと、リファレンスとそれに関連付けられたオブジェクトを解放できます。

スタックトップのオブジェクトが nil の場合は、定数 LUA_REFNIL を返します。 定数 LUA_NOREF は、 luaL_ref が返すいかなるリファレンスとも異なることが保証されています。

luaL_Reg

typedef struct luaL_Reg {
  const char *name;
  lua_CFunction func;
} luaL_Reg;

luaL_setfuncs で登録する関数配列の型です。 name は関数の名前で、 func は関数へのポインタです。 luaL_Reg の配列は最後に必ず番兵エントリを置かなければなりません。 番兵エントリは name と func が両方とも NULL のエントリです。

luaL_requiref

[-0, +1, e]

void luaL_requiref (lua_State *L, const char *modname,
                    lua_CFunction openf, int glb);

modname が package.loaded にまだ存在しなければ、 require を通して呼ばれたかのように文字列 modname を引数として関数 openf を呼び、 package.loaded[modname] にその呼び出しの結果を設定します。

glb が真であれば、グローバル変数 modname にもそのモジュールが格納されます。

そのモジュールをスタックに置きます。

luaL_setfuncs

[-nup, +0, e]

void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);

配列 l (luaL_Reg を参照) のすべての関数を、スタックトップのテーブル (ただし上位値がある場合はその下です。下記参照) に登録します。

nup がゼロでなければ、すべての関数は nup 個の上位値を共有した状態で作成されます。 これらの上位値は事前にライブラリテーブルの上に積んでおかなければならず、登録後にスタックから削除されます。

luaL_setmetatable

[-0, +0, –]

void luaL_setmetatable (lua_State *L, const char *tname);

スタックトップのオブジェクトのメタテーブルを、レジストリの名前 tname に関連付けられたメタテーブルとして設定します。 (luaL_newmetatable を参照)。

luaL_Stream

typedef struct luaL_Stream {
  FILE *f;
  lua_CFunction closef;
} luaL_Stream;

標準入出力ライブラリで使われるファイルハンドルの標準的な表現です。

ファイルハンドルは LUA_FILEHANDLE という名前のメタテーブルを持つフルユーザーデータとして実装されています (LUA_FILEHANDLE は実際のメタテーブルの名前に展開されるマクロです)。 このメタテーブルは入出力ライブラリによって作成されます (luaL_newmetatable を参照)。

このユーザーデータは先頭に構造体 luaL_Stream が存在しなければなりません。 この最初の構造体の後には任意のデータを持つことができます。 フィールド f は対応するCのストリームです (不完全に作成されたハンドルを表すために NULL になる場合もあります)。 フィールド closef は、ハンドルが閉じられたか回収されたときにストリームを閉じるために呼ばれる、Luaの関数を指します。 この関数は唯一の引数としてファイルハンドルを取り、 true (成功の場合) または nil とエラーメッセージ (エラーの場合) を返さなければなりません。 ひとたびこのフィールドが呼ばれると、ハンドルが閉じられたことを表すため、このフィールドの値は NULL に変更されます。

luaL_testudata

[-0, +0, e]

void *luaL_testudata (lua_State *L, int arg, const char *tname);

この関数は luaL_checkudata と同様に動作します。 ただしチェックが失敗した場合は、エラーを発生させる代わりに NULL を返します。

luaL_tolstring

[-0, +1, e]

const char *luaL_tolstring (lua_State *L, int idx, size_t *len);

指定されたインデックスの任意のLuaの値を、適当な書式でCの文字列に変換します。 結果の文字列はスタックに積まれ、また戻り値としても返されます。 len が NULL でなければ、 *len にその文字列の長さが設定されます。

その値に "__tostring" フィールドを持つメタテーブルがある場合は、その値を引数として対応するメタメソッドが呼ばれ、その呼び出しの戻り値が結果として使われます。

luaL_traceback

[-0, +1, e]

void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
                     int level);

L1 のスタックトレースを作成して積みます。 msg が NULL でなければ、スタックトレースの先頭にそれが追加されます。 level 引数はスタックトレースを開始するレベルを指定します。

luaL_typename

[-0, +0, –]

const char *luaL_typename (lua_State *L, int index);

指定されたインデックスの値の型の名前を返します。

luaL_unref

[-0, +0, –]

void luaL_unref (lua_State *L, int t, int ref);

インデックス t のテーブルからリファレンス ref を解放します (luaL_ref を参照)。 対応するエントリがテーブルから削除され、参照されていたオブジェクトが回収可能になります。 リファレンス ref もまた、後の再利用のために解放されます。

ref が LUA_NOREF または LUA_REFNIL の場合は、何もしません。

luaL_where

[-0, +1, e]

void luaL_where (lua_State *L, int lvl);

コールスタックのレベル lvl の現在の実行位置を表す文字列をスタックに積みます。 通常、この文字列は以下のような書式です。

     チャンクの名前:現在の行:

レベル0は実行中の関数、レベル1は実行中の関数の呼び出し元の関数以下同様です。

この関数はエラーメッセージのプレフィックスを作成するために使われます。

6 – 標準ライブラリ

標準LuaライブラリはCのAPIを通して直接実装できる便利な関数を提供しています。 これらの関数の中には、基本的な言語機能を提供しているもの (例えば type や getmetatable)、 「外部」のサービスへのアクセスを提供しているもの (例えば入出力)、Lua自身で実装可能だけれども非常に便利であるとか重大な性能上の要件のためにCで実装する価値のあるもの (例えば table.sort) などがあります。

すべてのライブラリは公式のCのAPIを使って実装されており、本体とは別のCのモジュールとして提供されています。 現在Luaには以下の標準ライブラリがあります。

  • 基本ライブラリ (§6.1);
  • コルーチンライブラリ (§6.2);
  • パッケージライブラリ (§6.3);
  • 文字列操作 (§6.4);
  • 基本的なUTF-8のサポート (§6.5);
  • テーブル操作 (§6.6);
  • 数学関数 (§6.7) (sin, log, etc.);
  • 入出力 (§6.8);
  • OS機能 (§6.9);
  • デバッグ機能 (§6.10).

基本ライブラリとパッケージライブラリを除き、各ライブラリのすべての機能はグローバルテーブルのフィールドとして、またはオブジェクトのメソッドとして提供されます。

これらのライブラリにアクセスするには、 luaL_openlibs 関数をCのホストプログラムから呼んでください。 これによりすべての標準ライブラリがオープンされます。 別の方法として、 luaL_requiref を使って以下の関数を呼ぶことで、個別にオープンすることもできます。

  • luaopen_base: 基本ライブラリ
  • luaopen_package: パッケージライブラリ
  • luaopen_coroutine: コルーチンライブラリ
  • luaopen_string: 文字列ライブラリ
  • luaopen_utf8: UTF8ライブラリ
  • luaopen_table: テーブルライブラリ
  • luaopen_math: 数学ライブラリ
  • luaopen_io: 入出力ライブラリ
  • luaopen_os: OSライブラリ
  • luaopen_debug: デバッグライブラリ

これらの関数は lualib.h で宣言されています。

6.1 – 基本機能

基本ライブラリはLuaの中核的な機能を提供します。 アプリケーションにこのライブラリを含めない場合は、これらの機能の代替品を用意する必要がないか、慎重に検討してください。

assert (v [, message])

引数 v の値が偽 (つまり nil または false) であれば error を呼びます。 そうでなければその引数をすべて返します。 エラーの場合、 message はエラーオブジェクトです。 指定しなかった場合はデフォルトの "assertion failed!" が使われます。

collectgarbage ([opt [, arg]])

この関数はガベージコレクタへの汎用インタフェースです。 第1引数 opt によって様々な機能を実行します。

  • "collect": 完全なガベージコレクションサイクルを実行します。 これはデフォルトのオプションです。
  • "stop": ガベージコレクタの自動実行を停止します。 自動実行を再開するまでの間、ガベージコレクタは明示的に呼び出された場合にのみ動作します。
  • "restart": ガベージコレクタの自動実行を再開します。
  • "count": Luaが使用している合計メモリをキロバイト単位で返します。 この値には小数部があるので、1024を掛けるとLuaが使用している正確なバイト数になります (オーバーフローした場合を除く)。
  • "step": ガベージコレクションのステップを実行します。 arg によってそのステップの「サイズ」を制御できます。 ゼロの場合、コレクタは基本的な (分割不可能な) ステップをひとつ実行します。 ゼロ以外の場合、コレクタはその量のメモリ (キロバイト単位) の確保を行ったかのように動作します。 そのステップでコレクションサイクルが完了した場合は true を返します。
  • "setpause": arg をコレクタの停止値 (§2.5 を参照) の新しい値として設定します。 停止値の以前の値を返します。
  • "setstepmul": arg をコレクタのステップ係数 (§2.5 を参照) の新しい値として設定します。 ステップ係数の以前の値を返します。
  • "isrunning": コレクタが実行中 (つまり停止していない) かどうかを表すブーリアン値を返します。

dofile ([filename])

指定された名前のファイルを開き、その内容をLuaのチャンクとして実行します。 引数なしで呼んだ場合は標準入力 (stdin) の内容を実行します。 チャンクから返されたすべての値を返します。 エラーの場合は呼び出し元にエラーを伝播させます (つまり保護モードで実行しません)。

error (message [, level])

最後の保護された関数呼び出しを終了し、 message をエラーオブジェクトとして返します。 関数 error は決して戻りません。

メッセージが文字列の場合は、通常、そのメッセージの先頭に、エラー位置に関する情報が追加されます。 level 引数は、そのエラー位置の取得方法を指定します。 レベル1 (デフォルト) の場合、エラー位置は error 関数の呼び出し元で、 レベル2は error の呼び出し元の呼び出し元を指し、以下同様です。 レベル0を指定すると、エラー位置に関する情報をメッセージに追加しません。

_G

グローバル環境 (§2.2 を参照) を保持するグローバル変数です (関数ではありません)。 Lua自身はこの変数を使用しません。 この値を変更しても環境には影響しませんし、逆も同様です。

getmetatable (object)

object にメタテーブルがなければ nil を返します。 そうでなく、そのオブジェクトのメタテーブルに "__metatable" フィールドがあれば、それに関連付けられた値を返します。 いずれでもなければ、指定されたオブジェクトのメタテーブルを返します。

ipairs (t)

以下の構文

     for i,v in ipairs(t) do body end

でキーと値のペア (1,t[1])、(2,t[2])、··· を最初のnil値まで巡回できるような3つの値 (イテレータ関数、テーブル t、0) を返します。

load (chunk [, chunkname [, mode [, env]]])

チャンクをロードします。

chunk が文字列であれば、チャンクはその文字列です。 chunk が関数であれば、チャンク片を取得するためにその関数が繰り返し呼ばれます。 chunk は呼ばれるたびに文字列を返さなければなりません。 この文字列は前回の戻り値と連結されます。 空文字列または nil を返すか、何も返さなければ、チャンクの終わりになります。

構文エラーがなければ、コンパイルされたチャンクが関数として返されます。 そうでなければ、 nil とエラーメッセージが返されます。

結果の関数に上位値がある場合、最初の上位値は env が指定されていればその値に、そうでなければグローバル環境に設定されます。 残りの上位値は nil に初期化されます。 (メインチャンクをロードした場合、結果の関数は必ず、ちょうど1個の上位値として _ENV 変数を持ちます (§2.2 を参照)。 しかし、関数から作成したバイナリチャンク (string.dump を参照) をロードした場合、結果の関数は任意の個数の上位値を持っている場合があります。) すべての上位値は新しく確保されます。 つまり他のいかなる関数とも共有されていません。

chunkname はエラーメッセージやデバッグ情報で使われるチャンクの名前です (§4.9 を参照)。 指定しなかった場合、 chunk が文字列であればデフォルトで chunk になり、そうでなければ "=(load)" になります。

文字列 mode は、テキストまたはバイナリ (コンパイル済みチャンク) いずれのチャンクを許可するかを制御します。 以下の文字列のいずれかを指定できます。

  • "b": バイナリチャンクのみ
  • "t": テキストチャンクのみ
  • "bt": バイナリとテキスト両方
デフォルトは "bt" です。

バイナリチャンクの一貫性はチェックされません。 悪意を持って作られたバイナリチャンクはインタプリタをクラッシュさせる可能性があります。

loadfile ([filename [, mode [, env]]])

load に似ていますが、チャンクをファイル filename から取得します。 ファイル名を指定しなかった場合は標準入力から取得します。

next (table [, index])

テーブルのすべてのフィールドを巡回します。 第1引数はテーブルで、第2引数はそのテーブルのインデックスです。 next は、そのテーブルの次のインデックスと、それに関連付けられた値を返します。 第2引数に nil を指定して呼ぶと、最初のインデックスと、それに関連付けられた値を返します。 最後のインデックスを指定して呼ぶか、空のテーブルに nil を指定して呼ぶと、 nil を返します。 第2引数を指定しなかった場合は、 nil を指定したものと解釈されます。 例えば、 next(t) でテーブルが空かどうかを調べることができます。

インデックスが列挙される順番は決まっていません。 これは数値のインデックスに対しても同様です。 (テーブルを数値順に巡回したい場合は数値用の for を使ってください。)

巡回の途中でテーブル中の元々存在しなかったフィールドに値を代入した場合、 next の動作は未定義です。 しかし既存のフィールドは変更しても構いません。 また既存のフィールドを削除しても構いません。

pairs (t)

t にメタメソッド __pairs があれば、 t を引数としてそれを呼び、その呼び出しの最初の3つの戻り値を返します。

そうでなければ、 next 関数、テーブル t、 nil の3つの値を返します。 そのため、以下の構文

     for k,v in pairs(t) do body end

でテーブル t のすべてのキーと値のペアを巡回できます。

巡回中にテーブルを変更する際の注意点については、関数 next を参照してください。

pcall (f [, arg1, ···])

指定された引数を渡して関数 f を保護モードで呼びます。 つまり f の内部で発生したいかなるエラーも伝播されないという意味です。 代わりに pcall がエラーをキャッチし、ステータスコードを返します。 最初の戻り値はステータスコード (ブーリアン) で、呼び出しがエラーなく成功した場合は真になります。 この場合、その最初の戻り値の後に、その呼び出しからの戻り値もすべて返されます。 エラーが発生した場合は false とエラーメッセージを返します。

print (···)

任意の個数の引数を受け取り、 tostring を使って各引数を文字列に変換し、それらの値を stdout に表示します。 この関数は書式化出力を意図していません。 例えばデバッグ用に、値を表示するための簡単な方法として用意されているだけです。 出力を完全に制御したい場合は string.format および io.write を使ってください。

rawequal (v1, v2)

メタメソッドを呼ばずに、 v1 と v2 が等しいかどうかを確認します。 ブーリアンを返します。

rawget (table, index)

メタメソッドを呼ばずに、 table[index] の実際の値を取得します。 table はテーブルでなければなりません。 index は任意の値を指定できます。

rawlen (v)

メタメソッドを呼ばずに、オブジェクト v の長さを返します。 v はテーブルか文字列でなければなりません。 整数を返します。

rawset (table, index, value)

メタメソッドを呼ばずに、 table[index] の実際の値を value に設定します。 table はテーブルでなければなりません。 index は nil とNaN以外の任意の値を指定できます。 value は任意のLuaの値を指定できます。

この関数は table を返します。

select (index, ···)

index が数値の場合、 index 番目以降の引数をすべて返します。 負の数値の場合は最後から数えます (-1が最後の引数です)。 そうでなければ、 index は文字列 "#" でなければならず、渡された追加の引数の合計個数を返します。

setmetatable (table, metatable)

指定されたテーブルのメタテーブルを設定します。 (それ以外の型のメタテーブルをLuaから変更することはできません。 Cからのみできます。) metatable が nil の場合、指定されたテーブルのメタテーブルは削除されます。 元のメタテーブルに "__metatable" フィールドがある場合はエラーが発生します。

この関数は table を返します。

tonumber (e [, base])

base を指定せずに呼ぶと、引数を数値に変換しようと試みます。 その引数がすでに数値であるか、数値に変換可能な文字列であれば、その数値を返します。 そうでなければ nil を返します。

文字列の変換結果はLuaの字句規約 (§3.1 を参照) に従って整数か浮動小数点数になります。 (文字列の前後に空白があってもよく、符号が付いていても構いません。)

base を指定して呼んだ場合、 e はその基数で整数値として解釈可能な文字列でなければなりません。 基数には2から36までの任意の整数を指定できます。 10より大きな基数の場合は、 'A' (大文字でも小文字でも構いません) が10を表し、 'B' が11を表し、以下同様で、 'Z' が35を表します。 文字列 e が、指定された基数で有効な数値でない場合は、 nil を返します。

tostring (v)

任意の型の値を受け取り、それを人間が読める形式の文字列に変換します。 (数値の変換方法を完全に制御したい場合は string.format を使ってください。)

v のメタテーブルに "__tostring" フィールドがあれば、 v を引数としてその対応する値を呼び、その呼び出しの戻り値が結果として使われます。

type (v)

引数の型を文字列として返します。 戻り値は以下のいずれかになります。
  • "nil" (という文字列、 nil 値ではなく)
  • "number"
  • "string"
  • "boolean"
  • "table"
  • "function"
  • "thread"
  • "userdata"

_VERSION

現在のインタプリタのバージョン文字列を保持しているグローバル変数です (関数ではありません)。 この変数の現在の値は "Lua 5.3" です。

xpcall (f, msgh [, arg1, ···])

pcall に似ていますが、新しいメッセージハンドラに msgh を設定します。

6.2 – コルーチン操作

このライブラリはコルーチンを操作する関数から構成されます。 このライブラリの関数はすべてテーブル coroutine の中に提供されます。 コルーチンの一般的な説明は §2.6 を参照してください。

coroutine.create (f)

f を本体に持つ新しいコルーチンを作成します。 f は関数でなければなりません。 その新しいコルーチンであるスレッド型のオブジェクトを返します。

coroutine.isyieldable ()

実行中のコルーチンがyield可能であれば真を返します。

実行中のコルーチンがメインスレッドでなく、yield可能でないCの関数の内部でなければ、そのコルーチンはyield可能です。

coroutine.resume (co [, val1, ···])

コルーチン co の実行を開始または続行します。 最初にコルーチンをresumeしたとき、その本体の実行が開始されます。 値 val1、··· は、その本体関数に引数として渡されます。 そのコルーチンがyieldされていた場合は、それを再開します。 値 val1、··· は、yieldからの戻り値として渡されます。

コルーチンをエラーなく実行できた場合は、 true に加え、 yield に渡されたあらゆる値 (コルーチンをyieldした場合) または本体関数から返されたあらゆる値 (コルーチンを終了した場合) を返します。 エラーが発生した場合は false とエラーメッセージを返します。

coroutine.running ()

実行中のコルーチンとブーリアンを返します。 このブーリアンは、そのコルーチンがメインスレッドであれば真です。

coroutine.status (co)

コルーチン co の状態を文字列として返します。

  • "running": コルーチンは実行中 (つまり呼び出し元のコルーチン) である。
  • "suspended": コルーチンは yield の呼び出しで中断されているか、 まだ実行開始していない。
  • "normal": コルーチンはアクティブであるが、実行中ではない (つまり他のコルーチンを resume した)。
  • "dead": コルーチンは本体関数を終了したか、エラーで停止した。

coroutine.wrap (f)

f を本体に持つ新しいコルーチンを作成します。 f は関数でなければなりません。 呼ばれるたびにそのコルーチンをresumeする関数を返します。 この関数に渡したあらゆる引数は、 resume に追加の引数として渡したのと同様の動作をします。 最初のブーリアンを除き、 resume から返されるものと同じ値を返します。 エラーが発生した場合は、そのエラーを伝播します。

coroutine.yield (···)

呼び出し元のコルーチンの実行を中断します。 yield に渡したあらゆる引数は、 resume に追加の戻り値として渡されます。

6.3 – モジュール

パッケージライブラリはLuaのモジュールをロードするための基本的な機能を提供します。 関数 require はグローバル環境に直接エクスポートされます。 それ以外のものはすべてテーブル package の中にエクスポートされます。

require (modname)

指定されたモジュールをロードします。 まず、 modname がすでにロード済みかどうかを確認するために、テーブル package.loaded が調べられます。 もしロード済みであれば、 package.loaded[modname] に格納されている値が返されます。 そうでなければ、そのモジュールのためにローダーの検索が試みられます。

ローダーを検索するにあたって、シーケンス package.searchers がガイドとして用いられます。 このシーケンスを変更すると、モジュールの検索方法を変えることができます。 以下の説明は package.searchers のデフォルトの設定に基づくものです。

まず package.preload[modname] が検索されます。 この値が存在すれば、その値 (関数でなければなりません) がローダーになります。 そうでなければ、 package.path に格納されているパスを使うLuaのローダーが検索されます。 それでも見つからなければ、 package.cpath に格納されているパスを使うCのローダーが検索されます。 それでも見つからなければ、オールインワンローダー (package.searchers を参照) が試みられます。

ローダーが見つかると、そのローダーに2個の引数、 modname と、そのローダーをどのように取得したかに依存する追加の値が渡されます。 (ローダーがファイル由来の場合、追加の引数はそのファイル名になります。) そのローダーがnilでない値を返すと、その返された値が package.loaded[modname] に代入されます。 ローダーがnilでない値を返さず、 package.loaded[modname] に何の値も代入しなかった場合は、そのエントリに true が代入されます。 いずれの場合も、 package.loaded[modname] の最終的な値が require から返されます。

モジュールのロード中または実行中に何らかのエラーが発生したか、そのモジュールのローダーを見つけることができなかった場合、 require はエラーを発生させます。

package.config

パッケージのコンパイル時設定を記述した文字列です。 この文字列は以下の行の並びです。

  • 1行目はディレクトリ区切り文字列です。 デフォルトはWindowsでは '\' で、それ以外のすべてのシステムでは '/' です。
  • 2行目はパス中のテンプレートを区切る文字です。 デフォルトは ';' です。
  • 3行目はテンプレート中の置換点を示す文字列です。 デフォルトは '?' です。
  • 4行目はWindowsのパス中の、実行可能ファイルのディレクトリに置換される文字列です。 デフォルトは '!' です。
  • 5行目は luaopen_ 関数の名前を作成するときに、その後のテキストをすべて無視する印です。 デフォルトは '-' です。

package.cpath

Cのローダーを検索するために require で使われるパスです。

Cのパス package.cpath は、環境変数 LUA_CPATH_5_3 または環境変数 LUA_CPATH または luaconf.h で定義されているデフォルトのパスを使って、Luaのパス package.path が初期化されるのと同じ方法で初期化されます。

package.loaded

モジュールがすでにロード済みかどうかを制御するために require で使われるテーブルです。 モジュール modname をrequireしたとき、 package.loaded[modname] が偽でなければ、 require は単にそこに格納されている値を返します。

この変数は実際のテーブルへの参照にすぎません。 この変数に代入しても require で使われるテーブルは変わりません。

package.loadlib (libname, funcname)

Cのライブラリ libname をダイナミックリンクします。

funcname が "*" であれば、そのライブラリをリンクし、そのライブラリがエクスポートしているシンボルを他のダイナミックリンクライブラリから利用できるようにだけします。 そうでなければ、そのライブラリ内の関数 funcname を検索し、その関数をCの関数として返します。 そのため、 funcname は lua_CFunction のプロトタイプに従わなければなりません。 (lua_CFunction を参照)。

これは低水準の関数です。 パッケージシステムやモジュールシステムを完全に迂回します。 require と異なり、パスを検索することもなく、拡張子を自動的に追加することもありません。 libname Cのライブラリの完全なファイル名でなければならず、必要であればパスや拡張子も含めなければなりません。 funcname はそのCのライブラリがエクスポートしている正確な名前でなければなりません (使用したCコンパイラやリンカに依存します)。

この機能は標準規格のCではサポートされていません。 そのため一部のプラットフォーム (Windows、Linux、Mac OS X、Solaris、BSD、および dlfcn 標準をサポートしている各種Unixシステム) でのみ利用可能です。

package.path

Luaのローダーを検索するために require で使われるパスです。

この変数はスタートアップ時に環境変数 LUA_PATH_5_3 または環境変数 LUA_PATH の値、またはそれらの環境変数が定義されていない場合は luaconf.h に定義されているデフォルトのパスに初期化されます。 環境変数の値の中の ";;" は (もしあれば) デフォルトのパスに置換されます。

package.preload

特定のモジュール用のローダーを格納するテーブルです (require を参照)。

この変数は実際のテーブルへの参照にすぎません。 この変数に代入しても require で使われるテーブルは変わりません。

package.searchers

モジュールのロード方法を制御するために require で使われるテーブルです。

このテーブルの各エントリは検索関数です。 モジュールを検索するとき、モジュール名 (require に渡した引数) を唯一の引数としてこれらの各検索関数が昇順で呼ばれます。 この関数は、別の関数 (モジュールローダー) と、そのローダーに渡す追加の値を返すことができます。 あるいは、モジュールが見つからなかった理由を表す文字列 (あるいは何も言うべきことがなければ nil) を返すこともできます。

このテーブルは4個の検索関数で初期化されます。

1番目の検索関数は単純に package.preload テーブルからローダーを検索します。

2番目の検索関数は package.path に格納されているパスを使ってLuaのライブラリとしてローダーを検索します。 検索は関数 package.searchpath で説明されているように行われます。

3番目の検索関数は変数 package.cpath で指定されたパスを使ってCのライブラリとしてローダーを検索します。 これも同様に、検索は関数 package.searchpath で説明されているように行われます。 例えばCのパスが以下の文字列である場合、

     "./?.so;./?.dll;/usr/local/?/init.so"

モジュール foo の検索は、ファイル ./foo.so、 ./foo.dll、 /usr/local/foo/init.so を、この順番で、開けるかどうか試します。 Cのライブラリが見つかったなら、ダイナミックリンクの機能を使ってそのライブラリをリンクします。 次に、ローダーとして使えるCの関数をそのライブラリ内から検索します。 Cの関数の名前は、文字列 "luaopen_" と、モジュール名のドットをアンダースコアで置換した文字列を連結したものです。 さらにモジュール名にハイフンが含まれている場合、最初のハイフンとその後の接尾辞は削除されます。 例えばモジュール名が a.b.c-v2.1 の場合、関数名は luaopen_a_b_c になります。

4番目の検索関数はオールインワンローダーを試みます。 指定されたモジュールのルート名に対してCのパスからライブラリを検索します。 例えば a.b.c をrequireすると、 a というCのライブラリが検索されます。 見つかれば、そのサブモジュールに対するオープン関数がライブラリ内から検索されます。 先程の例では luaopen_a_b_c になります。 この機能により、複数のCのサブモジュールを、各サブモジュールの元々のオープン関数を保ったまま、ひとつのライブラリにパッケージ化できます。

1番目 (preload) 以外のすべての検索関数は、 package.searchpath から返されるのと同様に、モジュールが見つかったファイル名を追加の値として返します。 1番目の検索関数は追加の値を返しません。

package.searchpath (name, path [, sep [, rep]])

指定された path から指定された name を検索します。

パスは一連のテンプレートをセミコロンで区切った文字列です。 各テンプレートに対して、テンプレート中の疑問符 (もしあれば) が name に置換され、 sep (デフォルトはドット) がすべて rep (デフォルトではシステムのディレクトリ区切り文字) に置換され、結果のファイル名が開けるかどうか試みられます。

例えばパスが以下の文字列の場合、

     "./?.lua;./?.lc;/usr/local/?/init.lua"

名前 foo.a を検索すると、ファイル ./foo/a.lua、 ./foo/a.lc、 /usr/local/foo/a/init.lua が、この順番で、開けるかどうか試みられます。

読み込みモードで開くことができた最初のファイル名を返します。 開けるファイルが無かった場合は、 nil とエラーメッセージを返します。 (このエラーメッセージには開けるかどうか試みられたすべてのファイル名が記載されます。)

6.4 – 文字列操作

このライブラリは部分文字列の検索、部分文字列の抽出、パターンマッチングなど、文字列操作のための汎用的な機能を提供しています。 Luaでは文字列中のインデックスを指定するとき、最初の文字が1の位置です (Cのように0ではありません)。 インデックスには負の値を指定することもでき、文字列の終わりから逆方向のインデックスとして解釈されます。 つまり最後の文字は-1の位置で、以下同様です。

文字列ライブラリの関数はすべてテーブル string の中に提供されます。 また文字列に対するメタテーブルも設定されます。 このメタテーブルは __index フィールドを持ち、 string テーブルを指します。 そのため文字列関数をオブジェクト指向スタイルで使うこともできます。 例えば string.byte(s,i) は s:byte(i) と書くこともできます。

文字列ライブラリでは1バイト文字のエンコーディングが想定されています。

string.byte (s [, i [, j]])

文字 s[i]、s[i+1]、...、s[j] の内部的な文字コードの数値を返します。 i のデフォルト値は1で、 j のデフォルト値は i です。 これらのインデックスは関数 string.sub と同じルールに従って修正されます。

文字コードの数値は異なるプラットフォームへの移植性が保証されていません。

string.char (···)

ゼロ個以上の整数を受け取り、引数の個数と同じ長さの文字列を返します。 この文字列中の各文字は、対応する引数に等しい内部的な文字コードの数値を持ちます。

文字コードの数値は異なるプラットフォームへの移植性が保証されていません。

string.dump (function [, strip])

指定された関数のバイナリ表現 (バイナリチャンク) を含む文字列を返します。 後にこの文字列を load に渡すと、その関数のコピーを作成できます (ただし上位値は新しいものになります)。 strip が真の値の場合は、空間を節約するため、その関数に関するすべてのデバッグ情報が含まれない場合があります。

上位値を持つ関数は、上位値の個数だけが保存されます。 (再) ロードされたとき、それらの上位値には新しいインスタンスが作成され、 nil に初期化されます。 (デバッグライブラリを使用し、関数の上位値を必要に応じて自分で保存、再ロードすることはできます。)

string.find (s, pattern [, init [, plain]])

文字列 s から pattern (§6.4.1 を参照) の最初のマッチを検索します。 マッチが見つかれば、その開始位置と終了位置を示す s のインデックスを返します。 見つからなければ nil を返します。 省略可能な第3引数 init は検索の開始位置を指定する数値です。 デフォルト値は1で、負の値も指定できます。 省略可能な第4引数 plain は、 true の値を指定するとパターンマッチの機能が無効化され、 pattern のどの文字も魔法扱いしない、ただの「部分文字列検索」処理になります。 plain を指定するときは init も指定しなければならないことに注意してください。

パターンにキャプチャがある場合は、マッチが成功すると、2つのインデックスの後にキャプチャした値も返されます。

string.format (formatstring, ···)

最初の引数 (文字列でなければなりません) で指定された記述に従い、可変長引数を書式化して返します。 書式文字列はISO Cの関数 sprintf と同じルールに従います。 ただしオプションおよび修飾子 *、 h、 L、 l、 n、 p はサポートされず、 追加のオプション q があるという点が異なります。 q オプションは二重引用符で囲った文字列を書式化します。 このとき、Luaインタプリタで安全に読み戻せることを保証するために、必要に応じてエスケープシーケンスが使われます。 例えば以下の呼び出しは

     string.format('%q', 'a string with "quotes" and \n new line')

以下の文字列を生成します。

     "a string with \"quotes\" and \
      new line"

オプション A、 a、 E、 e、 f、 G、 g はすべて引数として数値を期待します。 オプション c、 d、 i、 o、 u、 X、 x は整数を期待します。 オプション q は文字列を期待します。 オプション s はゼロを含まない文字列を期待します。 引数が文字列でなければ tostring と同じルールに従って文字列に変換されます。

LuaをC99でないコンパイラでコンパイルした場合、オプション A および a (16進浮動小数点数) ではいかなる修飾子 (フラグ、幅、長さ) もサポートされません。

string.gmatch (s, pattern)

呼ばれるたびに文字列 s に対して pattern (§6.4.1 を参照) から次のキャプチャを返すようなイテレータ関数を返します。 pattern にキャプチャが指定されていなければ、呼ばれるたびにマッチ全体が返されます。

例えば以下のループは文字列 s 中のすべての単語を巡回し、それを各行に表示します。

     s = "hello world from Lua"
     for w in string.gmatch(s, "%a+") do
       print(w)
     end

次の例は指定された文字列中の key=value ペアをすべて集め、 テーブルに格納します。

     t = {}
     s = "from=world, to=Lua"
     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
       t[k] = v
     end

この関数の場合、パターン先頭のキャレット '^' は巡回を妨げることになるので、アンカーとして機能しません。

string.gsub (s, pattern, repl [, n])

s 中のすべて (または指定されていれば最初の n 個) の pattern (§6.4.1 を参照) を repl で指定された置換文字列で置き換えた文字列を返します。 repl には文字列、テーブル、または関数を指定できます。 また、2つめの値として出現したマッチの合計数も返します。 gsub という名前は Global SUBstitution から来ています。

repl が文字列の場合はその値が置換に使われます。 文字 % はエスケープ文字として動作します。 repl 中の %d (ただし d は1から9) 形式の並びは、d番目のキャプチャした部分文字列の値を表します。 並び %0 はマッチ全体を表し、並び %% は単一の % を表します。

repl がテーブルの場合は、各マッチに対し、1番目のキャプチャをキーとして使ってテーブルが検索されます。

repl が関数の場合は、マッチが出現するたびにその関数が呼ばれ、キャプチャした部分文字列が順番通りに引数として渡されます。

どの場合でも、パターンにキャプチャが無ければ、パターン全体が1個のキャプチャ内にあるかのように動作します。

テーブル検索や関数呼び出しの戻り値が文字列または数値であれば、それが置換文字列として使われます。 そうでなく、 false または nil であれば、置換は行われません (つまり文字列中の元のマッチがそのまま保たれます)。

いくつか例を挙げます。

     x = string.gsub("hello world", "(%w+)", "%1 %1")
     --> x="hello hello world world"

     x = string.gsub("hello world", "%w+", "%0 %0", 1)
     --> x="hello hello world"

     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
     --> x="world hello Lua from"

     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
     --> x="home = /home/roberto, user = roberto"

     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
           return load(s)()
         end)
     --> x="4+5 = 9"

     local t = {name="lua", version="5.3"}
     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
     --> x="lua-5.3.tar.gz"

string.len (s)

文字列を受け取り、その長さを返します。 空文字列 "" の長さは0です。 ゼロも数えられるので、 "a\000bc\000" の長さは5です。

string.lower (s)

文字列を受け取り、その文字列中の大文字をすべて小文字に変更した文字列を返します。 それ以外の文字は変更されません。 何が大文字であるかの定義は現在のロケールに依存します。

string.match (s, pattern [, init])

文字列 s 中の pattern (§6.4.1 を参照) の最初のマッチを検索します。 見つかった場合は、そのパターンのキャプチャを返します。 そうでなければ nil を返します。 pattern にキャプチャが無ければ、マッチ全体が返されます。 省略可能な第3引数 init は検索の開始位置を指定する数値です。 デフォルト値は1で、負の値も指定できます。

string.pack (fmt, v1, v2, ···)

書式文字列 fmt (§6.4.2 を参照) に従って、値 v1、v2、··· をバイナリ文字列にパックし、その文字列を返します。

string.packsize (fmt)

指定された書式で string.pack から返される文字列のサイズを返します。 書式文字列には可変長のオプション 's' および 'z' を含めることはできません (§6.4.2 を参照)。

string.rep (s, n [, sep])

文字列 s を文字列 sep で区切って n 個連結した文字列を返します。 sep のデフォルト値は空文字列 (つまり区切り文字なし) です。 n が正の値でなければ空文字列を返します。

string.reverse (s)

文字列 s を反転した文字列を返します。

string.sub (s, i [, j])

s の i 文字目から j 文字目までの部分文字列を返します。 i および j には負の値も指定できます。 j を省略した場合は-1 (つまり文字列の長さ) になります。 例えば呼び出し string.sub(s,1,j) は s の先頭から j 文字を返し、 string.sub(s, -i) は s の最後から i 文字を返します。

負のインデックスを変換した後、 i が1より小さければ1に修正され、 j が文字列の長さより大きければその長さに修正されます。 これらの修正の後、 i が j より大きければ空文字列が返されます。

string.unpack (fmt, s [, pos])

書式文字列 fmt (§6.4.2 を参照) に従って、文字列 s にパックされた値を返します (string.pack を参照)。 省略可能な pos は s の読み込み開始位置を指定します (デフォルトは1です)。 値を読み込んだ後、 s の最初の未読バイトのインデックスも返されます。

string.upper (s)

文字列を受け取り、その文字列中の小文字をすべて大文字に変更した文字列を返します。 それ以外の文字は変更されません。 何が小文字であるかの定義は現在のロケールに依存します。

6.4.1 – パターン

Luaのパターンは、パターンマッチ関数 string.find、 string.gmatch、 string.gsub、 string.match によってパターンとして解釈される正規文字列によって記述されます。 この節ではこれらの文字列の構文と意味 (つまり何にマッチするのか) を説明します。

文字クラス

文字クラスは文字の集合を表すために使われます。 文字クラスの記述では以下の組み合わせが使えます。

  • x: (ただしxは魔法の文字^$()%.[]*+-?のいずれでもない) 文字x自身を表します。
  • .: (ドット) すべての文字を表します。
  • %a: すべての英字を表します。
  • %c: すべての制御文字を表します。
  • %d: すべての数字を表します。
  • %g: 空白以外のすべての印刷可能文字を表します。
  • %l: すべての小文字を表します。
  • %p: すべての句読点文字を表します。
  • %s: すべての空白文字を表します。
  • %u: すべての大文字を表します。
  • %w: すべての英数字を表します。
  • %x: すべての16進数字を表します。
  • %x: (ただしxは英数以外の任意の文字) 文字xを表します。 これは魔法の文字をエスケープする標準的な方法です。 英数以外のあらゆる文字 (魔法でない文字も含むすべての句読点文字が含まれます) は、前に '%' を付けることでパターン中でそれ自身を表すことができます。
  • [set]: setの中のすべての文字の和集合であるクラスを表します。 '-' を使って範囲の終わりの文字を区切ることによって、その範囲の文字を指定することができます。 範囲は昇順です。 上で説明したすべてのクラス %x はsetの中でも部品として使うことができます。 setの中のそれ以外の文字はすべてそれ自身を表します。 例えば [%w_] (または [_%w]) はすべての英数字にアンダースコアを加えたものを表し、 [0-7] は8進数字を表し、 [0-7%l%-] は8進数字に小文字と '-' 文字を加えたものを表します。

    範囲とクラスの相互作用は定義されていません。 そのため [%a-z] や [a-%%] といったパターンは無意味です。

  • [^set]: setの補集合を表します。 setは上で述べた通りに解釈されます。

ひとつの文字で表されているクラス (%a、%c など) はすべて、対応する大文字でそのクラスの補集合を表します。 例えば %S は空白以外のすべての文字を表します。

英字、空白などの文字グループは現在のロケールに依存します。 例えば、クラス [a-z] と %l は同等でない場合があります。

パターン項目

パターン項目は以下のいずれかです。

  • 単一の文字クラス。 そのクラス中の任意の1文字にマッチします。
  • 単一の文字クラスに '*' が続いたもの。 そのクラス中の文字の0回以上の繰り返しにマッチします。 これらの繰り返し項目は必ず最も長いマッチ可能な並びにマッチします。
  • 単一の文字クラスに '+' が続いたもの。 そのクラス中の文字の1回以上の繰り返しにマッチします。 これらの繰り返し項目は必ず最も長いマッチ可能な並びにマッチします。
  • 単一の文字クラスに '-' が続いたもの。 そのクラス中の文字の0回以上の繰り返しにマッチします。 '*' と異なり、 これらの繰り返し項目は必ず最も短いマッチ可能な並びにマッチします。
  • 単一の文字クラスに '?' が続いたもの。 そのクラス中の文字の0回または1回の出現にマッチします。 可能であれば常に1回の出現にマッチします。
  • %n (ただしnは1から9) この項目はn番目のキャプチャした文字列 (後述) と等しい部分文字列にマッチします。
  • %bxy (ただしxとyは2つの別々の文字) この項目は、xで始まりyで終わる、xとyの釣り合いが取れている文字列にマッチします。 つまり、文字列を左から右に読み進み、xのときに+1、yのときに-1をカウントするとき、最初にカウントが0になったyが終わりのyになります。 例えば、項目 %b() は括弧の釣り合いが取れている式にマッチします。
  • %f[set] (境界パターン) この項目は、次の文字がsetに属し、前の文字がsetに属しない、任意の位置の空文字列にマッチします。 集合setは先程説明したように解釈されます。 対象の先頭と末尾は文字 '\0' があるかのように処理されます。

パターン

パターンはパターン項目の並びです。 パターンの先頭にキャレット '^' があれば、マッチが対象文字列の先頭に固定されます。 パターンの最後に '$' があれば、マッチが対象文字列の最後に固定されます。 それ以外の場所では、 '^' および '$' は特別な意味を持たず、それ自身を表します。

キャプチャ

パターンには括弧で囲ったサブパターンを含めることができます。 これはキャプチャを表します。 マッチが成功すると、対象文字列のうちキャプチャにマッチした部分の文字列が、後の使用のために保存されます (キャプチャされます)。 キャプチャは、その左括弧によって番号付けされます。 例えばパターン "(a*(.)%w(%s*))" の場合、 "a*(.)%w(%s*)" にマッチした部分の文字列が最初のキャプチャ (つまり番号1) として保存され、 "." にマッチした文字が番号2でキャプチャされ、 "%s*" にマッチした部分が番号3になります。

特別な場合として、空のキャプチャ () を使うと現在の文字列位置 (数値) をキャプチャします。 例えば、パターン "()aa()" を文字列 "flaaap" に適用すると、2つのキャプチャ3と5が得られます。

6.4.2 – packおよびunpackの書式文字列

string.pack、 string.packsize、 string.unpack の第1引数は書式文字列で、作成する (または読み込む) 構造体のレイアウトを記述します。

書式文字列は変換オプションの並びです。 変換オプションは以下のものが指定できます。

  • <: リトルエンディアンに設定します。
  • >: ビッグエンディアンに設定します。
  • =: ネイティブエンディアンに設定します。
  • ![n]: アラインメントを n に設定します (デフォルトはネイティブアラインメント)。
  • b: 符号付きバイト (char)。
  • B: 符号無しバイト (char)。
  • h: 符号付きshort (ネイティブサイズ)。
  • H: 符号無しshort (ネイティブサイズ)。
  • l: 符号付きlong (ネイティブサイズ)。
  • L: 符号無しlong (ネイティブサイズ)。
  • j: lua_Integer。
  • J: lua_Unsigned。
  • T: size_t (ネイティブサイズ)。
  • i[n]: nバイトの符号付きint (デフォルトはネイティブサイズ)。
  • I[n]: nバイトの符号無しint (デフォルトはネイティブサイズ)。
  • f: float (ネイティブサイズ)。
  • d: double (ネイティブサイズ)。
  • n: lua_Number。
  • cn: nバイトの固定長文字列。
  • z: ゼロ終端文字列。
  • s[n]: 長さを前置した文字列。 長さはnバイトの符号無し整数 (デフォルトはsize_t) として符号化されます。
  • x: 1バイトのパディング。
  • Xop: オプションopに従ってアラインメントした空項目 (op はアラインメント以外は無視されます)。
  • ' ': (空白) 無視されます。

("[n]" は省略可能な整数値を表しています。) パディング、空白、設定 (オプション "xX <=>!") を除き、各オプションに引数がひとつずつ (string.pack の場合) または結果がひとつずつ (string.unpack の場合) 対応します。

オプション "!n"、"sn"、"in"、"In" において、 n は1から16までの任意の整数を指定できます。 整数オプションはすべてオーバーフローのチェックが行われます。 string.pack では指定した値が指定したサイズに収まるかチェックされ、 string.unpack では読み込んだ値がLuaの整数に収まるかチェックされます。

書式文字列はいずれも先頭に "!1=" が付いているかのように解釈されます。 つまり最大アラインメントは1 (アラインメントなし) で、ネイティブエンディアンです。

アラインメントは以下のように動作します。 各オプションに対して、そのオプションのサイズと最大アラインメントの間で最小の倍数のオフセットからデータが開始されるまでの間に、パディングが追加されます。 この最小は2の乗数でなければなりません。 オプション "c" および "z" はアラインメントされません。 オプション "s" は最初の整数のアラインメントに従います。

すべてのパディングは string.pack によってゼロで埋められます (そして string.unpack によって無視されます。)

6.5 – UTF-8サポート

このライブラリはUTF-8エンコーディングの基本的なサポートを提供します。 このライブラリの関数はすべてテーブル utf8 の中に提供されます。 このライブラリにはエンコーディング処理以外のUnicodeに対するサポートはありません。 文字の意味が必要な操作、例えば文字の分類などは対象外です。

特に明記されない限り、引数としてバイト位置を受け取る関数はすべて、その位置はバイトシーケンスの開始位置であるか、対象文字列の長さプラス1であるとみなされます。 文字列ライブラリと同様に、負のインデックスは文字列の終わりから数えられます。

utf8.char (···)

ゼロ個以上の整数を受け取り、それぞれを対応するUTF-8バイトシーケンスに変換し、それらのシーケンスをすべて連結した文字列を返します。

utf8.charpattern

対象が有効なUTF-8文字列であると仮定したときの、ちょうどひとつのUTF-8バイトシーケンスにマッチするパターン (§6.4.1 を参照) "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" です (文字列です。 関数ではありません)。

utf8.codes (s)

以下の構文

     for p, c in utf8.codes(s) do body end

で文字列 s 中のすべての文字を巡回できるような値を返します。 ただし p は位置 (バイト単位) で、 c は各文字のコードポイントです。 無効なバイトシーケンスに遭遇した場合はエラーが発生します。

utf8.codepoint (s [, i [, j]])

バイト位置 i と j の間 (両端を含む) で始まる s 中のすべての文字のコードポイントを (整数として) 返します。 i のデフォルト値は1、 j のデフォルト値は i です。 無効なバイトシーケンスに遭遇した場合はエラーが発生します。

utf8.len (s [, i [, j]])

バイト位置 i と j の間 (両端を含む) で始まる文字列 s 中のUTF-8文字の数を返します。 i のデフォルト値は1、 j のデフォルト値は-1です。 無効なバイトシーケンスが見つかった場合は、偽の値に加えて、最初の無効なバイトの位置を返します。

utf8.offset (s, n [, i])

s の n 文字目 (位置 i から数えて) のエンコーディングが始まる位置 (バイト単位) を返します。 n に負の値を指定すると、位置 i より前の文字になります。 i のデフォルト値は、 n が負でなければ1で、 負の場合は #s + 1 です。 例えば、 utf8.offset(s, -n) はその文字列の終わりから n 文字目のオフセットになります。 対象中に指定された文字が無いか、終端の直後の場合は、 nil を返します。

特殊な場合として、 n が0のときは、 s の i 番目のバイトを含む文字のエンコーディング開始位置を返します。

s は有効なUTF-8文字列であると仮定しています。

6.6 – テーブル操作

このライブラリはテーブル操作のための汎用的な機能を提供します。 このライブラリの関数はすべてテーブル table の中に提供されます。

操作がテーブルの長さを必要とするときは、テーブルは正規のシーケンスであるか、 __len メタメソッドを持たなければなりません (§3.4.7 を参照)。 いずれの関数においても、指定されたテーブル中の数値でないキーは無視されます。

table.concat (list [, sep [, i [, j]]])

すべての要素が文字列か数値であるリストを受け取り、文字列 list[i]..sep..list[i+1] ··· sep..list[j] を返します。 sep のデフォルト値は空文字列、 i のデフォルト値は1、 j のデフォルト値は #list です。 i が j より大きい場合は空文字列を返します。

table.insert (list, [pos,] value)

要素 list[pos]、list[pos+1]、···、list[#list] を上に移動し、 list の位置 pos に要素 value を挿入します。 pos のデフォルト値は #list+1 なので、 table.insert(t,x) はリスト t の最後に x を挿入します。

table.move (a1, f, e, t [,a2])

テーブル a1 の要素をテーブル a2 に移動します。 多重代入 a2[t],··· = a1[f],···,a1[e] と同等です。 a2 のデフォルト値は a1 です。 移動先の範囲と移動元の範囲は重なっていても構いません。 移動する要素の数はLuaの整数に収まらなければなりません。

table.pack (···)

すべての引数をキー 1、2、··· に格納し、その引数の合計個数をフィールド "n" に格納した、新しいテーブルを返します。 結果のテーブルはシーケンスでない場合があります。

table.remove (list [, pos])

list から位置 pos の要素を削除し、その削除した要素の値を返します。 pos が1と #list の間の整数であれば、要素 list[pos+1]、list[pos+2]、···、list[#list] は下へ移動し、要素 list[#list] は消去されます。 インデックス pos には #list + 1 も指定でき、また #list が0のときには0も指定できます。 これらの場合は要素 list[pos] が消去されます。

pos のデフォルト値は #list なので、呼び出し table.remove(l) はリスト l の最後の要素を削除します。

table.sort (list [, comp])

list[1] から list[#list] のリスト要素を、指定した順番にその場でソートします。 comp を指定する場合、それは関数でなければなりません。 この関数は、リストの要素を2個受け取り、1番目の要素が2番目の要素より前に来て欲しい場合に真を返さなければなりません (つまりソート後に not comp(list[i+1],list[i]) が真になるようにします)。 comp を指定しない場合は、標準のLuaの演算子 < が代わりに使われます。

ソートのアルゴリズムは安定ではありません。 つまり、指定された順序において等しいとみなされる要素は、ソートによってその相対位置が変化する場合があります。

table.unpack (list [, i [, j]])

指定されたリストの要素を返します。 以下と同等です。

     return list[i], list[i+1], ···, list[j]

デフォルトでは i は1で、 j は #list です。

6.7 – 数学関数

このライブラリは基本的な数学関数を提供します。 このライブラリの関数と定数はすべてテーブル math の中に提供されます。 "integer/float" という注釈が付いている関数は、整数の引数には整数の結果を、浮動小数点数の引数 (または両方が混在した引数) には浮動小数点数の結果を返します。 丸め関数 (math.ceil、 math.floor、 math.modf) は、結果が整数の範囲に収まる場合は整数を返し、そうでなければ浮動小数点数を返します。

math.abs (x)

x の絶対値を返します。 (integer/float)

math.acos (x)

x の逆余弦を (ラジアンで) 返します。

math.asin (x)

x の逆正弦を (ラジアンで) 返します。

math.atan (y [, x])

y/x の逆正接を (ラジアンで) 返します。 ただし結果の象限を決めるために両方の引数の符号が使われます。 (x がゼロの場合も正確に処理されます。)

x のデフォルト値は1です。 そのため呼び出し math.atan(y) は y の逆正接を返します。

math.ceil (x)

x より大きいまたは等しい最小の整数値を返します。

math.cos (x)

x (ラジアン) の余弦を返します。

math.deg (x)

角度 x をラジアンから度に変換します。

math.exp (x)

exの値を返します (ただし e は自然対数の底です)。

math.floor (x)

x より小さいまたは等しい最大の整数を返します。

math.fmod (x, y)

x を y で割った商をゼロに向かって丸めた余りを返します。 (integer/float)

math.huge

他のいかなる数値よりも大きな浮動小数点数の値 HUGE_VAL です。

math.log (x [, base])

指定されたbaseを底とする x の対数を返します。 base のデフォルト値はeです (つまり x の自然対数を返します)。

math.max (x, ···)

Luaの演算子 < に従って最大の値を持つ引数を返します。 (integer/float)

math.maxinteger

最も大きな整数です。

math.min (x, ···)

Luaの演算子 < に従って最小の値を持つ引数を返します。 (integer/float)

math.mininteger

最も小さな整数です。

math.modf (x)

x の整数部と x の小数部を返します。 2番目の戻り値は常に浮動小数点数です。

math.pi

円周率πの値です。

math.rad (x)

角度 x を度からラジアンに変換します。

math.random ([m [, n]])

引数を指定せずに呼ぶと、範囲 [0,1) に一様に分布する浮動小数点数の擬似乱数を返します。 2つの整数 m と n を指定して呼ぶと、範囲 [m, n] に一様に分布する整数の擬似乱数を返します。 (m-n の値を負にすることはできず、またLuaの整数に収まらなければなりません。) 呼び出し math.random(n) は math.random(1,n) と同等です。

この関数は基となるCが提供している擬似乱数生成関数へのインタフェースです。 統計的な性質については保証されていません。

math.randomseed (x)

x を擬似乱数生成器の「種」として設定します。 同じ種を指定すると同じ数列が生成されます。

math.sin (x)

x (ラジアン) の正弦を返します。

math.sqrt (x)

x の平方根を返します。 (この値は式 x^0.5 を使っても計算できます。)

math.tan (x)

x (ラジアン) の正接を返します。

math.tointeger (x)

値 x が整数に変換可能であれば、その整数を返します。 そうでなければ nil を返します。

math.type (x)

x が整数であれば "integer" を返し、浮動小数点数であれば "float" を返し、 x が数値でなければ nil を返します。

math.ult (m, n)

符号無しとして比較したとき m が n より下であれば真を返します。

6.8 – 入出力機能

入出力ライブラリは2種類のスタイルのファイル操作を提供します。 ひとつめは暗黙のファイルハンドルを使うもので、デフォルト入力ファイルとデフォルト出力ファイルを設定し、すべての入出力操作をこのデフォルトファイルに対して行います。 ふたつめのスタイルは明示的なファイルハンドルを使うものです。

暗黙のファイルハンドルを使うときは、すべての操作がテーブル io に提供されます。 明示的なファイルハンドルを使うときは、 io.open からファイルハンドルが返され、すべての操作はそのファイルハンドルのメソッドとして提供されます。

テーブル io にはCの通常の意味を持つ3つの定義済みファイルハンドル io.stdin、 io.stdout、 io.stderr も提供されています。 入出力ライブラリがこれらのファイルを閉じることはありません。

特に明記されない限り、すべての入出力関数は失敗時に nil (に加えて2番目の戻り値としてエラーメッセージと、3番目の戻り値としてシステム依存のエラーコード) を返し、 成功時は nil でない値を返します。 エラー発生時のエラーメッセージとエラーコードの計算はCのグローバル変数 errno に依存しているため、POSIX以外のシステムではスレッドセーフでない場合があります。

io.close ([file])

file:close() と同等です。 file を指定しない場合はデフォルト出力ファイルを閉じます。

io.flush ()

io.output():flush() と同等です。

io.input ([file])

ファイル名を指定して呼ぶと、その名前のファイルを (テキストモードで) 開き、そのハンドルをデフォルト入力ファイルとして設定します。 ファイルハンドルを指定して呼ぶと、単にそのファイルハンドルをデフォルト入力ファイルとして設定します。 引数を指定せずに呼ぶと、現在のデフォルト入力ファイルを返します。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

io.lines ([filename ···])

指定されたファイル名を読み込みモードで開き、その開いたファイルに対して file:lines(···) のように動作するイテレータ関数を返します。 イテレータ関数がファイルの終端を検出すると、 (ループを終えるため) 何の値も返さず、ファイルを自動的に閉じます。

呼び出し io.lines() (ファイル名を指定しない場合) は io.input():lines("*l") と同等です。 つまりデフォルト入力ファイルの各行を巡回します。 この場合、ループの終了時にファイルを閉じません。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

io.open (filename [, mode])

文字列 mode で指定されたモードでファイルを開きます。 新しいファイルハンドルを返します。 エラーの場合は nil とエラーメッセージを返します。

mode 文字列には以下のいずれかを指定できます。

  • "r": 読み込みモード (デフォルト)。
  • "w": 書き込みモード。
  • "a": 追記モード。
  • "r+: 更新モード。 以前のデータは維持されます。
  • "w+": 更新モード。 以前のデータは消去されます。
  • "a+": 追記モード。 以前のデータは維持されます。 ファイルの終端にのみ書き込むことができます。

また mode 文字列の最後に 'b' を付けることもできます。 これはシステムによってはバイナリモードでファイルを開く場合に必要です。

io.output ([file])

io.input と同様ですが、デフォルト出力ファイルに対して動作します。

io.popen (prog [, mode])

この関数はシステム依存であり、プラットフォームによっては利用できません。

別のプロセスでプログラム prog を開始し、そのプログラムからデータを読み込む (mode が "r" の場合、デフォルト) またはそのプログラムにデータを書き込む (mode が "w" の場合) ために使えるファイルハンドルを返します。

io.read (···)

io.input():read(···) と同等です。

io.tmpfile ()

テンポラリファイルのハンドルを返します。 このファイルは更新モードで開かれ、プログラム終了時に自動的に削除されます。

io.type (obj)

obj が有効なファイルハンドルであるかどうかを確認します。 obj が開かれているファイルハンドルであれば文字列 "file"、 obj が閉じられたファイルハンドルであれば "closed file"、 obj がファイルハンドルでなければ nil を返します。

io.write (···)

io.output():write(···) と同等です。

file:close ()

file を閉じます。 ハンドルがガベージコレクタに回収されればファイルは自動的に閉じられますが、そうなるまでの時間は予測できないことに注意してください。

io.popen で作成されたファイルハンドルを閉じるとき、 file:close は os.execute が返すのと同じ値を返します。

file:flush ()

file に書き込まれたデータを保存します。

file:lines (···)

呼ばれるたびに指定された書式に従ってファイルを読み込むイテレータ関数を返します。 書式が指定されない場合はデフォルトとして "l" が使われます。 例えば以下の構文は

     for c in file:lines(1) do body end

そのファイルの現在の位置から始まるすべての文字を巡回します。 io.lines と異なり、この関数はループ終了時にファイルを閉じません。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

file:read (···)

指定された書式に従ってファイル file を読み込みます。 書式は読み込む内容を指定します。 各書式に対して、読み込んだ内容の文字列または数値を返します。 指定された書式でデータを読めなかった場合は nil を返します。 (後者の場合、残りの書式に対する読み込みは実行されません。) 書式を指定せずに読んだ場合はデフォルトの書式 (次の行を読み込む) が使用されます (下記参照)。

以下の書式が利用可能です。

  • "n": 数値を読み込み、それをLuaの字句規約に従って浮動小数点数または整数として返します。 (数値の前に空白や符号があっても構いません。) この書式は必ず、数値として有効な部分を可能な限り長く読み込みます。 それが有効な数値を成していなければ (空文字、"0x"、"3.4e-" など)、それは読み捨てられ、 nil を返します。
  • "a": 現在の位置から始めてファイル全体を読み込みます。 ファイルの終端では空文字列を返します。
  • "l": 次の行を読み込みますが、行末は読み飛ばします。 ファイルの終端では nil を返します。 これはデフォルトの書式です。
  • "L": 行末文字 (もしあれば) を維持したまま次の行を読み込みます。 ファイルの終端では nil を返します。
  • 数値: 指定した数値のバイト数 (最大) の文字列を読み込みます。 数値がゼロの場合は、何も読み込まず空文字列を返します。 いずれの場合もファイルの終端では nil を返します。

書式 "l" および "L" はテキストファイルに対してのみ使うべきです。

file:seek ([whence [, offset]])

ファイルの位置を設定および取得します。 ファイルの位置はファイルの先頭から測られ、 offset で指定された位置に以下に示す文字列 whence で指定された基準点を加えた位置に設定されます。

  • "set": 基準は0 (ファイルの先頭)
  • "cur": 基準は現在位置
  • "end": 基準はファイルの終端

成功した場合はファイルの先頭からバイト単位で測った最終的なファイルの位置を返します。 失敗した場合は nil とエラーを説明する文字列を返します。

whence のデフォルト値は "cur" で、 offset のデフォルト値は0です。 例えば、呼び出し file:seek() は現在のファイルの位置を変更せずに返します。 呼び出し file:seek("set") は位置をファイルの先頭に設定します (そして0を返します)。 また、呼び出し file:seek("end") は位置をファイルの終端に設定し、そのサイズを返します。

file:setvbuf (mode [, size])

出力ファイルのバッファリングモードを設定します。 以下の3つのモードが利用可能です。

  • "no": バッファリングなし。 いかなる出力操作の結果も直ちに現れます。
  • "full": 完全バッファリング。 出力操作は、バッファが満杯になるか、そのファイルを明示的に flush したときだけ行われます (io.flush を参照)。
  • "line": 行バッファリング。 出力は、改行が出力されるか、何らかのスペシャルファイル (端末デバイスなど) から読み取りを行うまでバッファリングされます。

最後の2つの場合、 size はバッファのサイズ (バイト単位) を指定します。 デフォルトは適当なサイズです。

file:write (···)

各引数の値を file に出力します。 引数は文字列か数値でなければなりません。

成功した場合は file を返します。 そうでない場合は nil とエラーを説明する文字列を返します。

6.9 – OS機能

このライブラリはテーブル os を通して実装されています。

os.clock ()

プログラムが使用したCPU時間のおよその量を秒単位で返します。

os.date ([format [, time]])

指定された文字列 format に従って書式化された日付と時刻を含む文字列またはテーブルを返します。

time 引数を指定した場合はその時刻が書式化されます (この値の説明は os.time 関数を参照)。 そうでなければ現在時刻が書式化されます。

format が '!' で始まる場合、日付は協定世界時で書式化されます。 このオプション文字の後、 format が文字列 "*t" であれば、以下のフィールドを持つテーブルを返します。

  • year (4桁)
  • month (1–12)
  • day (1–31)
  • hour (0–23)
  • min (0–59)
  • sec (0–61)
  • wday (曜日、日曜日が1)
  • yday (通日)
  • isdst (夏時間フラグ、ブーリアン)

夏時間の情報が利用できない場合、最後のフィールドは存在しません。

format が "*t" でなければ、ISO Cの関数 strftime と同じルールに従って書式化した日付を文字列として返します。

引数を指定せずに呼ぶと、ホストシステムと現在のロケールに依存した適当な日付時刻の表現を返します (つまり os.date() は os.date("%c") と同等です)。

この関数はCの関数 gmtime およびCの関数 localtime に依存しているため、POSIX以外のシステムではスレッドセーフでない場合があります。

os.difftime (t2, t1)

時刻 t1 から時刻 t2 までの差を秒単位で返します (ただし時刻の値は os.time から返された値です)。 POSIX、Windows、その他いくつかのシステムでは、この値は正確に t2-t1 です。

os.execute ([command])

この関数はISO Cの関数 system と同等です。 OSのシェルによって実行される command を渡します。 最初の戻り値は、コマンドが正常終了した場合は true、そうでなければ nil です。 この最初の戻り値の後、以下のような文字列と数値が返されます。

  • "exit": コマンドは正常に終了しました。 後の数値はコマンドの終了ステータスです。
  • "signal": コマンドはシグナルによって終了しました。 後の数値はコマンドが終了した原因のシグナルです。

command を指定せずに呼ぶと、シェルが利用可能であれば真を返します。

os.exit ([code [, close]])

ISO Cの関数 exit を呼んでホストプログラムを終了させます。 code が true の場合、返されるステータスは EXIT_SUCCESS です。 code が false の場合、返されるステータスは EXIT_FAILURE です。 code が数値の場合、返されるステータスはその数値です。 code のデフォルト値は true です。

省略可能な第2引数 close が真であれば、終了前にLuaのステートが閉じられます。

os.getenv (varname)

プロセスの環境変数 varname の値を返します。 その変数が定義されていなければ nil を返します。

os.remove (filename)

指定した名前のファイル (または空のディレクトリ (POSIXシステムの場合)) を削除します。 失敗した場合は nil に加え、エラーを説明する文字列とエラーコードが返されます。

os.rename (oldname, newname)

oldname という名前のファイルまたはディレクトリを newname にリネームします。 失敗した場合は nil に加え、エラーを説明する文字列とエラーコードが返されます。

os.setlocale (locale [, category])

プログラムの現在のロケールを設定します。 locale はロケールを指定するシステム依存の文字列です。 category は変更するカテゴリを指定する省略可能な文字列で、以下のいずれかです。

  • "all"
  • "collate"
  • "ctype"
  • "monetary"
  • "numeric"
  • "time"

デフォルトのカテゴリは "all" です。 この関数は新しいロケールの名前を返します。 要求に沿えない場合は nil を返します。

locale が空文字列の場合、現在のロケールは実装依存のネイティブなロケールに設定されます。 locale が文字列 "C" の場合、現在のロケールは標準規格のCロケールに設定されます。

最初の引数に nil を指定して呼ぶと、指定したカテゴリに対する現在のロケールの名前を返します。

この関数はCの関数 setlocale に依存しているため、スレッドセーフでない場合があります。

os.time ([table])

引数を指定せずに呼ぶと現在時刻を返します。 そうでなければ、指定されたテーブルで表されたローカル日時に対応する時刻の値を返します。 このテーブルには以下のフィールドが必須です。

  • year
  • month
  • day

以下のフィールドは省略可能です。

  • hour (デフォルトは 12)
  • min (デフォルトは 0)
  • sec (デフォルトは 0)
  • isdst (デフォルトは nil)

それ以外のフィールドは無視されます。 これらのフィールドの説明は os.date 関数を参照してください。

これらのフィールドの値は有効な範囲内である必要はありません。 例えば sec が-10であれば、それ以外のフィールドで指定された時刻から-10秒を表します。 hour が1000であれば、それ以外のフィールドで指定された時刻から+1000時間を表します。

戻り値はシステム依存の意味を持つ数値です。 POSIX、Windows、その他いくつかのシステムでは、この数値は特定の開始点 (「エポック」) からの秒数です。 それ以外のシステムでは、その意味は規定されておらず、 os.date および os.difftime への引数としてのみ使うことができます。

os.tmpname ()

テンポラリファイルとして使うことのできるファイル名を持った文字列を返します。 このファイルは使用前に明示的に開かなければならず、必要なくなったときには明示的に削除しなければなりません。

POSIXシステムでは、セキュリティリスクを回避するため、その名前のファイルが作成されます。 (名前取得とファイル作成の間に他の誰かが間違ったパーミッションでファイルを作成する可能性があるためです。) その場合でもやはり使用前にはそのファイルを開く必要があり、 (結局使わなかったとしても) そのファイルを削除する必要があります。

可能であれば io.tmpfile を使う方がよいかもしれません。 こちらはプログラム終了時に自動的にファイルが削除されます。

6.10 – デバッグライブラリ

このライブラリはデバッグインタフェース (§4.9) の機能をLuaのプログラムに提供します。 このライブラリを使うときは気を付けてください。 これらの関数の中には、Luaのコードに関する基本的な想定 (関数ローカルな変数は外側からアクセスできない、ユーザーデータのメタテーブルはLuaのコードから変更できない、Luaのプログラムはクラッシュしない、など) を破るものがあり、安全なはずのコードを破壊する可能性があります。 また、このライブラリの関数の中には性能的の良くないものもあります。

このライブラリの関数はすべて debug テーブルの中に提供されます。 スレッドに対して動作する関数はすべて、省略可能な最初の引数として操作対象のスレッドを取ります。 デフォルトは常に現在のスレッドです。

debug.debug ()

ユーザーとの対話モードに入ります。 対話モードではユーザーが入力した文字列が実行されます。 単純なコマンドや様々なデバッグ機能を使うことで、ユーザーがグローバル変数やローカル変数を調査したり、その値を変更したり、式を評価したりできます。 単語 cont だけを含む行を入力するとこの関数を終了し、呼び出し元の実行を続けます。

debug.debug に対するコマンドは、どの関数の内部にも字句的にネストしていないため、ローカル変数に直接アクセスすることはできないことに注意してください。

debug.gethook ([thread])

スレッドの現在のフック設定を3つの値、現在のフック関数、現在のフックマスク、現在のフックカウントとして返します (debug.sethook 関数で設定するものと同様です)。

debug.getinfo ([thread,] f [, what])

関数に関する情報をテーブルに格納して返します。 関数は直接指定するか、 f の値として数値を指定できます。 数値の場合は、指定されたスレッドのコールスタックのレベル f で実行中の関数を表します。 レベル0は現在の関数 (getinfo 自身)、レベル1は getinfo の呼び出し元の関数 (スタックに残らない末尾呼び出しは除きます)、以下同様です。 f がアクティブな関数の数よりも大きい場合は nil を返します。

戻り値のテーブルには、埋めるフィールドを表す文字列 what に従って、 lua_getinfo が返すフィールドがすべて含まれる可能性があります。 what のデフォルト値は、有効な行番号のテーブル以外の利用可能なすべての情報を取得します。 オプション 'f' を指定すると、 func という名前のフィールドにその関数自身が追加されます。 オプション 'L' を指定すると、 activelines という名前のフィールドに有効な行番号のテーブルが追加されます。

例えば、式 debug.getinfo(1,"n").name は現在の関数の名前 (もし適当な名前が見つかれば) を返します。 式 debug.getinfo(print) は print 関数に関する利用可能なすべての情報を持ったテーブルを返します。

debug.getlocal ([thread,] f, local)

スタックのレベル f の関数のインデックス local のローカル変数の名前と値を返します。 明示的なローカル変数だけでなく引数や一時変数などもアクセスできます。

最初の引数またはローカル変数はインデックス1で、以下同様です。 その関数の現在のスコープで有効な変数のみが数えられ、コード中で宣言された順番に従って番号付けられます。 負のインデックスは可変長引数を参照します。 -1は最初の可変長引数です。 指定されたインデックスの変数が存在しなければ nil を返します。 範囲外のレベルが指定された場合はエラーが発生します。 (レベルが有効かどうかを確認するには debug.getinfo を呼びます。)

'(' (開き括弧) で始まる変数名は名前のわからない変数を表します。 ループ制御変数のような内部変数やデバッグ情報が保存されていないチャンクの変数などです。

引数 f には関数も指定できます。 この場合は関数の引数の名前のみが返されます。

debug.getmetatable (value)

指定された value のメタテーブルを返します。 メタテーブルがなければ nil を返します。

debug.getregistry ()

レジストリテーブル (§4.5 を参照) を返します。

debug.getupvalue (f, up)

関数 f のインデックス up の上位値の名前と値を返します。 指定したインデックスの上位値が存在しなければ nil を返します。

'(' (開き括弧) で始まる変数名は名前のわからない変数を表します。 デバッグ情報の保存されていないチャンクの変数などです。

debug.getuservalue (u)

u に関連付けられているLuaの値を返します。 u がユーザーデータでなければ nil を返します。

debug.sethook ([thread,] hook, mask [, count])

指定された関数をフックとして設定します。 文字列 mask および数値 count は、いつフックが呼ばれるかを指定します。 文字列maskは以下の文字の任意の組み合わせを指定できます。

  • 'c': 関数が呼ばれるたびにフックが呼ばれます。
  • 'r': 関数から戻るたびにフックが呼ばれます。
  • 'l': コードの新しい行に入るたびにフックが呼ばれます。

さらに、 count がゼロでなければ、 count 個の命令を実行するたびにフックが呼ばれます。

引数を指定せずに呼ぶとフックは無効化されます。

フックが呼ばれたとき、最初の引数は呼び出しの原因となったイベントを表す以下の文字列です。

  • "call" (または "tail call")
  • "return"
  • "line"
  • "count"

lineイベントの場合、フックには第2引数として新しい行番号が渡されます。 フック内でレベルに2を指定して getinfo を呼ぶことで、実行中の関数に関する情報をさらに取得できます (レベル0は getinfo で、レベル1はフック関数です)。

debug.setlocal ([thread,] level, local, value)

スタックのレベル level の関数のインデックス local のローカル変数の値に value を代入します。 指定したインデックスのローカル変数が存在しない場合は nil を返します。 level が範囲外の場合はエラーが発生します。 (レベルが有効かどうかを確認するには getinfo を呼びます。) そうでなければ、そのローカル変数の名前を返します。

変数のインデックスと名前についての詳しい情報は debug.getlocal を参照してください。

debug.setmetatable (value, table)

指定された value に対するメタテーブルを指定された table (nil も指定できます) に設定します。 value を返します。

debug.setupvalue (f, up, value)

関数 f のインデックス up の上位値に値 value を代入します。 指定したインデックスの上位値が存在しない場合は nil を返します。 そうでなければ、その上位値の名前を返します。

debug.setuservalue (udata, value)

指定された udata に指定されたLuaの値 value を関連付けます。 udata はフルユーザーデータでなければなりません。

udata を返します。

debug.traceback ([thread,] [message [, level]])

message が存在し、文字列でも nil でもなければ、 message を返します。 この場合はそれ以上何も処理しません。 そうでなければ、コールスタックのスタックトレースを表す文字列を返します。 省略可能な message 文字列はスタックトレースの先頭に追加されます。 省略可能な level の数値はスタックトレースを開始するレベルを表します (デフォルトは1で、 traceback の呼び出し元関数です)。

debug.upvalueid (f, n)

指定された関数の n 番目の上位値に対する一意な識別子を (ライトユーザーデータとして) 返します。

この一意な識別子を使うと、異なるクロージャが上位値を共有しているかどうかを確認することができます。 ひとつの上位値を共有している (つまり同じ外部ローカル変数にアクセスする) 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: 環境変数を無視します。
  • --: オプションの処理を停止します。
  • -: stdin をファイルとして実行し、オプションの処理を停止します。

オプションを処理した後、指定されたスクリプトが実行されます。 引数なしで起動すると、標準入力 (stdin) が端末の場合は lua -v -i のように動作し、そうでなければ lua - のように動作します。

オプション -E を付けずに起動すると、いかなる引数も実行する前に、環境変数 LUA_INIT_5_3 (バージョン名付きの変数が定義されていない場合は LUA_INIT) がチェックされます。 この変数の内容が @filename という書式であれば、そのファイルが実行されます。 そうでなければ、その文字列自身が実行されます。

オプション -E を付けて実行すると、 LUA_INIT を無視する以外に LUA_PATH および LUA_CPATH の値も無視されます。 package.path および package.cpath の値には、 luaconf.h で定義されているデフォルトのパスが設定されます。

-i と -E を除き、すべてのオプションは順番に処理されます。 例えば以下のようなコマンドは

     $ lua -e'a=1' -e 'print(a)' script.lua

まず a を1に設定し、次に a の値を表示し、最後にファイル script.lua を引数なしで実行します。 (ただし $ はシェルプロンプトです。 これは環境によって異なる場合があります。)

いかなるコードも実行する前に、 arg という名前のグローバルなテーブルにすべてのコマンドライン引数が集められます。 スクリプトの名前がインデックス0に格納され、最初の引数はスクリプト名の後のインデックス1に格納され、以下同様です。 スクリプト名より前の引数 (つまりインタプリタ名およびオプション) はすべて負のインデックスに格納されます。 例えば以下のコマンドでは

     $ lua -la b.lua t1 t2

このテーブルは以下のようになります。

     arg = { [-2] = "lua", [-1] = "-la",
             [0] = "b.lua",
             [1] = "t1", [2] = "t2" }

スクリプトが指定されていない場合は、インタプリタ名がインデックス0に格納され、残りの引数がそれに続きます。 例えば以下のコマンドは

     $ lua -e "print(arg[1])"

"-e" を表示します。 スクリプトがある場合、そのスクリプトには引数 arg[1]、···、arg[#arg] が渡されます。 (Luaのすべてのチャンクと同様に、スクリプトは可変長引数の関数としてコンパイルされます。)

対話モードではプロンプトの表示と行の待ち受けが繰り返されます。 行を読み込んだ後、その行が式として解釈されます。 成功した場合はその値が表示されます。 そうでなければその行が文として解釈されます。 不完全な文が入力された場合は、異なるプロンプトを表示し、文が完全になるまで待ち受けます。

スクリプト内で保護されていないエラーが発生した場合は、そのエラーが標準エラー出力に報告されます。 エラーオブジェクトが文字列でなく、メタメソッド __tostring があれば、そのメタメソッドが呼ばれて最終的なメッセージが生成されます。 そうでなければ、そのエラーオブジェクトが文字列に変換され、それにスタックトレースが付け加えられます。

正常に終了するとメインのLuaステートが閉じられます (lua_close を参照)。 os.exit を呼んで終了するとこの処理を回避できます。

LuaをUnixシステムのスクリプトインタプリタとして使用できるように、スタンドアロンのインタプリタはチャンクの最初の行が # で始まる場合、その行を読み飛ばします。 つまり、 chmod +x と以下のような #! 形式を使うと、Luaのスクリプトを実行可能なプログラムにすることができます。

     #!/usr/local/bin/lua

(Luaのインタプリタの場所は環境によって異なる場合があります。 lua が PATH の通った場所にあるならば、

     #!/usr/bin/env lua

がより移植性の高い方法です。)

8 – 前バージョンとの非互換な点

この節ではLua 5.2からLua 5.3にプログラムを移植する際に遭遇するかもしれない非互換な点の一覧を掲載しています。 非互換のいくつかは、適切なオプション (ファイル luaconf.h を参照) を使ってLuaをコンパイルすると回避できます。 しかし、これらの互換オプションは将来のバージョンでは削除される予定です。

LuaのバージョンごとにCのAPIが変更される可能性があります。 これはプログラムのソースコードを変更することを暗黙に意味するわけではなく、定数の数値やマクロとして実装された関数なども含まれています。 そのため、Luaの異なるバージョン間でのバイナリ互換は仮定するべきではありません。 新しいバージョンを使うときは、LuaのAPIを使うプログラムを必ず再コンパイルしてください。

同様に、Luaのバージョンごとにコンパイル済みチャンクの内部表現も変更される可能性があります。 コンパイル済みチャンクはLuaの異なるバージョン間での互換性はありません。

公式の配布物の標準のパスはバージョン間で変更される場合があります。

8.1 – 言語の変更

  • Lua 5.2とLua 5.3の主な違いは、数値のサブタイプである整数の導入です。 この変更が「通常の」計算に影響することはないと思われますが、場合によっては (主にオーバーフロー関係の影響で) 異なる結果になることがあります。

    この差異は数値を強制的に浮動小数点数にすることで修正できます (Lua 5.2ではすべての数値が浮動小数点数でした)。 例えば定数の最後に .0 を付けたり、 x = x + 0.0 で変数を変換したりできます。 (これらは非互換に対応するための臨時的な応急処理にすぎません。 良いプログラミングの一般的なガイドラインではありません。 良いプログラミングのためには、浮動小数点数が必要なところでは浮動小数点数を使い、整数が必要なところでは整数を使ってください。)

  • 浮動小数点数を文字列に変換するとき、整数のように見える場合は結果に接尾辞 .0 が追加されるようになりました。 (例えば、浮動小数点数の 2.0 は 2 ではなく 2.0 と表示されます。) 数値に対して特定の書式が必要な場合は、必ず明示的な書式を使ってください。

    (正確にはこれは非互換ではありません。 数値を文字列として書式化する方法は規定されていないためです。 しかし特定の書式を想定しているプログラムも存在していました。)

  • ガベージコレクタの世代別モードは削除されました。 (これはLua 5.2の実験的な機能でした。)

8.2 – ライブラリの変更

  • bit32 ライブラリは廃止されました。 互換性のある外部のライプラリをrequireするか、あるいはより良い方法として、その関数を適切なビット演算子に置き換えてください。 (bit32 は32ビット整数を扱っていましたが、Lua 5.3のビット演算子はLuaの整数 (デフォルトでは64ビット) を扱うことに気を付けてください。)
  • テーブルライブラリは要素の設定や取得の際にメタメソッドを考慮するようになりました。
  • ipairs のイテレータはメタメソッドを考慮するようになりました。 __ipairs メタメソッドは廃止されました。
  • io.read のオプション名の最初の '*' は無くなりました。 互換性のため、この文字は引き続き受け付けられます (そして無視されます)。
  • 数学ライブラリの以下の関数は廃止されました。
    • atan2
    • cosh
    • sinh
    • tanh
    • pow
    • frexp
    • ldexp

    math.pow(x,y) は x^y で置き換えることができます。 math.atan2 は math.atan で置き換えることができます。 math.atan は引数1個と引数2個のどちらでも受け付けるようになりました。 math.ldexp(x,exp) は x * 2.0^exp で置き換えることができます。 それ以外の演算については、外部のライブラリを使うかLuaで実装してください。

  • require で使われるCのローダーの検索関数でバージョン名の処理方法が変わりました。 バージョンは (他の多くのツールと同様に) モジュール名の後に来るようになりました。 互換性のため、この検索関数は新しい形式に従ったオープン関数が見つからなかった場合、古い書式も試みます。 (Lua 5.2ではすでにそのように動作していましたが、ドキュメントは変更されていませんでした。)
  • 呼び出し collectgarbage("count") の戻り値はひとつだけになりました。 (最初の戻り値の小数部から2番目の戻り値を計算できます。)

8.3 – APIの変更

  • 継続関数は lua_getctx を使って取得する必要があった値を引数として受け取るようになりました。 そのため lua_getctx は削除されました。 それに合わせてコードを変更してください。
  • 関数 lua_dump に引数 strip が追加されました。 以前の動作をするにはこの引数に0を渡してください。
  • 符号無し整数を扱う関数 (lua_pushunsigned、 lua_tounsigned、 lua_tounsignedx、 luaL_checkunsigned、 luaL_optunsigned) は廃止されました。 同等の符号付きバージョンを型キャストと共に使ってください。
  • デフォルトでない整数型を変換するマクロ (luaL_checkint、 luaL_optint、 luaL_checklong、 luaL_optlong) は廃止されました。 lua_Integer に対する同等のものを型キャストと共に使ってください (または、可能であれば、あなたのコードで lua_Integer を使ってください)。

9 – Lua の完全な構文

Luaの完全な構文を拡張BNF記法で以下に掲載します。 一般的な拡張BNF記法と同様に、 {A} はAの0回以上の繰り返しを表し、 [A] はAが省略可能であることを表します。 (演算子の優先順位は §3.4.8 を参照。 終端記号Name、Numeral、LiteralStringの説明は §3.1 を参照。)

    chunk ::= block

    block ::= {stat} [retstat]

    stat ::=  ‘;’ |
         varlist ‘=’ explist |
         functioncall |
         label |
         break |
         goto Name |
         do block end |
         while exp do block end |
         repeat block until exp |
         if exp then block {elseif exp then block} [else block] end |
         for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end |
         for namelist in explist do block end |
         function funcname funcbody |
         local function Name funcbody |
         local namelist [‘=’ explist]

    retstat ::= return [explist] [‘;’]

    label ::= ‘::’ Name ‘::’

    funcname ::= Name {‘.’ Name} [‘:’ Name]

    varlist ::= var {‘,’ var}

    var ::=  Name | prefixexp ‘[’ exp ‘]’ | prefixexp ‘.’ Name

    namelist ::= Name {‘,’ Name}

    explist ::= exp {‘,’ exp}

    exp ::=  nil | false | true | Numeral | LiteralString | ‘...’ | functiondef |
         prefixexp | tableconstructor | exp binop exp | unop exp

    prefixexp ::= var | functioncall | ‘(’ exp ‘)’

    functioncall ::=  prefixexp args | prefixexp ‘:’ Name args

    args ::=  ‘(’ [explist] ‘)’ | tableconstructor | LiteralString

    functiondef ::= function funcbody

    funcbody ::= ‘(’ [parlist] ‘)’ block end

    parlist ::= namelist [‘,’ ‘...’] | ‘...’

    tableconstructor ::= ‘{’ [fieldlist] ‘}’

    fieldlist ::= field {fieldsep field} [fieldsep]

    field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp

    fieldsep ::= ‘,’ | ‘;’

    binop ::=  ‘+’ | ‘-’ | ‘*’ | ‘/’ | ‘//’ | ‘^’ | ‘%’ |
         ‘&’ | ‘~’ | ‘|’ | ‘>>’ | ‘<<’ | ‘..’ |
         ‘<’ | ‘<=’ | ‘>’ | ‘>=’ | ‘==’ | ‘~=’ |
         and | or

    unop ::= ‘-’ | not | ‘#’ | ‘~’