Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 210 insertions, 0 deletions

diff --git a/kjs/debugger.h b/kjs/debugger.h
new file mode 100644
index 000000000..d30b570e8
--- /dev/null
+++ b/kjs/debugger.h
@@ -0,0 +1,210 @@
+// -*- c-basic-offset: 2 -*-
+/*
+ *  This file is part of the KDE libraries
+ *  Copyright (C) 1999-2001 Harri Porten (porten@kde.org)
+ *  Copyright (C) 2001 Peter Kelly (pmk@post.com)
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ */
+
+#ifndef _KJSDEBUGGER_H_
+#define _KJSDEBUGGER_H_
+
+#include "interpreter.h"
+
+namespace KJS {
+
+  class DebuggerImp;
+  class Interpreter;
+  class ExecState;
+  class Value;
+  class Object;
+  class UString;
+  class List;
+  class Completion;
+
+  /**
+   * @internal
+   *
+   * Provides an interface which receives notification about various
+   * script-execution related events such as statement execution and function
+   * calls.
+   *
+   * WARNING: This interface is still a work in progress and is not yet
+   * offically publicly available. It is likely to change in binary incompatible
+   * (and possibly source incompatible) ways in future versions. It is
+   * anticipated that at some stage the interface will be frozen and made
+   * available for general use.
+   */
+  class KJS_EXPORT Debugger {
+  public:
+
+    /**
+     * Creates a new debugger
+     */
+    Debugger();
+
+    /**
+     * Destroys the debugger. If the debugger is attached to any interpreters,
+     * it is automatically detached.
+     */
+    virtual ~Debugger();
+
+    DebuggerImp *imp() const { return rep; }
+
+    /**
+     * Attaches the debugger to specified interpreter. This will cause this
+     * object to receive notification of events from the interpreter.
+     *
+     * If the interpreter is deleted, the debugger will automatically be
+     * detached.
+     *
+     * Note: only one debugger can be attached to an interpreter at a time.
+     * Attaching another debugger to the same interpreter will cause the
+     * original debugger to be detached from that interpreter.
+     *
+     * @param interp The interpreter to attach to
+     *
+     * @see detach()
+     */
+    void attach(Interpreter *interp);
+
+    /**
+     * Detach the debugger from an interpreter
+     *
+     * @param interp The interpreter to detach from. If 0, the debugger will be
+     * detached from all interpreters to which it is attached.
+     *
+     * @see attach()
+     */
+    void detach(Interpreter *interp);
+
+    /**
+     * Called to notify the debugger that some javascript source code has
+     * been parsed. For calls to Interpreter::evaluate(), this will be called
+     * with the supplied source code before any other code is parsed.
+     * Other situations in which this may be called include creation of a
+     * function using the Function() constructor, or the eval() function.
+     *
+     * The default implementation does nothing. Override this method if
+     * you want to process this event.
+     *
+     * @param exec The current execution state
+     * @param sourceId The ID of the source code (corresponds to the
+     * sourceId supplied in other functions such as atStatement()
+     * @param source The source code that was parsed
+     * @param errorLine The line number at which parsing encountered an
+     * error, or -1 if the source code was valid and parsed successfully
+     * @return true if execution should be continue, false if it should
+     * be aborted
+     */
+    virtual bool sourceParsed(ExecState *exec, int sourceId,
+			      const UString &source, int errorLine);
+
+    /**
+     * Called when all functions/programs associated with a particular
+     * sourceId have been deleted. After this function has been called for
+     * a particular sourceId, that sourceId will not be used again.
+     *
+     * The default implementation does nothing. Override this method if
+     * you want to process this event.
+     *
+     * @param exec The current execution state
+     * @param sourceId The ID of the source code (corresponds to the
+     * sourceId supplied in other functions such as atLine()
+     * @return true if execution should be continue, false if it should
+     * be aborted
+     */
+    virtual bool sourceUnused(ExecState *exec, int sourceId);
+
+    /**
+     * Called when an exception is thrown during script execution.
+     *
+     * The default implementation does nothing. Override this method if
+     * you want to process this event.
+     *
+     * @param exec The current execution state
+     * @param value The value of the exception
+     * @param inTryCatch Whether or not the exception will be caught by the
+     * script
+     * @return true if execution should be continue, false if it should
+     * be aborted
+     */
+    virtual bool exception(ExecState *exec, const Value &value,
+			   bool inTryCatch);
+
+    /**
+     * Called when a line of the script is reached (before it is executed)
+     *
+     * The exec pointer's Context object can be inspected to determine
+     * the line number and sourceId of the statement.
+     *
+     * The default implementation does nothing. Override this method if
+     * you want to process this event.
+     *
+     * @param exec The current execution state
+     * @return true if execution should be continue, false if it should
+     * be aborted
+     */
+    virtual bool atStatement(ExecState *exec);
+
+    /**
+     * Called when the interpreter enters a new execution context (stack
+     * frame). This can happen in three situations:
+     * 
+     * <ul>
+     *   <li>A call to Interpreter::evaluate(). This has a codeType of
+     *   GlobalCode, and the sourceId is the id of the code passed to
+     *   evaluate(). The lineno here is always 0 since execution starts at the
+     *   beginning of the script.</li>
+     *   <li>A call to the builtin eval() function. The sourceId corresponds to
+     *   the code passed in to eval. This has a codeType of EvalCode. The
+     *   lineno here is always 0 since execution starts at the beginning of
+     *   the script.</li>
+     *   <li>A function call. This only occurs for functions defined in
+     *   ECMAScript code, whether via the normal function() { ... } syntax or
+     *   a call to the built-in Function() constructor (anonymous functions).
+     *   In the former case, the sourceId and lineno indicate the location at
+     *   which the function was defined. For anonymous functions, the sourceId
+     *   corresponds to the code passed into the Function() constructor.</li>
+     * </ul>
+     *
+     * enterContext() is not called for functions implemented in the native
+     * code, since these do not use an execution context.
+     * 
+     * @param exec The current execution state (corresponding to the new stack
+     * frame)
+     */
+    virtual bool enterContext(ExecState *exec);
+
+    /**
+     * Called when the inteprreter exits an execution context. This always
+     * corresponds to a previous call to enterContext()
+     *
+     * @param exec The current execution state (corresponding to the stack frame
+     * being exited from)
+     * @param completion The result of execution of the context. Can be used to
+     * inspect exceptions and return values
+     */
+    virtual bool exitContext(ExecState *exec, const Completion &completion);
+
+  private:
+    DebuggerImp *rep;
+  };
+
+}
+
+#endif