OpenTTD
squirrel.hpp
Go to the documentation of this file.
1 /* $Id$ */
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 
12 #ifndef SQUIRREL_HPP
13 #define SQUIRREL_HPP
14 
15 #include <squirrel.h>
16 
18 enum ScriptType {
21 };
22 
23 struct ScriptAllocator;
24 
25 class Squirrel {
26  friend class ScriptAllocatorScope;
27 
28 private:
29  typedef void (SQPrintFunc)(bool error_msg, const SQChar *message);
30 
31  HSQUIRRELVM vm;
33  SQPrintFunc *print_func;
34  bool crashed;
36  const char *APIName;
37  std::unique_ptr<ScriptAllocator> allocator;
38 
42  static SQInteger _RunError(HSQUIRRELVM vm);
43 
47  const char *GetAPIName() { return this->APIName; }
48 
50  void Initialize();
52  void Uninitialize();
53 
54 protected:
58  static void CompileError(HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column);
59 
63  static void RunError(HSQUIRRELVM vm, const SQChar *error);
64 
68  static void PrintFunc(HSQUIRRELVM vm, const SQChar *s, ...);
69 
73  static void ErrorPrintFunc(HSQUIRRELVM vm, const SQChar *s, ...);
74 
75 public:
76  Squirrel(const char *APIName);
77  ~Squirrel();
78 
82  HSQUIRRELVM GetVM() { return this->vm; }
83 
89  bool LoadScript(const char *script);
90  bool LoadScript(HSQUIRRELVM vm, const char *script, bool in_root = true);
91 
95  SQRESULT LoadFile(HSQUIRRELVM vm, const char *filename, SQBool printerror);
96 
101  void AddMethod(const char *method_name, SQFUNCTION proc, uint nparam = 0, const char *params = nullptr, void *userdata = nullptr, int size = 0);
102 
107  void AddConst(const char *var_name, int value);
108 
113  void AddConst(const char *var_name, uint value) { this->AddConst(var_name, (int)value); }
114 
119  void AddConst(const char *var_name, bool value);
120 
125  void AddClassBegin(const char *class_name);
126 
131  void AddClassBegin(const char *class_name, const char *parent_class);
132 
137  void AddClassEnd();
138 
142  bool Resume(int suspend = -1);
143 
147  void ResumeError();
148 
152  void CollectGarbage();
153 
154  void InsertResult(bool result);
155  void InsertResult(int result);
156  void InsertResult(uint result) { this->InsertResult((int)result); }
157 
162  bool CallMethod(HSQOBJECT instance, const char *method_name, HSQOBJECT *ret, int suspend);
163  bool CallMethod(HSQOBJECT instance, const char *method_name, int suspend) { return this->CallMethod(instance, method_name, nullptr, suspend); }
164  bool CallStringMethodStrdup(HSQOBJECT instance, const char *method_name, const char **res, int suspend);
165  bool CallIntegerMethod(HSQOBJECT instance, const char *method_name, int *res, int suspend);
166  bool CallBoolMethod(HSQOBJECT instance, const char *method_name, bool *res, int suspend);
167 
171  bool MethodExists(HSQOBJECT instance, const char *method_name);
172 
183  static bool CreateClassInstanceVM(HSQUIRRELVM vm, const char *class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name = false);
184 
188  bool CreateClassInstance(const char *class_name, void *real_instance, HSQOBJECT *instance);
189 
195  static bool GetRealInstance(HSQUIRRELVM vm, SQUserPointer *ptr) { return SQ_SUCCEEDED(sq_getinstanceup(vm, 1, ptr, 0)); }
196 
202  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; }
203 
207  static const char *ObjectToString(HSQOBJECT *ptr) { return sq_objtostring(ptr); }
208 
212  static int ObjectToInteger(HSQOBJECT *ptr) { return sq_objtointeger(ptr); }
213 
217  static bool ObjectToBool(HSQOBJECT *ptr) { return sq_objtobool(ptr) == 1; }
218 
223  void SetGlobalPointer(void *ptr) { this->global_pointer = ptr; }
224 
228  static void *GetGlobalPointer(HSQUIRRELVM vm) { return ((Squirrel *)sq_getforeignptr(vm))->global_pointer; }
229 
233  void SetPrintFunction(SQPrintFunc *func) { this->print_func = func; }
234 
238  void ThrowError(const char *error) { sq_throwerror(this->vm, error); }
239 
243  void ReleaseObject(HSQOBJECT *ptr) { sq_release(this->vm, ptr); }
244 
248  static void DecreaseOps(HSQUIRRELVM vm, int amount);
249 
254  bool IsSuspended();
255 
259  bool HasScriptCrashed();
260 
264  void CrashOccurred();
265 
269  bool CanSuspend();
270 
274  SQInteger GetOpsTillSuspend();
275 
279  void Reset();
280 
284  size_t GetAllocatedMemory() const noexcept;
285 };
286 
287 
288 extern ScriptAllocator *_squirrel_allocator;
289 
291  ScriptAllocator *old_allocator;
292 
293 public:
294  ScriptAllocatorScope(const Squirrel *engine)
295  {
296  this->old_allocator = _squirrel_allocator;
297  /* This may get called with a nullptr engine, in case of a crashed script */
298  _squirrel_allocator = engine != nullptr ? engine->allocator.get() : nullptr;
299  }
300 
302  {
303  _squirrel_allocator = this->old_allocator;
304  }
305 };
306 
307 #endif /* SQUIRREL_HPP */
static bool GetRealInstance(HSQUIRRELVM vm, SQUserPointer *ptr)
Get the real-instance pointer.
Definition: squirrel.hpp:195
static const char * ObjectToString(HSQOBJECT *ptr)
Convert a Squirrel-object to a string.
Definition: squirrel.hpp:207
static void PrintFunc(HSQUIRRELVM vm, const SQChar *s,...)
If a user runs &#39;print&#39; inside a script, this function gets the params.
Definition: squirrel.cpp:208
bool HasScriptCrashed()
Find out if the squirrel script made an error before.
Definition: squirrel.cpp:737
void * global_pointer
Can be set by who ever initializes Squirrel.
Definition: squirrel.hpp:32
void ThrowError(const char *error)
Throw a Squirrel error that will be nicely displayed to the user.
Definition: squirrel.hpp:238
bool CallMethod(HSQOBJECT instance, const char *method_name, HSQOBJECT *ret, int suspend)
Call a method of an instance, in various flavors.
Definition: squirrel.cpp:347
static void CompileError(HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column)
The CompileError handler.
Definition: squirrel.cpp:135
std::unique_ptr< ScriptAllocator > allocator
Allocator object used by this script.
Definition: squirrel.hpp:37
void CollectGarbage()
Tell the VM to do a garbage collection run.
Definition: squirrel.cpp:341
SQInteger GetOpsTillSuspend()
How many operations can we execute till suspension?
Definition: squirrel.cpp:753
static bool GetInstance(HSQUIRRELVM vm, HSQOBJECT *ptr, int pos=1)
Get the Squirrel-instance pointer.
Definition: squirrel.hpp:202
size_t GetAllocatedMemory() const noexcept
Get number of bytes allocated by this VM.
Definition: squirrel.cpp:128
static SQInteger _RunError(HSQUIRRELVM vm)
The internal RunError handler.
Definition: squirrel.cpp:193
void CrashOccurred()
Set the script status to crashed.
Definition: squirrel.cpp:742
static void DecreaseOps(HSQUIRRELVM vm, int amount)
Tell the VM to remove amount ops from the number of ops till suspend.
Definition: squirrel.cpp:727
bool CreateClassInstance(const char *class_name, void *real_instance, HSQOBJECT *instance)
Exactly the same as CreateClassInstanceVM, only callable without instance of Squirrel.
Definition: squirrel.cpp:459
The script is for AI scripts.
Definition: squirrel.hpp:19
static void * GetGlobalPointer(HSQUIRRELVM vm)
Get the pointer as set by SetGlobalPointer.
Definition: squirrel.hpp:228
bool crashed
True if the squirrel script made an error.
Definition: squirrel.hpp:34
const char * GetAPIName()
Get the API name.
Definition: squirrel.hpp:47
ScriptType
The type of script we&#39;re working with, i.e.
Definition: squirrel.hpp:18
static bool ObjectToBool(HSQOBJECT *ptr)
Convert a Squirrel-object to a bool.
Definition: squirrel.hpp:217
The script is for Game scripts.
Definition: squirrel.hpp:20
void ResumeError()
Resume the VM with an error so it prints a stack trace.
Definition: squirrel.cpp:334
int overdrawn_ops
The amount of operations we have overdrawn.
Definition: squirrel.hpp:35
static bool CreateClassInstanceVM(HSQUIRRELVM vm, const char *class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name=false)
Creates a class instance.
Definition: squirrel.cpp:409
bool IsSuspended()
Did the squirrel code suspend or return normally.
Definition: squirrel.cpp:732
void AddMethod(const char *method_name, SQFUNCTION proc, uint nparam=0, const char *params=nullptr, void *userdata=nullptr, int size=0)
Adds a function to the stack.
Definition: squirrel.cpp:227
HSQUIRRELVM GetVM()
Get the squirrel VM.
Definition: squirrel.hpp:82
static int ObjectToInteger(HSQOBJECT *ptr)
Convert a Squirrel-object to an integer.
Definition: squirrel.hpp:212
void Reset()
Completely reset the engine; start from scratch.
Definition: squirrel.cpp:699
bool CanSuspend()
Are we allowed to suspend the squirrel script at this moment?
Definition: squirrel.cpp:747
void SetGlobalPointer(void *ptr)
Sets a pointer in the VM that is reachable from where ever you are in SQ.
Definition: squirrel.hpp:223
void AddConst(const char *var_name, int value)
Adds a const to the stack.
Definition: squirrel.cpp:244
bool MethodExists(HSQOBJECT instance, const char *method_name)
Check if a method exists in an instance.
Definition: squirrel.cpp:294
SQRESULT LoadFile(HSQUIRRELVM vm, const char *filename, SQBool printerror)
Load a file to a given VM.
Definition: squirrel.cpp:569
void CDECL error(const char *s,...)
Error handling for fatal non-user errors.
Definition: openttd.cpp:114
void AddClassBegin(const char *class_name)
Adds a class to the global scope.
Definition: squirrel.cpp:262
void AddConst(const char *var_name, uint value)
Adds a const to the stack.
Definition: squirrel.hpp:113
HSQUIRRELVM vm
The VirtualMachine instance for squirrel.
Definition: squirrel.hpp:31
static void RunError(HSQUIRRELVM vm, const SQChar *error)
The RunError handler.
Definition: squirrel.cpp:170
const char * APIName
Name of the API used for this squirrel.
Definition: squirrel.hpp:36
bool LoadScript(const char *script)
Load a script.
Definition: squirrel.cpp:680
void Uninitialize()
Perform all the cleanups for the engine.
Definition: squirrel.cpp:690
void ReleaseObject(HSQOBJECT *ptr)
Release a SQ object.
Definition: squirrel.hpp:243
void AddClassEnd()
Finishes adding a class to the global scope.
Definition: squirrel.cpp:286
SQPrintFunc * print_func
Points to either nullptr, or a custom print handler.
Definition: squirrel.hpp:33
static void ErrorPrintFunc(HSQUIRRELVM vm, const SQChar *s,...)
If an error has to be print, this function is called.
Definition: squirrel.cpp:152
void Initialize()
Perform all initialization steps to create the engine.
Definition: squirrel.cpp:471
bool Resume(int suspend=-1)
Resume a VM when it was suspended via a throw.
Definition: squirrel.cpp:312
void SetPrintFunction(SQPrintFunc *func)
Set a custom print function, so you can handle outputs from SQ yourself.
Definition: squirrel.hpp:233