Skip to content

Commit cee4eda

Browse files
tchu-robloxtchu-roblox
authored
Revert "Removed duplicates of debug.info() (#1085)"
This reverts commit 4c02adc.
1 parent 631b131 commit cee4eda

File tree

1 file changed

+176
-33
lines changed
  • content/en-us/reference/engine/libraries

1 file changed

+176
-33
lines changed

‎content/en-us/reference/engine/libraries/debug.yaml‎

Lines changed: 176 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,57 @@ functions:
2424
the call of the function calling `Library.debug.traceback()`, and so on.
2525
See the code sample below for an example of sequential function calls.
2626
27-
This function can accept two variations in its parameters:
27+
Note that this function will often return inaccurate results (compared to
28+
the original source code) and that the format of the returned traceback
29+
may change at any time. You should **not** parse the return value for
30+
specific information such as script names or line numbers.
2831
29-
- `debug.traceback(message, level)`
30-
- `debug.traceback(thread, message, level)` — Similar except the first parameter is a thread as returned by `Library.coroutine.create()`.
32+
The following example includes sequential function calls; `fnB()` is
33+
called, and it calls `fnA()` which then calls `Library.debug.traceback()`.
34+
35+
```lua
36+
local function fnA()
37+
print(debug.traceback("Specific moment during fnA()"))
38+
end
39+
40+
local function fnB()
41+
fnA()
42+
end
43+
44+
-- Call function fnB() to begin traceback
45+
fnB()
46+
```
47+
parameters:
48+
- name: message
49+
type: string
50+
default: ''
51+
summary: |
52+
The first line of the returned string.
53+
- name: level
54+
type: number
55+
default: 1
56+
summary: |
57+
The number of calls "up" the call stack to return.
58+
returns:
59+
- type: string
60+
summary: |
61+
Traceback of the current function call stack.
62+
tags:
63+
code_samples:
64+
- name: debug.traceback
65+
summary: |
66+
Returns a string of undefined format that describes the current function
67+
call stack.
68+
description: |
69+
Returns a traceback of the current function call stack as a string; in
70+
other words, a description of the functions that have been called up to
71+
this point. During debugging, this behaves like an error stack trace but
72+
does not stop execution of the script.
73+
74+
The `level` parameter specifies what level of the call stack to consider,
75+
with `1` being the call of `Library.debug.traceback()` itself, `2` being
76+
the call of the function calling `Library.debug.traceback()`, and so on.
77+
See the code sample below for an example of sequential function calls.
3178
3279
Note that this function will often return inaccurate results (compared to
3380
the original source code) and that the format of the returned traceback
@@ -51,10 +98,10 @@ functions:
5198
```
5299
parameters:
53100
- name: thread
54-
type: thread?
101+
type: thread
55102
default:
56103
summary: |
57-
Optional thread as returned by `Library.coroutine.create()`.
104+
A thread as returned by `Library.coroutine.create()`.
58105
- name: message
59106
type: string
60107
default: ''
@@ -82,49 +129,145 @@ functions:
82129
as well as for sending the data to systems expecting structured input,
83130
such as crash aggregation.
84131
85-
This function can accept three variations in its parameters:
132+
```lua
133+
local function fnA()
134+
-- Output source identifier ("s") and line ("l") at levels 1 and 2
135+
print(debug.info(1, "sl")) --> fnA() 3
136+
print(debug.info(2, "sl")) --> fnA() 7
137+
end
86138
87-
- `debug.info(level, options)`
139+
fnA()
140+
```
88141
89-
```lua
90-
local function fnA()
91-
-- Output source identifier ("s") and line ("l") at levels 1 and 2
92-
print(debug.info(1, "sl")) --> fnA() 3
93-
print(debug.info(2, "sl")) --> fnA() 7
94-
end
142+
Note that this function is similar to
143+
[debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
144+
the standard Lua library which serves a similar purpose.
145+
parameters:
146+
- name: level
147+
type: number
148+
default:
149+
summary: |
150+
Determines at what level of the call stack the information returned
151+
should describe. A value of `1` represents the function which is
152+
calling `Library.debug.info()`, a value of `2` represents the function
153+
that called that function, and so on.
154+
- name: options
155+
type: string
156+
default:
157+
summary: |
158+
A string that describes what the returned information should
159+
represent. It must only contain 0 or 1 instances of the characters
160+
`slnaf`, each representing a piece of information:
161+
162+
- `s` ([string](/luau/strings.md)) — The function source identifier,
163+
equal to the full name of the script the function is defined in.
164+
- `l` ([number](/luau/numbers.md)) — The line number of the function
165+
call represented by `level`.
166+
- `n` ([string](/luau/strings.md)) — The name of the function; may be
167+
`nil` for anonymous functions and C functions without an assigned
168+
debug name.
169+
- `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
170+
Arity of the function, which refers to the parameter count and
171+
whether the function is variadic.
172+
- `f` ([function](/luau/functions.md)) — The function which was
173+
inspected.
174+
returns:
175+
- type: Tuple
176+
summary: ''
177+
tags:
178+
code_samples:
179+
- name: debug.info
180+
summary: |
181+
Traverses the entire stack of current thread and returns a string
182+
containing the call stack of target function details.
183+
description: |
184+
Allows programmatic inspection of the call stack. This function differs
185+
from `Library.debug.traceback()` in that it guarantees the format of the
186+
data it returns. This is useful for general logging and filtering purposes
187+
as well as for sending the data to systems expecting structured input,
188+
such as crash aggregation.
95189
96-
fnA()
97-
```
190+
```lua
191+
local function fnA()
98192
99-
- `debug.info(thread, level, options)` — Similar to above except the first parameter is a thread as returned by `Library.coroutine.create()`.
193+
end
100194
101-
- `debug.info(function, options)`
195+
local function fnB()
102196
103-
```lua
104-
local function fnA()
105-
end
197+
end
106198
107-
local function fnB()
108-
end
199+
-- Output line ("l"), name ("n"), and identifier ("f") for both fnA() and fnB()
200+
print(debug.info(fnA, "lnf")) --> 1 fnA function: 0x75e3d3c398a81252
201+
print(debug.info(fnB, "lnf")) --> 5 fnB function: 0x6022a6dc5ccf4ab2
202+
```
109203
110-
-- Output line ("l"), name ("n"), and identifier ("f") for both fnA() and fnB()
111-
print(debug.info(fnA, "lnf")) --> 1 fnA function: 0x75e3d3c398a81252
112-
print(debug.info(fnB, "lnf")) --> 5 fnB function: 0x6022a6dc5ccf4ab2
113-
```
204+
Note that this function is similar to
205+
[debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
206+
the standard Lua library which serves a similar purpose.
114207
parameters:
115-
- name: thread
116-
type: thread?
117-
default:
118-
summary: |
119-
Optional thread as returned by `Library.coroutine.create()`.
120208
- name: function
121-
type: function?
209+
type: function
122210
default:
123211
summary: |
124212
The function of the call stack which the information returned should
125213
describe.
214+
- name: options
215+
type: string
216+
default:
217+
summary: |
218+
A string that describes what the returned information should
219+
represent. It must only contain 0 or 1 instances of the characters
220+
`slnaf`, each representing a piece of information:
221+
222+
- `s` ([string](/luau/strings.md)) — The function source identifier,
223+
equal to the full name of the script the function is defined in.
224+
- `l` ([number](/luau/numbers.md)) — The line that `function` is
225+
defined on.
226+
- `n` ([string](/luau/strings.md)) — The name of the function; may be
227+
`nil` for anonymous functions and C functions without an assigned
228+
debug name.
229+
- `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
230+
Arity of the function, which refers to the parameter count and
231+
whether the function is variadic.
232+
- `f` ([function](/luau/functions.md)) — The function which was
233+
inspected.
234+
returns:
235+
- type: Tuple
236+
summary: ''
237+
tags:
238+
code_samples:
239+
- name: debug.info
240+
summary: |
241+
Traverses the entire stack of target thread and returns a string
242+
containing the call stack of target level details.
243+
description: |
244+
Allows programmatic inspection of the call stack. This function differs
245+
from `Library.debug.traceback()` in that it guarantees the format of the
246+
data it returns. This is useful for general logging and filtering purposes
247+
as well as for sending the data to systems expecting structured input,
248+
such as crash aggregation.
249+
250+
```lua
251+
local function fnA()
252+
-- Output source identifier ("s") and line ("l") at levels 1 and 2
253+
print(debug.info(1, "sl")) --> fnA() 3
254+
print(debug.info(2, "sl")) --> fnA() 7
255+
end
256+
257+
fnA()
258+
```
259+
260+
Note that this function is similar to
261+
[debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
262+
the standard Lua library which serves a similar purpose.
263+
parameters:
264+
- name: thread
265+
type: thread
266+
default:
267+
summary: |
268+
A thread as returned by `Library.coroutine.create()`.
126269
- name: level
127-
type: number?
270+
type: number
128271
default:
129272
summary: |
130273
Determines at what level of the call stack the information returned

0 commit comments

Comments
 (0)