/[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 3581 - (show annotations) (download) (as text)
Fri Aug 30 11:40:25 2019 UTC (4 years, 6 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 87504 byte(s)
NKSP: Allow more wider support of standard measuring units & 'final'ness.

* Raised compiler requirement to be C++14 compliant (due to severe
  restrictions regarding C-style aggregate initializer lists in C++11
  which are now massively used throughout the code base).

* NKSP VM API: Allow units and 'final'ness to be returned as result from
  built-in functions (added methods VMFunction::returnUnitType() and
  VMFunction::returnsFinal() for that purpose which must be implemented by
  built-in function implementations).

* NKSP language: Allow metric unit prefixes of numeric scalar and array
  variables to be changed freely at runtime (unlike unit types like Hz etc.
  which are still sticky parse-time features of variables which cannot be
  changed at runtime for the intentional sake of determinism).

* NKSP language: 'final' values are prohibited for array variables for now
  (attempt causes a parsers error).

* NKSP language: expressions with unit types (e.g. Hz) are prohibited for
  conditions of runtime control structures like if(), while(), select()
  (attempt causes a parser error).

* NKSP VM API: Allow built-in functions to perform their own, individual
  parse time checks of arguments going to be passed to the function at
  runtime (added method VMFunction::checkArgs() for that purpose).

* NKSP language: raise parser warning if only one operand of binary
  operators (like logical 'or' comparison) contain a 'final' value (because
  it would always yield in a 'final' result in such cases).

* NKSP language: Allow comparison (=, #, <, >, <=, >=) of values with
  different metric unit prefixes, which will behave as expected (e.g.
  result of expression '1000us < 2ms' is true).

* NKSP language: Allow adding values with different metric unit prefixes
  (e.g. result of expression '100Hz + 5kHz' is '5100Hz').

* NKSP language: Allow subtracting values with different metric unit
  prefixes (e.g. result of expression '1ms - 20us' is '980us').

* NKSP language: Allow multiplying with any metric unit prefixes
  (e.g. result of expression '2k * 3ms' is '6s'), however multiplications
  with unit types on both sides (e.g. '2s * 2s') is still prohibited since
  we don't have any considerable practical use for a term like '4s^2'
  (hence any attempt multiplying two unit types still causes parser error).

* NKSP language: Allow dividing by any metric unit prefixes and allow
  division of same unit type on both sides (e.g. expression '8kHz / 1000Hz'
  yields in unit free result '8'). So this is now a way to cast units away
  e.g. for passing the result to other expressions, certain function calls
  or variables which are not accepting any units (or that specific unit).

* NKSP language: integer arrays and real number arrays can now be converted
  to strings (e.g. for dumping their content with message() calls for
  script debugging purposes).

* NKSP language: expressions and variables with units are now correctly
  casted to strings (e.g. with message() calls).

* NKSP language: comparing real numbers for equalness (e.g. '~foo = 3.1') or
  unequalness (e.g. '~foo # 3.1') is now less strict and takes the expected
  floating point tolerances into account.

* NKSP VM API: Added methods VMScalarNumberExpr::evalCastInt() and
  VMScalarNumberExpr::evalCastReal().

* NKSP VM API: Added base class 'VMNumberArrayExpr' for classes
  'VMIntArrayExpr' and 'VMRealArrayExpr'.

* NKSP VM API: replaced all unitPrefix() (parse time) methods by
  unitFactor() (runtime) methods.

* Built-in function "exit()" supports now returning units and 'final'ness
  exclusively for test cases.

* The following built-in functions support now units as well: "abs()",
  "random()", "inc()", "dec()", "in_range()", "min()", "max()",
  "real_to_int()", "int()", "int_to_real()" and "real()".

* Built-in functions "array_equal()", "search()" and "sort()" support now
  real number arrays (correctly) as well.

* Added individual parse time checks of arguments to be passed to built-in
  functions "random()", "inc()", "dec()", "in_range()", "min()", "max()",
  "array_equal()" and "search()" specific for their individual purposes.

* Test cases: Added massive amount of NKSP test cases for standard
  measuring units and 'final' operator usage cases.

* Test cases: Added NKSP test cases for (floating point tolerance aware)
  real number equalness / unequalness comparison.

* Bumped version (2.1.1.svn8).

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 VMScalarNumberExpr;
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(), asScalarNumberExpr()
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(), asScalarNumberExpr()
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 * VMScalarNumberExpr 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 VMScalarNumberExpr* asScalarNumberExpr() 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 VMScalarNumberExpr : 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 real number. If this scalar number expression is
519 * an integer expression then this method automatically casts the value
520 * from integer to real number.
521 */
522 vmfloat evalCastReal();
523 };
524
525 /** @brief Virtual machine integer expression
526 *
527 * This is the abstract base class for all expressions inside scripts which
528 * evaluate to an integer (scalar) value. Deriving classes implement the
529 * abstract method evalInt() to return the actual integer result value of
530 * the expression.
531 */
532 class VMIntExpr : virtual public VMScalarNumberExpr {
533 public:
534 /**
535 * Returns the result of this expression as integer (scalar) value.
536 * This abstract method must be implemented by deriving classes.
537 */
538 virtual vmint evalInt() = 0;
539
540 /**
541 * Returns the result of this expression as integer (scalar) value and
542 * thus behaves similar to the previous method, however this overridden
543 * method automatically takes unit prefixes into account and returns a
544 * value corresponding to the expected given unit @a prefix.
545 *
546 * @param prefix - default measurement unit prefix expected by caller
547 */
548 vmint evalInt(MetricPrefix_t prefix);
549
550 /**
551 * This method behaves like the previous method, just that it takes
552 * a default measurement prefix with two elements (i.e. "milli cents"
553 * for tuning).
554 */
555 vmint evalInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
556
557 /**
558 * Returns always INT_EXPR for instances of this class.
559 */
560 ExprType_t exprType() const OVERRIDE { return INT_EXPR; }
561 };
562
563 /** @brief Virtual machine real number (floating point scalar) expression
564 *
565 * This is the abstract base class for all expressions inside scripts which
566 * evaluate to a real number (floating point scalar) value. Deriving classes
567 * implement the abstract method evalReal() to return the actual floating
568 * point result value of the expression.
569 */
570 class VMRealExpr : virtual public VMScalarNumberExpr {
571 public:
572 /**
573 * Returns the result of this expression as real number (floating point
574 * scalar) value. This abstract method must be implemented by deriving
575 * classes.
576 */
577 virtual vmfloat evalReal() = 0;
578
579 /**
580 * Returns the result of this expression as real number (floating point
581 * scalar) value and thus behaves similar to the previous method,
582 * however this overridden method automatically takes unit prefixes into
583 * account and returns a value corresponding to the expected given unit
584 * @a prefix.
585 *
586 * @param prefix - default measurement unit prefix expected by caller
587 */
588 vmfloat evalReal(MetricPrefix_t prefix);
589
590 /**
591 * This method behaves like the previous method, just that it takes
592 * a default measurement prefix with two elements (i.e. "milli cents"
593 * for tuning).
594 */
595 vmfloat evalReal(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
596
597 /**
598 * Returns always REAL_EXPR for instances of this class.
599 */
600 ExprType_t exprType() const OVERRIDE { return REAL_EXPR; }
601 };
602
603 /** @brief Virtual machine string expression
604 *
605 * This is the abstract base class for all expressions inside scripts which
606 * evaluate to a string value. Deriving classes implement the abstract
607 * method evalStr() to return the actual string result value of the
608 * expression.
609 */
610 class VMStringExpr : virtual public VMExpr {
611 public:
612 /**
613 * Returns the result of this expression as string value. This abstract
614 * method must be implemented by deriving classes.
615 */
616 virtual String evalStr() = 0;
617
618 /**
619 * Returns always STRING_EXPR for instances of this class.
620 */
621 ExprType_t exprType() const OVERRIDE { return STRING_EXPR; }
622 };
623
624 /** @brief Virtual Machine Array Value Expression
625 *
626 * This is the abstract base class for all expressions inside scripts which
627 * evaluate to some kind of array value. Deriving classes implement the
628 * abstract method arraySize() to return the amount of elements within the
629 * array.
630 */
631 class VMArrayExpr : virtual public VMExpr {
632 public:
633 /**
634 * Returns amount of elements in this array. This abstract method must
635 * be implemented by deriving classes.
636 */
637 virtual vmint arraySize() const = 0;
638 };
639
640 /** @brief Virtual Machine Number Array Expression
641 *
642 * This is the abstract base class for all expressions which either evaluate
643 * to an integer array or real number array.
644 */
645 class VMNumberArrayExpr : virtual public VMArrayExpr {
646 public:
647 /**
648 * Returns the metric unit factor of the requested array element.
649 *
650 * @param i - array element index (must be between 0 .. arraySize() - 1)
651 * @see VMUnit::unitFactor() for details about metric unit factors
652 */
653 virtual vmfloat unitFactorOfElement(vmuint i) const = 0;
654
655 /**
656 * Changes the current unit factor of the array element given by element
657 * index @a i.
658 *
659 * @param i - array element index (must be between 0 .. arraySize() - 1)
660 * @param factor - new unit factor to be assigned
661 * @see VMUnit::unitFactor() for details about metric unit factors
662 */
663 virtual void assignElementUnitFactor(vmuint i, vmfloat factor) = 0;
664 };
665
666 /** @brief Virtual Machine Integer Array Expression
667 *
668 * This is the abstract base class for all expressions inside scripts which
669 * evaluate to an array of integer values. Deriving classes implement the
670 * abstract methods arraySize(), evalIntElement() and assignIntElement() to
671 * access the individual integer array values.
672 */
673 class VMIntArrayExpr : virtual public VMNumberArrayExpr {
674 public:
675 /**
676 * Returns the (scalar) integer value of the array element given by
677 * element index @a i.
678 *
679 * @param i - array element index (must be between 0 .. arraySize() - 1)
680 */
681 virtual vmint evalIntElement(vmuint i) = 0;
682
683 /**
684 * Changes the current value of an element (given by array element
685 * index @a i) of this integer array.
686 *
687 * @param i - array element index (must be between 0 .. arraySize() - 1)
688 * @param value - new integer scalar value to be assigned to that array element
689 */
690 virtual void assignIntElement(vmuint i, vmint value) = 0;
691
692 /**
693 * Returns always INT_ARR_EXPR for instances of this class.
694 */
695 ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }
696 };
697
698 /** @brief Virtual Machine Real Number Array Expression
699 *
700 * This is the abstract base class for all expressions inside scripts which
701 * evaluate to an array of real numbers (floating point values). Deriving
702 * classes implement the abstract methods arraySize(), evalRealElement() and
703 * assignRealElement() to access the array's individual real numbers.
704 */
705 class VMRealArrayExpr : virtual public VMNumberArrayExpr {
706 public:
707 /**
708 * Returns the (scalar) real mumber (floating point value) of the array
709 * element given by element index @a i.
710 *
711 * @param i - array element index (must be between 0 .. arraySize() - 1)
712 */
713 virtual vmfloat evalRealElement(vmuint i) = 0;
714
715 /**
716 * Changes the current value of an element (given by array element
717 * index @a i) of this real number array.
718 *
719 * @param i - array element index (must be between 0 .. arraySize() - 1)
720 * @param value - new real number value to be assigned to that array element
721 */
722 virtual void assignRealElement(vmuint i, vmfloat value) = 0;
723
724 /**
725 * Returns always REAL_ARR_EXPR for instances of this class.
726 */
727 ExprType_t exprType() const OVERRIDE { return REAL_ARR_EXPR; }
728 };
729
730 /** @brief Arguments (parameters) for being passed to a built-in script function.
731 *
732 * An argument or a set of arguments passed to a script function are
733 * translated by the parser to an instance of this class. This abstract
734 * interface class is used by implementations of built-in functions to
735 * obtain the individual function argument values being passed to them at
736 * runtime.
737 */
738 class VMFnArgs {
739 public:
740 /**
741 * Returns the amount of arguments going to be passed to the script
742 * function.
743 */
744 virtual vmint argsCount() const = 0;
745
746 /**
747 * Returns the respective argument (requested by argument index @a i) of
748 * this set of arguments. This method is called by implementations of
749 * built-in script functions to obtain the value of each function
750 * argument passed to the function at runtime.
751 *
752 * @param i - function argument index (indexed from left to right)
753 */
754 virtual VMExpr* arg(vmint i) = 0;
755 };
756
757 /** @brief Result value returned from a call to a built-in script function.
758 *
759 * Implementations of built-in script functions return an instance of this
760 * object to let the virtual machine obtain the result value of the function
761 * call, which might then be further processed by the virtual machine
762 * according to the script. It also provides informations about the success
763 * or failure of the function call.
764 */
765 class VMFnResult {
766 public:
767 /**
768 * Returns the result value of the function call, represented by a high
769 * level expression object.
770 */
771 virtual VMExpr* resultValue() = 0;
772
773 /**
774 * Provides detailed informations of the success / failure of the
775 * function call. The virtual machine is evaluating the flags returned
776 * here to decide whether it must abort or suspend execution of the
777 * script at this point.
778 */
779 virtual StmtFlags_t resultFlags() { return STMT_SUCCESS; }
780 };
781
782 /** @brief Virtual machine built-in function.
783 *
784 * Abstract base class for built-in script functions, defining the interface
785 * for all built-in script function implementations. All built-in script
786 * functions are deriving from this abstract interface class in order to
787 * provide their functionality to the virtual machine with this unified
788 * interface.
789 *
790 * The methods of this interface class provide two purposes:
791 *
792 * 1. When a script is loaded, the script parser uses the methods of this
793 * interface to check whether the script author was calling the
794 * respective built-in script function in a correct way. For example
795 * the parser checks whether the required amount of parameters were
796 * passed to the function and whether the data types passed match the
797 * data types expected by the function. If not, loading the script will
798 * be aborted with a parser error, describing to the user (i.e. script
799 * author) the precise misusage of the respective function.
800 * 2. After the script was loaded successfully and the script is executed,
801 * the virtual machine calls the exec() method of the respective built-in
802 * function to provide the actual functionality of the built-in function
803 * call.
804 */
805 class VMFunction {
806 public:
807 /**
808 * Script data type of the function's return value. If the function does
809 * not return any value (void), then it returns EMPTY_EXPR here.
810 *
811 * Some functions may have a different return type depending on the
812 * arguments to be passed to this function. That's what the @a args
813 * parameter is for, so that the method implementation can look ahead
814 * of what kind of parameters are going to be passed to the built-in
815 * function later on in order to decide which return value type would
816 * be used and returned by the function accordingly in that case.
817 *
818 * @param args - function arguments going to be passed for executing
819 * this built-in function later on
820 */
821 virtual ExprType_t returnType(VMFnArgs* args) = 0;
822
823 /**
824 * Standard measuring unit type of the function's result value
825 * (e.g. second, Hertz).
826 *
827 * Some functions may have a different standard measuring unit type for
828 * their return value depending on the arguments to be passed to this
829 * function. That's what the @a args parameter is for, so that the
830 * method implementation can look ahead of what kind of parameters are
831 * going to be passed to the built-in function later on in order to
832 * decide which return value type would be used and returned by the
833 * function accordingly in that case.
834 *
835 * @param args - function arguments going to be passed for executing
836 * this built-in function later on
837 * @see Unit for details about standard measuring units
838 */
839 virtual StdUnit_t returnUnitType(VMFnArgs* args) = 0;
840
841 /**
842 * Whether the result value returned by this built-in function is
843 * considered to be a 'final' value.
844 *
845 * Some functions may have a different 'final' feature for their return
846 * value depending on the arguments to be passed to this function.
847 * That's what the @a args parameter is for, so that the method
848 * implementation can look ahead of what kind of parameters are going to
849 * be passed to the built-in function later on in order to decide which
850 * return value type would be used and returned by the function
851 * accordingly in that case.
852 *
853 * @param args - function arguments going to be passed for executing
854 * this built-in function later on
855 * @see VMScalarNumberExpr::isFinal() for details about 'final' values
856 */
857 virtual bool returnsFinal(VMFnArgs* args) = 0;
858
859 /**
860 * Minimum amount of function arguments this function accepts. If a
861 * script is calling this function with less arguments, the script
862 * parser will throw a parser error.
863 */
864 virtual vmint minRequiredArgs() const = 0;
865
866 /**
867 * Maximum amount of function arguments this functions accepts. If a
868 * script is calling this function with more arguments, the script
869 * parser will throw a parser error.
870 */
871 virtual vmint maxAllowedArgs() const = 0;
872
873 /**
874 * Script data type of the function's @c iArg 'th function argument.
875 * The information provided here is less strong than acceptsArgType().
876 * The parser will compare argument data types provided in scripts by
877 * calling acceptsArgType(). The return value of argType() is used by the
878 * parser instead to show an appropriate parser error which data type
879 * this function usually expects as "default" data type. Reason: a
880 * function may accept multiple data types for a certain function
881 * argument and would automatically cast the passed argument value in
882 * that case to the type it actually needs.
883 *
884 * @param iArg - index of the function argument in question
885 * (must be between 0 .. maxAllowedArgs() - 1)
886 */
887 virtual ExprType_t argType(vmint iArg) const = 0;
888
889 /**
890 * This method is called by the parser to check whether arguments
891 * passed in scripts to this function are accepted by this function. If
892 * a script calls this function with an argument's data type not
893 * accepted by this function, the parser will throw a parser error. On
894 * such errors the data type returned by argType() will be used to
895 * assemble an appropriate error message regarding the precise misusage
896 * of the built-in function.
897 *
898 * @param iArg - index of the function argument in question
899 * (must be between 0 .. maxAllowedArgs() - 1)
900 * @param type - script data type used for this function argument by
901 * currently parsed script
902 * @return true if the given data type would be accepted for the
903 * respective function argument by the function
904 */
905 virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0;
906
907 /**
908 * This method is called by the parser to check whether arguments
909 * passed in scripts to this function are accepted by this function. If
910 * a script calls this function with an argument's measuremnt unit type
911 * not accepted by this function, the parser will throw a parser error.
912 *
913 * This default implementation of this method does not accept any
914 * measurement unit. Deriving subclasses would override this method
915 * implementation in case they do accept any measurement unit for its
916 * function arguments.
917 *
918 * @param iArg - index of the function argument in question
919 * (must be between 0 .. maxAllowedArgs() - 1)
920 * @param type - standard measurement unit data type used for this
921 * function argument by currently parsed script
922 * @return true if the given standard measurement unit type would be
923 * accepted for the respective function argument by the function
924 */
925 virtual bool acceptsArgUnitType(vmint iArg, StdUnit_t type) const;
926
927 /**
928 * This method is called by the parser to check whether arguments
929 * passed in scripts to this function are accepted by this function. If
930 * a script calls this function with a metric unit prefix and metric
931 * prefixes are not accepted for that argument by this function, then
932 * the parser will throw a parser error.
933 *
934 * This default implementation of this method does not accept any
935 * metric prefix. Deriving subclasses would override this method
936 * implementation in case they do accept any metric prefix for its
937 * function arguments.
938 *
939 * @param iArg - index of the function argument in question
940 * (must be between 0 .. maxAllowedArgs() - 1)
941 * @param type - standard measurement unit data type used for that
942 * function argument by currently parsed script
943 *
944 * @return true if a metric prefix would be accepted for the respective
945 * function argument by this function
946 *
947 * @see MetricPrefix_t
948 */
949 virtual bool acceptsArgUnitPrefix(vmint iArg, StdUnit_t type) const;
950
951 /**
952 * This method is called by the parser to check whether arguments
953 * passed in scripts to this function are accepted by this function. If
954 * a script calls this function with an argument that is declared to be
955 * a "final" value and this is not accepted by this function, the parser
956 * will throw a parser error.
957 *
958 * This default implementation of this method does not accept a "final"
959 * value. Deriving subclasses would override this method implementation
960 * in case they do accept a "final" value for its function arguments.
961 *
962 * @param iArg - index of the function argument in question
963 * (must be between 0 .. maxAllowedArgs() - 1)
964 * @return true if a "final" value would be accepted for the respective
965 * function argument by the function
966 *
967 * @see VMScalarNumberExpr::isFinal(), returnsFinal()
968 */
969 virtual bool acceptsArgFinal(vmint iArg) const;
970
971 /**
972 * This method is called by the parser to check whether some arguments
973 * (and if yes which ones) passed to this script function will be
974 * modified by this script function. Most script functions simply use
975 * their arguments as inputs, that is they only read the argument's
976 * values. However some script function may also use passed
977 * argument(s) as output variables. In this case the function
978 * implementation must return @c true for the respective argument
979 * index here.
980 *
981 * @param iArg - index of the function argument in question
982 * (must be between 0 .. maxAllowedArgs() - 1)
983 */
984 virtual bool modifiesArg(vmint iArg) const = 0;
985
986 /**
987 * This method is called by the parser to let the built-in function
988 * perform its own, individual parse time checks on the arguments to be
989 * passed to the built-in function. So this method is the place for
990 * implementing custom checks which are very specific to the individual
991 * built-in function's purpose and its individual requirements.
992 *
993 * For instance the built-in 'in_range()' function uses this method to
994 * check whether the last 2 of their 3 arguments are of same data type
995 * and if not it triggers a parser error. 'in_range()' also checks
996 * whether all of its 3 arguments do have the same standard measuring
997 * unit type and likewise raises a parser error if not.
998 *
999 * For less critical issues built-in functions may also raise parser
1000 * warnings instead.
1001 *
1002 * It is recommended that classes implementing (that is overriding) this
1003 * method should always call their super class's implementation of this
1004 * method to ensure their potential parse time checks are always
1005 * performed as well.
1006 *
1007 * @param args - function arguments going to be passed for executing
1008 * this built-in function later on
1009 * @param err - the parser's error handler to be called by this method
1010 * implementation to trigger a parser error with the
1011 * respective error message text
1012 * @param wrn - the parser's warning handler to be called by this method
1013 * implementation to trigger a parser warning with the
1014 * respective warning message text
1015 */
1016 virtual void checkArgs(VMFnArgs* args,
1017 std::function<void(String)> err,
1018 std::function<void(String)> wrn);
1019
1020 /**
1021 * Implements the actual function execution. This exec() method is
1022 * called by the VM whenever this function implementation shall be
1023 * executed at script runtime. This method blocks until the function
1024 * call completed.
1025 *
1026 * @param args - function arguments for executing this built-in function
1027 * @returns function's return value (if any) and general status
1028 * informations (i.e. whether the function call caused a
1029 * runtime error)
1030 */
1031 virtual VMFnResult* exec(VMFnArgs* args) = 0;
1032
1033 /**
1034 * Convenience method for function implementations to show warning
1035 * messages during actual execution of the built-in function.
1036 *
1037 * @param txt - runtime warning text to be shown to user
1038 */
1039 void wrnMsg(const String& txt);
1040
1041 /**
1042 * Convenience method for function implementations to show error
1043 * messages during actual execution of the built-in function.
1044 *
1045 * @param txt - runtime error text to be shown to user
1046 */
1047 void errMsg(const String& txt);
1048 };
1049
1050 /** @brief Virtual machine relative pointer.
1051 *
1052 * POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not
1053 * intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr,
1054 * VMInt8RelPtr instead.
1055 *
1056 * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr
1057 */
1058 struct VMRelPtr {
1059 void** base; ///< Base pointer.
1060 vmint offset; ///< Offset (in bytes) relative to base pointer.
1061 bool readonly; ///< Whether the pointed data may be modified or just be read.
1062 };
1063
1064 /** @brief Pointer to built-in VM integer variable (interface class).
1065 *
1066 * This class acts as an abstract interface to all built-in integer script
1067 * variables, independent of their actual native size (i.e. some built-in
1068 * script variables are internally using a native int size of 64 bit or 32
1069 * bit or 8 bit). The virtual machine is using this interface class instead
1070 * of its implementing descendants (VMInt64RelPtr, VMInt32RelPtr,
1071 * VMInt8RelPtr) in order for the virtual machine for not being required to
1072 * handle each of them differently.
1073 */
1074 struct VMIntPtr {
1075 virtual vmint evalInt() = 0;
1076 virtual void assign(vmint i) = 0;
1077 virtual bool isAssignable() const = 0;
1078 };
1079
1080 /** @brief Pointer to built-in VM integer variable (of C/C++ type int64_t).
1081 *
1082 * Used for defining built-in 64 bit integer script variables.
1083 *
1084 * @b CAUTION: You may only use this class for pointing to C/C++ variables
1085 * of type "int64_t" (thus being exactly 64 bit in size). If the C/C++ int
1086 * variable you want to reference is only 32 bit in size then you @b must
1087 * use VMInt32RelPtr instead! Respectively for a referenced native variable
1088 * with only 8 bit in size you @b must use VMInt8RelPtr instead!
1089 *
1090 * For efficiency reasons the actual native C/C++ int variable is referenced
1091 * by two components here. The actual native int C/C++ variable in memory
1092 * is dereferenced at VM run-time by taking the @c base pointer dereference
1093 * and adding @c offset bytes. This has the advantage that for a large
1094 * number of built-in int variables, only one (or few) base pointer need
1095 * to be re-assigned before running a script, instead of updating each
1096 * built-in variable each time before a script is executed.
1097 *
1098 * Refer to DECLARE_VMINT() for example code.
1099 *
1100 * @see VMInt32RelPtr, VMInt8RelPtr, DECLARE_VMINT()
1101 */
1102 struct VMInt64RelPtr : VMRelPtr, VMIntPtr {
1103 VMInt64RelPtr() {
1104 base = NULL;
1105 offset = 0;
1106 readonly = false;
1107 }
1108 VMInt64RelPtr(const VMRelPtr& data) {
1109 base = data.base;
1110 offset = data.offset;
1111 readonly = false;
1112 }
1113 vmint evalInt() OVERRIDE {
1114 return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset];
1115 }
1116 void assign(vmint i) OVERRIDE {
1117 *(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i;
1118 }
1119 bool isAssignable() const OVERRIDE { return !readonly; }
1120 };
1121
1122 /** @brief Pointer to built-in VM integer variable (of C/C++ type int32_t).
1123 *
1124 * Used for defining built-in 32 bit integer script variables.
1125 *
1126 * @b CAUTION: You may only use this class for pointing to C/C++ variables
1127 * of type "int32_t" (thus being exactly 32 bit in size). If the C/C++ int
1128 * variable you want to reference is 64 bit in size then you @b must use
1129 * VMInt64RelPtr instead! Respectively for a referenced native variable with
1130 * only 8 bit in size you @b must use VMInt8RelPtr instead!
1131 *
1132 * For efficiency reasons the actual native C/C++ int variable is referenced
1133 * by two components here. The actual native int C/C++ variable in memory
1134 * is dereferenced at VM run-time by taking the @c base pointer dereference
1135 * and adding @c offset bytes. This has the advantage that for a large
1136 * number of built-in int variables, only one (or few) base pointer need
1137 * to be re-assigned before running a script, instead of updating each
1138 * built-in variable each time before a script is executed.
1139 *
1140 * Refer to DECLARE_VMINT() for example code.
1141 *
1142 * @see VMInt64RelPtr, VMInt8RelPtr, DECLARE_VMINT()
1143 */
1144 struct VMInt32RelPtr : VMRelPtr, VMIntPtr {
1145 VMInt32RelPtr() {
1146 base = NULL;
1147 offset = 0;
1148 readonly = false;
1149 }
1150 VMInt32RelPtr(const VMRelPtr& data) {
1151 base = data.base;
1152 offset = data.offset;
1153 readonly = false;
1154 }
1155 vmint evalInt() OVERRIDE {
1156 return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset];
1157 }
1158 void assign(vmint i) OVERRIDE {
1159 *(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i;
1160 }
1161 bool isAssignable() const OVERRIDE { return !readonly; }
1162 };
1163
1164 /** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t).
1165 *
1166 * Used for defining built-in 8 bit integer script variables.
1167 *
1168 * @b CAUTION: You may only use this class for pointing to C/C++ variables
1169 * of type "int8_t" (8 bit integer). If the C/C++ int variable you want to
1170 * reference is not exactly 8 bit in size then you @b must respectively use
1171 * either VMInt32RelPtr for native 32 bit variables or VMInt64RelPtrl for
1172 * native 64 bit variables instead!
1173 *
1174 * For efficiency reasons the actual native C/C++ int variable is referenced
1175 * by two components here. The actual native int C/C++ variable in memory
1176 * is dereferenced at VM run-time by taking the @c base pointer dereference
1177 * and adding @c offset bytes. This has the advantage that for a large
1178 * number of built-in int variables, only one (or few) base pointer need
1179 * to be re-assigned before running a script, instead of updating each
1180 * built-in variable each time before a script is executed.
1181 *
1182 * Refer to DECLARE_VMINT() for example code.
1183 *
1184 * @see VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT()
1185 */
1186 struct VMInt8RelPtr : VMRelPtr, VMIntPtr {
1187 VMInt8RelPtr() {
1188 base = NULL;
1189 offset = 0;
1190 readonly = false;
1191 }
1192 VMInt8RelPtr(const VMRelPtr& data) {
1193 base = data.base;
1194 offset = data.offset;
1195 readonly = false;
1196 }
1197 vmint evalInt() OVERRIDE {
1198 return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset];
1199 }
1200 void assign(vmint i) OVERRIDE {
1201 *(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i;
1202 }
1203 bool isAssignable() const OVERRIDE { return !readonly; }
1204 };
1205
1206 /** @brief Pointer to built-in VM integer variable (of C/C++ type vmint).
1207 *
1208 * Use this typedef if the native variable to be pointed to is using the
1209 * typedef vmint. If the native C/C++ variable to be pointed to is using
1210 * another C/C++ type then better use one of VMInt64RelPtr or VMInt32RelPtr
1211 * instead.
1212 */
1213 typedef VMInt64RelPtr VMIntRelPtr;
1214
1215 #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
1216 # define COMPILER_DISABLE_OFFSETOF_WARNING \
1217 _Pragma("GCC diagnostic push") \
1218 _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"")
1219 # define COMPILER_RESTORE_OFFSETOF_WARNING \
1220 _Pragma("GCC diagnostic pop")
1221 #else
1222 # define COMPILER_DISABLE_OFFSETOF_WARNING
1223 # define COMPILER_RESTORE_OFFSETOF_WARNING
1224 #endif
1225
1226 /**
1227 * Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr and
1228 * VMInt8RelPtr structures. Usage example:
1229 * @code
1230 * struct Foo {
1231 * uint8_t a; // native representation of a built-in integer script variable
1232 * int64_t b; // native representation of another built-in integer script variable
1233 * int64_t c; // native representation of another built-in integer script variable
1234 * uint8_t d; // native representation of another built-in integer script variable
1235 * };
1236 *
1237 * // initializing the built-in script variables to some values
1238 * Foo foo1 = (Foo) { 1, 2000, 3000, 4 };
1239 * Foo foo2 = (Foo) { 5, 6000, 7000, 8 };
1240 *
1241 * Foo* pFoo;
1242 *
1243 * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);
1244 * VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b);
1245 * VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c);
1246 * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);
1247 *
1248 * pFoo = &foo1;
1249 * printf("%d\n", varA->evalInt()); // will print 1
1250 * printf("%d\n", varB->evalInt()); // will print 2000
1251 * printf("%d\n", varC->evalInt()); // will print 3000
1252 * printf("%d\n", varD->evalInt()); // will print 4
1253 *
1254 * // same printf() code, just with pFoo pointer being changed ...
1255 *
1256 * pFoo = &foo2;
1257 * printf("%d\n", varA->evalInt()); // will print 5
1258 * printf("%d\n", varB->evalInt()); // will print 6000
1259 * printf("%d\n", varC->evalInt()); // will print 7000
1260 * printf("%d\n", varD->evalInt()); // will print 8
1261 * @endcode
1262 * As you can see above, by simply changing one single pointer, you can
1263 * remap a huge bunch of built-in integer script variables to completely
1264 * different native values/native variables. Which especially reduces code
1265 * complexity inside the sampler engines which provide the actual script
1266 * functionalities.
1267 */
1268 #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \
1269 /* Disable offsetof warning, trust us, we are cautios. */ \
1270 COMPILER_DISABLE_OFFSETOF_WARNING \
1271 (VMRelPtr) { \
1272 (void**) &basePtr, \
1273 offsetof(T_struct, T_member), \
1274 false \
1275 } \
1276 COMPILER_RESTORE_OFFSETOF_WARNING \
1277 ) \
1278
1279 /**
1280 * Same as DECLARE_VMINT(), but this one defines the VMInt64RelPtr,
1281 * VMInt32RelPtr and VMInt8RelPtr structures to be of read-only type.
1282 * That means the script parser will abort any script at parser time if the
1283 * script is trying to modify such a read-only built-in variable.
1284 *
1285 * @b NOTE: this is only intended for built-in read-only variables that
1286 * may change during runtime! If your built-in variable's data is rather
1287 * already available at parser time and won't change during runtime, then
1288 * you should rather register a built-in constant in your VM class instead!
1289 *
1290 * @see ScriptVM::builtInConstIntVariables()
1291 */
1292 #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
1293 /* Disable offsetof warning, trust us, we are cautios. */ \
1294 COMPILER_DISABLE_OFFSETOF_WARNING \
1295 (VMRelPtr) { \
1296 (void**) &basePtr, \
1297 offsetof(T_struct, T_member), \
1298 true \
1299 } \
1300 COMPILER_RESTORE_OFFSETOF_WARNING \
1301 ) \
1302
1303 /** @brief Built-in VM 8 bit integer array variable.
1304 *
1305 * Used for defining built-in integer array script variables (8 bit per
1306 * array element). Currently there is no support for any other kind of
1307 * built-in array type. So all built-in integer arrays accessed by scripts
1308 * use 8 bit data types.
1309 */
1310 struct VMInt8Array {
1311 int8_t* data;
1312 vmint size;
1313 bool readonly; ///< Whether the array data may be modified or just be read.
1314
1315 VMInt8Array() : data(NULL), size(0), readonly(false) {}
1316 };
1317
1318 /** @brief Virtual machine script variable.
1319 *
1320 * Common interface for all variables accessed in scripts, independent of
1321 * their precise data type.
1322 */
1323 class VMVariable : virtual public VMExpr {
1324 public:
1325 /**
1326 * Whether a script may modify the content of this variable by
1327 * assigning a new value to it.
1328 *
1329 * @see isConstExpr(), assign()
1330 */
1331 virtual bool isAssignable() const = 0;
1332
1333 /**
1334 * In case this variable is assignable, this method will be called to
1335 * perform the value assignment to this variable with @a expr
1336 * reflecting the new value to be assigned.
1337 *
1338 * @param expr - new value to be assigned to this variable
1339 */
1340 virtual void assignExpr(VMExpr* expr) = 0;
1341 };
1342
1343 /** @brief Dynamically executed variable (abstract base class).
1344 *
1345 * Interface for the implementation of a dynamically generated content of
1346 * a built-in script variable. Most built-in variables are simply pointers
1347 * to some native location in memory. So when a script reads them, the
1348 * memory location is simply read to get the value of the variable. A
1349 * dynamic variable however is not simply a memory location. For each access
1350 * to a dynamic variable some native code is executed to actually generate
1351 * and provide the content (value) of this type of variable.
1352 */
1353 class VMDynVar : public VMVariable {
1354 public:
1355 /**
1356 * Returns true in case this dynamic variable can be considered to be a
1357 * constant expression. A constant expression will retain the same value
1358 * throughout the entire life time of a script and the expression's
1359 * constant value may be evaluated already at script parse time, which
1360 * may result in performance benefits during script runtime.
1361 *
1362 * However due to the "dynamic" behavior of dynamic variables, almost
1363 * all dynamic variables are probably not constant expressions. That's
1364 * why this method returns @c false by default. If you are really sure
1365 * that your dynamic variable implementation can be considered a
1366 * constant expression then you may override this method and return
1367 * @c true instead. Note that when you return @c true here, your
1368 * dynamic variable will really just be executed once; and exectly
1369 * already when the script is loaded!
1370 *
1371 * As an example you may implement a "constant" built-in dynamic
1372 * variable that checks for a certain operating system feature and
1373 * returns the result of that OS feature check as content (value) of
1374 * this dynamic variable. Since the respective OS feature might become
1375 * available/unavailable after OS updates, software migration, etc. the
1376 * OS feature check should at least be performed once each time the
1377 * application is launched. And since the OS feature check might take a
1378 * certain amount of execution time, it might make sense to only
1379 * perform the check if the respective variable name is actually
1380 * referenced at all in the script to be loaded. Note that the dynamic
1381 * variable will still be evaluated again though if the script is
1382 * loaded again. So it is up to you to probably cache the result in the
1383 * implementation of your dynamic variable.
1384 *
1385 * On doubt, please rather consider to use a constant built-in script
1386 * variable instead of implementing a "constant" dynamic variable, due
1387 * to the runtime overhead a dynamic variable may cause.
1388 *
1389 * @see isAssignable()
1390 */
1391 bool isConstExpr() const OVERRIDE { return false; }
1392
1393 /**
1394 * In case this dynamic variable is assignable, the new value (content)
1395 * to be assigned to this dynamic variable.
1396 *
1397 * By default this method does nothing. Override and implement this
1398 * method in your subclass in case your dynamic variable allows to
1399 * assign a new value by script.
1400 *
1401 * @param expr - new value to be assigned to this variable
1402 */
1403 void assignExpr(VMExpr* expr) OVERRIDE {}
1404
1405 virtual ~VMDynVar() {}
1406 };
1407
1408 /** @brief Dynamically executed variable (of integer data type).
1409 *
1410 * This is the base class for all built-in integer script variables whose
1411 * variable content needs to be provided dynamically by executable native
1412 * code on each script variable access.
1413 */
1414 class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
1415 public:
1416 vmfloat unitFactor() const OVERRIDE { return VM_NO_FACTOR; }
1417 StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; }
1418 bool isFinal() const OVERRIDE { return false; }
1419 };
1420
1421 /** @brief Dynamically executed variable (of string data type).
1422 *
1423 * This is the base class for all built-in string script variables whose
1424 * variable content needs to be provided dynamically by executable native
1425 * code on each script variable access.
1426 */
1427 class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
1428 public:
1429 };
1430
1431 /** @brief Dynamically executed variable (of integer array data type).
1432 *
1433 * This is the base class for all built-in integer array script variables
1434 * whose variable content needs to be provided dynamically by executable
1435 * native code on each script variable access.
1436 */
1437 class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr {
1438 public:
1439 };
1440
1441 /** @brief Provider for built-in script functions and variables.
1442 *
1443 * Abstract base class defining the high-level interface for all classes
1444 * which add and implement built-in script functions and built-in script
1445 * variables.
1446 */
1447 class VMFunctionProvider {
1448 public:
1449 /**
1450 * Returns pointer to the built-in function with the given function
1451 * @a name, or NULL if there is no built-in function with that function
1452 * name.
1453 *
1454 * @param name - function name (i.e. "wait" or "message" or "exit", etc.)
1455 */
1456 virtual VMFunction* functionByName(const String& name) = 0;
1457
1458 /**
1459 * Returns @c true if the passed built-in function is disabled and
1460 * should be ignored by the parser. This method is called by the
1461 * parser on preprocessor level for each built-in function call within
1462 * a script. Accordingly if this method returns @c true, then the
1463 * respective function call is completely filtered out on preprocessor
1464 * level, so that built-in function won't make into the result virtual
1465 * machine representation, nor would expressions of arguments passed to
1466 * that built-in function call be evaluated, nor would any check
1467 * regarding correct usage of the built-in function be performed.
1468 * In other words: a disabled function call ends up as a comment block.
1469 *
1470 * @param fn - built-in function to be checked
1471 * @param ctx - parser context at the position where the built-in
1472 * function call is located within the script
1473 */
1474 virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0;
1475
1476 /**
1477 * Returns a variable name indexed map of all built-in script variables
1478 * which point to native "int" scalar (usually 32 bit) variables.
1479 */
1480 virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0;
1481
1482 /**
1483 * Returns a variable name indexed map of all built-in script integer
1484 * array variables with array element type "int8_t" (8 bit).
1485 */
1486 virtual std::map<String,VMInt8Array*> builtInIntArrayVariables() = 0;
1487
1488 /**
1489 * Returns a variable name indexed map of all built-in constant script
1490 * variables, which never change their value at runtime.
1491 */
1492 virtual std::map<String,vmint> builtInConstIntVariables() = 0;
1493
1494 /**
1495 * Returns a variable name indexed map of all built-in dynamic variables,
1496 * which are not simply data stores, rather each one of them executes
1497 * natively to provide or alter the respective script variable data.
1498 */
1499 virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
1500 };
1501
1502 /** @brief Execution state of a virtual machine.
1503 *
1504 * An instance of this abstract base class represents exactly one execution
1505 * state of a virtual machine. This encompasses most notably the VM
1506 * execution stack, and VM polyphonic variables. It does not contain global
1507 * variables. Global variables are contained in the VMParserContext object.
1508 * You might see a VMExecContext object as one virtual thread of the virtual
1509 * machine.
1510 *
1511 * In contrast to a VMParserContext, a VMExecContext is not tied to a
1512 * ScriptVM instance. Thus you can use a VMExecContext with different
1513 * ScriptVM instances, however not concurrently at the same time.
1514 *
1515 * @see VMParserContext
1516 */
1517 class VMExecContext {
1518 public:
1519 virtual ~VMExecContext() {}
1520
1521 /**
1522 * In case the script was suspended for some reason, this method returns
1523 * the amount of microseconds before the script shall continue its
1524 * execution. Note that the virtual machine itself does never put its
1525 * own execution thread(s) to sleep. So the respective class (i.e. sampler
1526 * engine) which is using the virtual machine classes here, must take
1527 * care by itself about taking time stamps, determining the script
1528 * handlers that shall be put aside for the requested amount of
1529 * microseconds, indicated by this method by comparing the time stamps in
1530 * real-time, and to continue passing the respective handler to
1531 * ScriptVM::exec() as soon as its suspension exceeded, etc. Or in other
1532 * words: all classes in this directory never have an idea what time it
1533 * is.
1534 *
1535 * You should check the return value of ScriptVM::exec() to determine
1536 * whether the script was actually suspended before calling this method
1537 * here.
1538 *
1539 * @see ScriptVM::exec()
1540 */
1541 virtual vmint suspensionTimeMicroseconds() const = 0;
1542
1543 /**
1544 * Causes all polyphonic variables to be reset to zero values. A
1545 * polyphonic variable is expected to be zero when entering a new event
1546 * handler instance. As an exception the values of polyphonic variables
1547 * shall only be preserved from an note event handler instance to its
1548 * correspending specific release handler instance. So in the latter
1549 * case the script author may pass custom data from the note handler to
1550 * the release handler, but only for the same specific note!
1551 */
1552 virtual void resetPolyphonicData() = 0;
1553
1554 /**
1555 * Returns amount of virtual machine instructions which have been
1556 * performed the last time when this execution context was executing a
1557 * script. So in case you need the overall amount of instructions
1558 * instead, then you need to add them by yourself after each
1559 * ScriptVM::exec() call.
1560 */
1561 virtual size_t instructionsPerformed() const = 0;
1562
1563 /**
1564 * Sends a signal to this script execution instance to abort its script
1565 * execution as soon as possible. This method is called i.e. when one
1566 * script execution instance intends to stop another script execution
1567 * instance.
1568 */
1569 virtual void signalAbort() = 0;
1570
1571 /**
1572 * Copies the current entire execution state from this object to the
1573 * given object. So this can be used to "fork" a new script thread which
1574 * then may run independently with its own polyphonic data for instance.
1575 */
1576 virtual void forkTo(VMExecContext* ectx) const = 0;
1577
1578 /**
1579 * In case the script called the built-in exit() function and passed a
1580 * value as argument to the exit() function, then this method returns
1581 * the value that had been passed as argument to the exit() function.
1582 * Otherwise if the exit() function has not been called by the script
1583 * or no argument had been passed to the exit() function, then this
1584 * method returns NULL instead.
1585 *
1586 * Currently this is only used for automated test cases against the
1587 * script engine, which return some kind of value in the individual
1588 * test case scripts to check their behaviour in automated way. There
1589 * is no purpose for this mechanism in production use. Accordingly this
1590 * exit result value is @b always completely ignored by the sampler
1591 * engines.
1592 *
1593 * Officially the built-in exit() function does not expect any arguments
1594 * to be passed to its function call, and by default this feature is
1595 * hence disabled and will yield in a parser error unless
1596 * ScriptVM::setExitResultEnabled() was explicitly set.
1597 *
1598 * @see ScriptVM::setExitResultEnabled()
1599 */
1600 virtual VMExpr* exitResult() = 0;
1601 };
1602
1603 /** @brief Script callback for a certain event.
1604 *
1605 * Represents a script callback for a certain event, i.e.
1606 * "on note ... end on" code block.
1607 */
1608 class VMEventHandler {
1609 public:
1610 /**
1611 * Type of this event handler, which identifies its purpose. For example
1612 * for a "on note ... end on" script callback block,
1613 * @c VM_EVENT_HANDLER_NOTE would be returned here.
1614 */
1615 virtual VMEventHandlerType_t eventHandlerType() const = 0;
1616
1617 /**
1618 * Name of the event handler which identifies its purpose. For example
1619 * for a "on note ... end on" script callback block, the name "note"
1620 * would be returned here.
1621 */
1622 virtual String eventHandlerName() const = 0;
1623
1624 /**
1625 * Whether or not the event handler makes any use of so called
1626 * "polyphonic" variables.
1627 */
1628 virtual bool isPolyphonic() const = 0;
1629 };
1630
1631 /**
1632 * Reflects the precise position and span of a specific code block within
1633 * a script. This is currently only used for the locations of commented
1634 * code blocks due to preprocessor statements, and for parser errors and
1635 * parser warnings.
1636 *
1637 * @see ParserIssue for code locations of parser errors and parser warnings
1638 *
1639 * @see VMParserContext::preprocessorComments() for locations of code which
1640 * have been filtered out by preprocessor statements
1641 */
1642 struct CodeBlock {
1643 int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
1644 int lastLine; ///< The last line number of this code block within the script.
1645 int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
1646 int lastColumn; ///< The last column of this code block within the script.
1647 };
1648
1649 /**
1650 * Encapsulates a noteworty parser issue. This encompasses the type of the
1651 * issue (either a parser error or parser warning), a human readable
1652 * explanation text of the error or warning and the location of the
1653 * encountered parser issue within the script.
1654 *
1655 * @see VMSourceToken for processing syntax highlighting instead.
1656 */
1657 struct ParserIssue : CodeBlock {
1658 String txt; ///< Human readable explanation text of the parser issue.
1659 ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning.
1660
1661 /**
1662 * Print this issue out to the console (stdio).
1663 */
1664 inline void dump() {
1665 switch (type) {
1666 case PARSER_ERROR:
1667 printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
1668 break;
1669 case PARSER_WARNING:
1670 printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
1671 break;
1672 }
1673 }
1674
1675 /**
1676 * Returns true if this issue is a parser error. In this case the parsed
1677 * script may not be executed!
1678 */
1679 inline bool isErr() const { return type == PARSER_ERROR; }
1680
1681 /**
1682 * Returns true if this issue is just a parser warning. A parsed script
1683 * that only raises warnings may be executed if desired, however the
1684 * script may not behave exactly as intended by the script author.
1685 */
1686 inline bool isWrn() const { return type == PARSER_WARNING; }
1687 };
1688
1689 /**
1690 * Convenience function used for converting an ExprType_t constant to a
1691 * string, i.e. for generating error message by the parser.
1692 */
1693 inline String typeStr(const ExprType_t& type) {
1694 switch (type) {
1695 case EMPTY_EXPR: return "empty";
1696 case INT_EXPR: return "integer";
1697 case INT_ARR_EXPR: return "integer array";
1698 case REAL_EXPR: return "real number";
1699 case REAL_ARR_EXPR: return "real number array";
1700 case STRING_EXPR: return "string";
1701 case STRING_ARR_EXPR: return "string array";
1702 }
1703 return "invalid";
1704 }
1705
1706 /**
1707 * Convenience function used for retrieving the data type of a script
1708 * variable name being passed to this function.
1709 *
1710 * @param name - some script variable name (e.g. "$foo")
1711 * @return variable's data type (e.g. INT_EXPR for example above)
1712 */
1713 inline ExprType_t exprTypeOfVarName(const String& name) {
1714 if (name.empty()) return (ExprType_t) -1;
1715 const char prefix = name[0];
1716 switch (prefix) {
1717 case '$': return INT_EXPR;
1718 case '%': return INT_ARR_EXPR;
1719 case '~': return REAL_EXPR;
1720 case '?': return REAL_ARR_EXPR;
1721 case '@': return STRING_EXPR;
1722 case '!': return STRING_ARR_EXPR;
1723 }
1724 return (ExprType_t) -1;
1725 }
1726
1727 /**
1728 * Returns @c true in case the passed data type is some array data type.
1729 */
1730 inline bool isArray(const ExprType_t& type) {
1731 return type == INT_ARR_EXPR || type == REAL_ARR_EXPR ||
1732 type == STRING_ARR_EXPR;
1733 }
1734
1735 /**
1736 * Returns @c true in case the passed data type is some scalar number type
1737 * (i.e. not an array and not a string).
1738 */
1739 inline bool isScalarNumber(const ExprType_t& type) {
1740 return type == INT_EXPR || type == REAL_EXPR;
1741 }
1742
1743 /**
1744 * Convenience function used for converting an StdUnit_t constant to a
1745 * string, i.e. for generating error message by the parser.
1746 */
1747 inline String unitTypeStr(const StdUnit_t& type) {
1748 switch (type) {
1749 case VM_NO_UNIT: return "none";
1750 case VM_SECOND: return "seconds";
1751 case VM_HERTZ: return "Hz";
1752 case VM_BEL: return "Bel";
1753 }
1754 return "invalid";
1755 }
1756
1757 /** @brief Virtual machine representation of a script.
1758 *
1759 * An instance of this abstract base class represents a parsed script,
1760 * translated into a virtual machine tree. You should first check if there
1761 * were any parser errors. If there were any parser errors, you should
1762 * refrain from executing the virtual machine. Otherwise if there were no
1763 * parser errors (i.e. only warnings), then you might access one of the
1764 * script's event handlers by i.e. calling eventHandlerByName() and pass the
1765 * respective event handler to the ScriptVM class (or to one of the ScriptVM
1766 * descendants) for execution.
1767 *
1768 * @see VMExecContext, ScriptVM
1769 */
1770 class VMParserContext {
1771 public:
1772 virtual ~VMParserContext() {}
1773
1774 /**
1775 * Returns all noteworthy issues encountered when the script was parsed.
1776 * These are parser errors and parser warnings.
1777 */
1778 virtual std::vector<ParserIssue> issues() const = 0;
1779
1780 /**
1781 * Same as issues(), but this method only returns parser errors.
1782 */
1783 virtual std::vector<ParserIssue> errors() const = 0;
1784
1785 /**
1786 * Same as issues(), but this method only returns parser warnings.
1787 */
1788 virtual std::vector<ParserIssue> warnings() const = 0;
1789
1790 /**
1791 * Returns all code blocks of the script which were filtered out by the
1792 * preprocessor.
1793 */
1794 virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1795
1796 /**
1797 * Returns the translated virtual machine representation of an event
1798 * handler block (i.e. "on note ... end on" code block) within the
1799 * parsed script. This translated representation of the event handler
1800 * can be executed by the virtual machine.
1801 *
1802 * @param index - index of the event handler within the script
1803 */
1804 virtual VMEventHandler* eventHandler(uint index) = 0;
1805
1806 /**
1807 * Same as eventHandler(), but this method returns the event handler by
1808 * its name. So for a "on note ... end on" code block of the parsed
1809 * script you would pass "note" for argument @a name here.
1810 *
1811 * @param name - name of the event handler (i.e. "init", "note",
1812 * "controller", "release")
1813 */
1814 virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
1815 };
1816
1817 class SourceToken;
1818
1819 /** @brief Recognized token of a script's source code.
1820 *
1821 * Represents one recognized token of a script's source code, for example
1822 * a keyword, variable name, etc. and it provides further informations about
1823 * that particular token, i.e. the precise location (line and column) of the
1824 * token within the original script's source code.
1825 *
1826 * This class is not actually used by the sampler itself. It is rather
1827 * provided for external script editor applications. Primary purpose of
1828 * this class is syntax highlighting for external script editors.
1829 *
1830 * @see ParserIssue for processing compile errors and warnings instead.
1831 */
1832 class VMSourceToken {
1833 public:
1834 VMSourceToken();
1835 VMSourceToken(SourceToken* ct);
1836 VMSourceToken(const VMSourceToken& other);
1837 virtual ~VMSourceToken();
1838
1839 // original text of this token as it is in the script's source code
1840 String text() const;
1841
1842 // position of token in script
1843 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.
1844 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().
1845
1846 // base types
1847 bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1848 bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1849 bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1850 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.
1851 bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1852 bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1853 bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1854 bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1855 bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1856 bool isMetricPrefix() const;
1857 bool isStdUnit() const;
1858 bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1859
1860 // extended types
1861 bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1862 bool isRealVariable() const; ///< Returns true in case this source token represents a floating point variable name (i.e. "~someRealVariable").
1863 bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1864 bool isIntArrayVariable() const; ///< Returns true in case this source token represents an integer array variable name (i.e. "%someArrayVariable").
1865 bool isRealArrayVariable() const; ///< Returns true in case this source token represents a real number array variable name (i.e. "?someArrayVariable").
1866 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.
1867 bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1868
1869 VMSourceToken& operator=(const VMSourceToken& other);
1870
1871 private:
1872 SourceToken* m_token;
1873 };
1874
1875 } // namespace LinuxSampler
1876
1877 #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H

  ViewVC Help
Powered by ViewVC