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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3583 - (hide annotations) (download) (as text)
Fri Aug 30 12:39:18 2019 UTC (2 years ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 86662 byte(s)
Moved function exprTypeOfVarName() from public API file common.h to
implementation internal file tree.h (since this function is only
intended to be called by the generated NKSP parser).

1 schoenebeck 2581 /*
2 schoenebeck 3551 * Copyright (c) 2014-2019 Christian Schoenebeck
3 schoenebeck 2581 *
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 schoenebeck 3292 // (located at other source directories). It also acts as public API of the
13     // Real-Time script engine for other applications.
14 schoenebeck 2581
15     #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H
16     #define LS_INSTR_SCRIPT_PARSER_COMMON_H
17    
18     #include "../common/global.h"
19 schoenebeck 2588 #include <vector>
20 schoenebeck 2594 #include <map>
21     #include <stddef.h> // offsetof()
22 schoenebeck 3581 #include <functional> // std::function<>
23 schoenebeck 2581
24     namespace LinuxSampler {
25 schoenebeck 2727
26     /**
27 schoenebeck 3557 * 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 schoenebeck 3573 * 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 schoenebeck 3561 */
45     typedef float vmfloat;
46    
47     /**
48 schoenebeck 2727 * Identifies the type of a noteworthy issue identified by the script
49     * parser. That's either a parser error or parser warning.
50     */
51 schoenebeck 2581 enum ParserIssueType_t {
52 schoenebeck 2727 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 schoenebeck 2581 };
55    
56 schoenebeck 2727 /** @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 schoenebeck 2581 enum ExprType_t {
64 schoenebeck 2727 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 schoenebeck 3573 REAL_EXPR, ///< floating point (scalar) expression
70     REAL_ARR_EXPR, ///< floating point array expression
71 schoenebeck 2581 };
72    
73 schoenebeck 2727 /** @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 schoenebeck 2581 enum StmtFlags_t {
84     STMT_SUCCESS = 0, ///< Function / statement was executed successfully, no error occurred.
85 schoenebeck 2727 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 schoenebeck 2581 };
89    
90 schoenebeck 2727 /** @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 schoenebeck 2581 enum VMExecStatus_t {
98 schoenebeck 2727 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 schoenebeck 2581 };
103    
104 schoenebeck 2879 /** @brief Script event handler type.
105     *
106     * Identifies one of the possible event handler callback types defined by
107     * the NKSP script language.
108 schoenebeck 3557 *
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 schoenebeck 2879 */
118 schoenebeck 3557 enum VMEventHandlerType_t : int32_t {
119 schoenebeck 2879 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 schoenebeck 3561 /**
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 schoenebeck 3581 * 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 schoenebeck 3561 * 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 schoenebeck 3581 //TODO: see Unit::hasUnitFactorEver()
166     enum EverTriState_t {
167     VM_NEVER = 0,
168     VM_MAYBE,
169     VM_ALWAYS,
170     };
171    
172 schoenebeck 2727 // just symbol prototyping
173 schoenebeck 2596 class VMIntExpr;
174 schoenebeck 3573 class VMRealExpr;
175 schoenebeck 2596 class VMStringExpr;
176 schoenebeck 3582 class VMNumberExpr;
177 schoenebeck 3581 class VMArrayExpr;
178 schoenebeck 2619 class VMIntArrayExpr;
179 schoenebeck 3573 class VMRealArrayExpr;
180 schoenebeck 2619 class VMStringArrayExpr;
181 schoenebeck 3311 class VMParserContext;
182 schoenebeck 2596
183 schoenebeck 3581 /** @brief Virtual machine standard measuring unit.
184 schoenebeck 3561 *
185     * Abstract base class representing standard measurement units throughout
186 schoenebeck 3581 * 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 schoenebeck 3561 *
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 schoenebeck 3581 * 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 schoenebeck 3561 */
209     class VMUnit {
210     public:
211     /**
212 schoenebeck 3581 * 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 schoenebeck 3561 *
218 schoenebeck 3581 * 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 schoenebeck 3561 *
224 schoenebeck 3581 * 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 schoenebeck 3561 */
233 schoenebeck 3581 virtual vmfloat unitFactor() const = 0;
234 schoenebeck 3561
235 schoenebeck 3581 //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 schoenebeck 3561 /**
239 schoenebeck 3581 * Whether this unit currently does have any metric unit prefix.
240 schoenebeck 3561 *
241 schoenebeck 3581 * 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 schoenebeck 3561 */
247 schoenebeck 3581 bool hasUnitFactorNow() const;
248 schoenebeck 3561
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 schoenebeck 3581 * 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 schoenebeck 3561 */
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 schoenebeck 3581 *
271     * @returns scale factor of given metric unit prefixes
272 schoenebeck 3561 */
273     static vmfloat unitFactor(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
274 schoenebeck 3581
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 schoenebeck 3561 };
286    
287 schoenebeck 2727 /** @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 schoenebeck 2581 class VMExpr {
301     public:
302 schoenebeck 2727 /**
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 schoenebeck 2581 virtual ExprType_t exprType() const = 0;
308 schoenebeck 2727
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 schoenebeck 3573 * return NULL! Same applies if this expression is actually a real
319     * number expression: asInt() would return NULL in that case as well.
320 schoenebeck 2727 *
321 schoenebeck 3582 * @see exprType(), asReal(), asNumber()
322 schoenebeck 2727 */
323 schoenebeck 2596 VMIntExpr* asInt() const;
324 schoenebeck 2727
325     /**
326 schoenebeck 3573 * 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 schoenebeck 3582 * @see exprType(), asInt(), asNumber()
338 schoenebeck 3573 */
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 schoenebeck 3582 * VMNumberExpr base class object. It returns NULL if this
346 schoenebeck 3573 * 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 schoenebeck 3582 VMNumberExpr* asNumber() const;
360 schoenebeck 3573
361     /**
362 schoenebeck 2727 * 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 schoenebeck 2596 VMStringExpr* asString() const;
375 schoenebeck 2727
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 schoenebeck 3573 * 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 schoenebeck 2727 *
387 schoenebeck 3056 * @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 schoenebeck 2727 * @see exprType()
396     */
397 schoenebeck 3056 virtual VMIntArrayExpr* asIntArray() const;
398 schoenebeck 2945
399     /**
400 schoenebeck 3573 * 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 schoenebeck 3581 * 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 schoenebeck 2945 * 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 schoenebeck 2960 *
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 schoenebeck 2945 */
454     virtual bool isConstExpr() const = 0;
455    
456 schoenebeck 2960 /**
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 schoenebeck 2945 bool isModifyable() const;
469 schoenebeck 2581 };
470    
471 schoenebeck 3573 /** @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 schoenebeck 3582 class VMNumberExpr : virtual public VMExpr, virtual public VMUnit {
477 schoenebeck 3573 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 schoenebeck 3581
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 schoenebeck 3573 };
524    
525 schoenebeck 2727 /** @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 schoenebeck 3582 class VMIntExpr : virtual public VMNumberExpr {
533 schoenebeck 2581 public:
534 schoenebeck 2727 /**
535     * Returns the result of this expression as integer (scalar) value.
536     * This abstract method must be implemented by deriving classes.
537     */
538 schoenebeck 3557 virtual vmint evalInt() = 0;
539 schoenebeck 2727
540     /**
541 schoenebeck 3561 * 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 schoenebeck 2727 * Returns always INT_EXPR for instances of this class.
559     */
560     ExprType_t exprType() const OVERRIDE { return INT_EXPR; }
561 schoenebeck 3573 };
562 schoenebeck 3561
563 schoenebeck 3573 /** @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 schoenebeck 3582 class VMRealExpr : virtual public VMNumberExpr {
571 schoenebeck 3573 public:
572 schoenebeck 3561 /**
573 schoenebeck 3573 * 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 schoenebeck 3561 *
586 schoenebeck 3573 * @param prefix - default measurement unit prefix expected by caller
587 schoenebeck 3561 */
588 schoenebeck 3573 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 schoenebeck 2581 };
602    
603 schoenebeck 2727 /** @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 schoenebeck 2581 class VMStringExpr : virtual public VMExpr {
611     public:
612 schoenebeck 2727 /**
613     * Returns the result of this expression as string value. This abstract
614     * method must be implemented by deriving classes.
615     */
616 schoenebeck 2581 virtual String evalStr() = 0;
617 schoenebeck 2727
618     /**
619     * Returns always STRING_EXPR for instances of this class.
620     */
621     ExprType_t exprType() const OVERRIDE { return STRING_EXPR; }
622 schoenebeck 2581 };
623    
624 schoenebeck 2727 /** @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 schoenebeck 2619 class VMArrayExpr : virtual public VMExpr {
632     public:
633 schoenebeck 2727 /**
634     * Returns amount of elements in this array. This abstract method must
635     * be implemented by deriving classes.
636     */
637 schoenebeck 3557 virtual vmint arraySize() const = 0;
638 schoenebeck 2619 };
639    
640 schoenebeck 3581 /** @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 schoenebeck 2727 /** @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 schoenebeck 3581 class VMIntArrayExpr : virtual public VMNumberArrayExpr {
674 schoenebeck 2619 public:
675 schoenebeck 2727 /**
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 schoenebeck 3557 virtual vmint evalIntElement(vmuint i) = 0;
682 schoenebeck 2727
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 schoenebeck 3557 virtual void assignIntElement(vmuint i, vmint value) = 0;
691 schoenebeck 2727
692     /**
693     * Returns always INT_ARR_EXPR for instances of this class.
694     */
695     ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }
696 schoenebeck 2619 };
697    
698 schoenebeck 3573 /** @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 schoenebeck 3581 class VMRealArrayExpr : virtual public VMNumberArrayExpr {
706 schoenebeck 3573 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 schoenebeck 2727 /** @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 schoenebeck 2581 class VMFnArgs {
739     public:
740 schoenebeck 2727 /**
741     * Returns the amount of arguments going to be passed to the script
742     * function.
743     */
744 schoenebeck 3557 virtual vmint argsCount() const = 0;
745 schoenebeck 2727
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 schoenebeck 3557 virtual VMExpr* arg(vmint i) = 0;
755 schoenebeck 2581 };
756    
757 schoenebeck 2727 /** @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 schoenebeck 2581 class VMFnResult {
766     public:
767 schoenebeck 2727 /**
768     * Returns the result value of the function call, represented by a high
769     * level expression object.
770     */
771 schoenebeck 2581 virtual VMExpr* resultValue() = 0;
772 schoenebeck 2727
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 schoenebeck 2581 virtual StmtFlags_t resultFlags() { return STMT_SUCCESS; }
780     };
781    
782 schoenebeck 2727 /** @brief Virtual machine built-in function.
783 schoenebeck 2612 *
784     * Abstract base class for built-in script functions, defining the interface
785 schoenebeck 2727 * 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 schoenebeck 2612 */
805 schoenebeck 2581 class VMFunction {
806     public:
807 schoenebeck 2612 /**
808     * Script data type of the function's return value. If the function does
809 schoenebeck 2727 * not return any value (void), then it returns EMPTY_EXPR here.
810 schoenebeck 3577 *
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 schoenebeck 2612 */
821 schoenebeck 3577 virtual ExprType_t returnType(VMFnArgs* args) = 0;
822 schoenebeck 2612
823     /**
824 schoenebeck 3581 * 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 schoenebeck 3582 * @see VMNumberExpr::isFinal() for details about 'final' values
856 schoenebeck 3581 */
857     virtual bool returnsFinal(VMFnArgs* args) = 0;
858    
859     /**
860 schoenebeck 2612 * 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 schoenebeck 3557 virtual vmint minRequiredArgs() const = 0;
865 schoenebeck 2612
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 schoenebeck 3557 virtual vmint maxAllowedArgs() const = 0;
872 schoenebeck 2612
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 schoenebeck 2871 * calling acceptsArgType(). The return value of argType() is used by the
878 schoenebeck 2612 * 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 schoenebeck 2727 * (must be between 0 .. maxAllowedArgs() - 1)
886 schoenebeck 2612 */
887 schoenebeck 3557 virtual ExprType_t argType(vmint iArg) const = 0;
888 schoenebeck 2612
889     /**
890 schoenebeck 2945 * This method is called by the parser to check whether arguments
891 schoenebeck 2612 * 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 schoenebeck 2727 * 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 schoenebeck 2612 *
898     * @param iArg - index of the function argument in question
899 schoenebeck 2727 * (must be between 0 .. maxAllowedArgs() - 1)
900 schoenebeck 2612 * @param type - script data type used for this function argument by
901     * currently parsed script
902 schoenebeck 2727 * @return true if the given data type would be accepted for the
903     * respective function argument by the function
904 schoenebeck 2612 */
905 schoenebeck 3557 virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0;
906 schoenebeck 2612
907     /**
908 schoenebeck 3561 * 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 schoenebeck 3564 * @param type - standard measurement unit data type used for that
942     * function argument by currently parsed script
943 schoenebeck 3561 *
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 schoenebeck 3564 virtual bool acceptsArgUnitPrefix(vmint iArg, StdUnit_t type) const;
950 schoenebeck 3561
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 schoenebeck 3582 * @see VMNumberExpr::isFinal(), returnsFinal()
968 schoenebeck 3561 */
969     virtual bool acceptsArgFinal(vmint iArg) const;
970    
971     /**
972 schoenebeck 2945 * 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 schoenebeck 3557 virtual bool modifiesArg(vmint iArg) const = 0;
985 schoenebeck 2945
986     /**
987 schoenebeck 3581 * 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 schoenebeck 2727 * 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 schoenebeck 2612 *
1026     * @param args - function arguments for executing this built-in function
1027 schoenebeck 2727 * @returns function's return value (if any) and general status
1028     * informations (i.e. whether the function call caused a
1029     * runtime error)
1030 schoenebeck 2612 */
1031 schoenebeck 2581 virtual VMFnResult* exec(VMFnArgs* args) = 0;
1032 schoenebeck 2612
1033     /**
1034 schoenebeck 2727 * Convenience method for function implementations to show warning
1035     * messages during actual execution of the built-in function.
1036 schoenebeck 2612 *
1037 schoenebeck 2727 * @param txt - runtime warning text to be shown to user
1038 schoenebeck 2612 */
1039 schoenebeck 2598 void wrnMsg(const String& txt);
1040 schoenebeck 2612
1041     /**
1042 schoenebeck 2727 * Convenience method for function implementations to show error
1043     * messages during actual execution of the built-in function.
1044 schoenebeck 2612 *
1045 schoenebeck 2727 * @param txt - runtime error text to be shown to user
1046 schoenebeck 2612 */
1047 schoenebeck 2598 void errMsg(const String& txt);
1048 schoenebeck 2581 };
1049    
1050 schoenebeck 2727 /** @brief Virtual machine relative pointer.
1051     *
1052 schoenebeck 3557 * POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not
1053     * intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr,
1054     * VMInt8RelPtr instead.
1055 schoenebeck 2727 *
1056 schoenebeck 3557 * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr
1057 schoenebeck 2594 */
1058     struct VMRelPtr {
1059     void** base; ///< Base pointer.
1060 schoenebeck 3557 vmint offset; ///< Offset (in bytes) relative to base pointer.
1061 schoenebeck 2948 bool readonly; ///< Whether the pointed data may be modified or just be read.
1062 schoenebeck 2594 };
1063    
1064 schoenebeck 3557 /** @brief Pointer to built-in VM integer variable (interface class).
1065 schoenebeck 2594 *
1066 schoenebeck 3557 * 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 schoenebeck 2727 * Used for defining built-in 32 bit integer script variables.
1125 schoenebeck 2594 *
1126     * @b CAUTION: You may only use this class for pointing to C/C++ variables
1127 schoenebeck 3557 * 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 schoenebeck 2594 *
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 schoenebeck 3557 * @see VMInt64RelPtr, VMInt8RelPtr, DECLARE_VMINT()
1143 schoenebeck 2594 */
1144 schoenebeck 3557 struct VMInt32RelPtr : VMRelPtr, VMIntPtr {
1145     VMInt32RelPtr() {
1146 schoenebeck 2594 base = NULL;
1147     offset = 0;
1148 schoenebeck 2948 readonly = false;
1149 schoenebeck 2594 }
1150 schoenebeck 3557 VMInt32RelPtr(const VMRelPtr& data) {
1151 schoenebeck 2594 base = data.base;
1152     offset = data.offset;
1153 schoenebeck 2948 readonly = false;
1154 schoenebeck 2594 }
1155 schoenebeck 3557 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 schoenebeck 2594 };
1163    
1164     /** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t).
1165     *
1166 schoenebeck 2727 * Used for defining built-in 8 bit integer script variables.
1167 schoenebeck 2594 *
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 schoenebeck 3557 * 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 schoenebeck 2594 *
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 schoenebeck 3557 * @see VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT()
1185 schoenebeck 2594 */
1186 schoenebeck 3557 struct VMInt8RelPtr : VMRelPtr, VMIntPtr {
1187     VMInt8RelPtr() {
1188     base = NULL;
1189     offset = 0;
1190     readonly = false;
1191 schoenebeck 2594 }
1192 schoenebeck 3557 VMInt8RelPtr(const VMRelPtr& data) {
1193     base = data.base;
1194     offset = data.offset;
1195     readonly = false;
1196 schoenebeck 2594 }
1197 schoenebeck 3557 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 schoenebeck 2594 };
1205    
1206 schoenebeck 3557 /** @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 schoenebeck 3035 #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 schoenebeck 2594 /**
1227 schoenebeck 3557 * Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr and
1228     * VMInt8RelPtr structures. Usage example:
1229 schoenebeck 2594 * @code
1230     * struct Foo {
1231 schoenebeck 2727 * uint8_t a; // native representation of a built-in integer script variable
1232 schoenebeck 3557 * 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 schoenebeck 2727 * uint8_t d; // native representation of another built-in integer script variable
1235 schoenebeck 2594 * };
1236     *
1237 schoenebeck 2727 * // 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 schoenebeck 2594 *
1241     * Foo* pFoo;
1242     *
1243 schoenebeck 2727 * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);
1244 schoenebeck 3557 * VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b);
1245     * VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c);
1246 schoenebeck 2727 * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);
1247 schoenebeck 2594 *
1248     * pFoo = &foo1;
1249 schoenebeck 2727 * 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 schoenebeck 2594 *
1254 schoenebeck 2727 * // same printf() code, just with pFoo pointer being changed ...
1255     *
1256 schoenebeck 2594 * pFoo = &foo2;
1257 schoenebeck 2727 * 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 schoenebeck 2594 * @endcode
1262 schoenebeck 2727 * 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 schoenebeck 2594 */
1268 schoenebeck 3034 #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \
1269     /* Disable offsetof warning, trust us, we are cautios. */ \
1270 schoenebeck 3035 COMPILER_DISABLE_OFFSETOF_WARNING \
1271 schoenebeck 3034 (VMRelPtr) { \
1272     (void**) &basePtr, \
1273     offsetof(T_struct, T_member), \
1274     false \
1275     } \
1276 schoenebeck 3035 COMPILER_RESTORE_OFFSETOF_WARNING \
1277 schoenebeck 3034 ) \
1278 schoenebeck 2594
1279 schoenebeck 2948 /**
1280 schoenebeck 3557 * 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 schoenebeck 2948 *
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 schoenebeck 3034 /* Disable offsetof warning, trust us, we are cautios. */ \
1294 schoenebeck 3035 COMPILER_DISABLE_OFFSETOF_WARNING \
1295 schoenebeck 3034 (VMRelPtr) { \
1296     (void**) &basePtr, \
1297     offsetof(T_struct, T_member), \
1298     true \
1299     } \
1300 schoenebeck 3035 COMPILER_RESTORE_OFFSETOF_WARNING \
1301 schoenebeck 3034 ) \
1302 schoenebeck 2948
1303 schoenebeck 2594 /** @brief Built-in VM 8 bit integer array variable.
1304     *
1305 schoenebeck 2727 * Used for defining built-in integer array script variables (8 bit per
1306 schoenebeck 3573 * 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 schoenebeck 2594 */
1310     struct VMInt8Array {
1311     int8_t* data;
1312 schoenebeck 3557 vmint size;
1313 schoenebeck 3253 bool readonly; ///< Whether the array data may be modified or just be read.
1314 schoenebeck 2594
1315 schoenebeck 3253 VMInt8Array() : data(NULL), size(0), readonly(false) {}
1316 schoenebeck 2594 };
1317    
1318 schoenebeck 2945 /** @brief Virtual machine script variable.
1319     *
1320 schoenebeck 3573 * Common interface for all variables accessed in scripts, independent of
1321     * their precise data type.
1322 schoenebeck 2945 */
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 schoenebeck 3573
1343 schoenebeck 2942 /** @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 schoenebeck 2945 class VMDynVar : public VMVariable {
1354 schoenebeck 2942 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 schoenebeck 2945 bool isConstExpr() const OVERRIDE { return false; }
1392 schoenebeck 2942
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 schoenebeck 2945 void assignExpr(VMExpr* expr) OVERRIDE {}
1404 schoenebeck 3034
1405     virtual ~VMDynVar() {}
1406 schoenebeck 2942 };
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 schoenebeck 3581 vmfloat unitFactor() const OVERRIDE { return VM_NO_FACTOR; }
1417 schoenebeck 3561 StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; }
1418     bool isFinal() const OVERRIDE { return false; }
1419 schoenebeck 2942 };
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 schoenebeck 3073 /** @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 schoenebeck 2612 /** @brief Provider for built-in script functions and variables.
1442     *
1443 schoenebeck 2727 * 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 schoenebeck 2612 */
1447 schoenebeck 2581 class VMFunctionProvider {
1448     public:
1449 schoenebeck 2612 /**
1450     * Returns pointer to the built-in function with the given function
1451 schoenebeck 2727 * @a name, or NULL if there is no built-in function with that function
1452     * name.
1453 schoenebeck 2612 *
1454 schoenebeck 2727 * @param name - function name (i.e. "wait" or "message" or "exit", etc.)
1455 schoenebeck 2612 */
1456 schoenebeck 2581 virtual VMFunction* functionByName(const String& name) = 0;
1457 schoenebeck 2612
1458     /**
1459 schoenebeck 3311 * 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 schoenebeck 2612 * Returns a variable name indexed map of all built-in script variables
1478 schoenebeck 2727 * which point to native "int" scalar (usually 32 bit) variables.
1479 schoenebeck 2612 */
1480 schoenebeck 3557 virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0;
1481 schoenebeck 2612
1482     /**
1483 schoenebeck 2727 * Returns a variable name indexed map of all built-in script integer
1484     * array variables with array element type "int8_t" (8 bit).
1485 schoenebeck 2612 */
1486 schoenebeck 2594 virtual std::map<String,VMInt8Array*> builtInIntArrayVariables() = 0;
1487 schoenebeck 2612
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 schoenebeck 3557 virtual std::map<String,vmint> builtInConstIntVariables() = 0;
1493 schoenebeck 2942
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 schoenebeck 2581 };
1501    
1502 schoenebeck 2594 /** @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 schoenebeck 2612 * execution stack, and VM polyphonic variables. It does not contain global
1507 schoenebeck 2727 * variables. Global variables are contained in the VMParserContext object.
1508 schoenebeck 2612 * You might see a VMExecContext object as one virtual thread of the virtual
1509     * machine.
1510 schoenebeck 2594 *
1511 schoenebeck 2612 * 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 schoenebeck 2594 * @see VMParserContext
1516     */
1517 schoenebeck 2581 class VMExecContext {
1518     public:
1519     virtual ~VMExecContext() {}
1520 schoenebeck 2727
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 schoenebeck 2871 * microseconds, indicated by this method by comparing the time stamps in
1530 schoenebeck 2727 * 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 schoenebeck 3557 virtual vmint suspensionTimeMicroseconds() const = 0;
1542 schoenebeck 3207
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 schoenebeck 3221
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 schoenebeck 3277
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 schoenebeck 3293
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 schoenebeck 3551
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 schoenebeck 2581 };
1602    
1603 schoenebeck 2645 /** @brief Script callback for a certain event.
1604     *
1605     * Represents a script callback for a certain event, i.e.
1606 schoenebeck 2727 * "on note ... end on" code block.
1607 schoenebeck 2645 */
1608 schoenebeck 2581 class VMEventHandler {
1609     public:
1610 schoenebeck 2645 /**
1611 schoenebeck 2879 * 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 schoenebeck 2645 * 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 schoenebeck 2581 virtual String eventHandlerName() const = 0;
1623 schoenebeck 2645
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 schoenebeck 2581 };
1630    
1631 schoenebeck 2727 /**
1632 schoenebeck 3285 * 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 schoenebeck 3292 * code blocks due to preprocessor statements, and for parser errors and
1635     * parser warnings.
1636 schoenebeck 3285 *
1637 schoenebeck 3292 * @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 schoenebeck 3285 */
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 schoenebeck 2727 * 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 schoenebeck 3012 *
1655     * @see VMSourceToken for processing syntax highlighting instead.
1656 schoenebeck 2727 */
1657 schoenebeck 3292 struct ParserIssue : CodeBlock {
1658 schoenebeck 2727 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 schoenebeck 2581
1661 schoenebeck 2727 /**
1662     * Print this issue out to the console (stdio).
1663     */
1664 schoenebeck 2581 inline void dump() {
1665     switch (type) {
1666     case PARSER_ERROR:
1667 schoenebeck 2889 printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
1668 schoenebeck 2581 break;
1669     case PARSER_WARNING:
1670 schoenebeck 2889 printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
1671 schoenebeck 2581 break;
1672     }
1673     }
1674 schoenebeck 2727
1675     /**
1676     * Returns true if this issue is a parser error. In this case the parsed
1677     * script may not be executed!
1678     */
1679 schoenebeck 2581 inline bool isErr() const { return type == PARSER_ERROR; }
1680 schoenebeck 2727
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 schoenebeck 2581 inline bool isWrn() const { return type == PARSER_WARNING; }
1687     };
1688    
1689 schoenebeck 2727 /**
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 schoenebeck 2581 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 schoenebeck 3573 case REAL_EXPR: return "real number";
1699     case REAL_ARR_EXPR: return "real number array";
1700 schoenebeck 2581 case STRING_EXPR: return "string";
1701     case STRING_ARR_EXPR: return "string array";
1702     }
1703     return "invalid";
1704     }
1705    
1706 schoenebeck 3561 /**
1707 schoenebeck 3573 * Returns @c true in case the passed data type is some array data type.
1708     */
1709     inline bool isArray(const ExprType_t& type) {
1710     return type == INT_ARR_EXPR || type == REAL_ARR_EXPR ||
1711     type == STRING_ARR_EXPR;
1712     }
1713    
1714     /**
1715     * Returns @c true in case the passed data type is some scalar number type
1716     * (i.e. not an array and not a string).
1717     */
1718 schoenebeck 3582 inline bool isNumber(const ExprType_t& type) {
1719 schoenebeck 3573 return type == INT_EXPR || type == REAL_EXPR;
1720     }
1721    
1722     /**
1723 schoenebeck 3561 * Convenience function used for converting an StdUnit_t constant to a
1724     * string, i.e. for generating error message by the parser.
1725     */
1726     inline String unitTypeStr(const StdUnit_t& type) {
1727     switch (type) {
1728     case VM_NO_UNIT: return "none";
1729     case VM_SECOND: return "seconds";
1730     case VM_HERTZ: return "Hz";
1731     case VM_BEL: return "Bel";
1732     }
1733     return "invalid";
1734     }
1735    
1736 schoenebeck 2594 /** @brief Virtual machine representation of a script.
1737     *
1738     * An instance of this abstract base class represents a parsed script,
1739 schoenebeck 2727 * translated into a virtual machine tree. You should first check if there
1740     * were any parser errors. If there were any parser errors, you should
1741     * refrain from executing the virtual machine. Otherwise if there were no
1742     * parser errors (i.e. only warnings), then you might access one of the
1743     * script's event handlers by i.e. calling eventHandlerByName() and pass the
1744     * respective event handler to the ScriptVM class (or to one of the ScriptVM
1745 schoenebeck 2594 * descendants) for execution.
1746     *
1747 schoenebeck 2727 * @see VMExecContext, ScriptVM
1748 schoenebeck 2594 */
1749 schoenebeck 2588 class VMParserContext {
1750     public:
1751     virtual ~VMParserContext() {}
1752 schoenebeck 2727
1753     /**
1754     * Returns all noteworthy issues encountered when the script was parsed.
1755     * These are parser errors and parser warnings.
1756     */
1757 schoenebeck 2588 virtual std::vector<ParserIssue> issues() const = 0;
1758 schoenebeck 2727
1759     /**
1760     * Same as issues(), but this method only returns parser errors.
1761     */
1762 schoenebeck 2588 virtual std::vector<ParserIssue> errors() const = 0;
1763 schoenebeck 2727
1764     /**
1765     * Same as issues(), but this method only returns parser warnings.
1766     */
1767 schoenebeck 2588 virtual std::vector<ParserIssue> warnings() const = 0;
1768 schoenebeck 2727
1769     /**
1770 schoenebeck 3285 * Returns all code blocks of the script which were filtered out by the
1771     * preprocessor.
1772     */
1773     virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1774    
1775     /**
1776 schoenebeck 2727 * Returns the translated virtual machine representation of an event
1777     * handler block (i.e. "on note ... end on" code block) within the
1778     * parsed script. This translated representation of the event handler
1779     * can be executed by the virtual machine.
1780     *
1781     * @param index - index of the event handler within the script
1782     */
1783 schoenebeck 2588 virtual VMEventHandler* eventHandler(uint index) = 0;
1784 schoenebeck 2727
1785     /**
1786     * Same as eventHandler(), but this method returns the event handler by
1787     * its name. So for a "on note ... end on" code block of the parsed
1788     * script you would pass "note" for argument @a name here.
1789     *
1790     * @param name - name of the event handler (i.e. "init", "note",
1791     * "controller", "release")
1792     */
1793 schoenebeck 2588 virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
1794     };
1795    
1796 schoenebeck 2885 class SourceToken;
1797    
1798     /** @brief Recognized token of a script's source code.
1799     *
1800     * Represents one recognized token of a script's source code, for example
1801     * a keyword, variable name, etc. and it provides further informations about
1802     * that particular token, i.e. the precise location (line and column) of the
1803     * token within the original script's source code.
1804     *
1805     * This class is not actually used by the sampler itself. It is rather
1806     * provided for external script editor applications. Primary purpose of
1807     * this class is syntax highlighting for external script editors.
1808 schoenebeck 3012 *
1809     * @see ParserIssue for processing compile errors and warnings instead.
1810 schoenebeck 2885 */
1811     class VMSourceToken {
1812     public:
1813     VMSourceToken();
1814     VMSourceToken(SourceToken* ct);
1815     VMSourceToken(const VMSourceToken& other);
1816     virtual ~VMSourceToken();
1817    
1818     // original text of this token as it is in the script's source code
1819     String text() const;
1820    
1821     // position of token in script
1822 schoenebeck 3012 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.
1823     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().
1824 schoenebeck 2885
1825     // base types
1826 schoenebeck 3012 bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1827     bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1828     bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1829     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.
1830     bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1831     bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1832     bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1833     bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1834     bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1835 schoenebeck 3562 bool isMetricPrefix() const;
1836     bool isStdUnit() const;
1837 schoenebeck 3012 bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1838 schoenebeck 2885
1839     // extended types
1840 schoenebeck 3012 bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1841 schoenebeck 3573 bool isRealVariable() const; ///< Returns true in case this source token represents a floating point variable name (i.e. "~someRealVariable").
1842 schoenebeck 3012 bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1843 schoenebeck 3573 bool isIntArrayVariable() const; ///< Returns true in case this source token represents an integer array variable name (i.e. "%someArrayVariable").
1844     bool isRealArrayVariable() const; ///< Returns true in case this source token represents a real number array variable name (i.e. "?someArrayVariable").
1845     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.
1846 schoenebeck 3012 bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1847 schoenebeck 2885
1848     VMSourceToken& operator=(const VMSourceToken& other);
1849    
1850     private:
1851     SourceToken* m_token;
1852     };
1853    
1854 schoenebeck 2581 } // namespace LinuxSampler
1855    
1856     #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H

  ViewVC Help
Powered by ViewVC