/[svn]/linuxsampler/trunk/src/scriptvm/common.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/scriptvm/common.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3845 - (show annotations) (download) (as text)
Tue Jan 5 20:42:32 2021 UTC (3 years, 2 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 93467 byte(s)
* ScriptVM: Fixed incorrect polyphonic data transfer from wrong "note"
  handler to "release" handler; which also fixes no "release" handler
  being executed sometimes, and due to the latter it also fixes potential
  crashes as some polyphonic script events were never released and the
  engine hence was running out of free script events.

* Bumped version (2.1.1.svn68).

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
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 */
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 */
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 */
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 */
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 */
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 */
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 {
1184 VMInt64RelPtr() {
1185 base = NULL;
1186 offset = 0;
1187 readonly = false;
1188 }
1189 VMInt64RelPtr(const VMRelPtr& data) {
1190 base = data.base;
1191 offset = data.offset;
1192 readonly = false;
1193 }
1194 vmint evalInt() OVERRIDE {
1195 return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset];
1196 }
1197 void assign(vmint i) OVERRIDE {
1198 *(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i;
1199 }
1200 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 {
1226 VMInt32RelPtr() {
1227 base = NULL;
1228 offset = 0;
1229 readonly = false;
1230 }
1231 VMInt32RelPtr(const VMRelPtr& data) {
1232 base = data.base;
1233 offset = data.offset;
1234 readonly = false;
1235 }
1236 vmint evalInt() OVERRIDE {
1237 return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset];
1238 }
1239 void assign(vmint i) OVERRIDE {
1240 *(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i;
1241 }
1242 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 {
1268 VMInt16RelPtr() {
1269 base = NULL;
1270 offset = 0;
1271 readonly = false;
1272 }
1273 VMInt16RelPtr(const VMRelPtr& data) {
1274 base = data.base;
1275 offset = data.offset;
1276 readonly = false;
1277 }
1278 vmint evalInt() OVERRIDE {
1279 return (vmint)*(int16_t*)&(*(uint8_t**)base)[offset];
1280 }
1281 void assign(vmint i) OVERRIDE {
1282 *(int16_t*)&(*(uint8_t**)base)[offset] = (int16_t)i;
1283 }
1284 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 {
1310 VMInt8RelPtr() {
1311 base = NULL;
1312 offset = 0;
1313 readonly = false;
1314 }
1315 VMInt8RelPtr(const VMRelPtr& data) {
1316 base = data.base;
1317 offset = data.offset;
1318 readonly = false;
1319 }
1320 vmint evalInt() OVERRIDE {
1321 return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset];
1322 }
1323 void assign(vmint i) OVERRIDE {
1324 *(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i;
1325 }
1326 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
1439 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 */
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 */
1527 void assignExpr(VMExpr* expr) OVERRIDE {}
1528
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:
1540 vmfloat unitFactor() const OVERRIDE { return VM_NO_FACTOR; }
1541 StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; }
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:
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 */
1805 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 */
1820 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 */
1827 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 */
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 */
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 */
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 */
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:
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

  ViewVC Help
Powered by ViewVC