kjs/interpreter.h

   1 /*
   2  *  This file is part of the KDE libraries
   3  *  Copyright (C) 1999-2001 Harri Porten (porten@kde.org)
   4  *  Copyright (C) 2001 Peter Kelly (pmk@post.com)
   5  *  Copyright (C) 2003 Apple Computer, Inc.
   6  *
   7  *  This library is free software; you can redistribute it and/or
   8  *  modify it under the terms of the GNU Library 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  *  Library General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU Library General Public License
  18  *  along with this library; see the file COPYING.LIB.  If not, write to
  19  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20  *  Boston, MA 02110-1301, USA.
  21  *
  22  */
  23
  24 #ifndef _KJS_INTERPRETER_H_
  25 #define _KJS_INTERPRETER_H_
  26
  27 #include "ExecState.h"
  28 #include "protect.h"
  29 #include "value.h"
  30 #include "types.h"
  31
  32 namespace KJS {
  33
  34   class Context;
  35   class Debugger;
  36   class SavedBuiltins;
  37   class TimeoutChecker;
  38   class Package;
  39
  40 #if USE(BINDINGS)
  41   namespace Bindings {
  42     class RootObject;
  43   }
  44 #endif
  45
  46   /**
  47    * Interpreter objects can be used to evaluate ECMAScript code. Each
  48    * interpreter has a global object which is used for the purposes of code
  49    * evaluation, and also provides access to built-in properties such as
  50    * " Object" and "Number".
  51    */
  52   class KJS_EXPORT Interpreter {
  53       friend class Collector;
  54       friend class TimeoutChecker;
  55   public:
  56     /**
  57      * Creates a new interpreter. The supplied object will be used as the global
  58      * object for all scripts executed with this interpreter. During
  59      * construction, all the standard properties such as "Object" and "Number"
  60      * will be added to the global object.
  61      *
  62      * Note: You should not use the same global object for multiple
  63      * interpreters.
  64      *
  65      * This is due do the fact that the built-in properties are set in the
  66      * constructor, and if these objects have been modified from another
  67      * interpreter (e.g. a script modifying String.prototype), the changes will
  68      * be overridden.
  69      *
  70      * @param global The object to use as the global object for this interpreter
  71      */
  72     Interpreter(JSObject* globalObject);
  73     /**
  74      * Creates a new interpreter. A global object will be created and
  75      * initialized with the standard global properties.
  76      */
  77     Interpreter();
  78
  79     /**
  80      * Returns the object that is used as the global object during all script
  81      * execution performed by this interpreter
  82      */
  83     JSObject* globalObject() const;
  84     void initGlobalObject();
  85
  86     /**
  87      * Returns the execution state object which can be used to execute
  88      * scripts using this interpreter at a the "global" level, i.e. one
  89      * with a execution context that has the global object as the "this"
  90      * value, and who's scope chain contains only the global object.
  91      *
  92      * Note: this pointer remains constant for the life of the interpreter
  93      * and should not be manually deleted.
  94      *
  95      * @return The interpreter global execution state object
  96      */
  97     virtual ExecState *globalExec();
  98
  99     /**
 100      * Sets the package instance that will be used to resolve the
 101      * first level of identifiers of import statements.
 102      *
 103      * If no package is set which will make any "import" script
 104      * statement fail with an error. This is the default in e.g.  a
 105      * Web browser where package imports should be disabled for
 106      * security reasons.
 107      */
 108     void setGlobalPackage(Package* p);
 109
 110     /**
 111      * Returns the package that was installed to handle top level
 112      * package requests. Returns 0, the default, when no package was
 113      * set.
 114      *
 115      * @return The global package
 116      */
 117     Package* globalPackage();
 118
 119     /**
 120      * Parses the supplied ECMAScript code and checks for syntax errors.
 121      *
 122      * @param code The code to check
 123      * @return A normal completion if there were no syntax errors in the code,
 124      * otherwise a throw completion with the syntax error as its value.
 125      */
 126     Completion checkSyntax(const UString& sourceURL, int startingLineNumber, const UString& code);
 127     Completion checkSyntax(const UString& sourceURL, int startingLineNumber, const UChar* code, int codeLength);
 128
 129     /**
 130      * Evaluates the supplied ECMAScript code.
 131      *
 132      * Since this method returns a Completion, you should check the type of
 133      * completion to detect an error or before attempting to access the returned
 134      * value. For example, if an error occurs during script execution and is not
 135      * caught by the script, the completion type will be Throw.
 136      *
 137      * If the supplied code is invalid, a SyntaxError will be thrown.
 138      *
 139      * @param code The code to evaluate
 140      * @param thisV The value to pass in as the "this" value for the script
 141      * execution. This should either be jsNull() or an Object.
 142      * @return A completion object representing the result of the execution.
 143      */
 144     Completion evaluate(const UString& sourceURL, int startingLineNumber, const UChar* code, int codeLength, JSValue* thisV = 0);
 145     Completion evaluate(const UString& sourceURL, int startingLineNumber, const UString& code, JSValue* thisV = 0);
 146
 147     /**
 148      * Returns the builtin "Object" object. This is the object that was set
 149      * as a property of the global object during construction; if the property
 150      * is replaced by script code, this method will still return the original
 151      * object.
 152      *
 153      * @return The builtin "Object" object
 154      */
 155     JSObject *builtinObject() const;
 156
 157     /**
 158      * Returns the builtin "Function" object.
 159      */
 160     JSObject *builtinFunction() const;
 161
 162     /**
 163      * Returns the builtin "Array" object.
 164      */
 165     JSObject *builtinArray() const;
 166
 167     /**
 168      * Returns the builtin "Boolean" object.
 169      */
 170     JSObject *builtinBoolean() const;
 171
 172     /**
 173      * Returns the builtin "String" object.
 174      */
 175     JSObject *builtinString() const;
 176
 177     /**
 178      * Returns the builtin "Number" object.
 179      */
 180     JSObject *builtinNumber() const;
 181
 182     /**
 183      * Returns the builtin "Date" object.
 184      */
 185     JSObject *builtinDate() const;
 186
 187     /**
 188      * Returns the builtin "RegExp" object.
 189      */
 190     JSObject *builtinRegExp() const;
 191
 192     /**
 193      * Returns the builtin "Error" object.
 194      */
 195     JSObject *builtinError() const;
 196
 197     /**
 198      * Returns the builtin "Object.prototype" object.
 199      */
 200     JSObject *builtinObjectPrototype() const;
 201
 202     /**
 203      * Returns the builtin "Function.prototype" object.
 204      */
 205     JSObject *builtinFunctionPrototype() const;
 206
 207     /**
 208      * Returns the builtin "Array.prototype" object.
 209      */
 210     JSObject *builtinArrayPrototype() const;
 211
 212     /**
 213      * Returns the builtin "Boolean.prototype" object.
 214      */
 215     JSObject *builtinBooleanPrototype() const;
 216
 217     /**
 218      * Returns the builtin "String.prototype" object.
 219      */
 220     JSObject *builtinStringPrototype() const;
 221
 222     /**
 223      * Returns the builtin "Number.prototype" object.
 224      */
 225     JSObject *builtinNumberPrototype() const;
 226
 227     /**
 228      * Returns the builtin "Date.prototype" object.
 229      */
 230     JSObject *builtinDatePrototype() const;
 231
 232     /**
 233      * Returns the builtin "RegExp.prototype" object.
 234      */
 235     JSObject *builtinRegExpPrototype() const;
 236
 237     /**
 238      * Returns the builtin "Error.prototype" object.
 239      */
 240     JSObject *builtinErrorPrototype() const;
 241
 242     /**
 243      * The initial value of "Error" global property
 244      */
 245     JSObject *builtinEvalError() const;
 246     JSObject *builtinRangeError() const;
 247     JSObject *builtinReferenceError() const;
 248     JSObject *builtinSyntaxError() const;
 249     JSObject *builtinTypeError() const;
 250     JSObject *builtinURIError() const;
 251
 252     JSObject *builtinEvalErrorPrototype() const;
 253     JSObject *builtinRangeErrorPrototype() const;
 254     JSObject *builtinReferenceErrorPrototype() const;
 255     JSObject *builtinSyntaxErrorPrototype() const;
 256     JSObject *builtinTypeErrorPrototype() const;
 257     JSObject *builtinURIErrorPrototype() const;
 258
 259     enum CompatMode { NativeMode, IECompat, NetscapeCompat };
 260     /**
 261      * Call this to enable a compatibility mode with another browser.
 262      * (by default konqueror is in "native mode").
 263      * Currently, in KJS, this only changes the behavior of Date::getYear()
 264      * which returns the full year under IE.
 265      */
 266     void setCompatMode(CompatMode mode) { m_compatMode = mode; }
 267     CompatMode compatMode() const { return m_compatMode; }
 268
 269     /**
 270      * Run the garbage collection. Returns true when at least one object
 271      * was collected; false otherwise.
 272      */
 273     static bool collect();
 274
 275     /**
 276      * Called during the mark phase of the garbage collector. Subclasses
 277      * implementing custom mark methods must make sure to chain to this one.
 278      */
 279     virtual void mark(bool currentThreadIsMainThread);
 280
 281     /**
 282      * Provides a way to distinguish derived classes.
 283      * Only useful if you reimplement Interpreter and if different kind of
 284      * interpreters are created in the same process.
 285      * The base class returns 0, the ECMA-bindings interpreter returns 1.
 286      */
 287     virtual int rtti() { return 0; }
 288
 289 #ifdef KJS_DEBUG_MEM
 290     /**
 291      * @internal
 292      */
 293     static void finalCheck();
 294 #endif
 295
 296     static bool shouldPrintExceptions();
 297     static void setShouldPrintExceptions(bool);
 298
 299     void saveBuiltins (SavedBuiltins&) const;
 300     void restoreBuiltins (const SavedBuiltins&);
 301
 302     /**
 303      * Determine if the value is a global object (for any interpreter).  This may
 304      * be difficult to determine for multiple uses of JSC in a process that are
 305      * logically independent of each other.  In the case of a Web browser, this method
 306      * is used to determine if an object is the Window object so we can perform
 307      * security checks.
 308      */
 309     virtual bool isGlobalObject(JSValue*) { return false; }
 310
 311     /**
 312      * Find the interpreter for a particular global object.  This should really
 313      * be a static method, but we can't do that is C++.  Again, as with isGlobalObject()
 314      * implementation really need to know about all instances of Interpreter
 315      * created in an application to correctly implement this method.  The only
 316      * override of this method is currently in WebCore.
 317      */
 318     virtual Interpreter* interpreterForGlobalObject(const JSValue*) { return 0; }
 319
 320     /**
 321      * Determine if the it is 'safe' to execute code in the target interpreter from an
 322      * object that originated in this interpreter.  This check is used to enforce WebCore
 323      * cross frame security rules.  In particular, attempts to access 'bound' objects are
 324      * not allowed unless isSafeScript returns true.
 325      */
 326     virtual bool isSafeScript(const Interpreter*) { return true; }
 327
 328 #if USE(BINDINGS)
 329     virtual void *createLanguageInstanceForValue(ExecState*, int language, JSObject* value, const Bindings::RootObject* origin, const Bindings::RootObject* current);
 330 #endif
 331
 332     // Chained list of interpreters (ring)
 333     static Interpreter* firstInterpreter() { return s_hook; }
 334     Interpreter* nextInterpreter() const { return next; }
 335     Interpreter* prevInterpreter() const { return prev; }
 336
 337     Debugger* debugger() const { return m_debugger; }
 338     void setDebugger(Debugger* d) { m_debugger = d; }
 339
 340     void setContext(Context* c) { m_context = c; }
 341     Context* context() const { return m_context; }
 342
 343     static Interpreter* interpreterWithGlobalObject(JSObject*);
 344
 345     void setTimeoutTime(unsigned timeoutTime) { m_timeoutTime = timeoutTime; }
 346
 347     void startTimeoutCheck();
 348     void stopTimeoutCheck();
 349
 350     void pauseTimeoutCheck();
 351     void resumeTimeoutCheck();
 352
 353     bool checkTimeout();
 354
 355     void ref() { ++m_refCount; }
 356     void deref() { if (--m_refCount <= 0) delete this; }
 357     int refCount() const { return m_refCount; }
 358
 359 protected:
 360     virtual ~Interpreter(); // only deref should delete us
 361     virtual bool shouldInterruptScript() const { return true; }
 362
 363     long m_timeoutTime;
 364
 365 private:
 366     bool handleTimeout();
 367     void init();
 368     void printException(const Completion& c, const UString& sourceURL);
 369
 370     /**
 371      * This constructor is not implemented, in order to prevent
 372      * copy-construction of Interpreter objects. You should always pass around
 373      * pointers to an interpreter instance instead.
 374      */
 375     Interpreter(const Interpreter&);
 376
 377     /**
 378      * This operator is not implemented, in order to prevent assignment of
 379      * Interpreter objects. You should always pass around pointers to an
 380      * interpreter instance instead.
 381      */
 382     Interpreter operator=(const Interpreter&);
 383
 384     int m_refCount;
 385
 386     ExecState m_globalExec;
 387     JSObject* m_globalObject;
 388     Package *globPkg;
 389
 390     // Chained list of interpreters (ring) - for collector
 391     static Interpreter* s_hook;
 392     Interpreter *next, *prev;
 393
 394     int m_recursion;
 395
 396     Debugger* m_debugger;
 397     Context* m_context;
 398     CompatMode m_compatMode;
 399
 400     TimeoutChecker* m_timeoutChecker;
 401     bool m_timedOut;
 402
 403     unsigned m_startTimeoutCheckCount;
 404     unsigned m_pauseTimeoutCheckCount;
 405
 406     ProtectedPtr<JSObject> m_Object;
 407     ProtectedPtr<JSObject> m_Function;
 408     ProtectedPtr<JSObject> m_Array;
 409     ProtectedPtr<JSObject> m_Boolean;
 410     ProtectedPtr<JSObject> m_String;
 411     ProtectedPtr<JSObject> m_Number;
 412     ProtectedPtr<JSObject> m_Date;
 413     ProtectedPtr<JSObject> m_RegExp;
 414     ProtectedPtr<JSObject> m_Error;
 415
 416     ProtectedPtr<JSObject> m_ObjectPrototype;
 417     ProtectedPtr<JSObject> m_FunctionPrototype;
 418     ProtectedPtr<JSObject> m_ArrayPrototype;
 419     ProtectedPtr<JSObject> m_BooleanPrototype;
 420     ProtectedPtr<JSObject> m_StringPrototype;
 421     ProtectedPtr<JSObject> m_NumberPrototype;
 422     ProtectedPtr<JSObject> m_DatePrototype;
 423     ProtectedPtr<JSObject> m_RegExpPrototype;
 424     ProtectedPtr<JSObject> m_ErrorPrototype;
 425
 426     ProtectedPtr<JSObject> m_EvalError;
 427     ProtectedPtr<JSObject> m_RangeError;
 428     ProtectedPtr<JSObject> m_ReferenceError;
 429     ProtectedPtr<JSObject> m_SyntaxError;
 430     ProtectedPtr<JSObject> m_TypeError;
 431     ProtectedPtr<JSObject> m_UriError;
 432
 433     ProtectedPtr<JSObject> m_EvalErrorPrototype;
 434     ProtectedPtr<JSObject> m_RangeErrorPrototype;
 435     ProtectedPtr<JSObject> m_ReferenceErrorPrototype;
 436     ProtectedPtr<JSObject> m_SyntaxErrorPrototype;
 437     ProtectedPtr<JSObject> m_TypeErrorPrototype;
 438     ProtectedPtr<JSObject> m_UriErrorPrototype;
 439   };
 440
 441   inline bool Interpreter::checkTimeout()
 442   {
 443     if (!m_timedOut)
 444       return false;
 445
 446     return handleTimeout();
 447   }
 448
 449   /**
 450    * Interface to set enhanced Unicode support functions. By default
 451    * the interpreter will use the standard C library functions.
 452    *
 453    * @internal
 454    */
 455   class KJS_EXPORT UnicodeSupport
 456   {
 457   public:
 458     UnicodeSupport();
 459
 460     typedef bool (*CharCategoryFunction)(int c);
 461     static void setIdentStartChecker(CharCategoryFunction f);
 462     static void setIdentPartChecker(CharCategoryFunction f);
 463
 464     typedef int (*StringConversionFunction)(uint16_t* str, int strLength,
 465                                             uint16_t*& destIfNeeded);
 466     static void setToLowerFunction(StringConversionFunction f);
 467     static void setToUpperFunction(StringConversionFunction f);
 468   };
 469
 470
 471 } // namespace
 472
 473 #endif // _KJS_INTERPRETER_H_