libcore/as_function.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   3 //   Foundation, Inc
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19 #ifndef GNASH_AS_FUNCTION_H
  20 #define GNASH_AS_FUNCTION_H
  21
  22 #include <string>
  23
  24 #include "as_object.h"
  25
  26 // Forward declarations
  27 namespace gnash {
  28     class NativeFunction;
  29     class Global_as;
  30     template <typename T> class FunctionArgs;
  31 }
  32
  33 namespace gnash {
  34
  35 /// ActionScript Function, either builtin or SWF-defined
  36 //
  37 /// In ActionScript, every Function is also a class.
  38 /// The *exported interface* of the class is defined
  39 /// as a 'prototype' member of the function object.
  40 ///
  41 /// Any instance of the class defined by this function will
  42 /// inherit any member of the class 'prototype'.
  43 /// To have an object inherit from a class you can set its
  44 /// __proto__ member so to point to the class prototype, ie:
  45 ///
  46 ///   function MyClass() {}
  47 ///   MyClass.prototype.doit = function() { trace("doing it"; }
  48 ///
  49 ///   var myobj = new Object;
  50 ///   myobj.__proto__ = MyClass.prototype;
  51 ///
  52 /// The 'prototype' of a class must provide a 'constructor'
  53 /// member, which would point back to the Function object
  54 /// itself, which is used as the constructor, so given the
  55 /// code above you can assert that:
  56 ///
  57 ///   myobj.__proto__.constructor == MyClass
  58 ///
  59 /// This class will automatically setup the 'prototype' member
  60 /// if not explicitly provided (ie: will set 'constructor' so
  61 /// that it points to the instance).
  62 class as_function : public as_object
  63 {
  64 public:
  65
  66     /// Destructor
  67         virtual ~as_function() {}
  68
  69     /// Return this as_object as an as_function.
  70         virtual as_function* to_function() { return this; }
  71
  72         /// Function dispatch.
  73     //
  74     /// Override from as_object, although as_objects cannot generally
  75     /// be called.
  76         virtual as_value call(const fn_call& fn) = 0;
  77
  78     /// Return the string value of this as_object subclass
  79     //
  80     /// It's "function".
  81     virtual std::string stringValue() const;
  82
  83         /// Run this function as a constructor on an object
  84     //
  85     /// This function assigns various constructor properties and runs the
  86     /// constructor.
  87     //
  88     /// NB: This function does not make the object an 'instance of' the
  89     /// constructor, i.e. it does not assign a __proto__ property. For
  90     /// ActionScript compatibility, callers should ensure this is already
  91     /// done.
  92     //
  93     /// @param newobj   The object to construct. This will be used as the
  94     ///                 'this' object in the constructor.
  95         /// @param env      The environment to use for stack, local variables,
  96         ///                     registers and scope chain.
  97         /// @param args     Arguments for the constructor invocation
  98     /// @return         The constructed object. TODO: return void; currently
  99     ///                 there is a hack to cope with some remaining bogus
 100     ///                 constructors, which
 101     ///                 necessitates returning a different object from the
 102     ///                 passed 'this' pointer.
 103     as_object* construct(as_object& newobj, const as_environment& env,
 104             FunctionArgs<as_value>& args);
 105
 106         /// Return true if this is a built-in class.
 107         virtual bool isBuiltin() { return false; }
 108
 109 protected:
 110
 111     /// Construct a function.
 112         as_function(Global_as& gl);
 113
 114 };
 115
 116
 117 /// Construct a new object from the given constructor
 118 //
 119 /// This function takes care of creating the new object and assigning the
 120 /// __proto__ property. The construct() function is then called with the
 121 /// new object as its 'this' object.
 122 //
 123 /// @param ctor     The constructor to run.
 124 /// @param env      The environment to use for the function call.
 125 /// @param arg      The arguments to pass to the constructor function.
 126 /// @return         A newly-created object constructed by the specified
 127 ///                 function.
 128 as_object* constructInstance(as_function& ctor, const as_environment& env,
 129         FunctionArgs<as_value>& args);
 130
 131 } // gnash namespace
 132
 133 #endif
 134