AngelScript
Debugger

Path: /sdk/add_on/debugger/

The CDebugger implements common debugging functionality for scripts, e.g. setting breakpoints, stepping through the code, examining values of variables, etc.

To use the debugger the line callback should be set in the context. This will allow the debugger to take over whenever a breakpoint is reached, so the script can be debugged.

By default the debugger uses the standard in and standard out streams to interact with the user, but this can be easily overloaded by deriving from the CDebugger class and implementing the methods TakeCommands and Output. With this it is possible to implement a graphical interface, or even remote debugging for an application.

The application developer may also be interested in registering to-string callbacks for registered types with calls to RegisterToStringCallback. Optionally the ToString method in the debugger can be overridden to implement custom to-string logic.

See also
The sample Command line runner for a complete example of how to use the debugger

Public C++ interface

class CDebugger
{
public:
CDebugger();
virtual ~CDebugger();
// Register callbacks to handle to-string conversions of application types
// The expandMembersLevel is a counter for how many recursive levels the members should be expanded.
// If the object that is being converted to a string has members of its own the callback should call
// the debugger's ToString passing in expandMembersLevel - 1.
typedef std::string (*ToStringCallback)(void *obj, int expandMembersLevel, CDebugger *dbg);
virtual void RegisterToStringCallback(const asITypeInfo *type, ToStringCallback callback);
// User interaction
virtual void TakeCommands(asIScriptContext *ctx);
virtual void Output(const std::string &str);
// Line callback invoked by context
virtual void LineCallback(asIScriptContext *ctx);
// Commands
virtual void PrintHelp();
virtual void AddFileBreakPoint(const std::string &file, int lineNbr);
virtual void AddFuncBreakPoint(const std::string &func);
virtual void ListBreakPoints();
virtual void ListLocalVariables(asIScriptContext *ctx);
virtual void ListGlobalVariables(asIScriptContext *ctx);
virtual void ListMemberProperties(asIScriptContext *ctx);
virtual void ListStatistics(asIScriptContext *ctx);
virtual void PrintCallstack(asIScriptContext *ctx);
virtual void PrintValue(const std::string &expr, asIScriptContext *ctx);
// Helpers
virtual bool InterpretCommand(const std::string &cmd, asIScriptContext *ctx);
virtual bool CheckBreakPoint(asIScriptContext *ctx);
virtual std::string ToString(void *value, asUINT typeId, int expandMembersLevel, asIScriptEngine *engine);
// Optionally set the engine pointer in the debugger so it can be retrieved
// by callbacks that need it. This will hold a reference to the engine.
virtual void SetEngine(asIScriptEngine *engine);
virtual asIScriptEngine *GetEngine();
};

Example usage

CDebugger dbg;
int ExecuteWithDebug(asIScriptContext *ctx)
{
// Tell the context to invoke the debugger's line callback
ctx->SetLineCallback(asMETHOD(CDebugger, LineCallback), &dbg, asCALL_THISCALL);
// Allow the user to initialize the debugging before moving on
dbg.TakeCommands(ctx);
// Execute the script normally. If a breakpoint is reached the
// debugger will take over the control loop.
return ctx->Execute();
}
asIScriptContext
The interface to the virtual machine.
Definition: angelscript.h:2717
asIScriptContext::Execute
virtual int Execute()=0
Executes the prepared function.
asIScriptEngine
The engine interface.
Definition: angelscript.h:1092
asITypeInfo
The interface for describing types This interface is used to describe the types in the script engine.
Definition: angelscript.h:3527
asMETHOD
#define asMETHOD(c, m)
Returns an asSFuncPtr representing the class method specified by class and method name.
Definition: angelscript.h:740
asIScriptContext::SetLineCallback
virtual int SetLineCallback(asSFuncPtr callback, void *obj, int callConv)=0
Sets a line callback function. The function will be called for each executed script statement.
asCALL_THISCALL
@ asCALL_THISCALL
A thiscall class method.
Definition: angelscript.h:232
asUINT
unsigned int asUINT
32 bit unsigned integer
Definition: angelscript.h:600