File indexing completed on 2024-07-14 14:35:12

0001 /* This file is part of the KDE libraries
0002     Copyright (C) 2005, 2006 Ian Reinhart Geiser <geiseri@kde.org>
0003     Copyright (C) 2005, 2006 Matt Broadstone <mbroadst@gmail.com>
0004     Copyright (C) 2005, 2006 Richard J. Moore <rich@kde.org>
0005     Copyright (C) 2005, 2006 Erik L. Bunce <kde@bunce.us>
0006 
0007     This library is free software; you can redistribute it and/or
0008     modify it under the terms of the GNU Library General Public
0009     License as published by the Free Software Foundation; either
0010     version 2 of the License, or (at your option) any later version.
0011 
0012     This library is distributed in the hope that it will be useful,
0013     but WITHOUT ANY WARRANTY; without even the implied warranty of
0014     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015     Library General Public License for more details.
0016 
0017     You should have received a copy of the GNU Library General Public License
0018     along with this library; see the file COPYING.LIB.  If not, write to
0019     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0020     Boston, MA 02110-1301, USA.
0021 */
0022 
0023 #ifndef KJSEMBED_H
0024 #define KJSEMBED_H
0025 
0026 class QObject;
0027 
0028 #include <kjsembed/kjsembed_export.h>
0029 #include <kjs/object.h>
0030 
0031 namespace KJS
0032 {
0033 class Interpreter;
0034 class Object;
0035 class Completion;
0036 }
0037 
0038 namespace KJSEmbed
0039 {
0040 
0041 /**
0042  * The main interface for running embedded Javascript.
0043  *
0044  * \code
0045  * KJSEmbed::Engine *engine = new KJSEmbed::Engine();
0046  * KJS::Interpreter *interpreter = engine->interpreter();
0047  * interpreter->setShouldPrintExceptions(true);
0048  * KJS::ExecState *exec = interpreter->globalExec();
0049  * KJS::UString code("print(\"Hello World\")");
0050  * KJSEmbed::Engine::ExitStatus exitstatus = engine->execute(code);
0051  * KJS::Completion completion = engine->completion();
0052  * if(exitstatus != KJSEmbed::Engine::Success) {
0053  *     KJS::JSValue* value = completion.value();
0054  *     qDebug() << value->toString(exec).qstring();
0055  * }
0056  * \endcode
0057  */
0058 class KJSEMBED_EXPORT Engine
0059 {
0060 public:
0061     /**
0062      * Status codes for script execution. Note that you can access the completion
0063      * object itself with completion() for more detail.
0064      */
0065     enum ExitStatus { Success = 0, Failure = 1 };
0066 
0067     /**
0068      * Constructs an embedded JS engine.
0069      *
0070      * @param enableBindings If true then the bindings will be added to the interpreter
0071      * created. Otherwise a plain interpreter with nothing beyond the JS built in functions
0072      * and objects is created. This allows users who want to run untrusted scripts to choose
0073      * exactly which bindings they offer.
0074      */
0075     Engine(bool enableBindings = true);
0076     /** Clean up. */
0077     virtual ~Engine();
0078 
0079     /** Returns true if the Engine was created with the bindings enabled. */
0080     bool isBindingsEnabled() const;
0081 
0082     /**
0083      * Execute the file with the specified name using the current interpreter.
0084      * @param file Filename to execute.
0085      */
0086     ExitStatus runFile(const KJS::UString &file);
0087 
0088     /**
0089      * Execute the file with the specified name using the specified interpreter.
0090      * @param interpreter Interpreter to use.
0091      * @param file Filename to execute.
0092      */
0093     static KJS::Completion runFile(KJS::Interpreter *interpreter, const KJS::UString &file);
0094 
0095     /**
0096      * Execute a code string using the current interpreter.
0097      * @param code The script code to execute.
0098      */
0099     ExitStatus execute(const KJS::UString &code);
0100 
0101     /**
0102      * Returns the Completion object for the last script executed.
0103      */
0104     KJS::Completion completion() const;
0105 
0106     /**
0107      * Returns the current interpreter.
0108      */
0109     KJS::Interpreter *interpreter() const;
0110 
0111     /**
0112     *  publishes a QObject to the global context of the javascript interpereter.
0113     */
0114     KJS::JSObject *addObject(QObject *obj, const KJS::UString &name = KJS::UString()) const;
0115 
0116     /**
0117     * publishes a QObject to a parent object.
0118     */
0119     KJS::JSObject *addObject(QObject *obj, KJS::JSObject *parent, const KJS::UString &name = KJS::UString()) const;
0120 
0121     /**
0122     * Create a new instance of an object that the Javascript engine knows about.  If the object
0123     * doesn't exist a KJS::jsNull() is returned and an exception thrown.
0124     */
0125     KJS::JSObject *construct(const KJS::UString &className, const KJS::List &args = KJS::List()) const;
0126 
0127     /**
0128     * Execute a method at the global scope of the javascript interpreter.
0129     */
0130     KJS::JSValue *callMethod(const KJS::UString &methodName, const KJS::List &args = KJS::List());
0131 
0132     /**
0133     * Execute a method on an object.
0134     */
0135     KJS::JSValue *callMethod(KJS::JSObject *parent, const KJS::UString &methodName, const KJS::List &args = KJS::List());
0136 
0137 private:
0138     class EnginePrivate *dptr;
0139 };
0140 
0141 }
0142 
0143 #endif
0144