kjs/context.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  *  Copyright (C) 2003, 2006 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_Context_h
  26 #define KJS_Context_h
  27
  28 #include "function.h"
  29 #include "internal.h"
  30
  31 namespace KJS  {
  32
  33   class FunctionBodyNode;
  34
  35   /**
  36    * @short Execution context.
  37    *
  38    * Represents an execution context, as specified by section 10 of the ECMA
  39    * spec.
  40    *
  41    * An execution context contains information about the current state of the
  42    * script - the scope for variable lookup, the value of "this", etc. A new
  43    * execution context is entered whenever global code is executed (e.g. with
  44    * Interpreter::evaluate()), a function is called (see
  45    * Object::call()), or the builtin "eval" function is executed.
  46    *
  47    * Most inheritable functions in the KJS api take a ExecState pointer as
  48    * their first parameter. This can be used to obtain a handle to the current
  49    * execution context.
  50    */
  51   class KJS_EXPORT Context {
  52   public:
  53     Context(JSObject* global, Interpreter*, JSObject* thisV,
  54             FunctionBodyNode* currentBody, CodeType type = GlobalCode,
  55             Context* callingContext = 0, FunctionImp* function = 0, const List* args = 0);
  56     ~Context();
  57
  58     /**
  59      * Returns the scope chain for this execution context. This is used for
  60      * variable lookup, with the list being searched from start to end until a
  61      * variable is found.
  62      *
  63      * @return The execution context's scope chain
  64      */
  65     const ScopeChain& scopeChain() const { return scope; }
  66
  67     /**
  68      * Returns the variable object for the execution context. This contains a
  69      * property for each variable declared in the execution context.
  70      *
  71      * @return The execution context's variable object
  72      */
  73     JSObject* variableObject() const { return m_variable; }
  74     void setVariableObject(JSObject* v) { m_variable = v; }
  75
  76     /**
  77      * Returns the "this" value for the execution context. This is the value
  78      * returned when a script references the special variable "this". It should
  79      * always be an Object, unless application-specific code has passed in a
  80      * different type.
  81      *
  82      * The object that is used as the "this" value depends on the type of
  83      * execution context - for global contexts, the global object is used. For
  84      * function objewcts, the value is given by the caller (e.g. in the case of
  85      * obj.func(), obj would be the "this" value). For code executed by the
  86      * built-in "eval" function, the this value is the same as the calling
  87      * context.
  88      *
  89      * @return The execution context's "this" value
  90      */
  91     JSObject* thisValue() const { return m_thisVal; }
  92
  93     /**
  94      * Returns the context from which the current context was invoked. For
  95      * global code this will be a null context (i.e. one for which
  96      * isNull() returns true). You should check isNull() on the returned
  97      * value before calling any of it's methods.
  98      *
  99      * @return The calling execution context
 100      */
 101     Context* callingContext() { return m_callingContext; }
 102
 103     JSObject* activationObject() { return m_activation; }
 104     CodeType codeType() { return m_codeType; }
 105     FunctionBodyNode* currentBody() { return m_currentBody; }
 106     FunctionImp* function() const { return m_function; }
 107     const List* arguments() const { return m_arguments; }
 108
 109     void pushScope(JSObject* s) { scope.push(s); }
 110     void popScope() { scope.pop(); }
 111
 112     void mark();
 113
 114   private:
 115     // Contexts are always stack-allocated, and the garbage collector
 116     // marks the stack, so we don't need to protect the objects below from GC.
 117
 118     Interpreter* m_interpreter;
 119     Context* m_callingContext;
 120     FunctionBodyNode* m_currentBody;
 121
 122     FunctionImp* m_function;
 123     const List* m_arguments;
 124     JSObject* m_activation;
 125
 126     ScopeChain scope;
 127     JSObject* m_variable;
 128     JSObject* m_thisVal;
 129
 130     CodeType m_codeType;
 131   };
 132
 133 } // namespace KJS
 134
 135 #endif
 136