1 | // -*- c-basic-offset: 2 -*- |
2 | /* |
3 | * This file is part of the KDE libraries |
4 | * Copyright (C) 1999-2001 Harri Porten (porten@kde.org) |
5 | * Copyright (C) 2001 Peter Kelly (pmk@post.com) |
6 | * |
7 | * This library is free software; you can redistribute it and/or |
8 | * modify it under the terms of the GNU Lesser General Public |
9 | * License as published by the Free Software Foundation; either |
10 | * version 2 of the License, or (at your option) any later version. |
11 | * |
12 | * This library is distributed in the hope that it will be useful, |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | * Lesser General Public License for more details. |
16 | * |
17 | * You should have received a copy of the GNU Lesser General Public |
18 | * License along with this library; if not, write to the Free Software |
19 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
20 | * |
21 | */ |
22 | |
23 | #ifndef _KJSDEBUGGER_H_ |
24 | #define _KJSDEBUGGER_H_ |
25 | |
26 | #include "global.h" |
27 | #include <wtf/HashMap.h> |
28 | #include "protect.h" |
29 | |
30 | namespace KJS { |
31 | |
32 | class DebuggerImp; |
33 | class Interpreter; |
34 | class ExecState; |
35 | class JSObject; |
36 | class JSValue; |
37 | class UString; |
38 | class List; |
39 | class FunctionBodyNode; |
40 | |
41 | /** |
42 | * @internal |
43 | * |
44 | * Provides an interface which receives notification about various |
45 | * script-execution related events such as statement execution and function |
46 | * calls. |
47 | * |
48 | * WARNING: This interface is still a work in progress and is not yet |
49 | * officially publicly available. It is likely to change in binary incompatible |
50 | * (and possibly source incompatible) ways in future versions. It is |
51 | * anticipated that at some stage the interface will be frozen and made |
52 | * available for general use. |
53 | */ |
54 | class KJS_EXPORT Debugger { |
55 | public: |
56 | |
57 | /** |
58 | * Creates a new debugger |
59 | */ |
60 | Debugger(); |
61 | |
62 | /** |
63 | * Destroys the debugger. If the debugger is attached to any interpreters, |
64 | * it is automatically detached. |
65 | */ |
66 | virtual ~Debugger(); |
67 | |
68 | DebuggerImp *imp() const { return rep; } |
69 | |
70 | /** |
71 | * Attaches the debugger to specified interpreter. This will cause this |
72 | * object to receive notification of events from the interpreter. |
73 | * |
74 | * If the interpreter is deleted, the debugger will automatically be |
75 | * detached. |
76 | * |
77 | * Note: only one debugger can be attached to an interpreter at a time. |
78 | * Attaching another debugger to the same interpreter will cause the |
79 | * original debugger to be detached from that interpreter. |
80 | * |
81 | * @param interp The interpreter to attach to |
82 | * |
83 | * @see detach() |
84 | */ |
85 | virtual void attach(Interpreter *interp); |
86 | |
87 | /** |
88 | * Detach the debugger from an interpreter |
89 | * |
90 | * @param interp The interpreter to detach from. If 0, the debugger will be |
91 | * detached from all interpreters to which it is attached. |
92 | * |
93 | * @see attach() |
94 | */ |
95 | virtual void detach(Interpreter *interp); |
96 | |
97 | /** |
98 | * Called to notify the debugger that some javascript source code has |
99 | * been parsed. For calls to Interpreter::evaluate(), this will be called |
100 | * with the supplied source code before any other code is parsed. |
101 | * Other situations in which this may be called include creation of a |
102 | * function using the Function() constructor, or the eval() function. |
103 | * |
104 | * The default implementation does nothing. Override this method if |
105 | * you want to process this event. |
106 | * |
107 | * @param exec The current execution state |
108 | * @param sourceId The ID of the source code (corresponds to the |
109 | * sourceId supplied in other functions such as atStatement() |
110 | * @param sourceURL Where the source code that was parsed came from |
111 | * @param source The source code that was parsed |
112 | * @param startingLineNumber The line number at which parsing started |
113 | * @param errorLine The line number at which parsing encountered an |
114 | * error, or -1 if the source code was valid and parsed successfully |
115 | * @param errorMsg The error description, or null if the source code |
116 | was valid and parsed successfully |
117 | * @return true if execution should be continue, false if it should |
118 | * be aborted |
119 | */ |
120 | virtual bool sourceParsed(ExecState *exec, int sourceId, const UString &sourceURL, |
121 | const UString &source, int startingLineNumber, int errorLine, const UString &errorMsg); |
122 | |
123 | /** |
124 | * Called when an exception is thrown during script execution. |
125 | * |
126 | * The default implementation does nothing. Override this method if |
127 | * you want to process this event. |
128 | * |
129 | * @param exec The current execution state |
130 | * @param sourceId The ID of the source code being executed |
131 | * @param lineno The line at which the error occurred |
132 | * @param exception The exception object |
133 | * @return true if execution should be continue, false if it should |
134 | * be aborted |
135 | */ |
136 | virtual bool exception(ExecState *exec, int sourceId, int lineno, |
137 | JSValue *exception); |
138 | |
139 | bool hasHandledException(ExecState *, JSValue *); |
140 | |
141 | /** |
142 | * Called when a line of the script is reached (before it is executed) |
143 | * |
144 | * The default implementation does nothing. Override this method if |
145 | * you want to process this event. |
146 | * |
147 | * @param exec The current execution state |
148 | * @param sourceId The ID of the source code being executed |
149 | * @param firstLine The starting line of the statement that is about to be |
150 | * executed |
151 | * @param lastLine The ending line of the statement that is about to be |
152 | * executed (usually the same as firstLine) |
153 | * @return true if execution should be continue, false if it should |
154 | * be aborted |
155 | */ |
156 | virtual bool atStatement(ExecState *exec, int sourceId, int firstLine, |
157 | int lastLine); |
158 | /** |
159 | * Called when the interpreter enters a new execution context (stack |
160 | * frame). This can happen in three situations: |
161 | * |
162 | * <ul> |
163 | * <li>A call to Interpreter::evaluate(). This has a codeType of |
164 | * GlobalCode </li> |
165 | * <li>A call to the builtin eval() function. The sourceId corresponds to |
166 | * the code passed in to eval. This has a codeType of EvalCode. The |
167 | * lineno here is always 0 since execution starts at the beginning of |
168 | * the script.</li> |
169 | * <li>A function call. This only occurs for functions defined in |
170 | * ECMAScript code, whether via the normal function() { ... } syntax or |
171 | * a call to the built-in Function() constructor (anonymous functions). |
172 | * In the former case, the sourceId and lineno indicate the location at |
173 | * which the function was defined. For anonymous functions, the sourceId |
174 | * corresponds to the code passed into the Function() constructor.</li> |
175 | * </ul> |
176 | * |
177 | * enterContext() is not called for functions implemented in the native |
178 | * code, since these do not use an execution context. |
179 | * |
180 | * @param exec The current execution state (corresponding to the new stack) |
181 | * @param sourceId The ID of the source code being executed |
182 | * @param lineno The line that is about to be executed |
183 | * @param function The function being called. 0 in non-function context. |
184 | * @param args The arguments that were passed to the function |
185 | * line is being executed. Empty in non-function contexts. |
186 | * |
187 | * @return true if execution should be continued, false if it should |
188 | * be aborted |
189 | */ |
190 | virtual bool enterContext(ExecState *exec, int sourceId, int lineno, |
191 | JSObject *function, const List &args); |
192 | |
193 | /** |
194 | * Called when the inteprreter exits an execution context. This always |
195 | * corresponds to a previous call to enterContext() |
196 | * |
197 | * The default implementation does nothing. Override this method if |
198 | * you want to process this event. |
199 | * |
200 | * @param exec The current execution state |
201 | * @param sourceId The ID of the source code being executed |
202 | * @param lineno The line that is about to be executed |
203 | * @param function The function being returned from, if there is one |
204 | * @return true if execution should be continue, false if it should |
205 | * be aborted |
206 | */ |
207 | virtual bool exitContext(ExecState *exec, int sourceId, int lineno, |
208 | JSObject *function); |
209 | |
210 | |
211 | // Override this and return true if you want the debugger to report |
212 | // pretty-printed versions of the source. |
213 | virtual bool shouldReindentSources() const; |
214 | |
215 | // Override this to return true if the debugger should report |
216 | // exceptions even if there is a try block waiting for it. |
217 | virtual bool shouldReportCaught() const; |
218 | |
219 | // The two methods below call the events but also keep track/use of line # information |
220 | // so we can associate it with exceptions |
221 | void reportAtStatement(ExecState *exec, int sourceId, int firstLine, int lastLine); |
222 | void reportException (ExecState *exec, JSValue *exception); |
223 | |
224 | // This notifies the debugger of source being parsed, reindenting it if need be. |
225 | void reportSourceParsed(ExecState *exec, FunctionBodyNode *body, int sourceId, UString sourceURL, |
226 | const UString &source, int startingLineNumber, int errorLine, const UString &errorMsg); |
227 | private: |
228 | DebuggerImp *rep; |
229 | HashMap<Interpreter*, ProtectedPtr<JSValue> > latestExceptions; |
230 | int lastLineRan; |
231 | int lastSourceParsed; // Needed for attributing syntax exceptions at top-level |
232 | public: |
233 | static int debuggersPresent; |
234 | }; |
235 | |
236 | } |
237 | |
238 | #endif |
239 | |
240 | // kate: indent-width 4; replace-tabs on; tab-width 4; space-indent on; |
241 | |