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