Debug 库教程

wiki

我实在受不了这里是空的，所以我直接从手册里摘了出来。随时可以根据自己的经验用自己的话来修改。这仍然是一个 wiki，请随意编辑。

6.10 Debug 库

这个库为 Lua 程序提供了调试接口（4.9）的功能。使用这个库时应格外小心。它的许多函数违反了关于 Lua 代码的基本假设（例如，函数内部的局部变量不能从外部访问；用户数据元表不能被 Lua 代码更改； Lua 程序不会崩溃），因此会损害原本安全的代码。此外，这个库中的一些函数可能会很慢。

这个库中的所有函数都包含在 debug 表中。所有操作线程的函数都有一个可选的第一个参数，即要操作的线程。默认始终是当前线程。

debug.debug ()

进入与用户的交互模式，执行用户输入的每个字符串。通过简单的命令和其他调试工具，用户可以检查全局和局部变量，更改它们的值，求值表达式等等。仅包含“cont”一词的一行将结束此函数，使调用者继续执行。

请注意，debug.debug 的命令不是在任何函数中词法嵌套的，因此无法直接访问局部变量。

debug.gethook ([thread])

返回线程的当前钩子设置，包括三个值：当前的钩子函数、当前的钩子掩码以及当前的钩子计数（由 debug.sethook 函数设置）。

debug.getinfo ([thread,] f [, what])

返回一个包含函数信息的表。你可以直接提供函数，或者提供一个数字作为 f 的值，这意味着给定线程调用堆栈中级别为 f 的正在运行的函数：级别 0 是当前函数（getinfo 本身）；级别 1 是调用 getinfo 的函数（尾调用除外，尾调用不计入堆栈）；依此类推。如果 f 大于活动函数的数量，则 getinfo 返回 nil。

返回的表可以包含 lua_getinfo 返回的所有字段，字符串 what 描述了要填充哪些字段。what 的默认值是获取所有可用信息，但不包括有效行的表。如果存在，选项 'f' 会添加一个名为 func 的字段，其中包含函数本身。如果存在，选项 'L' 会添加一个名为 activelines 的字段，其中包含有效行的表。

例如，表达式 debug.getinfo(1,"n").name 返回一个包含当前函数名称的表（如果能找到合理的名称），而表达式 debug.getinfo(print) 返回一个包含 print 函数所有可用信息的表。

debug.getlocal ([thread,] f, local)

此函数返回堆栈级别为 f 的函数中索引为 local 的局部变量的名称和值。此函数不仅访问显式局部变量，还访问参数、临时变量等。

第一个参数或局部变量的索引为 1，依此类推，直到最后一个活动变量。负索引引用 vararg 参数；-1 是第一个 vararg 参数。如果不存在指定索引的变量，则函数返回 nil，当以超出范围的级别调用时会引发错误。（你可以调用 debug.getinfo 来检查级别是否有效。）

以“("（开括号）开头的变量名表示内部变量（循环控制变量、临时变量、varargs 和 C 函数局部变量）。

参数 f 也可以是一个函数。在这种情况下，getlocal 只返回函数参数的名称。

debug.getmetatable (value)

返回给定值的元表，如果它没有元表则返回 nil。

debug.getregistry ()

返回注册表（参见 4.5）。

debug.getupvalue (f, up)

此函数返回函数 f 中索引为 up 的上值的名称和值。如果不存在指定索引的上值，则函数返回 nil。

debug.getuservalue (u)

返回与 u 关联的 Lua 值。如果 u 不是 userdata，则返回 nil。

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

将给定的函数设置为钩子。字符串 mask 和数字 count 描述了钩子何时被调用。字符串 mask 可能包含以下字符，含义如下：

'c'：Lua 调用函数时会调用钩子； 'r'：Lua 从函数返回时会调用钩子； 'l'：Lua 进入新代码行时会调用钩子。当 count 不为零时，钩子会在每 count 条指令后被调用。

当不带参数调用时，debug.sethook 会关闭钩子。

当钩子被调用时，它的第一个参数是一个描述触发其调用的事件的字符串：“call”（或“tail call”）、“return”、“line”和“count”。对于 line 事件，钩子还会接收新行号作为第二个参数。在钩子内部，你可以调用 getinfo 级别 2 来获取有关正在运行函数的更多信息（级别 0 是 getinfo 函数，级别 1 是钩子函数）。

debug.setlocal ([thread,] level, local, value)

此函数将值 value 分配给堆栈级别为 level 的函数中索引为 local 的局部变量。如果不存在指定索引的局部变量，则函数返回 nil，当以超出范围的级别调用时会引发错误。（你可以调用 getinfo 来检查级别是否有效。）否则，它会返回局部变量的名称。

有关变量索引和名称的更多信息，请参见 debug.getlocal。

debug.setmetatable (value, table)

将给定值的元表设置为给定的表（可以为 nil）。返回 value。

debug.setupvalue (f, up, value)

此函数将值 value 分配给函数 f 中索引为 up 的上值。如果不存在指定索引的上值，则函数返回 nil。否则，它会返回上值的名称。

debug.setuservalue (udata, value)

将给定的值设置为与给定 udata 关联的 Lua 值。value 必须是一个表或 nil；udata 必须是一个完整的 userdata。

返回 udata。

debug.traceback ([thread,] [message [, level]])

如果 message 存在但既不是字符串也不是 nil，此函数将不经进一步处理地返回 message。否则，它将返回一个包含调用堆栈跟踪的字符串。一个可选的消息字符串将附加在堆栈跟踪的开头。一个可选的级别数字用于指定从哪个级别开始堆栈跟踪（默认为 1，即调用 traceback 的函数）。

debug.upvalueid (f, n)

返回给定函数中编号为 n 的上值的唯一标识符（作为轻量级 userdata）。

这些唯一标识符允许程序检查不同的闭包是否共享上值。共享上值（即访问同一外部局部变量）的 Lua 闭包将为其上值索引返回相同的 ID。

debug.upvaluejoin (f1, n1, f2, n2)

使 Lua 闭包 f1 的第 n1 个上值引用 Lua 闭包 f2 的第 n2 个上值。在 Lua 5.3 和 5.2 中可用，但在 Lua 5.1 中不可用。

> local x = 0; function add_to_x(val) x = x + val; return x end
> local y = 0; function add_to_y(val) y = y + val; return y end
> = add_to_x(10)
10
> = add_to_y(20)
20
> debug.upvaluejoin(add_to_x, 1, add_to_y, 1) -- make the variable x in add_to_x refer to the upvalue y in add_to_y
> = add_to_x(0)
20
> = add_to_y(0)
20
> = add_to_x(10)
30
> = add_to_y(0)
30

-- ^ 直接摘自手册

评论

我不认为页面可以在没有内容的情况下创建。wiki 上有十几个骨架页面等待着可能永远不会出现的内容。而且，这里的参考布局是否与教程的目标相悖？--JohnBelmonte

~=不再为空=~

总的来说，我同意关于骨架页面的观点。为了与其他库教程保持一致，这个页面也需要填入内容。

~=不再需要填写=~

我也对库教程的结构感到担忧。例如，我们有 StringsTutorial 和 TablesTutorial 介绍了这些数据类型的基础特性。然后我们有 StringLibraryTutorial 和 TableLibraryTutorial 大致按字母顺序列出了所有模块函数，每个函数都有示例，并有一些对 Lua 参考手册描述的重复。这遵循教程的唯一方式是每个函数描述部分都以示例为导向。然而，从高层次来看，它并没有按照教程的结构来组织，要做到这一点需要做一些工作。另请参阅 LuaReferenceManualComments。

--DavidManura

嗯，它是一个 wiki！:) 我在这里创建它，以便其他人可以编辑它。而且他们似乎整体上做得很好。就像其他类型一样，StringsTutorial 只是为了展示特定的类型，而库教程则展示了用法示例，而 Lua 文档缺乏这些。我个人认为这是快速掌握新语言的最简单方法。口味可能不同。还有其他信息来源，比如代码片段等。我也发现参考类型的布局对于忘记某个功能时快速查找很有用。同样，口味可能不同；有些人可能更喜欢冗长的描述和用法讨论。-- 其他页面确实是留空的，希望人们会填补它们。我也还没来得及做。一开始 wiki 的结构很少，我对于 wiki 的经验是，如果有人不温和地、有指导性地拥有它，它可能会变得一团糟。--NickTrout

~=已编辑~=

我实在受不了这里是空的。