KJS

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

KDE's Doxygen guidelines are available online.