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
30namespace 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