/[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 3690 - (show annotations) (download) (as text)
Fri Jan 3 10:18:21 2020 UTC (9 months, 2 weeks ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 90812 byte(s)
NKSP: Added support for RPN and NRPN event handlers:

* NKSP language: Added support for RPN event handler
  ("on rpn ... end on" in instrument scripts).

* NKSP language: Added support for NRPN event handler
  ("on nrpn ... end on" in instrument scripts).

* Added built-in read-only variables "$RPN_ADDRESS" and "$RPN_VALUE" which
  may be read from the new RPN/NRPN script handlers to get the (N)RPN
  parameter that had been changed and its new value.

* Added built-in const variables "$NI_CB_TYPE_RPN" and "$NI_CB_TYPE_NRPN"
  which are identifying the new (N)RPN handlers as such at script runtime.

* Bumped version (2.1.1.svn30).

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

  ViewVC Help
Powered by ViewVC