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