6.11 – デバッグライブラリ
このライブラリは、デバッグインターフェース（§4.7）の機能をLuaプログラムへ提供します。
このライブラリを使うときは注意が必要です。その関数のいくつかは、Luaコードに関する基本的な前提（たとえば、関数のローカル変数に外部からアクセスできない、ユーザーデータのメタテーブルをLuaコードから変更できない、Luaプログラムはクラッシュしない、など）を破るため、本来なら安全なコードを危険にさらす可能性があります。さらに、このライブラリの一部の関数は低速な場合があります。使用前に必ずこのライブラリを明示的にrequireすることが望ましい慣行です。
このライブラリのすべての関数はdebugテーブル内にあります。スレッドを操作するすべての関数は、操作対象のスレッドを省略可能な第1引数として受け取ります。デフォルトは常に現在のスレッドです。
debug.debug ()
ユーザーとの対話モードに入り、ユーザーが入力した各文字列を実行します。簡単なコマンドとそのほかのデバッグ機能を使って、ユーザーはグローバル変数やローカル変数の調査、値の変更、式の評価などを行えます。単語contだけを含む行を入力するとこの関数が終了し、呼び出し元が実行を継続します。
debug.debugのコマンドはどの関数内にも字句的にネストされていないため、ローカル変数へ直接アクセスできないことに注意してください。
debug.gethook ([thread])
関数debug.sethookによって設定された、スレッドの現在のフック設定を3つの値、すなわち現在のフック関数、現在のフックマスク、現在のフックカウントとして返します。
アクティブなフックがなければfailを返します。
debug.getinfo ([thread,] f [, what])
関数に関する情報を持つテーブルを返します。関数を直接指定することも、fの値として数値を指定することもできます。数値の場合、指定されたスレッドのコールスタックでレベルfにある実行中の関数を意味します。レベル0は現在の関数（getinfo自体）、レベル1はgetinfoを呼び出した関数（スタックに数えられない末尾呼び出しを除く）で、以降も同様です。fがアクティブな関数の数より大きい数値なら、getinfoはfailを返します。
返されるテーブルには、lua_getinfoが返すすべてのフィールドを含められます。文字列whatが値を設定するフィールドを指定します。whatのデフォルトでは、有効な行のテーブルを除く、利用可能なすべての情報を取得します。オプション’f’は、関数自体を持つfuncという名前のフィールドを追加します。オプション’L’は、関数がLua関数なら、有効な行のテーブルを持つactivelinesという名前のフィールドを追加します。関数にデバッグ情報がなければ、テーブルは空です。
たとえば、式debug.getinfo(1,"n").nameは、妥当な名前が見つかれば現在の関数名を返します。式debug.getinfo(print)は、関数printについて利用可能なすべての情報を持つテーブルを返します。
debug.getlocal ([thread,] f, local)
この関数は、スタックのレベルfにある関数について、インデックスlocalのローカル変数の名前と値を返します。この関数は明示的なローカル変数だけでなく、引数と一時値にもアクセスします。
最初の引数またはローカル変数のインデックスは1で、以降も同様です。コード内で宣言された順序に従い、関数の現在のスコープでアクティブな変数だけを数えます。コンパイル時定数がコンパイラーによって最適化で除去された場合、この一覧に現れないことがあります。負のインデックスは可変長引数を参照し、-1が最初の可変長引数です。これらの負のインデックスを利用できるのは、可変長引数テーブルが最適化で除去されている場合だけです。それ以外の場合、可変長引数は可変長引数テーブル内で利用できます。
指定されたインデックスの変数がなければ、関数はfailを返します。範囲外のレベルを指定して呼び出すとエラーを発生させます。（debug.getinfoを呼び出してレベルが有効か確認できます。）
‘(’（開き丸括弧）で始まる変数名は、名前が不明な変数（ループ制御変数などの内部変数や、デバッグ情報なしで保存されたチャンクの変数）を表します。
引数fには関数を指定することもできます。その場合、getlocalは関数の引数名だけを返します。
debug.getmetatable (value)
指定されたvalueのメタテーブルを返します。メタテーブルがなければnilを返します。
debug.getregistry ()
レジストリテーブルを返します（§4.3を参照）。
debug.getupvalue (f, up)
この関数は、関数fのインデックスupにある上位値の名前と値を返します。指定されたインデックスの上位値がなければfailを返します。
（Lua関数において、上位値とは関数が使用し、その結果クロージャーに含まれる外部のローカル変数です。）
C関数では、この関数はすべての上位値の名前として空文字列""を使います。
変数名’?’（疑問符）は、名前が不明な変数（デバッグ情報なしで保存されたチャンクの変数）を表します。
debug.getuservalue (u, n)
ユーザーデータuに関連付けられたn番目のユーザー値とブール値を返します。ユーザーデータにその値がなければブール値はfalseです。
debug.sethook ([thread,] hook, mask [, count])
指定された関数をデバッグフックとして設定します。文字列maskと数値countは、フックを呼び出す時点を指定します。文字列のマスクには、次の文字を任意に組み合わせられます。それぞれの意味は次のとおりです。
- ‘
c’：Luaが関数を呼び出すたびにフックを呼び出します。 - ‘
r’：Luaが関数から戻るたびにフックを呼び出します。 - ‘
l’：Luaがコードの新しい行に入るたびにフックを呼び出します。 さらに、countが0でない場合、count個の命令を実行するたびにもフックを呼び出します。
引数なしで呼び出すと、debug.sethookはフックを無効にします。
フックが呼び出されるとき、第1引数は呼び出しを発生させたイベントを表す文字列、"call"、"tail call"、"return"、"line"、"count"のいずれかです。行イベントの場合、フックは第2引数として新しい行番号も受け取ります。フック内では、レベル2を指定してgetinfoを呼び出すことで、実行中の関数に関する詳細情報を取得できます。（レベル0は関数getinfo、レベル1はフック関数です。）
debug.setlocal ([thread,] level, local, value)
この関数は、スタックのレベルlevelにある関数について、インデックスlocalのローカル変数へ値valueを代入します。指定されたインデックスのローカル変数がなければfailを返し、範囲外のlevelを指定して呼び出すとエラーを発生させます。（getinfoを呼び出してレベルが有効か確認できます。）それ以外の場合、ローカル変数の名前を返します。
変数のインデックスと名前の詳細については、debug.getlocalを参照してください。
debug.setmetatable (value, table)
指定されたvalueのメタテーブルを、指定されたtable（nilでも可）に設定します。valueを返します。
debug.setupvalue (f, up, value)
この関数は、関数fのインデックスupにある上位値へ値valueを代入します。指定されたインデックスの上位値がなければfailを返します。それ以外の場合、上位値の名前を返します。
上位値の詳細については、debug.getupvalueを参照してください。
debug.setuservalue (udata, value, n)
指定されたvalueを、指定されたudataに関連付けられたn番目のユーザー値として設定します。udataはフルユーザーデータでなければなりません。
udataを返します。ユーザーデータにその値がなければfailを返します。
debug.traceback ([thread,] [message [, level]])
messageが存在するものの、文字列でもnilでもない場合、この関数は追加の処理をせずmessageを返します。それ以外の場合、コールスタックのトレースバックを持つ文字列を返します。省略可能な文字列messageはトレースバックの先頭に追加されます。省略可能な数値levelは、トレースバックを開始するレベルを指定します（デフォルトは1、tracebackを呼び出した関数）。
debug.upvalueid (f, n)
指定された関数のn番目の上位値について、一意な識別子をライトユーザーデータとして返します。
これらの一意な識別子により、異なるクロージャーが上位値を共有しているかをプログラムから確認できます。上位値を共有する（つまり、同じ外部ローカル変数へアクセスする）Luaクロージャーは、それらの上位値インデックスについて同一のIDを返します。
debug.upvaluejoin (f1, n1, f2, n2)
Luaクロージャーf1のn1番目の上位値が、Luaクロージャーf2のn2番目の上位値を参照するようにします。