1 /* 2 * Copyright (c) 2014-2021 Christian Schoenebeck 3 * 4 * http://www.linuxsampler.org 5 * 6 * This file is part of LinuxSampler and released under the same terms. 7 * See README file for details. 8 */ 9 10 // This header defines data types shared between the VM core implementation 11 // (inside the current source directory) and other parts of the sampler 12 // (located at other source directories). It also acts as public API of the 13 // Real-Time script engine for other applications. 14 15 #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H 16 #define LS_INSTR_SCRIPT_PARSER_COMMON_H 17 18 #include "../common/global.h" 19 #include <vector> 20 #include <map> 21 #include <stddef.h> // offsetof() 22 #include <functional> // std::function<> 23 24 namespace LinuxSampler { 25 26 /** 27 * Native data type used by the script engine both internally, as well as 28 * for all integer data types used by scripts (i.e. for all $foo variables 29 * in NKSP scripts). Note that this is different from the original KSP which 30 * is limited to 32 bit for integer variables in KSP scripts. 31 */ 32 typedef int64_t vmint; 33 34 /** 35 * Native data type used internally by the script engine for all unsigned 36 * integer types. This type is currently not exposed to scripts. 37 */ 38 typedef uint64_t vmuint; 39 40 /** 41 * Native data type used by the script engine both internally for floating 42 * point data, as well as for all @c real data types used by scripts (i.e. 43 * for all ~foo variables in NKSP scripts). 44 */ 45 typedef float vmfloat; 46 47 /** 48 * Identifies the type of a noteworthy issue identified by the script 49 * parser. That's either a parser error or parser warning. 50 */ 51 enum ParserIssueType_t { 52 PARSER_ERROR, ///< Script parser encountered an error, the script cannot be executed. 53 PARSER_WARNING ///< Script parser encountered a warning, the script may be executed if desired, but the script may not necessarily behave as originally intended by the script author. 54 }; 55 56 /** @brief Expression's data type. 57 * 58 * Identifies to which data type an expression within a script evaluates to. 59 * This can for example reflect the data type of script function arguments, 60 * script function return values, but also the resulting data type of some 61 * mathematical formula within a script. 62 */ 63 enum ExprType_t { 64 EMPTY_EXPR, ///< i.e. on invalid expressions or i.e. a function call that does not return a result value (the built-in wait() or message() functions for instance) 65 INT_EXPR, ///< integer (scalar) expression 66 INT_ARR_EXPR, ///< integer array expression 67 STRING_EXPR, ///< string expression 68 STRING_ARR_EXPR, ///< string array expression 69 REAL_EXPR, ///< floating point (scalar) expression 70 REAL_ARR_EXPR, ///< floating point array expression 71 }; 72 73 /** @brief Result flags of a script statement or script function call. 74 * 75 * A set of bit flags which provide informations about the success or 76 * failure of a statement within a script. That's also especially used for 77 * providing informations about success / failure of a call to a built-in 78 * script function. The virtual machine evaluates these flags during runtime 79 * to decide whether it should i.e. stop or suspend execution of a script. 80 * 81 * Since these are bit flags, these constants are bitwise combined. 82 */ 83 enum StmtFlags_t { 84 STMT_SUCCESS = 0, ///< Function / statement was executed successfully, no error occurred. 85 STMT_ABORT_SIGNALLED = 1, ///< VM should stop the current callback execution (usually because of an error, but might also be without an error reason, i.e. when the built-in script function exit() was called). 86 STMT_SUSPEND_SIGNALLED = (1<<1), ///< VM supended execution, either because the script called the built-in wait() script function or because the script consumed too much execution time and was forced by the VM to be suspended for some time 87 STMT_ERROR_OCCURRED = (1<<2), ///< VM stopped execution due to some script runtime error that occurred 88 STMT_RETURN_SIGNALLED = (1<<3), ///< VM should unwind stack and return to previous, calling subroutine (i.e. user function or event handler). 89 }; 90 91 /** @brief Virtual machine execution status. 92 * 93 * A set of bit flags which reflect the current overall execution status of 94 * the virtual machine concerning a certain script execution instance. 95 * 96 * Since these are bit flags, these constants are bitwise combined. 97 */ 98 enum VMExecStatus_t { 99 VM_EXEC_NOT_RUNNING = 0, ///< Script is currently not executed by the VM. 100 VM_EXEC_RUNNING = 1, ///< The VM is currently executing the script. 101 VM_EXEC_SUSPENDED = (1<<1), ///< Script is currently suspended by the VM, either because the script called the built-in wait() script function or because the script consumed too much execution time and was forced by the VM to be suspended for some time. 102 VM_EXEC_ERROR = (1<<2), ///< A runtime error occurred while executing the script (i.e. a call to some built-in script function failed). 103 }; 104 105 /** @brief Script event handler type. 106 * 107 * Identifies one of the possible event handler callback types defined by 108 * the NKSP script language. 109 * 110 * IMPORTANT: this type is forced to be emitted as int32_t type ATM, because 111 * that's the native size expected by the built-in instrument script 112 * variable bindings (see occurrences of VMInt32RelPtr and DECLARE_VMINT 113 * respectively. A native type mismatch between the two could lead to 114 * undefined behavior! Background: By definition the C/C++ compiler is free 115 * to choose a bit size for individual enums which it might find 116 * appropriate, which is usually decided by the compiler according to the 117 * biggest enum constant value defined (in practice it is usually 32 bit). 118 */ 119 enum VMEventHandlerType_t : int32_t { 120 VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block. 121 VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block. 122 VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block. 123 VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block. 124 VM_EVENT_HANDLER_RPN, ///< RPN event handler, that is script's "on rpn ... end on" code block. 125 VM_EVENT_HANDLER_NRPN, ///< NRPN event handler, that is script's "on nrpn ... end on" code block. 126 }; 127 128 /** 129 * All metric unit prefixes (actually just scale factors) supported by this 130 * script engine. 131 */ 132 enum MetricPrefix_t { 133 VM_NO_PREFIX = 0, ///< = 1 134 VM_KILO, ///< = 10^3, short 'k' 135 VM_HECTO, ///< = 10^2, short 'h' 136 VM_DECA, ///< = 10, short 'da' 137 VM_DECI, ///< = 10^-1, short 'd' 138 VM_CENTI, ///< = 10^-2, short 'c' (this is also used for tuning "cents") 139 VM_MILLI, ///< = 10^-3, short 'm' 140 VM_MICRO, ///< = 10^-6, short 'u' 141 }; 142 143 /** 144 * This constant is used for comparison with Unit::unitFactor() to check 145 * whether a number does have any metric unit prefix at all. 146 * 147 * @see Unit::unitFactor() 148 */ 149 static const vmfloat VM_NO_FACTOR = vmfloat(1); 150 151 /** 152 * All measurement unit types supported by this script engine. 153 * 154 * @e Note: there is no standard unit "cents" here (for pitch/tuning), use 155 * @c VM_CENTI for the latter instad. That's because the commonly cited 156 * "cents" unit is actually no measurement unit type but rather a metric 157 * unit prefix. 158 * 159 * @see MetricPrefix_t 160 */ 161 enum StdUnit_t { 162 VM_NO_UNIT = 0, ///< No unit used, the number is just an abstract number. 163 VM_SECOND, ///< Measuring time. 164 VM_HERTZ, ///< Measuring frequency. 165 VM_BEL, ///< Measuring relation between two energy levels (in logarithmic scale). Since we are using it for accoustics, we are always referring to A-weighted Bels (i.e. dBA). 166 }; 167 168 //TODO: see Unit::hasUnitFactorEver() 169 enum EverTriState_t { 170 VM_NEVER = 0, 171 VM_MAYBE, 172 VM_ALWAYS, 173 }; 174 175 // just symbol prototyping 176 class VMIntExpr; 177 class VMRealExpr; 178 class VMStringExpr; 179 class VMNumberExpr; 180 class VMArrayExpr; 181 class VMIntArrayExpr; 182 class VMRealArrayExpr; 183 class VMStringArrayExpr; 184 class VMParserContext; 185 186 /** @brief Virtual machine standard measuring unit. 187 * 188 * Abstract base class representing standard measurement units throughout 189 * the script engine. These might be e.g. "dB" (deci Bel) for loudness, 190 * "Hz" (Hertz) for frequencies or "s" for "seconds". These unit types can 191 * combined with metric prefixes, for instance "kHz" (kilo Hertz), 192 * "us" (micro second), etc. 193 * 194 * Originally the script engine only supported abstract integer values for 195 * controlling any synthesis parameter or built-in function argument or 196 * variable. Under certain situations it makes sense though for an 197 * instrument script author to provide values in real, standard measurement 198 * units to provide a more natural and intuitive approach for writing 199 * instrument scripts, for example by setting the frequency of some LFO 200 * directly to "20Hz" or reducing loudness by "-4.2dB". Hence support for 201 * standard units in scripts was added as an extension to the NKSP script 202 * engine. 203 * 204 * So a unit consists of 1) a sequence of metric prefixes as scale factor 205 * (e.g. "k" for kilo) and 2) the actual unit type (e.g. "Hz" for Hertz). 206 * The unit type is a constant feature of number literals and variables, so 207 * once a variable was declared with a unit type (or no unit type at all) 208 * then that unit type of that variable cannot be changed for the entire 209 * life time of the script. This is different from the unit's metric 210 * prefix(es) of variables which may freely be changed at runtime. 211 */ 212 class VMUnit { 213 public: 214 /** 215 * Returns the metric prefix(es) of this unit as unit factor. A metric 216 * prefix essentially is just a mathematical scale factor that should be 217 * applied to the number associated with the measurement unit. Consider 218 * a string literal in an NKSP script like '3kHz' where 'k' (kilo) is 219 * the metric prefix, which essentically is a scale factor of 1000. 220 * 221 * Usually a unit either has exactly none or one metric prefix, but note 222 * that there might also be units with more than one prefix, for example 223 * @c mdB (milli deci Bel) is used sometimes which has two prefixes. The 224 * latter is an exception though and more than two prefixes is currently 225 * not supported by the script engine. 226 * 227 * The factor returned by this method is the final mathematical factor 228 * that should be multiplied against the number associated with this 229 * unit. This factor results from the sequence of metric prefixes of 230 * this unit. 231 * 232 * @see MetricPrefix_t, hasUnitFactorNow(), hasUnitFactorEver(), 233 * VM_NO_FACTOR 234 * @returns current metric unit factor 235 */ 236 virtual vmfloat unitFactor() const = 0; 237 238 //TODO: this still needs to be implemented in tree.h/.pp, built-in functions and as 2nd pass of parser appropriately hasUnitFactorEver()239 /*virtual*/ EverTriState_t hasUnitFactorEver() const { return VM_NEVER; } 240 241 /** 242 * Whether this unit currently does have any metric unit prefix. 243 * 244 * This is actually just a convenience method which returns @c true if 245 * unitFactor() is not @c 1.0. 246 * 247 * @see MetricPrefix_t, unitFactor(), hasUnitFactorEver(), VM_NO_FACTOR 248 * @returns @c true if this unit currently has any metric prefix 249 */ 250 bool hasUnitFactorNow() const; 251 252 /** 253 * This is the actual fundamental measuring unit base type of this unit, 254 * which might be either Hertz, second or Bel. 255 * 256 * Note that a number without a unit type may still have metric 257 * prefixes. 258 * 259 * @returns standard unit type identifier or VM_NO_UNIT if no unit type 260 * is used for this object 261 */ 262 virtual StdUnit_t unitType() const = 0; 263 264 /** 265 * Returns the actual mathematical factor represented by the passed 266 * @a prefix argument. 267 */ 268 static vmfloat unitFactor(MetricPrefix_t prefix); 269 270 /** 271 * Returns the actual mathematical factor represented by the passed 272 * two @a prefix1 and @a prefix2 arguments. 273 * 274 * @returns scale factor of given metric unit prefixes 275 */ 276 static vmfloat unitFactor(MetricPrefix_t prefix1, MetricPrefix_t prefix2); 277 278 /** 279 * Returns the actual mathematical factor represented by the passed 280 * @a prefixes array. The passed array should always be terminated by a 281 * VM_NO_PREFIX value as last element. 282 * 283 * @param prefixes - sequence of metric prefixes 284 * @param size - max. amount of elements of array @a prefixes 285 * @returns scale factor of given metric unit prefixes 286 */ 287 static vmfloat unitFactor(const MetricPrefix_t* prefixes, vmuint size = 2); 288 }; 289 290 /** @brief Virtual machine expression 291 * 292 * This is the abstract base class for all expressions of scripts. 293 * Deriving classes must implement the abstract method exprType(). 294 * 295 * An expression within a script is translated into one instance of this 296 * class. It allows a high level access for the virtual machine to evaluate 297 * and handle expressions appropriately during execution. Expressions are 298 * for example all kinds of formulas, function calls, statements or a 299 * combination of them. Most of them evaluate to some kind of value, which 300 * might be further processed as part of encompassing expressions to outer 301 * expression results and so forth. 302 */ 303 class VMExpr { 304 public: 305 /** 306 * Identifies the data type to which the result of this expression 307 * evaluates to. This abstract method must be implemented by deriving 308 * classes. 309 */ 310 virtual ExprType_t exprType() const = 0; 311 312 /** 313 * In case this expression is an integer expression, then this method 314 * returns a casted pointer to that VMIntExpr object. It returns NULL 315 * if this expression is not an integer expression. 316 * 317 * @b Note: type casting performed by this method is strict! That means 318 * if this expression is i.e. actually a string expression like "12", 319 * calling asInt() will @b not cast that numerical string expression to 320 * an integer expression 12 for you, instead this method will simply 321 * return NULL! Same applies if this expression is actually a real 322 * number expression: asInt() would return NULL in that case as well. 323 * 324 * @see exprType(), asReal(), asNumber() 325 */ 326 VMIntExpr* asInt() const; 327 328 /** 329 * In case this expression is a real number (floating point) expression, 330 * then this method returns a casted pointer to that VMRealExpr object. 331 * It returns NULL if this expression is not a real number expression. 332 * 333 * @b Note: type casting performed by this method is strict! That means 334 * if this expression is i.e. actually a string expression like "12", 335 * calling asReal() will @b not cast that numerical string expression to 336 * a real number expression 12.0 for you, instead this method will 337 * simply return NULL! Same applies if this expression is actually an 338 * integer expression: asReal() would return NULL in that case as well. 339 * 340 * @see exprType(), asInt(), asNumber() 341 */ 342 VMRealExpr* asReal() const; 343 344 /** 345 * In case this expression is a scalar number expression, that is either 346 * an integer (scalar) expression or a real number (floating point 347 * scalar) expression, then this method returns a casted pointer to that 348 * VMNumberExpr base class object. It returns NULL if this 349 * expression is neither an integer (scalar), nor a real number (scalar) 350 * expression. 351 * 352 * Since the methods asInt() and asReal() are very strict, this method 353 * is provided as convenience access in case only very general 354 * information (e.g. which standard measurement unit is being used or 355 * whether final operator being effective to this expression) is 356 * intended to be retrieved of this scalar number expression independent 357 * from whether this expression is actually an integer or a real number 358 * expression. 359 * 360 * @see exprType(), asInt(), asReal() 361 */ 362 VMNumberExpr* asNumber() const; 363 364 /** 365 * In case this expression is a string expression, then this method 366 * returns a casted pointer to that VMStringExpr object. It returns NULL 367 * if this expression is not a string expression. 368 * 369 * @b Note: type casting performed by this method is strict! That means 370 * if this expression is i.e. actually an integer expression like 120, 371 * calling asString() will @b not cast that integer expression to a 372 * string expression "120" for you, instead this method will simply 373 * return NULL! 374 * 375 * @see exprType() 376 */ 377 VMStringExpr* asString() const; 378 379 /** 380 * In case this expression is an integer array expression, then this 381 * method returns a casted pointer to that VMIntArrayExpr object. It 382 * returns NULL if this expression is not an integer array expression. 383 * 384 * @b Note: type casting performed by this method is strict! That means 385 * if this expression is i.e. an integer scalar expression, a real 386 * number expression or a string expression, calling asIntArray() will 387 * @b not cast those expressions to an integer array expression for you, 388 * instead this method will simply return NULL! 389 * 390 * @b Note: this method is currently, and in contrast to its other 391 * counter parts, declared as virtual method. Some deriving classes are 392 * currently using this to override this default implementation in order 393 * to implement an "evaluate now as integer array" behavior. This has 394 * efficiency reasons, however this also currently makes this part of 395 * the API less clean and should thus be addressed in future with 396 * appropriate changes to the API. 397 * 398 * @see exprType() 399 */ 400 virtual VMIntArrayExpr* asIntArray() const; 401 402 /** 403 * In case this expression is a real number (floating point) array 404 * expression, then this method returns a casted pointer to that 405 * VMRealArrayExpr object. It returns NULL if this expression is not a 406 * real number array expression. 407 * 408 * @b Note: type casting performed by this method is strict! That means 409 * if this expression is i.e. a real number scalar expression, an 410 * integer expression or a string expression, calling asRealArray() will 411 * @b not cast those scalar expressions to a real number array 412 * expression for you, instead this method will simply return NULL! 413 * 414 * @b Note: this method is currently, and in contrast to its other 415 * counter parts, declared as virtual method. Some deriving classes are 416 * currently using this to override this default implementation in order 417 * to implement an "evaluate now as real number array" behavior. This 418 * has efficiency reasons, however this also currently makes this part 419 * of the API less clean and should thus be addressed in future with 420 * appropriate changes to the API. 421 * 422 * @see exprType() 423 */ 424 virtual VMRealArrayExpr* asRealArray() const; 425 426 /** 427 * This is an alternative to calling either asIntArray() or 428 * asRealArray(). This method here might be used if the fundamental 429 * scalar data type (real or integer) of the array is not relevant, 430 * i.e. for just getting the size of the array. Since all as*() methods 431 * here are very strict regarding type casting, this asArray() method 432 * sometimes can reduce code complexity. 433 * 434 * Likewise calling this method only returns a valid pointer if the 435 * expression is some array type (currently either integer array or real 436 * number array). For any other expression type this method will return 437 * NULL instead. 438 * 439 * @see exprType() 440 */ 441 VMArrayExpr* asArray() const; 442 443 /** 444 * Returns true in case this expression can be considered to be a 445 * constant expression. A constant expression will retain the same 446 * value throughout the entire life time of a script and the 447 * expression's constant value may be evaluated already at script 448 * parse time, which may result in performance benefits during script 449 * runtime. 450 * 451 * @b NOTE: A constant expression is per se always also non modifyable. 452 * But a non modifyable expression may not necessarily be a constant 453 * expression! 454 * 455 * @see isModifyable() 456 */ 457 virtual bool isConstExpr() const = 0; 458 459 /** 460 * Returns true in case this expression is allowed to be modified. 461 * If this method returns @c false then this expression must be handled 462 * as read-only expression, which means that assigning a new value to it 463 * is either not possible or not allowed. 464 * 465 * @b NOTE: A constant expression is per se always also non modifyable. 466 * But a non modifyable expression may not necessarily be a constant 467 * expression! 468 * 469 * @see isConstExpr() 470 */ 471 bool isModifyable() const; 472 }; 473 474 /** @brief Virtual machine scalar number expression 475 * 476 * This is the abstract base class for integer (scalar) expressions and 477 * real number (floating point scalar) expressions of scripts. 478 */ 479 class VMNumberExpr : virtual public VMExpr, virtual public VMUnit { 480 public: 481 /** 482 * Returns @c true if the value of this expression should be applied 483 * as final value to the respective destination synthesis chain 484 * parameter. 485 * 486 * This property is somewhat special and dedicated for the purpose of 487 * this expression's (integer or real number) value to be applied as 488 * parameter to the synthesis chain of the sampler (i.e. for altering a 489 * filter cutoff frequency). Now historically and by default all values 490 * of scripts are applied relatively to the sampler's synthesis chain, 491 * that is the synthesis parameter value of a script is multiplied 492 * against other sources for the same synthesis parameter (i.e. an LFO 493 * or a dedicated MIDI controller either hard wired in the engine or 494 * defined by the instrument patch). So by default the resulting actual 495 * final synthesis parameter is a combination of all these sources. This 496 * has the advantage that it creates a very living and dynamic overall 497 * sound. 498 * 499 * However sometimes there are requirements by script authors where this 500 * is not what you want. Therefore the NKSP script engine added a 501 * language extension by prefixing a value in scripts with a @c ! 502 * character the value will be defined as being the "final" value of the 503 * destination synthesis parameter, so that causes this value to be 504 * applied exclusively, and the values of all other sources are thus 505 * entirely ignored by the sampler's synthesis core as long as this 506 * value is assigned by the script engine as "final" value for the 507 * requested synthesis parameter. 508 */ 509 virtual bool isFinal() const = 0; 510 511 /** 512 * Calling this method evaluates the expression and returns the value 513 * of the expression as integer. If this scalar number expression is a 514 * real number expression then this method automatically casts the value 515 * from real number to integer. 516 */ 517 vmint evalCastInt(); 518 519 /** 520 * Calling this method evaluates the expression and returns the value 521 * of the expression as integer and thus behaves similar to the previous 522 * method, however this overridden method automatically takes unit 523 * prefixes into account and returns a converted value corresponding to 524 * the given unit @a prefix expected by the caller. 525 * 526 * Example: Assume this expression was an integer expression '12kHz' 527 * then calling this method as @c evalCastInt(VM_MILLI) would return 528 * the value @c 12000000. 529 * 530 * @param prefix - measuring unit prefix expected for result by caller 531 */ 532 vmint evalCastInt(MetricPrefix_t prefix); 533 534 /** 535 * This method behaves like the previous method, just that it takes a 536 * measuring unit prefix with two elements (e.g. "milli cents" for 537 * tuning). 538 * 539 * @param prefix1 - 1st measuring unit prefix element expected by caller 540 * @param prefix2 - 2nd measuring unit prefix element expected by caller 541 */ 542 vmint evalCastInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2); 543 544 /** 545 * Calling this method evaluates the expression and returns the value 546 * of the expression as real number. If this scalar number expression is 547 * an integer expression then this method automatically casts the value 548 * from integer to real number. 549 */ 550 vmfloat evalCastReal(); 551 552 /** 553 * Calling this method evaluates the expression and returns the value 554 * of the expression as real number and thus behaves similar to the 555 * previous method, however this overridden method automatically takes 556 * unit prefixes into account and returns a converted value 557 * corresponding to the given unit @a prefix expected by the caller. 558 * 559 * Example: Assume this expression was an integer expression '8ms' then 560 * calling this method as @c evalCastReal(VM_NO_PREFIX) would return the 561 * value @c 0.008. 562 * 563 * @param prefix - measuring unit prefix expected for result by caller 564 */ 565 vmfloat evalCastReal(MetricPrefix_t prefix); 566 567 /** 568 * This method behaves like the previous method, just that it takes a 569 * measuring unit prefix with two elements (e.g. "milli cents" for 570 * tuning). 571 * 572 * @param prefix1 - 1st measuring unit prefix element expected by caller 573 * @param prefix2 - 2nd measuring unit prefix element expected by caller 574 */ 575 vmfloat evalCastReal(MetricPrefix_t prefix1, MetricPrefix_t prefix2); 576 }; 577 578 /** @brief Virtual machine integer expression 579 * 580 * This is the abstract base class for all expressions inside scripts which 581 * evaluate to an integer (scalar) value. Deriving classes implement the 582 * abstract method evalInt() to return the actual integer result value of 583 * the expression. 584 */ 585 class VMIntExpr : virtual public VMNumberExpr { 586 public: 587 /** 588 * Returns the result of this expression as integer (scalar) value. 589 * This abstract method must be implemented by deriving classes. 590 */ 591 virtual vmint evalInt() = 0; 592 593 /** 594 * Returns the result of this expression as integer (scalar) value and 595 * thus behaves similar to the previous method, however this overridden 596 * method automatically takes unit prefixes into account and returns a 597 * value corresponding to the expected given unit @a prefix. 598 * 599 * @param prefix - default measurement unit prefix expected by caller 600 */ 601 vmint evalInt(MetricPrefix_t prefix); 602 603 /** 604 * This method behaves like the previous method, just that it takes 605 * a default measurement prefix with two elements (i.e. "milli cents" 606 * for tuning). 607 */ 608 vmint evalInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2); 609 610 /** 611 * Returns always INT_EXPR for instances of this class. 612 */ exprType()613 ExprType_t exprType() const OVERRIDE { return INT_EXPR; } 614 }; 615 616 /** @brief Virtual machine real number (floating point scalar) expression 617 * 618 * This is the abstract base class for all expressions inside scripts which 619 * evaluate to a real number (floating point scalar) value. Deriving classes 620 * implement the abstract method evalReal() to return the actual floating 621 * point result value of the expression. 622 */ 623 class VMRealExpr : virtual public VMNumberExpr { 624 public: 625 /** 626 * Returns the result of this expression as real number (floating point 627 * scalar) value. This abstract method must be implemented by deriving 628 * classes. 629 */ 630 virtual vmfloat evalReal() = 0; 631 632 /** 633 * Returns the result of this expression as real number (floating point 634 * scalar) value and thus behaves similar to the previous method, 635 * however this overridden method automatically takes unit prefixes into 636 * account and returns a value corresponding to the expected given unit 637 * @a prefix. 638 * 639 * @param prefix - default measurement unit prefix expected by caller 640 */ 641 vmfloat evalReal(MetricPrefix_t prefix); 642 643 /** 644 * This method behaves like the previous method, just that it takes 645 * a default measurement prefix with two elements (i.e. "milli cents" 646 * for tuning). 647 */ 648 vmfloat evalReal(MetricPrefix_t prefix1, MetricPrefix_t prefix2); 649 650 /** 651 * Returns always REAL_EXPR for instances of this class. 652 */ exprType()653 ExprType_t exprType() const OVERRIDE { return REAL_EXPR; } 654 }; 655 656 /** @brief Virtual machine string expression 657 * 658 * This is the abstract base class for all expressions inside scripts which 659 * evaluate to a string value. Deriving classes implement the abstract 660 * method evalStr() to return the actual string result value of the 661 * expression. 662 */ 663 class VMStringExpr : virtual public VMExpr { 664 public: 665 /** 666 * Returns the result of this expression as string value. This abstract 667 * method must be implemented by deriving classes. 668 */ 669 virtual String evalStr() = 0; 670 671 /** 672 * Returns always STRING_EXPR for instances of this class. 673 */ exprType()674 ExprType_t exprType() const OVERRIDE { return STRING_EXPR; } 675 }; 676 677 /** @brief Virtual Machine Array Value Expression 678 * 679 * This is the abstract base class for all expressions inside scripts which 680 * evaluate to some kind of array value. Deriving classes implement the 681 * abstract method arraySize() to return the amount of elements within the 682 * array. 683 */ 684 class VMArrayExpr : virtual public VMExpr { 685 public: 686 /** 687 * Returns amount of elements in this array. This abstract method must 688 * be implemented by deriving classes. 689 */ 690 virtual vmint arraySize() const = 0; 691 }; 692 693 /** @brief Virtual Machine Number Array Expression 694 * 695 * This is the abstract base class for all expressions which either evaluate 696 * to an integer array or real number array. 697 */ 698 class VMNumberArrayExpr : virtual public VMArrayExpr { 699 public: 700 /** 701 * Returns the metric unit factor of the requested array element. 702 * 703 * @param i - array element index (must be between 0 .. arraySize() - 1) 704 * @see VMUnit::unitFactor() for details about metric unit factors 705 */ 706 virtual vmfloat unitFactorOfElement(vmuint i) const = 0; 707 708 /** 709 * Changes the current unit factor of the array element given by element 710 * index @a i. 711 * 712 * @param i - array element index (must be between 0 .. arraySize() - 1) 713 * @param factor - new unit factor to be assigned 714 * @see VMUnit::unitFactor() for details about metric unit factors 715 */ 716 virtual void assignElementUnitFactor(vmuint i, vmfloat factor) = 0; 717 }; 718 719 /** @brief Virtual Machine Integer Array Expression 720 * 721 * This is the abstract base class for all expressions inside scripts which 722 * evaluate to an array of integer values. Deriving classes implement the 723 * abstract methods arraySize(), evalIntElement() and assignIntElement() to 724 * access the individual integer array values. 725 */ 726 class VMIntArrayExpr : virtual public VMNumberArrayExpr { 727 public: 728 /** 729 * Returns the (scalar) integer value of the array element given by 730 * element index @a i. 731 * 732 * @param i - array element index (must be between 0 .. arraySize() - 1) 733 */ 734 virtual vmint evalIntElement(vmuint i) = 0; 735 736 /** 737 * Changes the current value of an element (given by array element 738 * index @a i) of this integer array. 739 * 740 * @param i - array element index (must be between 0 .. arraySize() - 1) 741 * @param value - new integer scalar value to be assigned to that array element 742 */ 743 virtual void assignIntElement(vmuint i, vmint value) = 0; 744 745 /** 746 * Returns always INT_ARR_EXPR for instances of this class. 747 */ exprType()748 ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; } 749 }; 750 751 /** @brief Virtual Machine Real Number Array Expression 752 * 753 * This is the abstract base class for all expressions inside scripts which 754 * evaluate to an array of real numbers (floating point values). Deriving 755 * classes implement the abstract methods arraySize(), evalRealElement() and 756 * assignRealElement() to access the array's individual real numbers. 757 */ 758 class VMRealArrayExpr : virtual public VMNumberArrayExpr { 759 public: 760 /** 761 * Returns the (scalar) real mumber (floating point value) of the array 762 * element given by element index @a i. 763 * 764 * @param i - array element index (must be between 0 .. arraySize() - 1) 765 */ 766 virtual vmfloat evalRealElement(vmuint i) = 0; 767 768 /** 769 * Changes the current value of an element (given by array element 770 * index @a i) of this real number array. 771 * 772 * @param i - array element index (must be between 0 .. arraySize() - 1) 773 * @param value - new real number value to be assigned to that array element 774 */ 775 virtual void assignRealElement(vmuint i, vmfloat value) = 0; 776 777 /** 778 * Returns always REAL_ARR_EXPR for instances of this class. 779 */ exprType()780 ExprType_t exprType() const OVERRIDE { return REAL_ARR_EXPR; } 781 }; 782 783 /** @brief Arguments (parameters) for being passed to a built-in script function. 784 * 785 * An argument or a set of arguments passed to a script function are 786 * translated by the parser to an instance of this class. This abstract 787 * interface class is used by implementations of built-in functions to 788 * obtain the individual function argument values being passed to them at 789 * runtime. 790 */ 791 class VMFnArgs { 792 public: 793 /** 794 * Returns the amount of arguments going to be passed to the script 795 * function. 796 */ 797 virtual vmint argsCount() const = 0; 798 799 /** 800 * Returns the respective argument (requested by argument index @a i) of 801 * this set of arguments. This method is called by implementations of 802 * built-in script functions to obtain the value of each function 803 * argument passed to the function at runtime. 804 * 805 * @param i - function argument index (indexed from left to right) 806 * @return requested function argument or NULL if @a i out of bounds 807 */ 808 virtual VMExpr* arg(vmint i) = 0; 809 }; 810 811 /** @brief Result value returned from a call to a built-in script function. 812 * 813 * Implementations of built-in script functions return an instance of this 814 * object to let the virtual machine obtain the result value of the function 815 * call, which might then be further processed by the virtual machine 816 * according to the script. It also provides informations about the success 817 * or failure of the function call. 818 */ 819 class VMFnResult { 820 public: 821 virtual ~VMFnResult(); 822 823 /** 824 * Returns the result value of the function call, represented by a high 825 * level expression object. 826 */ 827 virtual VMExpr* resultValue() = 0; 828 829 /** 830 * Provides detailed informations of the success / failure of the 831 * function call. The virtual machine is evaluating the flags returned 832 * here to decide whether it must abort or suspend execution of the 833 * script at this point. 834 */ resultFlags()835 virtual StmtFlags_t resultFlags() { return STMT_SUCCESS; } 836 }; 837 838 /** @brief Virtual machine built-in function. 839 * 840 * Abstract base class for built-in script functions, defining the interface 841 * for all built-in script function implementations. All built-in script 842 * functions are deriving from this abstract interface class in order to 843 * provide their functionality to the virtual machine with this unified 844 * interface. 845 * 846 * The methods of this interface class provide two purposes: 847 * 848 * 1. When a script is loaded, the script parser uses the methods of this 849 * interface to check whether the script author was calling the 850 * respective built-in script function in a correct way. For example 851 * the parser checks whether the required amount of parameters were 852 * passed to the function and whether the data types passed match the 853 * data types expected by the function. If not, loading the script will 854 * be aborted with a parser error, describing to the user (i.e. script 855 * author) the precise misusage of the respective function. 856 * 2. After the script was loaded successfully and the script is executed, 857 * the virtual machine calls the exec() method of the respective built-in 858 * function to provide the actual functionality of the built-in function 859 * call. 860 */ 861 class VMFunction { 862 public: 863 /** 864 * Script data type of the function's return value. If the function does 865 * not return any value (void), then it returns EMPTY_EXPR here. 866 * 867 * Some functions may have a different return type depending on the 868 * arguments to be passed to this function. That's what the @a args 869 * parameter is for, so that the method implementation can look ahead 870 * of what kind of parameters are going to be passed to the built-in 871 * function later on in order to decide which return value type would 872 * be used and returned by the function accordingly in that case. 873 * 874 * @param args - function arguments going to be passed for executing 875 * this built-in function later on 876 */ 877 virtual ExprType_t returnType(VMFnArgs* args) = 0; 878 879 /** 880 * Standard measuring unit type of the function's result value 881 * (e.g. second, Hertz). 882 * 883 * Some functions may have a different standard measuring unit type for 884 * their return value depending on the arguments to be passed to this 885 * function. That's what the @a args parameter is for, so that the 886 * method implementation can look ahead of what kind of parameters are 887 * going to be passed to the built-in function later on in order to 888 * decide which return value type would be used and returned by the 889 * function accordingly in that case. 890 * 891 * @param args - function arguments going to be passed for executing 892 * this built-in function later on 893 * @see Unit for details about standard measuring units 894 */ 895 virtual StdUnit_t returnUnitType(VMFnArgs* args) = 0; 896 897 /** 898 * Whether the result value returned by this built-in function is 899 * considered to be a 'final' value. 900 * 901 * Some functions may have a different 'final' feature for their return 902 * value depending on the arguments to be passed to this function. 903 * That's what the @a args parameter is for, so that the method 904 * implementation can look ahead of what kind of parameters are going to 905 * be passed to the built-in function later on in order to decide which 906 * return value type would be used and returned by the function 907 * accordingly in that case. 908 * 909 * @param args - function arguments going to be passed for executing 910 * this built-in function later on 911 * @see VMNumberExpr::isFinal() for details about 'final' values 912 */ 913 virtual bool returnsFinal(VMFnArgs* args) = 0; 914 915 /** 916 * Minimum amount of function arguments this function accepts. If a 917 * script is calling this function with less arguments, the script 918 * parser will throw a parser error. 919 */ 920 virtual vmint minRequiredArgs() const = 0; 921 922 /** 923 * Maximum amount of function arguments this functions accepts. If a 924 * script is calling this function with more arguments, the script 925 * parser will throw a parser error. 926 */ 927 virtual vmint maxAllowedArgs() const = 0; 928 929 /** 930 * This method is called by the parser to check whether arguments 931 * passed in scripts to this function are accepted by this function. If 932 * a script calls this function with an argument's data type not 933 * accepted by this function, the parser will throw a parser error. 934 * 935 * The parser will also use this method to assemble a list of actually 936 * supported data types accepted by this built-in function for the 937 * function argument in question, that is to provide an appropriate and 938 * precise parser error message in such cases. 939 * 940 * @param iArg - index of the function argument in question 941 * (must be between 0 .. maxAllowedArgs() - 1) 942 * @param type - script data type used for this function argument by 943 * currently parsed script 944 * @return true if the given data type would be accepted for the 945 * respective function argument by the function 946 */ 947 virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0; 948 949 /** 950 * This method is called by the parser to check whether arguments 951 * passed in scripts to this function are accepted by this function. If 952 * a script calls this function with an argument's measuremnt unit type 953 * not accepted by this function, the parser will throw a parser error. 954 * 955 * This default implementation of this method does not accept any 956 * measurement unit. Deriving subclasses would override this method 957 * implementation in case they do accept any measurement unit for its 958 * function arguments. 959 * 960 * @param iArg - index of the function argument in question 961 * (must be between 0 .. maxAllowedArgs() - 1) 962 * @param type - standard measurement unit data type used for this 963 * function argument by currently parsed script 964 * @return true if the given standard measurement unit type would be 965 * accepted for the respective function argument by the function 966 */ 967 virtual bool acceptsArgUnitType(vmint iArg, StdUnit_t type) const; 968 969 /** 970 * This method is called by the parser to check whether arguments 971 * passed in scripts to this function are accepted by this function. If 972 * a script calls this function with a metric unit prefix and metric 973 * prefixes are not accepted for that argument by this function, then 974 * the parser will throw a parser error. 975 * 976 * This default implementation of this method does not accept any 977 * metric prefix. Deriving subclasses would override this method 978 * implementation in case they do accept any metric prefix for its 979 * function arguments. 980 * 981 * @param iArg - index of the function argument in question 982 * (must be between 0 .. maxAllowedArgs() - 1) 983 * @param type - standard measurement unit data type used for that 984 * function argument by currently parsed script 985 * 986 * @return true if a metric prefix would be accepted for the respective 987 * function argument by this function 988 * 989 * @see MetricPrefix_t 990 */ 991 virtual bool acceptsArgUnitPrefix(vmint iArg, StdUnit_t type) const; 992 993 /** 994 * This method is called by the parser to check whether arguments 995 * passed in scripts to this function are accepted by this function. If 996 * a script calls this function with an argument that is declared to be 997 * a "final" value and this is not accepted by this function, the parser 998 * will throw a parser error. 999 * 1000 * This default implementation of this method does not accept a "final" 1001 * value. Deriving subclasses would override this method implementation 1002 * in case they do accept a "final" value for its function arguments. 1003 * 1004 * @param iArg - index of the function argument in question 1005 * (must be between 0 .. maxAllowedArgs() - 1) 1006 * @return true if a "final" value would be accepted for the respective 1007 * function argument by the function 1008 * 1009 * @see VMNumberExpr::isFinal(), returnsFinal() 1010 */ 1011 virtual bool acceptsArgFinal(vmint iArg) const; 1012 1013 /** 1014 * This method is called by the parser to check whether some arguments 1015 * (and if yes which ones) passed to this script function will be 1016 * modified by this script function. Most script functions simply use 1017 * their arguments as inputs, that is they only read the argument's 1018 * values. However some script function may also use passed 1019 * argument(s) as output variables. In this case the function 1020 * implementation must return @c true for the respective argument 1021 * index here. 1022 * 1023 * @param iArg - index of the function argument in question 1024 * (must be between 0 .. maxAllowedArgs() - 1) 1025 */ 1026 virtual bool modifiesArg(vmint iArg) const = 0; 1027 1028 /** @brief Parse-time check of function arguments. 1029 * 1030 * This method is called by the parser to let the built-in function 1031 * perform its own, individual parse time checks on the arguments to be 1032 * passed to the built-in function. So this method is the place for 1033 * implementing custom checks which are very specific to the individual 1034 * built-in function's purpose and its individual requirements. 1035 * 1036 * For instance the built-in 'in_range()' function uses this method to 1037 * check whether the last 2 of their 3 arguments are of same data type 1038 * and if not it triggers a parser error. 'in_range()' also checks 1039 * whether all of its 3 arguments do have the same standard measuring 1040 * unit type and likewise raises a parser error if not. 1041 * 1042 * For less critical issues built-in functions may also raise parser 1043 * warnings instead. 1044 * 1045 * It is recommended that classes implementing (that is overriding) this 1046 * method should always call their super class's implementation of this 1047 * method to ensure their potential parse time checks are always 1048 * performed as well. 1049 * 1050 * @param args - function arguments going to be passed for executing 1051 * this built-in function later on 1052 * @param err - the parser's error handler to be called by this method 1053 * implementation to trigger a parser error with the 1054 * respective error message text 1055 * @param wrn - the parser's warning handler to be called by this method 1056 * implementation to trigger a parser warning with the 1057 * respective warning message text 1058 */ 1059 virtual void checkArgs(VMFnArgs* args, 1060 std::function<void(String)> err, 1061 std::function<void(String)> wrn); 1062 1063 /** @brief Allocate storage location for function's result value. 1064 * 1065 * This method is invoked at parse time to allocate object(s) suitable 1066 * to store a result value returned after executing this function 1067 * implementation. Function implementation returns an instance of some 1068 * type (being subclass of @c VMFnArgs) which allows it to store its 1069 * result value to appropriately. Life time of the returned object is 1070 * controlled by caller which will call delete on returned object once 1071 * it no longer needs the storage location anymore (usually when script 1072 * is unloaded). 1073 * 1074 * @param args - function arguments for executing this built-in function 1075 * @returns storage location for storing a result value of this function 1076 */ 1077 virtual VMFnResult* allocResult(VMFnArgs* args) = 0; 1078 1079 /** @brief Bind storage location for a result value to this function. 1080 * 1081 * This method is called to tell this function implementation where it 1082 * shall store its result value to when @c exec() is called 1083 * subsequently. 1084 * 1085 * @param res - storage location for a result value, previously 1086 * allocated by calling @c allocResult() 1087 */ 1088 virtual void bindResult(VMFnResult* res) = 0; 1089 1090 /** @brief Current storage location bound to this function for result. 1091 * 1092 * Returns storage location currently being bound for result value of 1093 * this function. 1094 */ 1095 virtual VMFnResult* boundResult() const = 0; 1096 1097 /** @brief Execute this function. 1098 * 1099 * Implements the actual function execution. This exec() method is 1100 * called by the VM whenever this function implementation shall be 1101 * executed at script runtime. This method blocks until the function 1102 * call completed. 1103 * 1104 * @remarks The actual storage location for returning a result value is 1105 * assigned by calling @c bindResult() before invoking @c exec(). 1106 * 1107 * @param args - function arguments for executing this built-in function 1108 * @returns function's return value (if any) and general status 1109 * informations (i.e. whether the function call caused a 1110 * runtime error) 1111 */ 1112 virtual VMFnResult* exec(VMFnArgs* args) = 0; 1113 1114 /** 1115 * Convenience method for function implementations to show warning 1116 * messages during actual execution of the built-in function. 1117 * 1118 * @param txt - runtime warning text to be shown to user 1119 */ 1120 void wrnMsg(const String& txt); 1121 1122 /** 1123 * Convenience method for function implementations to show error 1124 * messages during actual execution of the built-in function. 1125 * 1126 * @param txt - runtime error text to be shown to user 1127 */ 1128 void errMsg(const String& txt); 1129 }; 1130 1131 /** @brief Virtual machine relative pointer. 1132 * 1133 * POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not 1134 * intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr, 1135 * VMInt8RelPtr instead. 1136 * 1137 * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr 1138 */ 1139 struct VMRelPtr { 1140 void** base; ///< Base pointer. 1141 vmint offset; ///< Offset (in bytes) relative to base pointer. 1142 bool readonly; ///< Whether the pointed data may be modified or just be read. 1143 }; 1144 1145 /** @brief Pointer to built-in VM integer variable (interface class). 1146 * 1147 * This class acts as an abstract interface to all built-in integer script 1148 * variables, independent of their actual native size (i.e. some built-in 1149 * script variables are internally using a native int size of 64 bit or 32 1150 * bit or 8 bit). The virtual machine is using this interface class instead 1151 * of its implementing descendants (VMInt64RelPtr, VMInt32RelPtr, 1152 * VMInt8RelPtr) in order for the virtual machine for not being required to 1153 * handle each of them differently. 1154 */ 1155 struct VMIntPtr { 1156 virtual vmint evalInt() = 0; 1157 virtual void assign(vmint i) = 0; 1158 virtual bool isAssignable() const = 0; 1159 }; 1160 1161 /** @brief Pointer to built-in VM integer variable (of C/C++ type int64_t). 1162 * 1163 * Used for defining built-in 64 bit integer script variables. 1164 * 1165 * @b CAUTION: You may only use this class for pointing to C/C++ variables 1166 * of type "int64_t" (thus being exactly 64 bit in size). If the C/C++ int 1167 * variable you want to reference is only 32 bit in size then you @b must 1168 * use VMInt32RelPtr instead! Respectively for a referenced native variable 1169 * with only 8 bit in size you @b must use VMInt8RelPtr instead! 1170 * 1171 * For efficiency reasons the actual native C/C++ int variable is referenced 1172 * by two components here. The actual native int C/C++ variable in memory 1173 * is dereferenced at VM run-time by taking the @c base pointer dereference 1174 * and adding @c offset bytes. This has the advantage that for a large 1175 * number of built-in int variables, only one (or few) base pointer need 1176 * to be re-assigned before running a script, instead of updating each 1177 * built-in variable each time before a script is executed. 1178 * 1179 * Refer to DECLARE_VMINT() for example code. 1180 * 1181 * @see VMInt32RelPtr, VMInt16RelPtr, VMInt8RelPtr, DECLARE_VMINT() 1182 */ 1183 struct VMInt64RelPtr : VMRelPtr, VMIntPtr { VMInt64RelPtrVMInt64RelPtr1184 VMInt64RelPtr() { 1185 base = NULL; 1186 offset = 0; 1187 readonly = false; 1188 } VMInt64RelPtrVMInt64RelPtr1189 VMInt64RelPtr(const VMRelPtr& data) { 1190 base = data.base; 1191 offset = data.offset; 1192 readonly = false; 1193 } evalIntVMInt64RelPtr1194 vmint evalInt() OVERRIDE { 1195 return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset]; 1196 } assignVMInt64RelPtr1197 void assign(vmint i) OVERRIDE { 1198 *(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i; 1199 } isAssignableVMInt64RelPtr1200 bool isAssignable() const OVERRIDE { return !readonly; } 1201 }; 1202 1203 /** @brief Pointer to built-in VM integer variable (of C/C++ type int32_t). 1204 * 1205 * Used for defining built-in 32 bit integer script variables. 1206 * 1207 * @b CAUTION: You may only use this class for pointing to C/C++ variables 1208 * of type "int32_t" (thus being exactly 32 bit in size). If the C/C++ int 1209 * variable you want to reference is 64 bit in size then you @b must use 1210 * VMInt64RelPtr instead! Respectively for a referenced native variable with 1211 * only 8 bit in size you @b must use VMInt8RelPtr instead! 1212 * 1213 * For efficiency reasons the actual native C/C++ int variable is referenced 1214 * by two components here. The actual native int C/C++ variable in memory 1215 * is dereferenced at VM run-time by taking the @c base pointer dereference 1216 * and adding @c offset bytes. This has the advantage that for a large 1217 * number of built-in int variables, only one (or few) base pointer need 1218 * to be re-assigned before running a script, instead of updating each 1219 * built-in variable each time before a script is executed. 1220 * 1221 * Refer to DECLARE_VMINT() for example code. 1222 * 1223 * @see VMInt64RelPtr, VMInt16RelPtr, VMInt8RelPtr, DECLARE_VMINT() 1224 */ 1225 struct VMInt32RelPtr : VMRelPtr, VMIntPtr { VMInt32RelPtrVMInt32RelPtr1226 VMInt32RelPtr() { 1227 base = NULL; 1228 offset = 0; 1229 readonly = false; 1230 } VMInt32RelPtrVMInt32RelPtr1231 VMInt32RelPtr(const VMRelPtr& data) { 1232 base = data.base; 1233 offset = data.offset; 1234 readonly = false; 1235 } evalIntVMInt32RelPtr1236 vmint evalInt() OVERRIDE { 1237 return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset]; 1238 } assignVMInt32RelPtr1239 void assign(vmint i) OVERRIDE { 1240 *(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i; 1241 } isAssignableVMInt32RelPtr1242 bool isAssignable() const OVERRIDE { return !readonly; } 1243 }; 1244 1245 /** @brief Pointer to built-in VM integer variable (of C/C++ type int16_t). 1246 * 1247 * Used for defining built-in 16 bit integer script variables. 1248 * 1249 * @b CAUTION: You may only use this class for pointing to C/C++ variables 1250 * of type "int16_t" (thus being exactly 16 bit in size). If the C/C++ int 1251 * variable you want to reference is 64 bit in size then you @b must use 1252 * VMInt64RelPtr instead! Respectively for a referenced native variable with 1253 * only 8 bit in size you @b must use VMInt8RelPtr instead! 1254 * 1255 * For efficiency reasons the actual native C/C++ int variable is referenced 1256 * by two components here. The actual native int C/C++ variable in memory 1257 * is dereferenced at VM run-time by taking the @c base pointer dereference 1258 * and adding @c offset bytes. This has the advantage that for a large 1259 * number of built-in int variables, only one (or few) base pointer need 1260 * to be re-assigned before running a script, instead of updating each 1261 * built-in variable each time before a script is executed. 1262 * 1263 * Refer to DECLARE_VMINT() for example code. 1264 * 1265 * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr, DECLARE_VMINT() 1266 */ 1267 struct VMInt16RelPtr : VMRelPtr, VMIntPtr { VMInt16RelPtrVMInt16RelPtr1268 VMInt16RelPtr() { 1269 base = NULL; 1270 offset = 0; 1271 readonly = false; 1272 } VMInt16RelPtrVMInt16RelPtr1273 VMInt16RelPtr(const VMRelPtr& data) { 1274 base = data.base; 1275 offset = data.offset; 1276 readonly = false; 1277 } evalIntVMInt16RelPtr1278 vmint evalInt() OVERRIDE { 1279 return (vmint)*(int16_t*)&(*(uint8_t**)base)[offset]; 1280 } assignVMInt16RelPtr1281 void assign(vmint i) OVERRIDE { 1282 *(int16_t*)&(*(uint8_t**)base)[offset] = (int16_t)i; 1283 } isAssignableVMInt16RelPtr1284 bool isAssignable() const OVERRIDE { return !readonly; } 1285 }; 1286 1287 /** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t). 1288 * 1289 * Used for defining built-in 8 bit integer script variables. 1290 * 1291 * @b CAUTION: You may only use this class for pointing to C/C++ variables 1292 * of type "int8_t" (8 bit integer). If the C/C++ int variable you want to 1293 * reference is not exactly 8 bit in size then you @b must respectively use 1294 * either VMInt32RelPtr for native 32 bit variables or VMInt64RelPtrl for 1295 * native 64 bit variables instead! 1296 * 1297 * For efficiency reasons the actual native C/C++ int variable is referenced 1298 * by two components here. The actual native int C/C++ variable in memory 1299 * is dereferenced at VM run-time by taking the @c base pointer dereference 1300 * and adding @c offset bytes. This has the advantage that for a large 1301 * number of built-in int variables, only one (or few) base pointer need 1302 * to be re-assigned before running a script, instead of updating each 1303 * built-in variable each time before a script is executed. 1304 * 1305 * Refer to DECLARE_VMINT() for example code. 1306 * 1307 * @see VMInt16RelPtr, VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT() 1308 */ 1309 struct VMInt8RelPtr : VMRelPtr, VMIntPtr { VMInt8RelPtrVMInt8RelPtr1310 VMInt8RelPtr() { 1311 base = NULL; 1312 offset = 0; 1313 readonly = false; 1314 } VMInt8RelPtrVMInt8RelPtr1315 VMInt8RelPtr(const VMRelPtr& data) { 1316 base = data.base; 1317 offset = data.offset; 1318 readonly = false; 1319 } evalIntVMInt8RelPtr1320 vmint evalInt() OVERRIDE { 1321 return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset]; 1322 } assignVMInt8RelPtr1323 void assign(vmint i) OVERRIDE { 1324 *(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i; 1325 } isAssignableVMInt8RelPtr1326 bool isAssignable() const OVERRIDE { return !readonly; } 1327 }; 1328 1329 /** @brief Pointer to built-in VM integer variable (of C/C++ type vmint). 1330 * 1331 * Use this typedef if the native variable to be pointed to is using the 1332 * typedef vmint. If the native C/C++ variable to be pointed to is using 1333 * another C/C++ type then better use one of VMInt64RelPtr or VMInt32RelPtr 1334 * instead. 1335 */ 1336 typedef VMInt64RelPtr VMIntRelPtr; 1337 1338 #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS 1339 # define COMPILER_DISABLE_OFFSETOF_WARNING \ 1340 _Pragma("GCC diagnostic push") \ 1341 _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"") 1342 # define COMPILER_RESTORE_OFFSETOF_WARNING \ 1343 _Pragma("GCC diagnostic pop") 1344 #else 1345 # define COMPILER_DISABLE_OFFSETOF_WARNING 1346 # define COMPILER_RESTORE_OFFSETOF_WARNING 1347 #endif 1348 1349 /** 1350 * Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr, 1351 * VMInt16RelPtr and VMInt8RelPtr structures. Usage example: 1352 * @code 1353 * struct Foo { 1354 * uint8_t a; // native representation of a built-in integer script variable 1355 * int64_t b; // native representation of another built-in integer script variable 1356 * int64_t c; // native representation of another built-in integer script variable 1357 * uint8_t d; // native representation of another built-in integer script variable 1358 * }; 1359 * 1360 * // initializing the built-in script variables to some values 1361 * Foo foo1 = (Foo) { 1, 2000, 3000, 4 }; 1362 * Foo foo2 = (Foo) { 5, 6000, 7000, 8 }; 1363 * 1364 * Foo* pFoo; 1365 * 1366 * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a); 1367 * VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b); 1368 * VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c); 1369 * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d); 1370 * 1371 * pFoo = &foo1; 1372 * printf("%d\n", varA->evalInt()); // will print 1 1373 * printf("%d\n", varB->evalInt()); // will print 2000 1374 * printf("%d\n", varC->evalInt()); // will print 3000 1375 * printf("%d\n", varD->evalInt()); // will print 4 1376 * 1377 * // same printf() code, just with pFoo pointer being changed ... 1378 * 1379 * pFoo = &foo2; 1380 * printf("%d\n", varA->evalInt()); // will print 5 1381 * printf("%d\n", varB->evalInt()); // will print 6000 1382 * printf("%d\n", varC->evalInt()); // will print 7000 1383 * printf("%d\n", varD->evalInt()); // will print 8 1384 * @endcode 1385 * As you can see above, by simply changing one single pointer, you can 1386 * remap a huge bunch of built-in integer script variables to completely 1387 * different native values/native variables. Which especially reduces code 1388 * complexity inside the sampler engines which provide the actual script 1389 * functionalities. 1390 */ 1391 #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \ 1392 /* Disable offsetof warning, trust us, we are cautios. */ \ 1393 COMPILER_DISABLE_OFFSETOF_WARNING \ 1394 (VMRelPtr) { \ 1395 (void**) &basePtr, \ 1396 offsetof(T_struct, T_member), \ 1397 false \ 1398 } \ 1399 COMPILER_RESTORE_OFFSETOF_WARNING \ 1400 ) \ 1401 1402 /** 1403 * Same as DECLARE_VMINT(), but this one defines the VMInt64RelPtr, 1404 * VMInt32RelPtr, VMInt16RelPtr and VMInt8RelPtr structures to be of 1405 * read-only type. That means the script parser will abort any script at 1406 * parser time if the script is trying to modify such a read-only built-in 1407 * variable. 1408 * 1409 * @b NOTE: this is only intended for built-in read-only variables that 1410 * may change during runtime! If your built-in variable's data is rather 1411 * already available at parser time and won't change during runtime, then 1412 * you should rather register a built-in constant in your VM class instead! 1413 * 1414 * @see ScriptVM::builtInConstIntVariables() 1415 */ 1416 #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \ 1417 /* Disable offsetof warning, trust us, we are cautios. */ \ 1418 COMPILER_DISABLE_OFFSETOF_WARNING \ 1419 (VMRelPtr) { \ 1420 (void**) &basePtr, \ 1421 offsetof(T_struct, T_member), \ 1422 true \ 1423 } \ 1424 COMPILER_RESTORE_OFFSETOF_WARNING \ 1425 ) \ 1426 1427 /** @brief Built-in VM 8 bit integer array variable. 1428 * 1429 * Used for defining built-in integer array script variables (8 bit per 1430 * array element). Currently there is no support for any other kind of 1431 * built-in array type. So all built-in integer arrays accessed by scripts 1432 * use 8 bit data types. 1433 */ 1434 struct VMInt8Array { 1435 int8_t* data; 1436 vmint size; 1437 bool readonly; ///< Whether the array data may be modified or just be read. 1438 VMInt8ArrayVMInt8Array1439 VMInt8Array() : data(NULL), size(0), readonly(false) {} 1440 }; 1441 1442 /** @brief Virtual machine script variable. 1443 * 1444 * Common interface for all variables accessed in scripts, independent of 1445 * their precise data type. 1446 */ 1447 class VMVariable : virtual public VMExpr { 1448 public: 1449 /** 1450 * Whether a script may modify the content of this variable by 1451 * assigning a new value to it. 1452 * 1453 * @see isConstExpr(), assign() 1454 */ 1455 virtual bool isAssignable() const = 0; 1456 1457 /** 1458 * In case this variable is assignable, this method will be called to 1459 * perform the value assignment to this variable with @a expr 1460 * reflecting the new value to be assigned. 1461 * 1462 * @param expr - new value to be assigned to this variable 1463 */ 1464 virtual void assignExpr(VMExpr* expr) = 0; 1465 }; 1466 1467 /** @brief Dynamically executed variable (abstract base class). 1468 * 1469 * Interface for the implementation of a dynamically generated content of 1470 * a built-in script variable. Most built-in variables are simply pointers 1471 * to some native location in memory. So when a script reads them, the 1472 * memory location is simply read to get the value of the variable. A 1473 * dynamic variable however is not simply a memory location. For each access 1474 * to a dynamic variable some native code is executed to actually generate 1475 * and provide the content (value) of this type of variable. 1476 */ 1477 class VMDynVar : public VMVariable { 1478 public: 1479 /** 1480 * Returns true in case this dynamic variable can be considered to be a 1481 * constant expression. A constant expression will retain the same value 1482 * throughout the entire life time of a script and the expression's 1483 * constant value may be evaluated already at script parse time, which 1484 * may result in performance benefits during script runtime. 1485 * 1486 * However due to the "dynamic" behavior of dynamic variables, almost 1487 * all dynamic variables are probably not constant expressions. That's 1488 * why this method returns @c false by default. If you are really sure 1489 * that your dynamic variable implementation can be considered a 1490 * constant expression then you may override this method and return 1491 * @c true instead. Note that when you return @c true here, your 1492 * dynamic variable will really just be executed once; and exectly 1493 * already when the script is loaded! 1494 * 1495 * As an example you may implement a "constant" built-in dynamic 1496 * variable that checks for a certain operating system feature and 1497 * returns the result of that OS feature check as content (value) of 1498 * this dynamic variable. Since the respective OS feature might become 1499 * available/unavailable after OS updates, software migration, etc. the 1500 * OS feature check should at least be performed once each time the 1501 * application is launched. And since the OS feature check might take a 1502 * certain amount of execution time, it might make sense to only 1503 * perform the check if the respective variable name is actually 1504 * referenced at all in the script to be loaded. Note that the dynamic 1505 * variable will still be evaluated again though if the script is 1506 * loaded again. So it is up to you to probably cache the result in the 1507 * implementation of your dynamic variable. 1508 * 1509 * On doubt, please rather consider to use a constant built-in script 1510 * variable instead of implementing a "constant" dynamic variable, due 1511 * to the runtime overhead a dynamic variable may cause. 1512 * 1513 * @see isAssignable() 1514 */ isConstExpr()1515 bool isConstExpr() const OVERRIDE { return false; } 1516 1517 /** 1518 * In case this dynamic variable is assignable, the new value (content) 1519 * to be assigned to this dynamic variable. 1520 * 1521 * By default this method does nothing. Override and implement this 1522 * method in your subclass in case your dynamic variable allows to 1523 * assign a new value by script. 1524 * 1525 * @param expr - new value to be assigned to this variable 1526 */ assignExpr(VMExpr * expr)1527 void assignExpr(VMExpr* expr) OVERRIDE {} 1528 ~VMDynVar()1529 virtual ~VMDynVar() {} 1530 }; 1531 1532 /** @brief Dynamically executed variable (of integer data type). 1533 * 1534 * This is the base class for all built-in integer script variables whose 1535 * variable content needs to be provided dynamically by executable native 1536 * code on each script variable access. 1537 */ 1538 class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr { 1539 public: unitFactor()1540 vmfloat unitFactor() const OVERRIDE { return VM_NO_FACTOR; } unitType()1541 StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; } isFinal()1542 bool isFinal() const OVERRIDE { return false; } 1543 }; 1544 1545 /** @brief Dynamically executed variable (of string data type). 1546 * 1547 * This is the base class for all built-in string script variables whose 1548 * variable content needs to be provided dynamically by executable native 1549 * code on each script variable access. 1550 */ 1551 class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr { 1552 public: 1553 }; 1554 1555 /** @brief Dynamically executed variable (of integer array data type). 1556 * 1557 * This is the base class for all built-in integer array script variables 1558 * whose variable content needs to be provided dynamically by executable 1559 * native code on each script variable access. 1560 */ 1561 class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr { 1562 public: 1563 }; 1564 1565 /** @brief Provider for built-in script functions and variables. 1566 * 1567 * Abstract base class defining the high-level interface for all classes 1568 * which add and implement built-in script functions and built-in script 1569 * variables. 1570 */ 1571 class VMFunctionProvider { 1572 public: 1573 /** 1574 * Returns pointer to the built-in function with the given function 1575 * @a name, or NULL if there is no built-in function with that function 1576 * name. 1577 * 1578 * @param name - function name (i.e. "wait" or "message" or "exit", etc.) 1579 */ 1580 virtual VMFunction* functionByName(const String& name) = 0; 1581 1582 /** 1583 * Returns @c true if the passed built-in function is disabled and 1584 * should be ignored by the parser. This method is called by the 1585 * parser on preprocessor level for each built-in function call within 1586 * a script. Accordingly if this method returns @c true, then the 1587 * respective function call is completely filtered out on preprocessor 1588 * level, so that built-in function won't make into the result virtual 1589 * machine representation, nor would expressions of arguments passed to 1590 * that built-in function call be evaluated, nor would any check 1591 * regarding correct usage of the built-in function be performed. 1592 * In other words: a disabled function call ends up as a comment block. 1593 * 1594 * @param fn - built-in function to be checked 1595 * @param ctx - parser context at the position where the built-in 1596 * function call is located within the script 1597 */ 1598 virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0; 1599 1600 /** 1601 * Returns a variable name indexed map of all built-in script variables 1602 * which point to native "int" scalar (usually 32 bit) variables. 1603 */ 1604 virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0; 1605 1606 /** 1607 * Returns a variable name indexed map of all built-in script integer 1608 * array variables with array element type "int8_t" (8 bit). 1609 */ 1610 virtual std::map<String,VMInt8Array*> builtInIntArrayVariables() = 0; 1611 1612 /** 1613 * Returns a variable name indexed map of all built-in constant script 1614 * variables of integer type, which never change their value at runtime. 1615 */ 1616 virtual std::map<String,vmint> builtInConstIntVariables() = 0; 1617 1618 /** 1619 * Returns a variable name indexed map of all built-in constant script 1620 * variables of real number (floating point) type, which never change 1621 * their value at runtime. 1622 */ 1623 virtual std::map<String,vmfloat> builtInConstRealVariables() = 0; 1624 1625 /** 1626 * Returns a variable name indexed map of all built-in dynamic variables, 1627 * which are not simply data stores, rather each one of them executes 1628 * natively to provide or alter the respective script variable data. 1629 */ 1630 virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0; 1631 }; 1632 1633 /** @brief Execution state of a virtual machine. 1634 * 1635 * An instance of this abstract base class represents exactly one execution 1636 * state of a virtual machine. This encompasses most notably the VM 1637 * execution stack, and VM polyphonic variables. It does not contain global 1638 * variables. Global variables are contained in the VMParserContext object. 1639 * You might see a VMExecContext object as one virtual thread of the virtual 1640 * machine. 1641 * 1642 * In contrast to a VMParserContext, a VMExecContext is not tied to a 1643 * ScriptVM instance. Thus you can use a VMExecContext with different 1644 * ScriptVM instances, however not concurrently at the same time. 1645 * 1646 * @see VMParserContext 1647 */ 1648 class VMExecContext { 1649 public: ~VMExecContext()1650 virtual ~VMExecContext() {} 1651 1652 /** 1653 * In case the script was suspended for some reason, this method returns 1654 * the amount of microseconds before the script shall continue its 1655 * execution. Note that the virtual machine itself does never put its 1656 * own execution thread(s) to sleep. So the respective class (i.e. sampler 1657 * engine) which is using the virtual machine classes here, must take 1658 * care by itself about taking time stamps, determining the script 1659 * handlers that shall be put aside for the requested amount of 1660 * microseconds, indicated by this method by comparing the time stamps in 1661 * real-time, and to continue passing the respective handler to 1662 * ScriptVM::exec() as soon as its suspension exceeded, etc. Or in other 1663 * words: all classes in this directory never have an idea what time it 1664 * is. 1665 * 1666 * You should check the return value of ScriptVM::exec() to determine 1667 * whether the script was actually suspended before calling this method 1668 * here. 1669 * 1670 * @see ScriptVM::exec() 1671 */ 1672 virtual vmint suspensionTimeMicroseconds() const = 0; 1673 1674 /** 1675 * Causes all polyphonic variables to be reset to zero values. A 1676 * polyphonic variable is expected to be zero when entering a new event 1677 * handler instance. As an exception the values of polyphonic variables 1678 * shall only be preserved from an note event handler instance to its 1679 * correspending specific release handler instance. So in the latter 1680 * case the script author may pass custom data from the note handler to 1681 * the release handler, but only for the same specific note! 1682 */ 1683 virtual void resetPolyphonicData() = 0; 1684 1685 /** 1686 * Copies all polyphonic variables from the passed source object to this 1687 * destination object. 1688 * 1689 * @param ectx - source object to be copied from 1690 */ 1691 virtual void copyPolyphonicDataFrom(VMExecContext* ectx) = 0; 1692 1693 /** 1694 * Returns amount of virtual machine instructions which have been 1695 * performed the last time when this execution context was executing a 1696 * script. So in case you need the overall amount of instructions 1697 * instead, then you need to add them by yourself after each 1698 * ScriptVM::exec() call. 1699 */ 1700 virtual size_t instructionsPerformed() const = 0; 1701 1702 /** 1703 * Sends a signal to this script execution instance to abort its script 1704 * execution as soon as possible. This method is called i.e. when one 1705 * script execution instance intends to stop another script execution 1706 * instance. 1707 */ 1708 virtual void signalAbort() = 0; 1709 1710 /** 1711 * Copies the current entire execution state from this object to the 1712 * given object. So this can be used to "fork" a new script thread which 1713 * then may run independently with its own polyphonic data for instance. 1714 */ 1715 virtual void forkTo(VMExecContext* ectx) const = 0; 1716 1717 /** 1718 * In case the script called the built-in exit() function and passed a 1719 * value as argument to the exit() function, then this method returns 1720 * the value that had been passed as argument to the exit() function. 1721 * Otherwise if the exit() function has not been called by the script 1722 * or no argument had been passed to the exit() function, then this 1723 * method returns NULL instead. 1724 * 1725 * Currently this is only used for automated test cases against the 1726 * script engine, which return some kind of value in the individual 1727 * test case scripts to check their behaviour in automated way. There 1728 * is no purpose for this mechanism in production use. Accordingly this 1729 * exit result value is @b always completely ignored by the sampler 1730 * engines. 1731 * 1732 * Officially the built-in exit() function does not expect any arguments 1733 * to be passed to its function call, and by default this feature is 1734 * hence disabled and will yield in a parser error unless 1735 * ScriptVM::setExitResultEnabled() was explicitly set. 1736 * 1737 * @see ScriptVM::setExitResultEnabled() 1738 */ 1739 virtual VMExpr* exitResult() = 0; 1740 }; 1741 1742 /** @brief Script callback for a certain event. 1743 * 1744 * Represents a script callback for a certain event, i.e. 1745 * "on note ... end on" code block. 1746 */ 1747 class VMEventHandler { 1748 public: 1749 /** 1750 * Type of this event handler, which identifies its purpose. For example 1751 * for a "on note ... end on" script callback block, 1752 * @c VM_EVENT_HANDLER_NOTE would be returned here. 1753 */ 1754 virtual VMEventHandlerType_t eventHandlerType() const = 0; 1755 1756 /** 1757 * Name of the event handler which identifies its purpose. For example 1758 * for a "on note ... end on" script callback block, the name "note" 1759 * would be returned here. 1760 */ 1761 virtual String eventHandlerName() const = 0; 1762 1763 /** 1764 * Whether or not the event handler makes any use of so called 1765 * "polyphonic" variables. 1766 */ 1767 virtual bool isPolyphonic() const = 0; 1768 }; 1769 1770 /** 1771 * Reflects the precise position and span of a specific code block within 1772 * a script. This is currently only used for the locations of commented 1773 * code blocks due to preprocessor statements, and for parser errors and 1774 * parser warnings. 1775 * 1776 * @see ParserIssue for code locations of parser errors and parser warnings 1777 * 1778 * @see VMParserContext::preprocessorComments() for locations of code which 1779 * have been filtered out by preprocessor statements 1780 */ 1781 struct CodeBlock { 1782 int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line). 1783 int lastLine; ///< The last line number of this code block within the script. 1784 int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column). 1785 int lastColumn; ///< The last column of this code block within the script. 1786 int firstByte; ///< The first byte of this code block within the script. 1787 int lengthBytes; ///< Length of this code block within the script (in bytes). 1788 }; 1789 1790 /** 1791 * Encapsulates a noteworty parser issue. This encompasses the type of the 1792 * issue (either a parser error or parser warning), a human readable 1793 * explanation text of the error or warning and the location of the 1794 * encountered parser issue within the script. 1795 * 1796 * @see VMSourceToken for processing syntax highlighting instead. 1797 */ 1798 struct ParserIssue : CodeBlock { 1799 String txt; ///< Human readable explanation text of the parser issue. 1800 ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning. 1801 1802 /** 1803 * Print this issue out to the console (stdio). 1804 */ dumpParserIssue1805 inline void dump() { 1806 switch (type) { 1807 case PARSER_ERROR: 1808 printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str()); 1809 break; 1810 case PARSER_WARNING: 1811 printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str()); 1812 break; 1813 } 1814 } 1815 1816 /** 1817 * Returns true if this issue is a parser error. In this case the parsed 1818 * script may not be executed! 1819 */ isErrParserIssue1820 inline bool isErr() const { return type == PARSER_ERROR; } 1821 1822 /** 1823 * Returns true if this issue is just a parser warning. A parsed script 1824 * that only raises warnings may be executed if desired, however the 1825 * script may not behave exactly as intended by the script author. 1826 */ isWrnParserIssue1827 inline bool isWrn() const { return type == PARSER_WARNING; } 1828 }; 1829 1830 /** 1831 * Convenience function used for converting an ExprType_t constant to a 1832 * string, i.e. for generating error message by the parser. 1833 */ typeStr(const ExprType_t & type)1834 inline String typeStr(const ExprType_t& type) { 1835 switch (type) { 1836 case EMPTY_EXPR: return "empty"; 1837 case INT_EXPR: return "integer"; 1838 case INT_ARR_EXPR: return "integer array"; 1839 case REAL_EXPR: return "real number"; 1840 case REAL_ARR_EXPR: return "real number array"; 1841 case STRING_EXPR: return "string"; 1842 case STRING_ARR_EXPR: return "string array"; 1843 } 1844 return "invalid"; 1845 } 1846 1847 /** 1848 * Returns @c true in case the passed data type is some array data type. 1849 */ isArray(const ExprType_t & type)1850 inline bool isArray(const ExprType_t& type) { 1851 return type == INT_ARR_EXPR || type == REAL_ARR_EXPR || 1852 type == STRING_ARR_EXPR; 1853 } 1854 1855 /** 1856 * Returns @c true in case the passed data type is some scalar number type 1857 * (i.e. not an array and not a string). 1858 */ isNumber(const ExprType_t & type)1859 inline bool isNumber(const ExprType_t& type) { 1860 return type == INT_EXPR || type == REAL_EXPR; 1861 } 1862 1863 /** 1864 * Convenience function used for converting an StdUnit_t constant to a 1865 * string, i.e. for generating error message by the parser. 1866 */ unitTypeStr(const StdUnit_t & type)1867 inline String unitTypeStr(const StdUnit_t& type) { 1868 switch (type) { 1869 case VM_NO_UNIT: return "none"; 1870 case VM_SECOND: return "seconds"; 1871 case VM_HERTZ: return "Hz"; 1872 case VM_BEL: return "Bel"; 1873 } 1874 return "invalid"; 1875 } 1876 1877 /** @brief Virtual machine representation of a script. 1878 * 1879 * An instance of this abstract base class represents a parsed script, 1880 * translated into a virtual machine tree. You should first check if there 1881 * were any parser errors. If there were any parser errors, you should 1882 * refrain from executing the virtual machine. Otherwise if there were no 1883 * parser errors (i.e. only warnings), then you might access one of the 1884 * script's event handlers by i.e. calling eventHandlerByName() and pass the 1885 * respective event handler to the ScriptVM class (or to one of the ScriptVM 1886 * descendants) for execution. 1887 * 1888 * @see VMExecContext, ScriptVM 1889 */ 1890 class VMParserContext { 1891 public: ~VMParserContext()1892 virtual ~VMParserContext() {} 1893 1894 /** 1895 * Returns all noteworthy issues encountered when the script was parsed. 1896 * These are parser errors and parser warnings. 1897 */ 1898 virtual std::vector<ParserIssue> issues() const = 0; 1899 1900 /** 1901 * Same as issues(), but this method only returns parser errors. 1902 */ 1903 virtual std::vector<ParserIssue> errors() const = 0; 1904 1905 /** 1906 * Same as issues(), but this method only returns parser warnings. 1907 */ 1908 virtual std::vector<ParserIssue> warnings() const = 0; 1909 1910 /** 1911 * Returns all code blocks of the script which were filtered out by the 1912 * preprocessor. 1913 */ 1914 virtual std::vector<CodeBlock> preprocessorComments() const = 0; 1915 1916 /** 1917 * Returns the translated virtual machine representation of an event 1918 * handler block (i.e. "on note ... end on" code block) within the 1919 * parsed script. This translated representation of the event handler 1920 * can be executed by the virtual machine. 1921 * 1922 * @param index - index of the event handler within the script 1923 */ 1924 virtual VMEventHandler* eventHandler(uint index) = 0; 1925 1926 /** 1927 * Same as eventHandler(), but this method returns the event handler by 1928 * its name. So for a "on note ... end on" code block of the parsed 1929 * script you would pass "note" for argument @a name here. 1930 * 1931 * @param name - name of the event handler (i.e. "init", "note", 1932 * "controller", "release") 1933 */ 1934 virtual VMEventHandler* eventHandlerByName(const String& name) = 0; 1935 }; 1936 1937 class SourceToken; 1938 1939 /** @brief Recognized token of a script's source code. 1940 * 1941 * Represents one recognized token of a script's source code, for example 1942 * a keyword, variable name, etc. and it provides further informations about 1943 * that particular token, i.e. the precise location (line and column) of the 1944 * token within the original script's source code. 1945 * 1946 * This class is not actually used by the sampler itself. It is rather 1947 * provided for external script editor applications. Primary purpose of 1948 * this class is syntax highlighting for external script editors. 1949 * 1950 * @see ParserIssue for processing compile errors and warnings instead. 1951 */ 1952 class VMSourceToken { 1953 public: 1954 VMSourceToken(); 1955 VMSourceToken(SourceToken* ct); 1956 VMSourceToken(const VMSourceToken& other); 1957 virtual ~VMSourceToken(); 1958 1959 // original text of this token as it is in the script's source code 1960 String text() const; 1961 1962 // position of token in script 1963 int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line). Most source code tokens are not spanning over multiple lines, the only current exception are comments, in the latter case you need to process text() to get the last line and last column for the comment. 1964 int firstColumn() const; ///< First column on the first line this source token is located at in script source code (indexed with 0 being the very first column). To get the length of this token use text().length(). 1965 int firstByte() const; ///< First raw byte position of this source token in script source code. 1966 int lengthBytes() const; ///< Raw byte length of this source token (in bytes). 1967 1968 // base types 1969 bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file. 1970 bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems). 1971 bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.). 1972 bool isVariableName() const; ///< Returns true in case this source token represents a variable name (i.e. "$someIntVariable", "%someArrayVariable", "\@someStringVariable"). @see isIntegerVariable(), isStringVariable(), isArrayVariable() for the precise variable type. 1973 bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name. 1974 bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123). 1975 bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text"). 1976 bool isComment() const; ///< Returns true in case this source token represents a source code comment. 1977 bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement. 1978 bool isMetricPrefix() const; 1979 bool isStdUnit() const; 1980 bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above. 1981 1982 // extended types 1983 bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable"). 1984 bool isRealVariable() const; ///< Returns true in case this source token represents a floating point variable name (i.e. "~someRealVariable"). 1985 bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable"). 1986 bool isIntArrayVariable() const; ///< Returns true in case this source token represents an integer array variable name (i.e. "%someArrayVariable"). 1987 bool isRealArrayVariable() const; ///< Returns true in case this source token represents a real number array variable name (i.e. "?someArrayVariable"). 1988 bool isArrayVariable() const DEPRECATED_API; ///< Returns true in case this source token represents an @b integer array variable name (i.e. "%someArrayVariable"). @deprecated This method will be removed, use isIntArrayVariable() instead. 1989 bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller"). 1990 1991 VMSourceToken& operator=(const VMSourceToken& other); 1992 1993 private: 1994 SourceToken* m_token; 1995 }; 1996 1997 } // namespace LinuxSampler 1998 1999 #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H 2000