 | PixelLight 0.9.10-R1 Copyright (C) 2002-2011 by The PixelLight Team Last modified Fri Dec 23 2011 15:51:01 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: Script.h * 00003 * 00004 * Copyright (C) 2002-2011 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLCORE_SCRIPT_H__ 00024 #define __PLCORE_SCRIPT_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLCore/Base/Object.h" 00032 00033 00034 //[-------------------------------------------------------] 00035 //[ Namespace ] 00036 //[-------------------------------------------------------] 00037 namespace PLCore { 00038 00039 00040 //[-------------------------------------------------------] 00041 //[ Classes ] 00042 //[-------------------------------------------------------] 00043 /** 00044 * @brief 00045 * Abstract script base class 00046 * 00047 * @remarks 00048 * Each script should have the following properties: 00049 * - "Language": Script language (for example: "JavaScript" or "Lua") 00050 * - "Formats": File format extensions this script can load in (for example: "js" or "lua") 00051 * 00052 * Supported script features: 00053 * - Global variables (with namespace support) 00054 * - Global functions (with namespace support) 00055 * - C++ calls script 00056 * - Script calls C++ 00057 * - RTTI objects 00058 * - Properties 00059 * - Attributes 00060 * - Methods 00061 * - Signals 00062 * - Slots 00063 * 00064 * Supported primitive data types: bool, float, double, int8, int16, int32, int64, uint8, uint16, uint32, uint64, PLCore::Object*, PLCore::Object& 00065 * Please note that not each script language/API may make such a detailed data type distinction. 00066 * Because strings are fundamental within scripts, String is supported as well. 00067 */ 00068 class Script : public Object { 00069 00070 00071 //[-------------------------------------------------------] 00072 //[ RTTI interface ] 00073 //[-------------------------------------------------------] 00074 pl_class(PLCORE_RTTI_EXPORT, Script, "PLCore", PLCore::Object, "Abstract script base class") 00075 // Properties 00076 pl_properties 00077 pl_property("Language", "Unknown") 00078 pl_property("Formats", "Unknown") 00079 pl_properties_end 00080 // Attributes 00081 pl_attribute(Name, String, "", ReadWrite, DirectValue, "Name of this script, optional but recommended for better debugging", "") 00082 pl_class_end 00083 00084 00085 //[-------------------------------------------------------] 00086 //[ Public functions ] 00087 //[-------------------------------------------------------] 00088 public: 00089 /** 00090 * @brief 00091 * Destructor 00092 */ 00093 PLCORE_API virtual ~Script(); 00094 00095 /** 00096 * @brief 00097 * Returns the name of the script language the script is using 00098 * 00099 * @return 00100 * The name of the script language the script is using (for example "Lua" or "JavaScript") 00101 */ 00102 PLCORE_API String GetScriptLanguage() const; 00103 00104 /** 00105 * @brief 00106 * Returns a list of file formats this script supports 00107 * 00108 * @param[out] lstFormats 00109 * List of file formats this script supports (the given list is not cleared before new entries are added) 00110 */ 00111 PLCORE_API void GetFormats(Array<String> &lstFormats) const; 00112 00113 /** 00114 * @brief 00115 * Adds a script binding to connect the given RTTI class instance with this script 00116 * 00117 * @param[in] cObject 00118 * RTTI class instance, must stay valid as long as this script lives 00119 * @param[in] sNamespace 00120 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00121 * 00122 * @note 00123 * - The added RTTI class instance methods will be available to the script as simple global functions 00124 */ 00125 PLCORE_API void AddBinding(Object &cObject, const String &sNamespace = ""); 00126 00127 /** 00128 * @brief 00129 * Add all script bindings to this script 00130 * 00131 * @remarks 00132 * Iterates over all available script binding instances and adds them to this script. 00133 * 00134 * @note 00135 * - The added RTTI class instance methods will be available to the script as simple global functions 00136 */ 00137 PLCORE_API void AddBindings(); 00138 00139 00140 //[-------------------------------------------------------] 00141 //[ Public virtual Script functions ] 00142 //[-------------------------------------------------------] 00143 public: 00144 //[-------------------------------------------------------] 00145 //[ Global functions ] 00146 //[-------------------------------------------------------] 00147 /** 00148 * @brief 00149 * Returns whether or not the given name belongs to a global function 00150 * 00151 * @param[in] sName 00152 * Name of the global function 00153 * @param[in] sNamespace 00154 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00155 * 00156 * @return 00157 * 'true' if the given name belongs to a global function, else 'false' 00158 * 00159 * @remarks 00160 * When calling a global script function, the script backend usually writes an error into the 00161 * log when the given global script function wasn't found. So, when using optional global script 00162 * functions, it's a good idea to check whether there's such a global script function by using "IsGlobalFunction()". 00163 */ 00164 virtual bool IsGlobalFunction(const String &sName, const String &sNamespace = "") = 0; 00165 00166 /** 00167 * @brief 00168 * Adds a global function to the script 00169 * 00170 * @param[in] sFunction 00171 * Function name used inside the script to call the global function 00172 * @param[in] cDynFunc 00173 * Dynamic function 00174 * @param[in] sNamespace 00175 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00176 * 00177 * @return 00178 * 'true' if all went fine, else 'false' (maybe a script is already set?) 00179 * 00180 * @note 00181 * - If there's already a set script ("SetSourceCode()") this method will return an error 00182 */ 00183 virtual bool AddGlobalFunction(const String &sFunction, const DynFunc &cDynFunc, const String &sNamespace = "") = 0; 00184 00185 /** 00186 * @brief 00187 * Removes all global functions from the script 00188 * 00189 * @return 00190 * 'true' if all went fine, else 'false' (maybe a script is already set?) 00191 * 00192 * @note 00193 * - If there's already a set script ("SetSourceCode()") this method will return an error 00194 */ 00195 virtual bool RemoveAllGlobalFunctions() = 0; 00196 00197 //[-------------------------------------------------------] 00198 //[ Script source code ] 00199 //[-------------------------------------------------------] 00200 /** 00201 * @brief 00202 * Returns the script source code 00203 * 00204 * @return 00205 * The script source code 00206 */ 00207 virtual String GetSourceCode() const = 0; 00208 00209 /** 00210 * @brief 00211 * Sets the script source code 00212 * 00213 * @param[in] sSourceCode 00214 * Script source code, usually blank ASCII code, empty string to set to script at all 00215 * 00216 * @return 00217 * 'true' if all went fine, else 'false' 00218 */ 00219 virtual bool SetSourceCode(const String &sSourceCode) = 0; 00220 00221 //[-------------------------------------------------------] 00222 //[ Global variables ] 00223 //[-------------------------------------------------------] 00224 /** 00225 * @brief 00226 * Adds the names of found global variables to a given list 00227 * 00228 * @param[out] lstGlobalVariables 00229 * List to be filled with the names (without namespace) of the found global variables, the given list is not cleared before new entries are added 00230 * @param[in] sNamespace 00231 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00232 */ 00233 virtual void GetGlobalVariables(Array<String> &lstGlobalVariables, const String &sNamespace = "") = 0; 00234 00235 /** 00236 * @brief 00237 * Returns whether or not the given name belongs to a global variable 00238 * 00239 * @param[in] sName 00240 * Name of the global variable 00241 * @param[in] sNamespace 00242 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00243 * 00244 * @return 00245 * 'true' if the given name belongs to a global variable, else 'false' 00246 */ 00247 virtual bool IsGlobalVariable(const String &sName, const String &sNamespace = "") = 0; 00248 00249 /** 00250 * @brief 00251 * Returns the type ID a global variable 00252 * 00253 * @param[in] sName 00254 * Name of the global variable 00255 * @param[in] sNamespace 00256 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00257 * 00258 * @return 00259 * The type ID of the global variable (e.g. "PLCore::TypeFloat" for "float") or "PLCore::TypeInvalid" on error 00260 */ 00261 virtual ETypeID GetGlobalVariableTypeID(const String &sName, const String &sNamespace = "") = 0; 00262 00263 /** 00264 * @brief 00265 * Returns the current value of a global variable 00266 * 00267 * @param[in] sName 00268 * Name of the global variable 00269 * @param[in] sNamespace 00270 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00271 * 00272 * @return 00273 * The current value of the global variable 00274 */ 00275 virtual String GetGlobalVariable(const String &sName, const String &sNamespace = "") = 0; 00276 00277 /** 00278 * @brief 00279 * Sets the current value of a global variable 00280 * 00281 * @param[in] sName 00282 * Name of the global variable 00283 * @param[in] cValue 00284 * New value of the global variable 00285 * @param[in] sNamespace 00286 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00287 * 00288 * @note 00289 * - If there's no global variable with the given name, a new global variable is added to the script 00290 * - Please note that it depends on the used script language/API which data types are really available, 00291 * this means that "GetGlobalVariableTypeID()" may return another data type as the one you specified 00292 */ 00293 virtual void SetGlobalVariable(const String &sName, const DynVar &cValue, const String &sNamespace = "") = 0; 00294 00295 //[-------------------------------------------------------] 00296 //[ Global function call, used by "FuncScriptPtr" ] 00297 //[-------------------------------------------------------] 00298 /** 00299 * @brief 00300 * Starts a function call 00301 * 00302 * @param[in] sFunctionName 00303 * Name of the function to call 00304 * @param[in] sFunctionSignature 00305 * Signature of the function to call (e.g. "void(int,float)") 00306 * @param[in] sNamespace 00307 * Optional namespace (e.g. "MyNamespace", "MyNamespace.MyOtherNamespace" and so on) 00308 * 00309 * @return 00310 * 'true' if all went fine, else 'false' 00311 * 00312 * @note 00313 * - It's not recommended to use this method directly, use "FuncScriptPtr" instead 00314 * 00315 * @see 00316 * - Have a look at "IsGlobalFunction()" for additional information 00317 */ 00318 virtual bool BeginCall(const String &sFunctionName, const String &sFunctionSignature, const String &sNamespace = "") = 0; 00319 00320 /** 00321 * @brief 00322 * Pushes an argument required for the current function call 00323 * 00324 * @param[in] nValue 00325 * Argument value 00326 * 00327 * @note 00328 * - It's not recommended to use this method directly, use "FuncScriptPtr" instead 00329 */ 00330 virtual void PushArgument(bool bValue) = 0; 00331 virtual void PushArgument(float fValue) = 0; 00332 virtual void PushArgument(double fValue) = 0; 00333 virtual void PushArgument(int8 nValue) = 0; 00334 virtual void PushArgument(int16 nValue) = 0; 00335 virtual void PushArgument(int32 nValue) = 0; 00336 virtual void PushArgument(int64 nValue) = 0; 00337 virtual void PushArgument(uint8 nValue) = 0; 00338 virtual void PushArgument(uint16 nValue) = 0; 00339 virtual void PushArgument(uint32 nValue) = 0; 00340 virtual void PushArgument(uint64 nValue) = 0; 00341 virtual void PushArgument(const String &sString) = 0; 00342 virtual void PushArgument(Object *pObject) = 0; 00343 virtual void PushArgument(Object &cObject) = 0; 00344 00345 /** 00346 * @brief 00347 * Ends a function call 00348 * 00349 * @return 00350 * 'true' if all went fine, else 'false' 00351 * 00352 * @note 00353 * - It's not recommended to use this method directly, use "FuncScriptPtr" instead 00354 * - This actually performs the prepared function call 00355 */ 00356 virtual bool EndCall() = 0; 00357 00358 /** 00359 * @brief 00360 * Returns the result of a function call 00361 * 00362 * @param[in] nValue 00363 * Unused value... just there so the compiler can figure out the proper method 00364 * 00365 * @return 00366 * The result of a function call 00367 * 00368 * @note 00369 * - It's not recommended to use this method directly, use "FuncScriptPtr" instead 00370 */ 00371 virtual bool GetReturn(bool nValue) = 0; 00372 virtual float GetReturn(float nValue) = 0; 00373 virtual double GetReturn(double nValue) = 0; 00374 virtual int8 GetReturn(int8 nValue) = 0; 00375 virtual int16 GetReturn(int16 nValue) = 0; 00376 virtual int32 GetReturn(int32 nValue) = 0; 00377 virtual int64 GetReturn(int64 nValue) = 0; 00378 virtual uint8 GetReturn(uint8 nValue) = 0; 00379 virtual uint16 GetReturn(uint16 nValue) = 0; 00380 virtual uint32 GetReturn(uint32 nValue) = 0; 00381 virtual uint64 GetReturn(uint64 nValue) = 0; 00382 virtual String GetReturn(String nValue) = 0; 00383 virtual Object *GetReturn(Object *nValue) = 0; 00384 virtual Object &GetReturn(Object &nValue) = 0; 00385 00386 00387 //[-------------------------------------------------------] 00388 //[ Protected functions ] 00389 //[-------------------------------------------------------] 00390 protected: 00391 /** 00392 * @brief 00393 * Constructor 00394 */ 00395 PLCORE_API Script(); 00396 00397 /** 00398 * @brief 00399 * Write a string into the log 00400 * 00401 * @param[in] nLogLevel 00402 * Log level 00403 * @param[in] sText 00404 * Text which should be written into the log 00405 * 00406 * @return 00407 * 'true' if all went fine, else 'false' 00408 * 00409 * @remarks 00410 * The text is written to the log only if the current 00411 * log level is greater or equal to the specified value. 00412 * This method is an extension of "Log::Output()" 00413 * which also adds the name of the script to the given 00414 * text. 00415 */ 00416 PLCORE_API bool LogOutput(uint8 nLogLevel, const String &sText); 00417 00418 00419 //[-------------------------------------------------------] 00420 //[ Private functions ] 00421 //[-------------------------------------------------------] 00422 private: 00423 /** 00424 * @brief 00425 * Copy constructor 00426 * 00427 * @param[in] cSource 00428 * Source to copy from 00429 */ 00430 Script(const Script &cSource); 00431 00432 /** 00433 * @brief 00434 * Copy operator 00435 * 00436 * @param[in] cSource 00437 * Source to copy from 00438 * 00439 * @return 00440 * Reference to this instance 00441 */ 00442 Script &operator =(const Script &cSource); 00443 00444 00445 }; 00446 00447 00448 //[-------------------------------------------------------] 00449 //[ Namespace ] 00450 //[-------------------------------------------------------] 00451 } // PLCore 00452 00453 00454 #endif // __PLCORE_SCRIPT_H__
|