Reviewed by Maciej
[WebKit-https.git] / JavaScriptCore / kjs / debugger.h
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 Steet, Fifth Floor, Boston, MA  02110-1301  USA
20  *
21  */
22
23 #ifndef _KJSDEBUGGER_H_
24 #define _KJSDEBUGGER_H_
25
26 namespace KJS {
27
28   class DebuggerImp;
29   class Interpreter;
30   class ExecState;
31   class JSObject;
32   class UString;
33   class List;
34
35   /**
36    * @internal
37    *
38    * Provides an interface which receives notification about various
39    * script-execution related events such as statement execution and function
40    * calls.
41    *
42    * WARNING: This interface is still a work in progress and is not yet
43    * offically publicly available. It is likely to change in binary incompatible
44    * (and possibly source incompatible) ways in future versions. It is
45    * anticipated that at some stage the interface will be frozen and made
46    * available for general use.
47    */
48   class Debugger {
49   public:
50
51     /**
52      * Creates a new debugger
53      */
54     Debugger();
55
56     /**
57      * Destroys the debugger. If the debugger is attached to any interpreters,
58      * it is automatically detached.
59      */
60     virtual ~Debugger();
61
62     DebuggerImp *imp() const { return rep; }
63
64     /**
65      * Attaches the debugger to specified interpreter. This will cause this
66      * object to receive notification of events from the interpreter.
67      *
68      * If the interpreter is deleted, the debugger will automatically be
69      * detached.
70      *
71      * Note: only one debugger can be attached to an interpreter at a time.
72      * Attaching another debugger to the same interpreter will cause the
73      * original debugger to be detached from that interpreter.
74      *
75      * @param interp The interpreter to attach to
76      *
77      * @see detach()
78      */
79     void attach(Interpreter *interp);
80
81     /**
82      * Detach the debugger from an interpreter
83      *
84      * @param interp The interpreter to detach from. If 0, the debugger will be
85      * detached from all interpreters to which it is attached.
86      *
87      * @see attach()
88      */
89     void detach(Interpreter *interp);
90
91     /**
92      * Called to notify the debugger that some javascript source code has
93      * been parsed. For calls to Interpreter::evaluate(), this will be called
94      * with the supplied source code before any other code is parsed.
95      * Other situations in which this may be called include creation of a
96      * function using the Function() constructor, or the eval() function.
97      *
98      * The default implementation does nothing. Override this method if
99      * you want to process this event.
100      *
101      * @param exec The current execution state
102      * @param sourceId The ID of the source code (corresponds to the
103      * sourceId supplied in other functions such as atStatement()
104      * @param sourceURL Where the source code that was parsed came from
105      * @param source The source code that was parsed
106      * @param errorLine The line number at which parsing encountered an
107      * error, or -1 if the source code was valid and parsed successfully
108      * @return true if execution should be continue, false if it should
109      * be aborted
110      */
111     virtual bool sourceParsed(ExecState *exec, int sourceId, const UString &sourceURL,
112                               const UString &source, int errorLine);
113
114     /**
115      * Called when all functions/programs associated with a particular
116      * sourceId have been deleted. After this function has been called for
117      * a particular sourceId, that sourceId will not be used again.
118      *
119      * The default implementation does nothing. Override this method if
120      * you want to process this event.
121      *
122      * @param exec The current execution state
123      * @param sourceId The ID of the source code (corresponds to the
124      * sourceId supplied in other functions such as atLine()
125      * @return true if execution should be continue, false if it should
126      * be aborted
127      */
128     virtual bool sourceUnused(ExecState *exec, int sourceId);
129
130     /**
131      * Called when an exception is thrown during script execution.
132      *
133      * The default implementation does nothing. Override this method if
134      * you want to process this event.
135      *
136      * @param exec The current execution state
137      * @param sourceId The ID of the source code being executed
138      * @param lineno The line at which the error occurred
139      * @param exceptionObj The exception object
140      * @return true if execution should be continue, false if it should
141      * be aborted
142      */
143     virtual bool exception(ExecState *exec, int sourceId, int lineno,
144                            JSObject *exceptionObj);
145
146     /**
147      * Called when a line of the script is reached (before it is executed)
148      *
149      * The default implementation does nothing. Override this method if
150      * you want to process this event.
151      *
152      * @param exec The current execution state
153      * @param sourceId The ID of the source code being executed
154      * @param firstLine The starting line of the statement  that is about to be
155      * executed
156      * @param firstLine The ending line of the statement  that is about to be
157      * executed (usually the same as firstLine)
158      * @return true if execution should be continue, false if it should
159      * be aborted
160      */
161     virtual bool atStatement(ExecState *exec, int sourceId, int firstLine,
162                              int lastLine);
163     /**
164      * Called on each function call. Use together with @ref #returnEvent
165      * if you want to keep track of the call stack.
166      *
167      * Note: This only gets called for functions that are declared in ECMAScript
168      * source code or passed to eval(), not for internal KJS or
169      * application-supplied functions.
170      *
171      * The default implementation does nothing. Override this method if
172      * you want to process this event.
173      *
174      * @param exec The current execution state
175      * @param sourceId The ID of the source code being executed
176      * @param lineno The line that is about to be executed
177      * @param function The function being called
178      * @param args The arguments that were passed to the function
179      * line is being executed
180      * @return true if execution should be continue, false if it should
181      * be aborted
182      */
183     virtual bool callEvent(ExecState *exec, int sourceId, int lineno,
184                            JSObject *function, const List &args);
185
186     /**
187      * Called on each function exit. The function being returned from is that
188      * which was supplied in the last callEvent().
189      *
190      * Note: This only gets called for functions that are declared in ECMAScript
191      * source code or passed to eval(), not for internal KJS or
192      * application-supplied functions.
193      *
194      * The default implementation does nothing. Override this method if
195      * you want to process this event.
196      *
197      * @param exec The current execution state
198      * @param sourceId The ID of the source code being executed
199      * @param lineno The line that is about to be executed
200      * @param function The function being called
201      * @return true if execution should be continue, false if it should
202      * be aborted
203      */
204     virtual bool returnEvent(ExecState *exec, int sourceId, int lineno,
205                              JSObject *function);
206
207   private:
208     DebuggerImp *rep;
209
210   public:
211     static int debuggersPresent;
212   };
213
214 }
215
216 #endif