Skip to content

Commit e49f68c

Browse files
gilzoidegilzoide
committed
Update docs around LuaDebug
1 parent dba2e03 commit e49f68c

File tree

3 files changed

+83
-0
lines changed

3 files changed

+83
-0
lines changed

‎doc_classes/LuaDebug.xml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="LuaDebug" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd">
3+
<brief_description>
4+
A structure used to carry different pieces of information about a Lua function or an activation record.
5+
</brief_description>
6+
<description>
7+
See [url]https://www.lua.org/manual/5.4/manual.html#lua_Debug[/url].
8+
</description>
9+
<tutorials>
10+
</tutorials>
11+
<methods>
12+
<method name="is_tail_call" qualifiers="const">
13+
<return type="bool" />
14+
<description>
15+
Returns [code]true[/code] if this function invocation was called by a tail call. In this case, the caller of this level is not in the stack.
16+
</description>
17+
</method>
18+
<method name="is_vararg" qualifiers="const">
19+
<return type="bool" />
20+
<description>
21+
Returns [code]true[/code] if the function is a variadic function (always true for C functions).
22+
</description>
23+
</method>
24+
</methods>
25+
<members>
26+
<member name="current_line" type="int" setter="" getter="get_current_line">
27+
The current line where the given function is executing. When no line information is available, current_line is set to -1.
28+
</member>
29+
<member name="event" type="int" setter="" getter="get_event" enum="LuaThread.HookEvent">
30+
Hook event that generated this activation record. Only meaningful during hooks.
31+
</member>
32+
<member name="last_line_defined" type="int" setter="" getter="get_last_line_defined">
33+
The line number where the definition of the function ends.
34+
</member>
35+
<member name="line_defined" type="int" setter="" getter="get_line_defined">
36+
The line number where the definition of the function starts.
37+
</member>
38+
<member name="name" type="String" setter="" getter="get_name">
39+
A reasonable name for the given function. Because functions in Lua are first-class values, they do not have a fixed name: some functions can be the value of multiple global variables, while others can be stored only in a table field. If Lua cannot find a name, then name is empty.
40+
</member>
41+
<member name="name_what" type="String" setter="" getter="get_name_what">
42+
Explains the name field. The value of name_what can be "global", "local", "method", "field", "upvalue", or "" (the empty string), according to how the function was called. (Lua uses the empty string when no other option seems to apply.)
43+
</member>
44+
<member name="nparams" type="int" setter="" getter="get_nparams">
45+
The number of parameters of the function (always 0 for C functions).
46+
</member>
47+
<member name="short_src" type="String" setter="" getter="get_short_src">
48+
A "printable" version of source, to be used in error messages.
49+
</member>
50+
<member name="source" type="String" setter="" getter="get_source">
51+
The source of the chunk that created the function. If source starts with a '@', it means that the function was defined in a file where the file name follows the '@'. If source starts with a '=', the remainder of its contents describes the source in a user-dependent manner. Otherwise, the function was defined in a string where source is that string.
52+
</member>
53+
<member name="what" type="String" setter="" getter="get_what">
54+
The string "Lua" if the function is a Lua function, "C" if it is a C function, "main" if it is the main part of a chunk.
55+
</member>
56+
</members>
57+
</class>

‎doc_classes/LuaFunction.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,12 @@
1010
<tutorials>
1111
</tutorials>
1212
<methods>
13+
<method name="get_debug_info" qualifiers="const">
14+
<return type="LuaDebug" />
15+
<description>
16+
Get the debug information available about this function.
17+
</description>
18+
</method>
1319
<method name="invoke" qualifiers="const vararg">
1420
<return type="Variant" />
1521
<description>

‎doc_classes/LuaThread.xml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,19 +34,26 @@
3434
<method name="get_stack_info" qualifiers="const">
3535
<return type="LuaDebug[]" />
3636
<description>
37+
Get debug information about the stack of this thread of execution.
3738
</description>
3839
</method>
3940
<method name="get_stack_level_info" qualifiers="const">
4041
<return type="LuaDebug" />
4142
<param index="0" name="level" type="int" />
4243
<description>
44+
Get debug information about the activation record of the function executing at a given [param level].
45+
Level 0 is the current running function, whereas level n+1 is the function that has called level n (except for tail calls, which do not count in the stack).
46+
When called with a level greater than the stack depth, returns [code]null[/code].
4347
</description>
4448
</method>
4549
<method name="get_traceback" qualifiers="const">
4650
<return type="String" />
4751
<param index="0" name="message" type="String" default="&quot;&quot;" />
4852
<param index="1" name="level" type="int" default="0" />
4953
<description>
54+
Returns a traceback of the stack.
55+
[param message] is appended at the beginning of the traceback.
56+
[param level] tells at which level to start the traceback.
5057
</description>
5158
</method>
5259
<method name="is_main_thread" qualifiers="const">
@@ -68,6 +75,19 @@
6875
[param count] is only meaningful when the mask includes [constant HOOK_MASK_COUNT].
6976
See [enum HookEvent] for the available hook events.
7077
See also [url]https://www.lua.org/manual/5.4/manual.html#lua_sethook[/url].
78+
[codeblocks]
79+
[gdscript]
80+
var line_hook := func(ar: LuaDebug): prints("Running line: ", ar.current_line)
81+
var state := LuaState.new()
82+
state.main_thread.set_hook(line_hook, LuaThread.HOOK_MASK_LINE)
83+
# The line hook will be called once for each line of Lua code
84+
state.do_string("""
85+
local line1 = 1
86+
local line2 = 2
87+
local line3 = 3
88+
""")
89+
[/gdscript]
90+
[/codeblocks]
7191
</description>
7292
</method>
7393
</methods>

0 commit comments

Comments
 (0)