Editing WoW:API debugstack

{{wowapi}}

Output a string representation of the current calling stack, similar to the standard Lua debug.traceback() call, which is not present in WoW.

 description = debugstack([thread, ][start[, count1[, count2]]]])

== Arguments ==
=== Parameters ===
:;thread:Thread - a coroutine thread, obtained with coroutine.create(). Use to inspect the current call stack inside a coroutine that has yielded or died.
:;start
:Number - the stack depth at which to start the stack trace (default 1 - the function calling debugstack)
:;count1:Number - the number of functions to output at the top of the stack (default 12)
:;count2:Number - the number of functions to output at the bottom of the stack (default 10)

=== Returns ===
:;description:String - a multi-line string showing what the current call stack looks like

If there are more than count1+count2 calls in the stack, they are separated by a "..." line.

== Example ==

Assume the following example file, "file.lua":

  1: function a()
  2:   error("Boom!"); 
  3: end
  4:
  5: function b() a(); end
  6:
  7: function c() b(); end
  8:
  9: function d() c(); end
 10:
 11: function e() d(); end
 12:
 13: function f() e(); end
 14:
 15: function errhandler(msg)
 16:   print (msg .. "\nCall stack: \n" .. debugstack(2, 3, 2));
 17: end
 18:
 19: xpcall(f, errhandler);

This would output something along the following:

 file.lua:2: Boom!
 Call stack:
 file.lua:2: in function a
 file.lua:5: in function b
 file.lua:7: in function c
 ...
 file.lua:13: in function f
 file.lua:19
  

== Example 2 ==
Combining debugstack with a strmatch can enable you to get the current line of a function call.
  1: function debugprint(msg)
  2:   local line = strmatch(debugstack(2),":(%d):");
  3:   print("Debug Print on Line "..line.." with message: "..msg);
  4: end
  5:
  6: function doSomething()
  7:   debugprint("We tried to do something.");
  8: end
This would return the following output from print:
 Debug Print on Line 7 with message: We tried to do something.

== Example 3 ==
Using debugstack to find out the location of an error in a coroutine.
  1: function f()
  2:   print ("a">0)  -- this will cause an error
  3: end
  4:
  5: thread = coroutine.create(f)
  6: executed_ok,message = coroutine.resume(thread)
  7:
  8: if not executed_ok then
  9:   print("Error: "..message.." in "..debugstack(thread))
 10: end

Note that despite its all-lowercase name, this is not a core [[Lua]] function. It is a WoW API.