home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kjs / interpreter.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  15.2 KB  |  499 lines
  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.  *  Copyright (C) 2003 Apple Computer, Inc.
  7.  *
  8.  *  This library is free software; you can redistribute it and/or
  9.  *  modify it under the terms of the GNU Library General Public
  10.  *  License as published by the Free Software Foundation; either
  11.  *  version 2 of the License, or (at your option) any later version.
  12.  *
  13.  *  This library is distributed in the hope that it will be useful,
  14.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16.  *  Library General Public License for more details.
  17.  *
  18.  *  You should have received a copy of the GNU Library General Public License
  19.  *  along with this library; see the file COPYING.LIB.  If not, write to
  20.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21.  *  Boston, MA 02110-1301, USA.
  22.  *
  23.  */
  24.  
  25. #ifndef _KJS_INTERPRETER_H_
  26. #define _KJS_INTERPRETER_H_
  27.  
  28. #include "value.h"
  29. #include "object.h"
  30. #include "types.h"
  31.  
  32. namespace KJS {
  33.  
  34.   class ContextImp;
  35.   class InterpreterImp;
  36.  
  37.   /**
  38.    * The three different types of code that can be executed in a Context.
  39.    * These are:
  40.    * <ul>
  41.    *   <li>GlobalCode - code executed as a result of a call to
  42.    *   Interpreter::evaluate().</li>
  43.    *   <li>EvalCode - executed by a call to the builtin eval() function</li>
  44.    *   <li>FunctionCode - inside a function call (ECMAScript functions only;
  45.    *   does not include builtin native functions or funcitons supplied by the
  46.    *   host environment</li>
  47.    * </ul>
  48.    */
  49.   enum CodeType {
  50.     GlobalCode   = 0,
  51.     EvalCode     = 1,
  52.     FunctionCode = 2
  53.   };
  54.  
  55.   /**
  56.    * Represents an execution context, as specified by section 10 of the ECMA
  57.    * spec.
  58.    *
  59.    * An execution context contains information about the current state of the
  60.    * script - the scope for variable lookup, the value of "this", etc. A new
  61.    * execution context is entered whenever global code is executed (e.g. with
  62.    * Interpreter::evaluate()), a function is called (see
  63.    * Object::call()), or the builtin "eval" function is executed.
  64.    *
  65.    * Most inheritable functions in the KJS api take a ExecState pointer as
  66.    * their first parameter. This can be used to obtain a handle to the current
  67.    * execution context.
  68.    *
  69.    * Note: Context objects are wrapper classes/smart pointers for the internal
  70.    * KJS ContextImp type. When one context variable is assigned to another, it
  71.    * is still referencing the same internal object.
  72.    */
  73.   class KJS_EXPORT Context {
  74.   public:
  75.     Context(ContextImp *i) : rep(i) { }
  76.  
  77.     ContextImp *imp() const { return rep; }
  78.  
  79.     /**
  80.      * Returns the scope chain for this execution context. This is used for
  81.      * variable lookup, with the list being searched from start to end until a
  82.      * variable is found.
  83.      *
  84.      * @return The execution context's scope chain
  85.      */
  86.     const ScopeChain &scopeChain() const;
  87.  
  88.     /**
  89.      * Returns the variable object for the execution context. This contains a
  90.      * property for each variable declared in the execution context.
  91.      *
  92.      * @return The execution context's variable object
  93.      */
  94.     Object variableObject() const;
  95.  
  96.     /**
  97.      * Returns the "this" value for the execution context. This is the value
  98.      * returned when a script references the special variable "this". It should
  99.      * always be an Object, unless application-specific code has passed in a
  100.      * different type.
  101.      *
  102.      * The object that is used as the "this" value depends on the type of
  103.      * execution context - for global contexts, the global object is used. For
  104.      * function objewcts, the value is given by the caller (e.g. in the case of
  105.      * obj.func(), obj would be the "this" value). For code executed by the
  106.      * built-in "eval" function, the this value is the same as the calling
  107.      * context.
  108.      *
  109.      * @return The execution context's "this" value
  110.      */
  111.     Object thisValue() const;
  112.  
  113.     /**
  114.      * Returns the context from which the current context was invoked. For
  115.      * global code this will be a null context (i.e. one for which
  116.      * isNull() returns true). You should check isNull() on the returned
  117.      * value before calling any of it's methods.
  118.      *
  119.      * @return The calling execution context
  120.      */
  121.     const Context callingContext() const;
  122.  
  123.     /**
  124.      * The type of code being executed in this context. One of GlobalCode,
  125.      * EvalCode or FunctionCode
  126.      */
  127.     CodeType codeType() const;
  128.  
  129.     /**
  130.      * The identifier of the source code fragment containing the code being
  131.      * executed
  132.      */
  133.     int sourceId() const;
  134.  
  135.     /**
  136.      * The line number on which the current statement begins
  137.      */
  138.     int curStmtFirstLine() const;
  139.  
  140.     /**
  141.      * The line number on which the current statement ends
  142.      */
  143.     int curStmtLastLine() const;
  144.  
  145.     /**
  146.      * In the case of FunctionCode, the function objects being called
  147.      */
  148.     Object function() const;
  149.  
  150.     /**
  151.      * In the case of FunctionCode, the name of the function being called
  152.      */
  153.     Identifier functionName() const;
  154.  
  155.     /**
  156.      * In the case of FunctionCode, the arguments passed to the function
  157.      */
  158.     List args() const;
  159.  
  160.   private:
  161.     ContextImp *rep;
  162.   };
  163.  
  164.   bool operator==(const Context &c1, const Context &c2);
  165.   bool operator!=(const Context &c1, const Context &c2);
  166.  
  167.   /**
  168.    * Interpreter objects can be used to evaluate ECMAScript code. Each
  169.    * interpreter has a global object which is used for the purposes of code
  170.    * evaluation, and also provides access to built-in properties such as
  171.    * " Object" and "Number".
  172.    */
  173.   class KJS_EXPORT Interpreter {
  174.   public:
  175.     /**
  176.      * Creates a new interpreter. The supplied object will be used as the global
  177.      * object for all scripts executed with this interpreter. During
  178.      * constuction, all the standard properties such as "Object" and "Number"
  179.      * will be added to the global object.
  180.      *
  181.      * Note: You should not use the same global object for multiple
  182.      * interpreters.
  183.      *
  184.      * This is due do the fact that the built-in properties are set in the
  185.      * constructor, and if these objects have been modified from another
  186.      * interpreter (e.g. a script modifying String.prototype), the changes will
  187.      * be overridden.
  188.      *
  189.      * @param global The object to use as the global object for this interpreter
  190.      */
  191.     Interpreter(const Object &global);
  192.     /**
  193.      * Creates a new interpreter. A global object will be created and
  194.      * initialized with the standard global properties.
  195.      */
  196.     Interpreter();
  197.     virtual ~Interpreter();
  198.  
  199.     /**
  200.      * Returns the object that is used as the global object during all script
  201.      * execution performed by this interpreter
  202.      */
  203.     Object &globalObject() const;
  204.  
  205.     void initGlobalObject();
  206.  
  207.     static void lock();
  208.     static void unlock();
  209.  
  210.     /**
  211.      * Returns the execution state object which can be used to execute
  212.      * scripts using this interpreter at a the "global" level, i.e. one
  213.      * with a execution context that has the global object as the "this"
  214.      * value, and who's scope chain contains only the global object.
  215.      *
  216.      * Note: this pointer remains constant for the life of the interpreter
  217.      * and should not be manually deleted.
  218.      *
  219.      * @return The interpreter global execution state object
  220.      */
  221.     ExecState *globalExec();
  222.  
  223.     /**
  224.      * Parses the supplied ECMAScript code and checks for syntax errors.
  225.      *
  226.      * @param code The code to check
  227.      * @param errLine Returns the line the error was on (if there was one).
  228.      * @param errMsg Returns the error message (if there was one).
  229.      * @return true if there were no syntax errors in the code, otherwise false
  230.      */
  231.     bool checkSyntax(const UString &code, int *errLine, UString *errMsg);
  232.  
  233.     /**
  234.      * Parses the supplied ECMAScript code and checks for syntax errors.
  235.      *
  236.      * @param code The code to check
  237.      * @return true if there were no syntax errors in the code, otherwise false
  238.      */
  239.     bool checkSyntax(const UString &code);
  240.  
  241.     /**
  242.      * Evaluates the supplied ECMAScript code.
  243.      *
  244.      * Since this method returns a Completion, you should check the type of
  245.      * completion to detect an error or before attempting to access the returned
  246.      * value. For example, if an error occurs during script execution and is not
  247.      * caught by the script, the completion type will be Throw.
  248.      *
  249.      * If the supplied code is invalid, a SyntaxError will be thrown.
  250.      *
  251.      * @param code The code to evaluate
  252.      * @param thisV The value to pass in as the "this" value for the script
  253.      * execution. This should either be Null() or an Object.
  254.      * @return A completion object representing the result of the execution.
  255.      */
  256.     Completion evaluate(const UString &code, const Value &thisV = Value());
  257.  
  258.     /**
  259.      * @internal
  260.      *
  261.      * Returns the implementation object associated with this interpreter.
  262.      * Only useful for internal KJS operations.
  263.      */
  264.     InterpreterImp *imp();
  265.  
  266.     /**
  267.      * Returns the builtin "Object" object. This is the object that was set
  268.      * as a property of the global object during construction; if the property
  269.      * is replaced by script code, this method will still return the original
  270.      * object.
  271.      *
  272.      * @return The builtin "Object" object
  273.      */
  274.     Object builtinObject() const;
  275.  
  276.     /**
  277.      * Returns the builtin "Function" object.
  278.      */
  279.     Object builtinFunction() const;
  280.  
  281.     /**
  282.      * Returns the builtin "Array" object.
  283.      */
  284.     Object builtinArray() const;
  285.  
  286.     /**
  287.      * Returns the builtin "Boolean" object.
  288.      */
  289.     Object builtinBoolean() const;
  290.  
  291.     /**
  292.      * Returns the builtin "String" object.
  293.      */
  294.     Object builtinString() const;
  295.  
  296.     /**
  297.      * Returns the builtin "Number" object.
  298.      */
  299.     Object builtinNumber() const;
  300.  
  301.     /**
  302.      * Returns the builtin "Date" object.
  303.      */
  304.     Object builtinDate() const;
  305.  
  306.     /**
  307.      * Returns the builtin "RegExp" object.
  308.      */
  309.     Object builtinRegExp() const;
  310.  
  311.     /**
  312.      * Returns the builtin "Error" object.
  313.      */
  314.     Object builtinError() const;
  315.  
  316.     /**
  317.      * Returns the builtin "Object.prototype" object.
  318.      */
  319.     Object builtinObjectPrototype() const;
  320.  
  321.     /**
  322.      * Returns the builtin "Function.prototype" object.
  323.      */
  324.     Object builtinFunctionPrototype() const;
  325.  
  326.     /**
  327.      * Returns the builtin "Array.prototype" object.
  328.      */
  329.     Object builtinArrayPrototype() const;
  330.  
  331.     /**
  332.      * Returns the builtin "Boolean.prototype" object.
  333.      */
  334.     Object builtinBooleanPrototype() const;
  335.  
  336.     /**
  337.      * Returns the builtin "String.prototype" object.
  338.      */
  339.     Object builtinStringPrototype() const;
  340.  
  341.     /**
  342.      * Returns the builtin "Number.prototype" object.
  343.      */
  344.     Object builtinNumberPrototype() const;
  345.  
  346.     /**
  347.      * Returns the builtin "Date.prototype" object.
  348.      */
  349.     Object builtinDatePrototype() const;
  350.  
  351.     /**
  352.      * Returns the builtin "RegExp.prototype" object.
  353.      */
  354.     Object builtinRegExpPrototype() const;
  355.  
  356.     /**
  357.      * Returns the builtin "Error.prototype" object.
  358.      */
  359.     Object builtinErrorPrototype() const;
  360.  
  361.     /**
  362.      * The initial value of "Error" global property
  363.      */
  364.     Object builtinEvalError() const;
  365.     Object builtinRangeError() const;
  366.     Object builtinReferenceError() const;
  367.     Object builtinSyntaxError() const;
  368.     Object builtinTypeError() const;
  369.     Object builtinURIError() const;
  370.  
  371.     Object builtinEvalErrorPrototype() const;
  372.     Object builtinRangeErrorPrototype() const;
  373.     Object builtinReferenceErrorPrototype() const;
  374.     Object builtinSyntaxErrorPrototype() const;
  375.     Object builtinTypeErrorPrototype() const;
  376.     Object builtinURIErrorPrototype() const;
  377.  
  378.     enum CompatMode { NativeMode, IECompat, NetscapeCompat };
  379.     /**
  380.      * Call this to enable a compatibility mode with another browser.
  381.      * (by default konqueror is in "native mode").
  382.      * Currently, in KJS, this only changes the behavior of Date::getYear()
  383.      * which returns the full year under IE.
  384.      */
  385.     void setCompatMode(CompatMode mode);
  386.     CompatMode compatMode() const;
  387.  
  388.     /**
  389.      * Run the garbage collection. Returns true when at least one object
  390.      * was collected; false otherwise.
  391.      */
  392.     static bool collect();
  393.  
  394.     /**
  395.      * Called by InterpreterImp during the mark phase of the garbage collector
  396.      * Default implementation does nothing, this exist for classes that reimplement Interpreter.
  397.      */
  398.     virtual void mark() {}
  399.  
  400.     /**
  401.      * Provides a way to distinguish derived classes.
  402.      * Only useful if you reimplement Interpreter and if different kind of
  403.      * interpreters are created in the same process.
  404.      * The base class returns 0, the ECMA-bindings interpreter returns 1.
  405.      */
  406.     virtual int rtti() { return 0; }
  407.  
  408. #ifdef KJS_DEBUG_MEM
  409.     /**
  410.      * @internal
  411.      */
  412.     static void finalCheck();
  413. #endif
  414.   private:
  415.     InterpreterImp *rep;
  416.  
  417.     /**
  418.      * This constructor is not implemented, in order to prevent
  419.      * copy-construction of Interpreter objects. You should always pass around
  420.      * pointers to an interpreter instance instead.
  421.      */
  422.     Interpreter(const Interpreter&);
  423.  
  424.     /**
  425.      * This constructor is not implemented, in order to prevent assignment of
  426.      * Interpreter objects. You should always pass around pointers to an
  427.      * interpreter instance instead.
  428.      */
  429.     Interpreter operator=(const Interpreter&);
  430.   protected:
  431.     virtual void virtual_hook( int id, void* data );
  432.   };
  433.  
  434.   /**
  435.    * Represents the current state of script execution. This object allows you
  436.    * obtain a handle the interpreter that is currently executing the script,
  437.    * and also the current execution state context.
  438.    */
  439.   class KJS_EXPORT ExecState {
  440.     friend class InterpreterImp;
  441.     friend class FunctionImp;
  442.     friend class GlobalFuncImp;
  443.     friend class TryNode;
  444.     friend class VarDeclNode;
  445.     friend class FuncDeclNode;
  446.   public:
  447.     /**
  448.      * Returns the interpreter associated with this execution state
  449.      *
  450.      * @return The interpreter executing the script
  451.      */
  452.     // ### make non-const or provide an overload pair
  453.     Interpreter *dynamicInterpreter() const { return _interpreter; }
  454.  
  455.     // for compatibility
  456.     Interpreter *interpreter() const { return dynamicInterpreter(); }
  457.  
  458.     /**
  459.      * Returns the interpreter associated with the current scope's
  460.      * global object
  461.      *
  462.      * @return The interpreter currently in scope
  463.      */
  464.     Interpreter *lexicalInterpreter() const;
  465.  
  466.     /**
  467.      * Returns the execution context associated with this execution state
  468.      *
  469.      * @return The current execution state context
  470.      */
  471.     Context context() const { return _context; }
  472.  
  473.     void setException(const Value &e);
  474.     void clearException();
  475.     Value exception() const { return _exception; }
  476.     // ### make const
  477.     bool hadException();
  478.  
  479.     /*
  480.      * request for ending execution with an exception
  481.      */
  482.     static void requestTerminate() { terminate_request = true; }
  483.     /*
  484.      * optional confirmation for ending execution after requestTerminate()
  485.      */
  486.     static bool (*confirmTerminate)();
  487.   private:
  488.     ExecState(Interpreter *interp, ContextImp *con)
  489.         : _interpreter(interp), _context(con) { }
  490.     Interpreter *_interpreter;
  491.     ContextImp *_context;
  492.     Value _exception;
  493.     static bool terminate_request;
  494.   };
  495.  
  496. } // namespace
  497.  
  498. #endif // _KJS_INTERPRETER_H_
  499.