src/script/squirrel.hpp

   1 /* $Id: squirrel.hpp 23604 2011-12-19 20:50:54Z truebrain $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /** @file squirrel.hpp defines the Squirrel class */
  11
  12 #ifndef SQUIRREL_HPP
  13 #define SQUIRREL_HPP
  14
  15 #include <squirrel.h>
  16
  17 /** The type of script we're working with, i.e. for who is it? */
  18 enum ScriptType {
  19         ST_AI, ///< The script is for AI scripts.
  20         ST_GS, ///< The script is for Game scripts.
  21 };
  22
  23 class Squirrel {
  24 private:
  25         typedef void (SQPrintFunc)(bool error_msg, const SQChar *message);
  26
  27         HSQUIRRELVM vm;          ///< The VirtualMachine instance for squirrel
  28         void *global_pointer;    ///< Can be set by who ever initializes Squirrel
  29         SQPrintFunc *print_func; ///< Points to either NULL, or a custom print handler
  30         bool crashed;            ///< True if the squirrel script made an error.
  31         int overdrawn_ops;       ///< The amount of operations we have overdrawn.
  32         const char *APIName;     ///< Name of the API used for this squirrel.
  33
  34         /**
  35          * The internal RunError handler. It looks up the real error and calls RunError with it.
  36          */
  37         static SQInteger _RunError(HSQUIRRELVM vm);
  38
  39         /**
  40          * Get the API name.
  41          */
  42         const char *GetAPIName() { return this->APIName; }
  43
  44         /** Perform all initialization steps to create the engine. */
  45         void Initialize();
  46         /** Perform all the cleanups for the engine. */
  47         void Uninitialize();
  48
  49 protected:
  50         /**
  51          * The CompileError handler.
  52          */
  53         static void CompileError(HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column);
  54
  55         /**
  56          * The RunError handler.
  57          */
  58         static void RunError(HSQUIRRELVM vm, const SQChar *error);
  59
  60         /**
  61          * If a user runs 'print' inside a script, this function gets the params.
  62          */
  63         static void PrintFunc(HSQUIRRELVM vm, const SQChar *s, ...);
  64
  65         /**
  66          * If an error has to be print, this function is called.
  67          */
  68         static void ErrorPrintFunc(HSQUIRRELVM vm, const SQChar *s, ...);
  69
  70 public:
  71         Squirrel(const char *APIName);
  72         ~Squirrel();
  73
  74         /**
  75          * Get the squirrel VM. Try to avoid using this.
  76          */
  77         HSQUIRRELVM GetVM() { return this->vm; }
  78
  79         /**
  80          * Load a script.
  81          * @param script The full script-name to load.
  82          * @return False if loading failed.
  83          */
  84         bool LoadScript(const char *script);
  85         bool LoadScript(HSQUIRRELVM vm, const char *script, bool in_root = true);
  86
  87         /**
  88          * Load a file to a given VM.
  89          */
  90         SQRESULT LoadFile(HSQUIRRELVM vm, const char *filename, SQBool printerror);
  91
  92         /**
  93          * Adds a function to the stack. Depending on the current state this means
  94          *  either a method or a global function.
  95          */
  96         void AddMethod(const char *method_name, SQFUNCTION proc, uint nparam = 0, const char *params = NULL, void *userdata = NULL, int size = 0);
  97
  98         /**
  99          * Adds a const to the stack. Depending on the current state this means
 100          *  either a const to a class or to the global space.
 101          */
 102         void AddConst(const char *var_name, int value);
 103
 104         /**
 105          * Adds a const to the stack. Depending on the current state this means
 106          *  either a const to a class or to the global space.
 107          */
 108         void AddConst(const char *var_name, uint value) { this->AddConst(var_name, (int)value); }
 109
 110         /**
 111          * Adds a const to the stack. Depending on the current state this means
 112          *  either a const to a class or to the global space.
 113          */
 114         void AddConst(const char *var_name, bool value);
 115
 116         /**
 117          * Adds a class to the global scope. Make sure to call AddClassEnd when you
 118          *  are done adding methods.
 119          */
 120         void AddClassBegin(const char *class_name);
 121
 122         /**
 123          * Adds a class to the global scope, extending 'parent_class'.
 124          * Make sure to call AddClassEnd when you are done adding methods.
 125          */
 126         void AddClassBegin(const char *class_name, const char *parent_class);
 127
 128         /**
 129          * Finishes adding a class to the global scope. If this isn't called, no
 130          *  class is really created.
 131          */
 132         void AddClassEnd();
 133
 134         /**
 135          * Resume a VM when it was suspended via a throw.
 136          */
 137         bool Resume(int suspend = -1);
 138
 139         /**
 140          * Resume the VM with an error so it prints a stack trace.
 141          */
 142         void ResumeError();
 143
 144         /**
 145          * Tell the VM to do a garbage collection run.
 146          */
 147         void CollectGarbage();
 148
 149         void InsertResult(bool result);
 150         void InsertResult(int result);
 151         void InsertResult(uint result) { this->InsertResult((int)result); }
 152
 153         /**
 154          * Call a method of an instance, in various flavors.
 155          * @return False if the script crashed or returned a wrong type.
 156          */
 157         bool CallMethod(HSQOBJECT instance, const char *method_name, HSQOBJECT *ret, int suspend);
 158         bool CallMethod(HSQOBJECT instance, const char *method_name, int suspend) { return this->CallMethod(instance, method_name, NULL, suspend); }
 159         bool CallStringMethodStrdup(HSQOBJECT instance, const char *method_name, const char **res, int suspend);
 160         bool CallIntegerMethod(HSQOBJECT instance, const char *method_name, int *res, int suspend);
 161         bool CallBoolMethod(HSQOBJECT instance, const char *method_name, bool *res, int suspend);
 162
 163         /**
 164          * Check if a method exists in an instance.
 165          */
 166         bool MethodExists(HSQOBJECT instance, const char *method_name);
 167
 168         /**
 169          * Creates a class instance.
 170          * @param vm The VM to create the class instance for
 171          * @param class_name The name of the class of which we create an instance.
 172          * @param real_instance The instance to the real class, if it represents a real class.
 173          * @param instance Returning value with the pointer to the instance.
 174          * @param release_hook Optional param to give a release hook.
 175          * @param prepend_API_name Optional parameter; if true, the class_name is prefixed with the current API name.
 176          * @return False if creating failed.
 177          */
 178         static bool CreateClassInstanceVM(HSQUIRRELVM vm, const char *class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name = false);
 179
 180         /**
 181          * Exactly the same as CreateClassInstanceVM, only callable without instance of Squirrel.
 182          */
 183         bool CreateClassInstance(const char *class_name, void *real_instance, HSQOBJECT *instance);
 184
 185         /**
 186          * Get the real-instance pointer.
 187          * @note This will only work just after a function-call from within Squirrel
 188          *  to your C++ function.
 189          */
 190         static bool GetRealInstance(HSQUIRRELVM vm, SQUserPointer *ptr) { return SQ_SUCCEEDED(sq_getinstanceup(vm, 1, ptr, 0)); }
 191
 192         /**
 193          * Get the Squirrel-instance pointer.
 194          * @note This will only work just after a function-call from within Squirrel
 195          *  to your C++ function.
 196          */
 197         static bool GetInstance(HSQUIRRELVM vm, HSQOBJECT *ptr, int pos = 1) { sq_getclass(vm, pos); sq_getstackobj(vm, pos, ptr); sq_pop(vm, 1); return true; }
 198
 199         /**
 200          * Convert a Squirrel-object to a string.
 201          */
 202         static const char *ObjectToString(HSQOBJECT *ptr) { return sq_objtostring(ptr); }
 203
 204         /**
 205          * Convert a Squirrel-object to an integer.
 206          */
 207         static int ObjectToInteger(HSQOBJECT *ptr) { return sq_objtointeger(ptr); }
 208
 209         /**
 210          * Convert a Squirrel-object to a bool.
 211          */
 212         static bool ObjectToBool(HSQOBJECT *ptr) { return sq_objtobool(ptr) == 1; }
 213
 214         /**
 215          * Sets a pointer in the VM that is reachable from where ever you are in SQ.
 216          *  Useful to keep track of the main instance.
 217          */
 218         void SetGlobalPointer(void *ptr) { this->global_pointer = ptr; }
 219
 220         /**
 221          * Get the pointer as set by SetGlobalPointer.
 222          */
 223         static void *GetGlobalPointer(HSQUIRRELVM vm) { return ((Squirrel *)sq_getforeignptr(vm))->global_pointer; }
 224
 225         /**
 226          * Set a custom print function, so you can handle outputs from SQ yourself.
 227          */
 228         void SetPrintFunction(SQPrintFunc *func) { this->print_func = func; }
 229
 230         /**
 231          * Throw a Squirrel error that will be nicely displayed to the user.
 232          */
 233         void ThrowError(const char *error) { sq_throwerror(this->vm, error); }
 234
 235         /**
 236          * Release a SQ object.
 237          */
 238         void ReleaseObject(HSQOBJECT *ptr) { sq_release(this->vm, ptr); }
 239
 240         /**
 241          * Tell the VM to remove \c amount ops from the number of ops till suspend.
 242          */
 243         static void DecreaseOps(HSQUIRRELVM vm, int amount);
 244
 245         /**
 246          * Did the squirrel code suspend or return normally.
 247          * @return True if the function suspended.
 248          */
 249         bool IsSuspended();
 250
 251         /**
 252          * Find out if the squirrel script made an error before.
 253          */
 254         bool HasScriptCrashed();
 255
 256         /**
 257          * Set the script status to crashed.
 258          */
 259         void CrashOccurred();
 260
 261         /**
 262          * Are we allowed to suspend the squirrel script at this moment?
 263          */
 264         bool CanSuspend();
 265
 266         /**
 267          * How many operations can we execute till suspension?
 268          */
 269         SQInteger GetOpsTillSuspend();
 270
 271         /**
 272          * Completely reset the engine; start from scratch.
 273          */
 274         void Reset();
 275 };
 276
 277 #endif /* SQUIRREL_HPP */