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

以下是引用原文：

程序员改Bug的时候

Lua 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 # to ()” のエラーを生成する。ただし func はコールスタックから取得する。

luaL_argerror
      int luaL_argerror (lua_State *L, int numarg, const char *extramsg);
メッセージ “bad argument # to ()” のエラーを生成する。ただし 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);
: bad argument to ( expected, got )
のようなメッセージのエラーを生成する。ただしは luaL_where によって生成されたもので、は現在の関数の名前、 and は実引数の型名である。

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 の制御の現在位置を識別する文字列をスタックに積む。典型的にこの文字列は :: のような書式になっている。レベル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 番目にキャプチャされた文字列にマッチするような要素である (下の説明を参照)。 %bxy (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  |  `#´

原文