libcore/as_environment.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
   3 //   Free Software 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_ENVIRONMENT_H
  20 #define GNASH_AS_ENVIRONMENT_H
  21
  22 #include <string>
  23 #include <vector>
  24 #include <algorithm>
  25
  26 #include "dsodefs.h" // for DSOTEXPORT
  27 #include "as_value.h"
  28 #include "SafeStack.h"
  29
  30 // Forward declarations
  31 namespace gnash {
  32     class DisplayObject;
  33     class VM;
  34     class Global_as;
  35     class movie_root;
  36     class string_table;
  37 }
  38
  39 namespace gnash {
  40
  41
  42 /// Provides information about timeline context.
  43 //
  44 /// This class stores information about the current and original "target"
  45 /// of execution. A target is a MovieClip or other AS-referenceable
  46 /// DisplayObject. Non-timeline code has no target.
  47 //
  48 /// Why should a timeline context provide access to the VM stack? It shouldn't!
  49 /// TODO: remove stack access proxy functions, SWF version, etc.
  50 class as_environment
  51 {
  52 public:
  53
  54     /// A stack of objects used for variables/members lookup
  55     typedef std::vector<as_object*> ScopeStack;
  56
  57     DSOTEXPORT as_environment(VM& vm);
  58
  59     VM& getVM() const { return _vm; }
  60
  61     DisplayObject* target() const { return _target; }
  62
  63     /// Set default target for timeline opcodes
  64     //
  65     /// @param target   A DisplayObject to apply timeline opcodes on.
  66     ///                 Zero is a valid target, disabling timeline
  67     ///                 opcodes (would get ignored).
  68     void set_target(DisplayObject* target) {
  69         if (!_original_target) _original_target = target;
  70         _target = target;
  71     }
  72
  73     void set_original_target(DisplayObject* target) {
  74         _original_target = target;
  75     }
  76
  77     DisplayObject* get_original_target() const { return _original_target; }
  78
  79     // Reset target to its original value
  80     void reset_target() { _target = _original_target; }
  81
  82     /// Push a value on the stack
  83     void push(const as_value& val) {
  84         _stack.push(val);
  85     }
  86
  87     /// Pops an as_value off the stack top and return it.
  88     as_value pop()
  89     try {
  90         return _stack.pop();
  91     }
  92     catch (const StackException&) {
  93         return as_value();
  94     }
  95
  96     /// Get stack value at the given distance from top.
  97     //
  98     /// top(0) is actual stack top
  99     ///
 100     /// Throw StackException if index is out of range
 101     ///
 102     as_value& top(size_t dist) const
 103     try {
 104         return _stack.top(dist);
 105     }
 106     catch (const StackException&) {
 107         return undefVal;
 108     }
 109
 110     /// Drop 'count' values off the top of the stack.
 111     void drop(size_t count) {
 112         // in case count > stack size, just drop all, forget about
 113         // exceptions...
 114         _stack.drop(std::min(count, _stack.size()));
 115     }
 116
 117     size_t stack_size() const { return _stack.size(); }
 118
 119     /// Mark all reachable resources.
 120     //
 121     /// Only the targets are reachable.
 122     void markReachableResources() const;
 123
 124     /// Return the SWF version we're running for.
 125     //
 126     /// This is merely a proxy for VM::getSWFVersion.
 127     int get_version() const;
 128
 129 private:
 130
 131     VM& _vm;
 132
 133     /// Stack of as_values in this environment
 134     SafeStack<as_value>& _stack;
 135
 136     /// Movie target.
 137     DisplayObject* _target;
 138
 139     /// Movie target.
 140     DisplayObject* _original_target;
 141
 142     static as_value undefVal;
 143
 144 };
 145
 146 /// Return the (possibly undefined) value of the named var.
 147 //
 148 /// @param ctx         Timeline context to use for variable finding.
 149 /// @param varname     Variable name. Can contain path elements.
 150 /// @param scope       The Scope stack to use for lookups.
 151 /// @param retTarget   If not null, the pointer will be set to the actual
 152 ///                    object containing the found variable (if found).
 153 as_value getVariable(const as_environment& ctx, const std::string& varname,
 154     const as_environment::ScopeStack& scope, as_object** retTarget = nullptr);
 155
 156 /// Given a path to variable, set its value.
 157 //
 158 /// If no variable with that name is found, a new one is created.
 159 ///
 160 /// For path-less variables, this would act as a proxy for
 161 /// set_variable_raw.
 162 //
 163 /// @param ctx     Timeline context to use for variable finding.
 164 /// @param path    Variable path.
 165 /// @param val     The value to assign to the variable.
 166 /// @param scope   The Scope stack to use for lookups.
 167 void setVariable(const as_environment& ctx, const std::string& path,
 168     const as_value& val, const as_environment::ScopeStack& scope);
 169
 170 /// Delete a variable, without support for the path, using a ScopeStack.
 171 //
 172 /// @param ctx      Timeline context to use for variable finding.
 173 /// @param varname  Variable name. Must not contain path elements.
 174 /// @param scope    The Scope stack to use for lookups.
 175 bool delVariable(const as_environment& ctx, const std::string& varname,
 176         const as_environment::ScopeStack& scope);
 177
 178 /// See if the given variable name is actually a sprite path
 179 /// followed by a variable name.  These come in the format:
 180 ///
 181 /// /path/to/some/sprite/:varname
 182 ///
 183 /// (or same thing, without the last '/')
 184 ///
 185 /// or
 186 /// path.to.some.var
 187 ///
 188 /// If that's the format, puts the path part (no colon or
 189 /// trailing slash) in *path, and the varname part (no colon, no dot)
 190 /// in *var and returns true.
 191 ///
 192 /// If no colon or dot, returns false and leaves *path & *var alone.
 193 ///
 194 /// TODO: return an integer: 0 not a path, 1 a slash-based path, 2 a
 195 /// dot-based path
 196 DSOEXPORT bool parsePath(const std::string& var_path, std::string& path,
 197         std::string& var);
 198
 199 /// Find the object referenced by the given path.
 200 //
 201 /// This is exposed to allow AS-scoped lookup from C++.
 202 //
 203 /// Supports both /slash/syntax and dot.syntax
 204 //
 205 /// @param ctx     Timeline context to use for variable finding.
 206 /// @param path    Variable path.
 207 /// @param scope   The Scope stack to use for lookups.
 208 DSOEXPORT as_object* findObject(const as_environment& ctx, const std::string& path,
 209         const as_environment::ScopeStack* scope = nullptr);
 210
 211 /// Find the DisplayObject referenced by the given path.
 212 //
 213 /// Supports both /slash/syntax and dot.syntax. This is a wrapper round
 214 /// findObject().
 215 //
 216 /// Note that only AS-referenceable DisplayObjects can be found by path,
 217 /// so that the returned object (if it exists) will have an associated
 218 /// as_object. This logic can't be reflected in the return type.
 219 DisplayObject* findTarget(const as_environment& env, const std::string& path);
 220
 221 inline VM&
 222 getVM(const as_environment& env)
 223 {
 224     return env.getVM();
 225 }
 226
 227 movie_root& getRoot(const as_environment& env);
 228 string_table& getStringTable(const as_environment& env);
 229 int getSWFVersion(const as_environment& env);
 230 DSOTEXPORT Global_as& getGlobal(const as_environment &env);
 231
 232 } // namespace gnash
 233
 234 #endif
 235
 236
 237 // Local Variables:
 238 // mode: C++
 239 // indent-tabs-mode: t
 240 // End: