/[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 3585 - (show annotations) (download) (as text)
Fri Aug 30 17:51:24 2019 UTC (4 years, 6 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 88241 byte(s)
NKSP: Cleanup regarding multiple data types for built-in function args.

* NKSP VM API cleanup: Get rid of legacy method
  VMFunction::argType(vmint iArg) which was already superseded by its new
  replacement VMFunction::acceptsArgType(vmint iArg, ExprType_t type).

* NKSP parser: if wrong argument type was passed to a built-in function and
  that built-in function accepts more than one data type for the argument,
  then show all supported data types as parser error message.

* Bumped version (2.1.1.svn10).

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

  ViewVC Help
Powered by ViewVC