1 /* "CodeWorker": a scripting language for parsing and generating text. 2 3 Copyright (C) 1996-1997, 1999-2003 C�dric Lemaire 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 This library 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 GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with this library; if not, write to the Free Software 17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 19 To contact the author: codeworker@free.fr 20 */ 21 22 #ifndef _CodeWorker_for_dynamic_libraries_h_ 23 #define _CodeWorker_for_dynamic_libraries_h_ 24 25 /** 26 * ------------------------------------------------------- 27 * CW4dl: CodeWorker header for building dynamic libraries 28 * ------------------------------------------------------- 29 * 30 * This C++ header provides all what you need to construct a new package 31 * intended to CodeWorker. 32 * There is no C++ body for this file. Just include this file in your 33 * project, and it is sufficient. 34 * 35 * 36 * What you have to know for building a new package. 37 * ------------------------------------------------- 38 * 39 * Let say that the package's name is 'XXX'. The corresponding executable 40 * module (dynamic library) will be "XXXcw.dll" under Windows, and 41 * "XXXcw.so" under Linux or other. 42 * 43 * When the interpreter will found the preprocessor directive '#use XXX' 44 * in a script, it will load the executable module and execute the 45 * exported C-like function 'void XXX_Init(CW4dl::Interpreter*)'. 46 * 47 * This C-like function MUST be present! 'C-like' means that it is declared 48 * extern "C". 49 * 50 * Initializing the module that way is useful for registering new functions 51 * in the engine, via the function 'createCommand()' of the interpreter 52 * (see below in the declaration of the class 'Interpreter' for learning 53 * more about it). 54 * 55 * Every function to export must start its declaration with the preprocessor 56 * definition 'CW4DL_EXPORT_SYMBOL' (means 'extern "C"', but a little more 57 * under Windows). 58 * 59 * # Up to 4 parameters, the signature of such a function looks like: 60 * CW4DL_EXPORT_SYMBOL const char* selectList(CW4dl::Interpreter*, 61 * CW4dl::Parameter p1, 62 * CW4dl::Parameter p2); 63 * where 'selectList' is a function expecting 2 parameters. 64 * 65 * The initializer 'XXX_Init' informs the engine about the existence 66 * of this function in the package: 67 * createCommand("selectList", VALUE_PARAMETER, NODE_PARAMETER); 68 * which means that 'selectList' expects a string followed by a tree. 69 * 70 * In the body of the function 'selectList(...)', the C++ binding is 71 * obtained easily by a cast of 'CW4dl::Parameter': 72 * - '(const char*) p1' for the value parameter 'p1', 73 * - '(CW4dl::Tree*) p2' for the node parameter 'p2', 74 * 75 * # if a function contains strictly more than 4 parameter, its signature 76 * # changes and requires a variable number of parameters: 77 * CW4DL_EXPORT_SYMBOL const char* myFunction(CW4dl::Interpreter*, 78 * int nbParams, 79 * CW4dl::Parameter* tParams); 80 * where 'tParams' is an array of parameter types, and where 'nbParams' gives 81 * the size. 82 * 83 * The initializer 'XXX_Init' informs the engine about the existence 84 * of this function in the package differently too: 85 * createCommand("myFunction", 6, tParams); 86 * which means that 'myFunction' has 6 parameters whose types are provided 87 * in 'tParams'. 88 * 89 * Note that every function returns 'const char*'. 90 **/ 91 92 93 /** 94 * ------------------------------------------------------- 95 * CW4dl: CodeWorker header for building dynamic libraries 96 * ------------------------------------------------------- 97 * 98 * This C++ header provides all what you need to construct a new package 99 * intended to CodeWorker. 100 * There is no C++ body for this file. Just include this file in your 101 * project, and it is sufficient. 102 * 103 * 104 * What you have to know for building a new package. 105 * ------------------------------------------------- 106 * 107 * Let say that the package's name is 'XXX'. The corresponding executable 108 * module (dynamic library) will be "XXXcw.dll" under Windows, and 109 * "XXXcw.so" under Linux or other. 110 * 111 * When the interpreter will found the preprocessor directive '#use XXX' 112 * in a script, it will load the executable module and execute the 113 * exported C-like function 'void XXX_Init(CW4dl::Interpreter*)'. 114 * 115 * This C-like function MUST be present! 'C-like' means that it is declared 116 * extern "C". 117 * 118 * Initializing the module that way is useful for registering new functions 119 * in the engine, via the function 'createCommand()' of the interpreter 120 * (see below in the declaration of the class 'Interpreter' for learning 121 * more about it). 122 * 123 * Every function to export must start its declaration with the preprocessor 124 * definition 'CW4DL_EXPORT_SYMBOL' (means 'extern "C"', but a little more 125 * under Windows). 126 * 127 * # Up to 4 parameters, the signature of such a function looks like: 128 * CW4DL_EXPORT_SYMBOL const char* selectList(CW4dl::Interpreter*, 129 * CW4dl::Parameter p1, 130 * CW4dl::Parameter p2); 131 * where 'selectList' is a function expecting 2 parameters. 132 * 133 * The initializer 'XXX_Init' informs the engine about the existence 134 * of this function in the package: 135 * createCommand("selectList", VALUE_PARAMETER, NODE_PARAMETER); 136 * which means that 'selectList' expects a string followed by a tree. 137 * 138 * In the body of the function 'selectList(...)', the C++ binding is 139 * obtained easily by a cast of 'CW4dl::Parameter': 140 * - '(const char*) p1' for the value parameter 'p1', 141 * - '(CW4dl::Tree*) p2' for the node parameter 'p2', 142 * 143 * # if a function contains strictly more than 4 parameter, its signature 144 * # changes and requires a variable number of parameters: 145 * CW4DL_EXPORT_SYMBOL const char* myFunction(CW4dl::Interpreter*, 146 * int nbParams, 147 * CW4dl::Parameter* tParams); 148 * where 'tParams' is an array of parameter types, and where 'nbParams' gives 149 * the size. 150 * 151 * The initializer 'XXX_Init' informs the engine about the existence 152 * of this function in the package differently too: 153 * createCommand("myFunction", 6, tParams); 154 * which means that 'myFunction' has 6 parameters whose types are provided 155 * in 'tParams'. 156 * 157 * Note that every function returns 'const char*'. 158 **/ 159 160 namespace CodeWorker { 161 // type of an external instance, of a type defined by the plugin developer. 162 class ExternalValueNode; 163 } 164 165 166 namespace CW4dl { 167 /** 168 * One may share 2 kinds of parameter between the interpreter and 169 * the executable module: 170 * - value: binds to a 'const char*' 171 * - node: binds to a 'CW4dl::Tree*', which refers to the classical 172 * tree structure of CodeWorker 173 **/ 174 enum PARAMETER_TYPE { 175 VALUE_PARAMETER, 176 NODE_PARAMETER 177 }; 178 179 // see further to understand the role of 'Interpreter' 180 class Interpreter; 181 182 /** 183 * The preprocessor definition 'CW4DL_EXPORT_SYMBOL' must appear just 184 * before the declaration of functions to export. 185 **/ 186 # ifdef WIN32 187 # define CW4DL_EXPORT_SYMBOL extern "C" _declspec(dllexport) 188 # else 189 # define CW4DL_EXPORT_SYMBOL extern "C" 190 # endif 191 192 typedef void* Parameter; 193 typedef void* Tree; 194 typedef void* Function; 195 196 typedef void* DynPackage; // private declaration. Don't care about it. 197 198 199 /** class 'Parameter2CW' 200 * Type of parameters to pass to the interpreter when calling a CodeWorker's 201 * function. See Interpreter::callFunction(...). 202 **/ 203 class Parameter2CW { 204 private: 205 bool _bValue; 206 union PARAMETER2CW_TYPE { 207 const char* _tcValue; 208 Tree* _pNode; 209 }; 210 PARAMETER2CW_TYPE _param; 211 212 public: Parameter2CW(const char * tcValue)213 inline Parameter2CW(const char* tcValue) : _bValue(true) { _param._tcValue = tcValue; } Parameter2CW(Tree * pNode)214 inline Parameter2CW(Tree* pNode) : _bValue(false) { _param._pNode = pNode; } 215 }; 216 217 218 // Private callback signatures for calling CodeWorker's features from 219 // the module. 220 // You aren't concerned by them. 221 typedef bool (*CREATE_COMMAND0)(DynPackage*, const char*); 222 typedef bool (*CREATE_COMMAND1)(DynPackage*, const char*, bool); 223 typedef bool (*CREATE_COMMAND2)(DynPackage*, const char*, bool, bool); 224 typedef bool (*CREATE_COMMAND3)(DynPackage*, const char*, bool, bool, bool); 225 typedef bool (*CREATE_COMMAND4)(DynPackage*, const char*, bool, bool, bool, bool); 226 typedef bool (*CREATE_COMMANDN)(DynPackage*, const char*, int, int*); 227 typedef Tree* (*CREATE_VARIABLE)(DynPackage*, const char*); 228 typedef void (*ERROR_COMMAND)(const char*); 229 typedef const char* (*COPY_LOCAL_STRING)(Interpreter* pInterpreter, const char*); 230 typedef const char* (*COPY_LOCAL_BOOLEAN)(Interpreter* pInterpreter, bool); 231 typedef const char* (*COPY_LOCAL_INT)(Interpreter* pInterpreter, int); 232 typedef const char* (*COPY_LOCAL_DOUBLE)(Interpreter* pInterpreter, double); 233 234 typedef Tree* (*CREATE_TREE)(const char*); 235 typedef const char* (*GET_VALUE)(Tree*); 236 typedef int (*GET_INT_VALUE)(Tree*); 237 typedef double (*GET_DOUBLE_VALUE)(Tree*); 238 typedef bool (*GET_BOOLEAN_VALUE)(Tree*); 239 typedef CodeWorker::ExternalValueNode* (*GET_EXTERNAL_VALUE)(Tree*); 240 typedef void (*SET_VALUE)(Tree*, const char*); 241 typedef void (*SET_EXTERNAL_VALUE)(Tree*, CodeWorker::ExternalValueNode*); 242 typedef void (*SET_INT_VALUE)(Tree*, int); 243 typedef void (*SET_BOOLEAN_VALUE)(Tree*, bool); 244 typedef void (*SET_DOUBLE_VALUE)(Tree*, double); 245 typedef Tree* (*NEXT_NODE)(Tree*, const char*); 246 typedef Tree* (*INSERT_NODE)(Tree*, const char*); 247 typedef void (*CLEAR_NODE)(Tree*); 248 typedef int (*SIZE_ARRAY)(Tree*); 249 typedef int (*ALL_KEYS)(Tree*, const char**); 250 typedef int (*ALL_VALUES)(Tree*, const char**); 251 typedef Tree* (*GET_ITEM_FROM_KEY)(Tree*, const char*); 252 typedef Tree* (*GET_ITEM_FROM_POS)(Tree*, int); 253 typedef const char* (*GET_ITEM_KEY)(Tree*, int); 254 typedef Tree* (*PUSH_ITEM)(Tree*, const char*); 255 typedef Tree* (*INSERT_ITEM)(Tree*, const char*, const char*); 256 257 typedef Function* (*FIND_FUNCTION)(Interpreter* pInterpreter, const char*); 258 259 typedef const char* (*CALL_FUNCTION0)(Interpreter* pInterpreter, Function*); 260 typedef const char* (*CALL_FUNCTION1)(Interpreter* pInterpreter, Function*, Parameter2CW); 261 typedef const char* (*CALL_FUNCTION2)(Interpreter* pInterpreter, Function*, Parameter2CW, Parameter2CW); 262 typedef const char* (*CALL_FUNCTION3)(Interpreter* pInterpreter, Function*, Parameter2CW, Parameter2CW, Parameter2CW); 263 typedef const char* (*CALL_FUNCTION4)(Interpreter* pInterpreter, Function*, Parameter2CW, Parameter2CW, Parameter2CW, Parameter2CW); 264 265 typedef void (*RELEASE_FUNCTION)(Function*); 266 267 268 /** class 'Interpreter' 269 * It represents the runtime context of CodeWorker. It is the unavoidable 270 * intermediary between the module you are building and CodeWorker. 271 * Use it for: 272 * - registering new functions into the CodeWorker's engine, 273 * - throwing an error, 274 * - handling parse trees, 275 **/ 276 class Interpreter { 277 private: 278 // Private callbacks for calling CodeWorker's features. 279 // Don't care about it 280 CREATE_COMMAND0 _createCommand0; 281 CREATE_COMMAND1 _createCommand1; 282 CREATE_COMMAND2 _createCommand2; 283 CREATE_COMMAND3 _createCommand3; 284 CREATE_COMMAND4 _createCommand4; 285 CREATE_COMMANDN _createCommandN; 286 CREATE_VARIABLE _createVariable; 287 ERROR_COMMAND _error; 288 COPY_LOCAL_STRING _copyLocalString; 289 COPY_LOCAL_BOOLEAN _copyLocalBoolean; 290 COPY_LOCAL_INT _copyLocalInt; 291 COPY_LOCAL_DOUBLE _copyLocalDouble; 292 293 CREATE_TREE _createTree; 294 GET_VALUE _getValue; 295 GET_INT_VALUE _getIntValue; 296 GET_DOUBLE_VALUE _getDoubleValue; 297 GET_BOOLEAN_VALUE _getBooleanValue; 298 GET_EXTERNAL_VALUE _getExternalValue; 299 SET_VALUE _setValue; 300 SET_EXTERNAL_VALUE _setExternalValue; 301 SET_INT_VALUE _setIntValue; 302 SET_DOUBLE_VALUE _setDoubleValue; 303 SET_BOOLEAN_VALUE _setBooleanValue; 304 NEXT_NODE _nextNode; 305 INSERT_NODE _insertNode; 306 CLEAR_NODE _clearNode; 307 308 SIZE_ARRAY _sizeArray; 309 ALL_KEYS _allKeys; 310 ALL_VALUES _allValues; 311 GET_ITEM_FROM_KEY _getItemFromKey; 312 GET_ITEM_FROM_POS _getItemFromPos; 313 GET_ITEM_KEY _getItemKey; 314 PUSH_ITEM _pushItem; 315 INSERT_ITEM _insertItem; 316 317 FIND_FUNCTION _findFunction; 318 CALL_FUNCTION0 _callFunction0; 319 CALL_FUNCTION1 _callFunction1; 320 CALL_FUNCTION2 _callFunction2; 321 CALL_FUNCTION3 _callFunction3; 322 CALL_FUNCTION4 _callFunction4; 323 RELEASE_FUNCTION _releaseFunction; 324 325 // Reference to the CodeWorker's package that manages this module. 326 // Don't care about it. 327 DynPackage* _pPackage; 328 329 // Variable scope of the interpreter. 330 // Not used, but might be in future callbacks. 331 Tree* _pVisibility; 332 333 // Contains a string allocated locally. Don't care about this field. 334 char* _tcLocalString; 335 336 public: 337 //------------------------------------------------------------------ 338 // Creating new functions to register in CodeWorker. 339 //-------------------------------------------------- 340 // 341 // Enriching the engine of CodeWorker with new functions is done by 342 // calling 'createCommand()'. 343 // 344 // These calls are done just after loading the module in 345 // CodeWorker (preprocessor statement '#use'), when the engine 346 // initializes the library, running the exported special function 347 // 'xxx_Init' (where 'xxx' is the name of the package). 348 // 349 // The signature of the initializer conforms to: 350 // 'CW4DL_EXPORT_SYMBOL void xxx_Init(CW4dl::Interpreter* interpreter)' 351 //------------------------------------------------------------------ 352 353 /** function 'createCommand()' 354 * createCommand() serves to inform the engine of CodeWorker about 355 * the functions exported by the package, giving their signature. 356 * Each createCommand() takes the name of the function as the first 357 * parameter. Then, it describes the type of parameters: 358 * - VALUE_PARAMETER: 'const char*' in the C++ binding, 359 * - NODE_PARAMETER: 'CW4dl::Tree*' in the C++ binding. 360 * 361 * To register functions belonging up to 4 parameters, use the function 362 * with the fixed number of parameters (5 first functions). 363 * To register functions expecting strictly more that 4 parameters, 364 * use the 'createCommand()' with variable number of parameters. 365 **/ createCommand(const char * tcName)366 inline bool createCommand(const char* tcName) { return _createCommand0(_pPackage, tcName); } createCommand(const char * tcName,PARAMETER_TYPE p1)367 inline bool createCommand(const char* tcName, PARAMETER_TYPE p1) { return _createCommand1(_pPackage, tcName, (p1 == NODE_PARAMETER)); } createCommand(const char * tcName,PARAMETER_TYPE p1,PARAMETER_TYPE p2)368 inline bool createCommand(const char* tcName, PARAMETER_TYPE p1, PARAMETER_TYPE p2) { return _createCommand2(_pPackage, tcName, (p1 == NODE_PARAMETER), (p2 == NODE_PARAMETER)); } createCommand(const char * tcName,PARAMETER_TYPE p1,PARAMETER_TYPE p2,PARAMETER_TYPE p3)369 inline bool createCommand(const char* tcName, PARAMETER_TYPE p1, PARAMETER_TYPE p2, PARAMETER_TYPE p3) { return _createCommand3(_pPackage, tcName, (p1 == NODE_PARAMETER), (p2 == NODE_PARAMETER), (p3 == NODE_PARAMETER)); } createCommand(const char * tcName,PARAMETER_TYPE p1,PARAMETER_TYPE p2,PARAMETER_TYPE p3,PARAMETER_TYPE p4)370 inline bool createCommand(const char* tcName, PARAMETER_TYPE p1, PARAMETER_TYPE p2, PARAMETER_TYPE p3, PARAMETER_TYPE p4) { return _createCommand4(_pPackage, tcName, (p1 == NODE_PARAMETER), (p2 == NODE_PARAMETER), (p3 == NODE_PARAMETER), (p4 == NODE_PARAMETER)); } createCommand(const char * tcName,int iNbParams,PARAMETER_TYPE * tParams)371 inline bool createCommand(const char* tcName, int iNbParams, PARAMETER_TYPE* tParams) { return _createCommandN(_pPackage, tcName, iNbParams, (int*) tParams); } 372 createVariable(const char * tcName)373 inline Tree* createVariable(const char* tcName) { return _createVariable(_pPackage, tcName); } 374 375 /** function 'copyLocalString(...)' 376 * Both CodeWorker and the shared library have their own heap 377 * management. 378 * You can't allocate memory in the module and desallocate 379 * it in CodeWorker. 380 * To pass a string as a result of function, it must be either 381 * a constant string or a string you have to delete after its 382 * use. 383 * But when, and how? 384 * The string will be allocated in the body of the function and 385 * desallocated by the interpreter after the call. You allocate 386 * the string by running 'copyLocalString()': 387 * Parameter: 388 * - tcText: a constant string to copy, 389 * Return value: 390 * The duplicated input string, allocated in the scope of 391 * the interpreter. 392 **/ copyLocalString(const char * tcText)393 inline const char* copyLocalString(const char* tcText) { return _copyLocalString(this, tcText); } copyLocalBoolean(bool bValue)394 inline const char* copyLocalBoolean(bool bValue) { return _copyLocalBoolean(this, bValue); } copyLocalInt(int iValue)395 inline const char* copyLocalInt(int iValue) { return _copyLocalInt(this, iValue); } copyLocalDouble(double dValue)396 inline const char* copyLocalDouble(double dValue) { return _copyLocalDouble(this, dValue); } 397 398 /** function 'error(...)' 399 * Throws an error. 400 * 401 * Equivalent to the function 'error(...)' available in the 402 * scripting language. 403 **/ error(const char * tcError)404 inline void error(const char* tcError) { _error(tcError); } 405 406 /** function 'trueConstant()' 407 * Returns the boolean value 'true'. 408 **/ trueConstant()409 inline static const char* trueConstant() { return "true"; } 410 411 //------------------------------------------------------------------ 412 // Node creation 413 //------------------------------------------------------------------ 414 415 /** function 'createTree(...)' 416 * Returns a new local tree. The caller has to delete this tree after 417 * use. 418 **/ createTree(const char * tcName)419 inline Tree* createTree(const char* tcName) { return _createTree(tcName); } 420 421 //------------------------------------------------------------------ 422 // Node value 423 //------------------------------------------------------------------ 424 425 /** function 'getValue(...)' 426 * Returns the value of a node. 427 **/ getValue(Tree * pTree)428 inline const char* getValue(Tree* pTree) { return _getValue(pTree); } 429 430 /** function 'getIntValue(...)' 431 * Returns the value of a node as an integer. 432 **/ getIntValue(Tree * pTree)433 inline int getIntValue(Tree* pTree) { return _getIntValue(pTree); } 434 435 /** function 'getDoubleValue(...)' 436 * Returns the value of a node as a double. 437 **/ getDoubleValue(Tree * pTree)438 inline double getDoubleValue(Tree* pTree) { return _getDoubleValue(pTree); } 439 440 /** function 'getBooleanValue(...)' 441 * Returns the value of a node as a boolean. 442 **/ getBooleanValue(Tree * pTree)443 inline bool getBooleanValue(Tree* pTree) { return _getBooleanValue(pTree); } 444 445 /** function 'getExternalValue(...)' 446 * Returns the external instance of a node. 447 **/ getExternalValue(Tree * pTree)448 inline CodeWorker::ExternalValueNode* getExternalValue(Tree* pTree) { return _getExternalValue(pTree); } 449 450 /** function 'setValue(...)' 451 * Assigns a value to a node. 452 **/ setValue(Tree * pTree,const char * tcValue)453 inline void setValue(Tree* pTree, const char* tcValue) { _setValue(pTree, tcValue); } 454 455 /** function 'setIntValue(...)' 456 * Assigns an integer value to a node. 457 **/ setIntValue(Tree * pTree,int iValue)458 inline void setIntValue(Tree* pTree, int iValue) { _setIntValue(pTree, iValue); } 459 460 /** function 'setDoubleValue(...)' 461 * Assigns a double value to a node. 462 **/ setDoubleValue(Tree * pTree,double dValue)463 inline void setDoubleValue(Tree* pTree, double dValue) { _setDoubleValue(pTree, dValue); } 464 465 /** function 'setBooleanValue(...)' 466 * Assigns a boolean value to a node. 467 **/ setBooleanValue(Tree * pTree,bool bValue)468 inline void setBooleanValue(Tree* pTree, bool bValue) { _setBooleanValue(pTree, bValue); } 469 470 /** function 'setExternalValue(...)' 471 * Assigns an external object type to a node. 472 **/ setExternalValue(Tree * pTree,CodeWorker::ExternalValueNode * pInstance)473 inline void setExternalValue(Tree* pTree, CodeWorker::ExternalValueNode* pInstance) { _setExternalValue(pTree, pInstance); } 474 475 //------------------------------------------------------------------ 476 // Node attribute 477 //------------------------------------------------------------------ 478 479 /** function 'nextNode(...)' 480 * Navigates to the node an attribute is pointing to. 481 * If the node doesn't exist, it returns a null pointer. 482 * 483 * Example: 484 * CW4dl::Tree* pClassName = interpreter->nextNode(pClass, "name"); 485 **/ nextNode(Tree * pTree,const char * tcAttribute)486 inline Tree* nextNode(Tree* pTree, const char* tcAttribute) { return _nextNode(pTree, tcAttribute); } 487 488 /** function 'insertNode(...)' 489 * Inserts a subnode to a node. 490 * If the node already exists, it does nothing. 491 * 492 * Example: 493 * CW4dl::Tree* pMethods = interpreter->insertNode(pClass, "methods"); 494 **/ insertNode(Tree * pTree,const char * tcAttribute)495 inline Tree* insertNode(Tree* pTree, const char* tcAttribute) { return _insertNode(pTree, tcAttribute); } 496 497 /** function 'clearNode(...)' 498 * Clears the value and erases all subnodes. 499 **/ clearNode(Tree * pTree)500 inline void clearNode(Tree* pTree) { _clearNode(pTree); } 501 502 //------------------------------------------------------------------ 503 // Node array 504 //------------------------------------------------------------------ 505 506 /** function 'size(...)' 507 * Returns the size of an array (i.e the number of items). 508 **/ size(Tree * pTree)509 inline int size(Tree* pTree) { return _sizeArray(pTree); } 510 511 /** function 'allKeys(..., const char**)' 512 * Populates a list of all keys of the array owned by the node, and 513 * returns the size. 514 * Note: you must allocate sufficient memory for the storage of keys. 515 * 516 * Example: 517 * const char** tcKeys = new const char*[interpreter->size(listOfRooms)]; 518 * interpreter->allKeys(listOfRooms, "kitchen"); 519 * ... 520 * delete [] tcKeys; 521 **/ allKeys(Tree * pTree,const char ** tcKeys)522 inline int allKeys(Tree* pTree, const char** tcKeys) { return _allKeys(pTree, tcKeys); } 523 524 /** function 'allValues(..., const char**)' 525 * Populates a list of all values of the array owned by the node, and 526 * returns the size. 527 * Note: you must allocate sufficient memory for the storage of values. 528 * 529 * Example: 530 * const char** tcValues = new const char*[interpreter->size(listOfRooms)]; 531 * interpreter->allValues(listOfRooms, "kitchen"); 532 * ... 533 * delete [] tcValues; 534 **/ allValues(Tree * pTree,const char ** tcValues)535 inline int allValues(Tree* pTree, const char** tcValues) { return _allValues(pTree, tcValues); } 536 537 /** function 'getItem(..., const char*)' 538 * Returns the item of an array, whose key is passed as parameter. 539 * 540 * Example: 541 * CW4dl::Tree* pItem = interpreter->getItem(listOfRooms, "kitchen"); 542 * In CodeWorker: 543 * localref pItem = listOfRooms["kitchen"]; 544 **/ getItem(Tree * pTree,const char * tcKey)545 inline Tree* getItem(Tree* pTree, const char* tcKey) { return _getItemFromKey(pTree, tcKey); } 546 547 /** function 'getItem(..., int)' 548 * Returns the item of an array, whose rank is passed as parameter. 549 * It starts counting a 0. 550 * 551 * Example: 552 * CW4dl::Tree* pItem = getItem(listOfRooms, 2); 553 * In CodeWorker: 554 * localref pItem = listOfRooms#[2]; 555 **/ getItem(Tree * pTree,int iKey)556 inline Tree* getItem(Tree* pTree, int iKey) { return _getItemFromPos(pTree, iKey); } 557 558 /** function 'getItemKey(..., int)' 559 * Returns the key of an array's item, whose rank is passed as parameter. 560 * It starts counting a 0. 561 * 562 * Example: 563 * interpreter->insertItem(listOfRooms, "kitchen", "2nd floor"); 564 * interpreter->insertItem(listOfRooms, "bathroom"); 565 * const char* tcKey0 = getItemKey(listOfRooms, 0); 566 * const char* tcKey1 = getItemKey(listOfRooms, 1); 567 * with: 568 * tcKey0 equals "kitchen" 569 * tcKey1 equals "bathroom" 570 **/ getItemKey(Tree * pTree,int iKey)571 inline const char* getItemKey(Tree* pTree, int iKey) { return _getItemKey(pTree, iKey); } 572 573 /** function 'pushItem(...)' 574 * Adds a new item in a list, where the key is automatically computed as 575 * the rank of the item in the list (starting at 0), and returns it. 576 * A value may be assigned to the new item. 577 * 578 * Example: 579 * CW4dl::Tree* pItem = interpreter->pushItem(pList, "myFile.txt"); 580 * In CodeWorker: 581 * pushItem pList = "myFile.txt"; 582 * localref pItem = pList#back; 583 **/ 584 inline Tree* pushItem(Tree* pArray, const char* tcValue = NULL) { return _pushItem(pArray, tcValue); } 585 586 /** function 'insertItem(...)' 587 * Inserts a new item in a list, associated to a given key. 588 * A value may be assigned to the new item. 589 * 590 * Example: 591 * interpreter->insertItem(pList, "kitchen", "2nd floor"); 592 * interpreter->insertItem(pList, "bathroom"); 593 * In CodeWorker: 594 * insert pList["kitchen"] = "2nd floor"; 595 * insert pList["bathroom"]; 596 **/ 597 inline Tree* insertItem(Tree* pArray, const char* tcKey, const char* tcValue = NULL) { return _insertItem(pArray, tcKey, tcValue); } 598 599 /** function 'findFunction(...)' 600 * Searches a function implemented in CodeWorker, at the current 601 * instruction scope. 602 * This function may be either predefined or user defined. 603 * 604 * Example: 605 * CW4dl::Function* pFunction = interpreter->findFunction("traceObject"); 606 * interpreter->callFunction(pFunction, pList); 607 **/ findFunction(const char * tcFunctionName)608 inline Function* findFunction(const char* tcFunctionName) { return _findFunction(this, tcFunctionName); } 609 610 /** function 'callFunction(...)' 611 * Calls a CodeWorker's function previously obtained with 'findFunction()'. 612 * This function may be either predefined or user defined. 613 * 614 * Important: you have to delete the function's pointer after use, with 615 * 'releaseFunction()'. 616 * 617 * Example: 618 * CW4dl::Function* pFunction = interpreter->findFunction("traceObject"); 619 * interpreter->callFunction(pFunction, pList); 620 * ... 621 * interpreter->releaseFunction(pFunction); // not used anymore 622 **/ callFunction(Function * pfFunction)623 inline const char* callFunction(Function* pfFunction) { return _callFunction0(this, pfFunction); } callFunction(Function * pfFunction,Parameter2CW p1)624 inline const char* callFunction(Function* pfFunction, Parameter2CW p1) { return _callFunction1(this, pfFunction, p1); } callFunction(Function * pfFunction,Parameter2CW p1,Parameter2CW p2)625 inline const char* callFunction(Function* pfFunction, Parameter2CW p1, Parameter2CW p2) { return _callFunction2(this, pfFunction, p1, p2); } callFunction(Function * pfFunction,Parameter2CW p1,Parameter2CW p2,Parameter2CW p3)626 inline const char* callFunction(Function* pfFunction, Parameter2CW p1, Parameter2CW p2, Parameter2CW p3) { return _callFunction3(this, pfFunction, p1, p2, p3); } callFunction(Function * pfFunction,Parameter2CW p1,Parameter2CW p2,Parameter2CW p3,Parameter2CW p4)627 inline const char* callFunction(Function* pfFunction, Parameter2CW p1, Parameter2CW p2, Parameter2CW p3, Parameter2CW p4) { return _callFunction4(this, pfFunction, p1, p2, p3, p4); } 628 releaseFunction(Function * pfFunction)629 inline void releaseFunction(Function* pfFunction) { _releaseFunction(pfFunction); } 630 631 private: 632 Interpreter(); 633 Interpreter(const Interpreter&); 634 }; 635 } 636 637 #endif 638