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