1 |
/* |
/* |
2 |
* Copyright (c) 2014-2016 Christian Schoenebeck |
* Copyright (c) 2014-2019 Christian Schoenebeck |
3 |
* |
* |
4 |
* http://www.linuxsampler.org |
* http://www.linuxsampler.org |
5 |
* |
* |
9 |
|
|
10 |
// This header defines data types shared between the VM core implementation |
// This header defines data types shared between the VM core implementation |
11 |
// (inside the current source directory) and other parts of the sampler |
// (inside the current source directory) and other parts of the sampler |
12 |
// (located at other source directories). |
// (located at other source directories). It also acts as public API of the |
13 |
|
// Real-Time script engine for other applications. |
14 |
|
|
15 |
#ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H |
#ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H |
16 |
#define LS_INSTR_SCRIPT_PARSER_COMMON_H |
#define LS_INSTR_SCRIPT_PARSER_COMMON_H |
23 |
namespace LinuxSampler { |
namespace LinuxSampler { |
24 |
|
|
25 |
/** |
/** |
26 |
|
* Native data type used by the script engine both internally, as well as |
27 |
|
* for all integer data types used by scripts (i.e. for all $foo variables |
28 |
|
* in NKSP scripts). Note that this is different from the original KSP which |
29 |
|
* is limited to 32 bit for integer variables in KSP scripts. |
30 |
|
*/ |
31 |
|
typedef int64_t vmint; |
32 |
|
|
33 |
|
/** |
34 |
|
* Native data type used internally by the script engine for all unsigned |
35 |
|
* integer types. This type is currently not exposed to scripts. |
36 |
|
*/ |
37 |
|
typedef uint64_t vmuint; |
38 |
|
|
39 |
|
/** |
40 |
|
* Native data type used internally by the script engine for floating point |
41 |
|
* data types. This type is currently not exposed to scripts. |
42 |
|
*/ |
43 |
|
typedef float vmfloat; |
44 |
|
|
45 |
|
/** |
46 |
* Identifies the type of a noteworthy issue identified by the script |
* Identifies the type of a noteworthy issue identified by the script |
47 |
* parser. That's either a parser error or parser warning. |
* parser. That's either a parser error or parser warning. |
48 |
*/ |
*/ |
101 |
* |
* |
102 |
* Identifies one of the possible event handler callback types defined by |
* Identifies one of the possible event handler callback types defined by |
103 |
* the NKSP script language. |
* the NKSP script language. |
104 |
|
* |
105 |
|
* IMPORTANT: this type is forced to be emitted as int32_t type ATM, because |
106 |
|
* that's the native size expected by the built-in instrument script |
107 |
|
* variable bindings (see occurrences of VMInt32RelPtr and DECLARE_VMINT |
108 |
|
* respectively. A native type mismatch between the two could lead to |
109 |
|
* undefined behavior! Background: By definition the C/C++ compiler is free |
110 |
|
* to choose a bit size for individual enums which it might find |
111 |
|
* appropriate, which is usually decided by the compiler according to the |
112 |
|
* biggest enum constant value defined (in practice it is usually 32 bit). |
113 |
*/ |
*/ |
114 |
enum VMEventHandlerType_t { |
enum VMEventHandlerType_t : int32_t { |
115 |
VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block. |
VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block. |
116 |
VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block. |
VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block. |
117 |
VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block. |
VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block. |
118 |
VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block. |
VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block. |
119 |
}; |
}; |
120 |
|
|
121 |
|
/** |
122 |
|
* All metric unit prefixes (actually just scale factors) supported by this |
123 |
|
* script engine. |
124 |
|
*/ |
125 |
|
enum MetricPrefix_t { |
126 |
|
VM_NO_PREFIX = 0, ///< = 1 |
127 |
|
VM_KILO, ///< = 10^3, short 'k' |
128 |
|
VM_HECTO, ///< = 10^2, short 'h' |
129 |
|
VM_DECA, ///< = 10, short 'da' |
130 |
|
VM_DECI, ///< = 10^-1, short 'd' |
131 |
|
VM_CENTI, ///< = 10^-2, short 'c' (this is also used for tuning "cents") |
132 |
|
VM_MILLI, ///< = 10^-3, short 'm' |
133 |
|
VM_MICRO, ///< = 10^-6, short 'u' |
134 |
|
}; |
135 |
|
|
136 |
|
/** |
137 |
|
* All measurement unit types supported by this script engine. |
138 |
|
* |
139 |
|
* @e Note: there is no standard unit "cents" here (for pitch/tuning), use |
140 |
|
* @c VM_CENTI for the latter instad. That's because the commonly cited |
141 |
|
* "cents" unit is actually no measurement unit type but rather a metric |
142 |
|
* unit prefix. |
143 |
|
* |
144 |
|
* @see MetricPrefix_t |
145 |
|
*/ |
146 |
|
enum StdUnit_t { |
147 |
|
VM_NO_UNIT = 0, ///< No unit used, the number is just an abstract number. |
148 |
|
VM_SECOND, ///< Measuring time. |
149 |
|
VM_HERTZ, ///< Measuring frequency. |
150 |
|
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). |
151 |
|
}; |
152 |
|
|
153 |
// just symbol prototyping |
// just symbol prototyping |
154 |
class VMIntExpr; |
class VMIntExpr; |
155 |
class VMStringExpr; |
class VMStringExpr; |
156 |
class VMIntArrayExpr; |
class VMIntArrayExpr; |
157 |
class VMStringArrayExpr; |
class VMStringArrayExpr; |
158 |
|
class VMParserContext; |
159 |
|
|
160 |
|
/** @brief Virtual machine measuring unit. |
161 |
|
* |
162 |
|
* Abstract base class representing standard measurement units throughout |
163 |
|
* the script engine. These might be i.e. "dB" (deci Bel) for loudness, |
164 |
|
* "Hz" (Hertz) for frequencies or "s" for "seconds". |
165 |
|
* |
166 |
|
* Originally the script engine only supported abstract integer values for |
167 |
|
* controlling any synthesis parameter or built-in function argument or |
168 |
|
* variable. Under certain situations it makes sense though for an |
169 |
|
* instrument script author to provide values in real, standard measurement |
170 |
|
* units, for example setting the frequency of some LFO directly to "20Hz". |
171 |
|
* Hence support for standard units in scripts was added as an extension to |
172 |
|
* the NKSP script engine. |
173 |
|
*/ |
174 |
|
class VMUnit { |
175 |
|
public: |
176 |
|
/** |
177 |
|
* Returns the metric prefix of this unit. A metric prefix essentially |
178 |
|
* is just a mathematical scale factor that should be applied to the |
179 |
|
* number associated with the measurement unit. Usually a unit either |
180 |
|
* has exactly none or one prefix, but note that there might also be |
181 |
|
* units with more than one prefix, for example mdB (mili deci bel) |
182 |
|
* is used sometimes which has two prefixes. This is an exception though |
183 |
|
* and more than two prefixes is currently not supported by the script |
184 |
|
* engine. |
185 |
|
* |
186 |
|
* Start iterating over the prefixes of this unit by passing @c 0 as |
187 |
|
* argument to this method. The prefixes are terminated with return |
188 |
|
* value VM_NO_PREFIX being always the last element. |
189 |
|
* |
190 |
|
* @param i - index of prefix |
191 |
|
* @returns prefix of requested index or VM_NO_PREFIX otherwise |
192 |
|
* @see unitFactor() |
193 |
|
*/ |
194 |
|
virtual MetricPrefix_t unitPrefix(vmuint i) const = 0; |
195 |
|
|
196 |
|
/** |
197 |
|
* Conveniently returns the final mathematical factor that should be |
198 |
|
* multiplied against the number associated with this unit. This factor |
199 |
|
* results from the sequence of metric prefixes of this unit. |
200 |
|
* |
201 |
|
* @see unitPrefix() |
202 |
|
*/ |
203 |
|
vmfloat unitFactor() const; |
204 |
|
|
205 |
|
/** |
206 |
|
* This is the actual fundamental measuring unit base type of this unit, |
207 |
|
* which might be either Hertz, second or Bel. |
208 |
|
* |
209 |
|
* @returns standard unit type identifier or VM_NO_UNIT if no unit used |
210 |
|
*/ |
211 |
|
virtual StdUnit_t unitType() const = 0; |
212 |
|
|
213 |
|
/** |
214 |
|
* Returns the actual mathematical factor represented by the passed |
215 |
|
* @a prefix argument. |
216 |
|
*/ |
217 |
|
static vmfloat unitFactor(MetricPrefix_t prefix); |
218 |
|
|
219 |
|
/** |
220 |
|
* Returns the actual mathematical factor represented by the passed |
221 |
|
* two @a prefix1 and @a prefix2 arguments. |
222 |
|
*/ |
223 |
|
static vmfloat unitFactor(MetricPrefix_t prefix1, MetricPrefix_t prefix2); |
224 |
|
}; |
225 |
|
|
226 |
/** @brief Virtual machine expression |
/** @brief Virtual machine expression |
227 |
* |
* |
286 |
* expressions to an array expression for you, instead this method will |
* expressions to an array expression for you, instead this method will |
287 |
* simply return NULL! |
* simply return NULL! |
288 |
* |
* |
289 |
|
* @b Note: this method is currently, and in contrast to its other |
290 |
|
* counter parts, declared as virtual method. Some deriving classes are |
291 |
|
* currently using this to override this default implementation in order |
292 |
|
* to implement an "evaluate now as integer array" behavior. This has |
293 |
|
* efficiency reasons, however this also currently makes this part of |
294 |
|
* the API less clean and should thus be addressed in future with |
295 |
|
* appropriate changes to the API. |
296 |
|
* |
297 |
* @see exprType() |
* @see exprType() |
298 |
*/ |
*/ |
299 |
VMIntArrayExpr* asIntArray() const; |
virtual VMIntArrayExpr* asIntArray() const; |
300 |
|
|
301 |
/** |
/** |
302 |
* Returns true in case this expression can be considered to be a |
* Returns true in case this expression can be considered to be a |
305 |
* expression's constant value may be evaluated already at script |
* expression's constant value may be evaluated already at script |
306 |
* parse time, which may result in performance benefits during script |
* parse time, which may result in performance benefits during script |
307 |
* runtime. |
* runtime. |
308 |
|
* |
309 |
|
* @b NOTE: A constant expression is per se always also non modifyable. |
310 |
|
* But a non modifyable expression may not necessarily be a constant |
311 |
|
* expression! |
312 |
|
* |
313 |
|
* @see isModifyable() |
314 |
*/ |
*/ |
315 |
virtual bool isConstExpr() const = 0; |
virtual bool isConstExpr() const = 0; |
316 |
|
|
317 |
|
/** |
318 |
|
* Returns true in case this expression is allowed to be modified. |
319 |
|
* If this method returns @c false then this expression must be handled |
320 |
|
* as read-only expression, which means that assigning a new value to it |
321 |
|
* is either not possible or not allowed. |
322 |
|
* |
323 |
|
* @b NOTE: A constant expression is per se always also non modifyable. |
324 |
|
* But a non modifyable expression may not necessarily be a constant |
325 |
|
* expression! |
326 |
|
* |
327 |
|
* @see isConstExpr() |
328 |
|
*/ |
329 |
bool isModifyable() const; |
bool isModifyable() const; |
330 |
}; |
}; |
331 |
|
|
336 |
* abstract method evalInt() to return the actual integer result value of |
* abstract method evalInt() to return the actual integer result value of |
337 |
* the expression. |
* the expression. |
338 |
*/ |
*/ |
339 |
class VMIntExpr : virtual public VMExpr { |
class VMIntExpr : virtual public VMExpr, virtual public VMUnit { |
340 |
public: |
public: |
341 |
/** |
/** |
342 |
* Returns the result of this expression as integer (scalar) value. |
* Returns the result of this expression as integer (scalar) value. |
343 |
* This abstract method must be implemented by deriving classes. |
* This abstract method must be implemented by deriving classes. |
344 |
*/ |
*/ |
345 |
virtual int evalInt() = 0; |
virtual vmint evalInt() = 0; |
346 |
|
|
347 |
|
/** |
348 |
|
* Returns the result of this expression as integer (scalar) value and |
349 |
|
* thus behaves similar to the previous method, however this overridden |
350 |
|
* method automatically takes unit prefixes into account and returns a |
351 |
|
* value corresponding to the expected given unit @a prefix. |
352 |
|
* |
353 |
|
* @param prefix - default measurement unit prefix expected by caller |
354 |
|
*/ |
355 |
|
vmint evalInt(MetricPrefix_t prefix); |
356 |
|
|
357 |
|
/** |
358 |
|
* This method behaves like the previous method, just that it takes |
359 |
|
* a default measurement prefix with two elements (i.e. "milli cents" |
360 |
|
* for tuning). |
361 |
|
*/ |
362 |
|
vmint evalInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2); |
363 |
|
|
364 |
/** |
/** |
365 |
* Returns always INT_EXPR for instances of this class. |
* Returns always INT_EXPR for instances of this class. |
366 |
*/ |
*/ |
367 |
ExprType_t exprType() const OVERRIDE { return INT_EXPR; } |
ExprType_t exprType() const OVERRIDE { return INT_EXPR; } |
368 |
|
|
369 |
|
/** |
370 |
|
* Returns @c true if the value of this expression should be applied |
371 |
|
* as final value to the respective destination synthesis chain |
372 |
|
* parameter. |
373 |
|
* |
374 |
|
* This property is somewhat special and dedicated for the purpose of |
375 |
|
* this expression's integer value to be applied as parameter to the |
376 |
|
* synthesis chain of the sampler (i.e. for altering a filter cutoff |
377 |
|
* frequency). Now historically and by default all values of scripts are |
378 |
|
* applied relatively to the sampler's synthesis chain, that is the |
379 |
|
* synthesis parameter value of a script is multiplied against other |
380 |
|
* sources for the same synthesis parameter (i.e. an LFO or a dedicated |
381 |
|
* MIDI controller either hard wired in the engine or defined by the |
382 |
|
* instrument patch). So by default the resulting actual final synthesis |
383 |
|
* parameter is a combination of all these sources. This has the |
384 |
|
* advantage that it creates a very living and dynamic overall sound. |
385 |
|
* |
386 |
|
* However sometimes there are requirements by script authors where this |
387 |
|
* is not what you want. Therefore the NKSP script engine added a |
388 |
|
* language extension by prefixing a value in scripts with a @c ! |
389 |
|
* character the value will be defined as being the "final" value of the |
390 |
|
* destination synthesis parameter, so that causes this value to be |
391 |
|
* applied exclusively, and the values of all other sources are thus |
392 |
|
* entirely ignored by the sampler's synthesis core as long as this |
393 |
|
* value is assigned by the script engine as "final" value for the |
394 |
|
* requested synthesis parameter. |
395 |
|
*/ |
396 |
|
virtual bool isFinal() const = 0; |
397 |
}; |
}; |
398 |
|
|
399 |
/** @brief Virtual machine string expression |
/** @brief Virtual machine string expression |
430 |
* Returns amount of elements in this array. This abstract method must |
* Returns amount of elements in this array. This abstract method must |
431 |
* be implemented by deriving classes. |
* be implemented by deriving classes. |
432 |
*/ |
*/ |
433 |
virtual int arraySize() const = 0; |
virtual vmint arraySize() const = 0; |
434 |
}; |
}; |
435 |
|
|
436 |
/** @brief Virtual Machine Integer Array Expression |
/** @brief Virtual Machine Integer Array Expression |
448 |
* |
* |
449 |
* @param i - array element index (must be between 0 .. arraySize() - 1) |
* @param i - array element index (must be between 0 .. arraySize() - 1) |
450 |
*/ |
*/ |
451 |
virtual int evalIntElement(uint i) = 0; |
virtual vmint evalIntElement(vmuint i) = 0; |
452 |
|
|
453 |
/** |
/** |
454 |
* Changes the current value of an element (given by array element |
* Changes the current value of an element (given by array element |
457 |
* @param i - array element index (must be between 0 .. arraySize() - 1) |
* @param i - array element index (must be between 0 .. arraySize() - 1) |
458 |
* @param value - new integer scalar value to be assigned to that array element |
* @param value - new integer scalar value to be assigned to that array element |
459 |
*/ |
*/ |
460 |
virtual void assignIntElement(uint i, int value) = 0; |
virtual void assignIntElement(vmuint i, vmint value) = 0; |
461 |
|
|
462 |
/** |
/** |
463 |
* Returns always INT_ARR_EXPR for instances of this class. |
* Returns always INT_ARR_EXPR for instances of this class. |
479 |
* Returns the amount of arguments going to be passed to the script |
* Returns the amount of arguments going to be passed to the script |
480 |
* function. |
* function. |
481 |
*/ |
*/ |
482 |
virtual int argsCount() const = 0; |
virtual vmint argsCount() const = 0; |
483 |
|
|
484 |
/** |
/** |
485 |
* Returns the respective argument (requested by argument index @a i) of |
* Returns the respective argument (requested by argument index @a i) of |
489 |
* |
* |
490 |
* @param i - function argument index (indexed from left to right) |
* @param i - function argument index (indexed from left to right) |
491 |
*/ |
*/ |
492 |
virtual VMExpr* arg(int i) = 0; |
virtual VMExpr* arg(vmint i) = 0; |
493 |
}; |
}; |
494 |
|
|
495 |
/** @brief Result value returned from a call to a built-in script function. |
/** @brief Result value returned from a call to a built-in script function. |
553 |
* script is calling this function with less arguments, the script |
* script is calling this function with less arguments, the script |
554 |
* parser will throw a parser error. |
* parser will throw a parser error. |
555 |
*/ |
*/ |
556 |
virtual int minRequiredArgs() const = 0; |
virtual vmint minRequiredArgs() const = 0; |
557 |
|
|
558 |
/** |
/** |
559 |
* Maximum amount of function arguments this functions accepts. If a |
* Maximum amount of function arguments this functions accepts. If a |
560 |
* script is calling this function with more arguments, the script |
* script is calling this function with more arguments, the script |
561 |
* parser will throw a parser error. |
* parser will throw a parser error. |
562 |
*/ |
*/ |
563 |
virtual int maxAllowedArgs() const = 0; |
virtual vmint maxAllowedArgs() const = 0; |
564 |
|
|
565 |
/** |
/** |
566 |
* Script data type of the function's @c iArg 'th function argument. |
* Script data type of the function's @c iArg 'th function argument. |
576 |
* @param iArg - index of the function argument in question |
* @param iArg - index of the function argument in question |
577 |
* (must be between 0 .. maxAllowedArgs() - 1) |
* (must be between 0 .. maxAllowedArgs() - 1) |
578 |
*/ |
*/ |
579 |
virtual ExprType_t argType(int iArg) const = 0; |
virtual ExprType_t argType(vmint iArg) const = 0; |
580 |
|
|
581 |
/** |
/** |
582 |
* This method is called by the parser to check whether arguments |
* This method is called by the parser to check whether arguments |
594 |
* @return true if the given data type would be accepted for the |
* @return true if the given data type would be accepted for the |
595 |
* respective function argument by the function |
* respective function argument by the function |
596 |
*/ |
*/ |
597 |
virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0; |
virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0; |
598 |
|
|
599 |
|
/** |
600 |
|
* This method is called by the parser to check whether arguments |
601 |
|
* passed in scripts to this function are accepted by this function. If |
602 |
|
* a script calls this function with an argument's measuremnt unit type |
603 |
|
* not accepted by this function, the parser will throw a parser error. |
604 |
|
* |
605 |
|
* This default implementation of this method does not accept any |
606 |
|
* measurement unit. Deriving subclasses would override this method |
607 |
|
* implementation in case they do accept any measurement unit for its |
608 |
|
* function arguments. |
609 |
|
* |
610 |
|
* @param iArg - index of the function argument in question |
611 |
|
* (must be between 0 .. maxAllowedArgs() - 1) |
612 |
|
* @param type - standard measurement unit data type used for this |
613 |
|
* function argument by currently parsed script |
614 |
|
* @return true if the given standard measurement unit type would be |
615 |
|
* accepted for the respective function argument by the function |
616 |
|
*/ |
617 |
|
virtual bool acceptsArgUnitType(vmint iArg, StdUnit_t type) const; |
618 |
|
|
619 |
|
/** |
620 |
|
* This method is called by the parser to check whether arguments |
621 |
|
* passed in scripts to this function are accepted by this function. If |
622 |
|
* a script calls this function with a metric unit prefix and metric |
623 |
|
* prefixes are not accepted for that argument by this function, then |
624 |
|
* the parser will throw a parser error. |
625 |
|
* |
626 |
|
* This default implementation of this method does not accept any |
627 |
|
* metric prefix. Deriving subclasses would override this method |
628 |
|
* implementation in case they do accept any metric prefix for its |
629 |
|
* function arguments. |
630 |
|
* |
631 |
|
* @param iArg - index of the function argument in question |
632 |
|
* (must be between 0 .. maxAllowedArgs() - 1) |
633 |
|
* |
634 |
|
* @return true if a metric prefix would be accepted for the respective |
635 |
|
* function argument by this function |
636 |
|
* |
637 |
|
* @see MetricPrefix_t |
638 |
|
*/ |
639 |
|
virtual bool acceptsArgUnitPrefix(vmint iArg) const; |
640 |
|
|
641 |
|
/** |
642 |
|
* This method is called by the parser to check whether arguments |
643 |
|
* passed in scripts to this function are accepted by this function. If |
644 |
|
* a script calls this function with an argument that is declared to be |
645 |
|
* a "final" value and this is not accepted by this function, the parser |
646 |
|
* will throw a parser error. |
647 |
|
* |
648 |
|
* This default implementation of this method does not accept a "final" |
649 |
|
* value. Deriving subclasses would override this method implementation |
650 |
|
* in case they do accept a "final" value for its function arguments. |
651 |
|
* |
652 |
|
* @param iArg - index of the function argument in question |
653 |
|
* (must be between 0 .. maxAllowedArgs() - 1) |
654 |
|
* @return true if a "final" value would be accepted for the respective |
655 |
|
* function argument by the function |
656 |
|
* |
657 |
|
* @see VMIntExpr::isFinal() |
658 |
|
*/ |
659 |
|
virtual bool acceptsArgFinal(vmint iArg) const; |
660 |
|
|
661 |
/** |
/** |
662 |
* This method is called by the parser to check whether some arguments |
* This method is called by the parser to check whether some arguments |
671 |
* @param iArg - index of the function argument in question |
* @param iArg - index of the function argument in question |
672 |
* (must be between 0 .. maxAllowedArgs() - 1) |
* (must be between 0 .. maxAllowedArgs() - 1) |
673 |
*/ |
*/ |
674 |
virtual bool modifiesArg(int iArg) const = 0; |
virtual bool modifiesArg(vmint iArg) const = 0; |
675 |
|
|
676 |
/** |
/** |
677 |
* Implements the actual function execution. This exec() method is |
* Implements the actual function execution. This exec() method is |
705 |
|
|
706 |
/** @brief Virtual machine relative pointer. |
/** @brief Virtual machine relative pointer. |
707 |
* |
* |
708 |
* POD base of VMIntRelPtr and VMInt8RelPtr structures. Not intended to be |
* POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not |
709 |
* used directly. Use VMIntRelPtr or VMInt8RelPtr instead. |
* intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr, |
710 |
|
* VMInt8RelPtr instead. |
711 |
* |
* |
712 |
* @see VMIntRelPtr, VMInt8RelPtr |
* @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr |
713 |
*/ |
*/ |
714 |
struct VMRelPtr { |
struct VMRelPtr { |
715 |
void** base; ///< Base pointer. |
void** base; ///< Base pointer. |
716 |
int offset; ///< Offset (in bytes) relative to base pointer. |
vmint offset; ///< Offset (in bytes) relative to base pointer. |
717 |
bool readonly; ///< Whether the pointed data may be modified or just be read. |
bool readonly; ///< Whether the pointed data may be modified or just be read. |
718 |
}; |
}; |
719 |
|
|
720 |
/** @brief Pointer to built-in VM integer variable (of C/C++ type int). |
/** @brief Pointer to built-in VM integer variable (interface class). |
721 |
|
* |
722 |
|
* This class acts as an abstract interface to all built-in integer script |
723 |
|
* variables, independent of their actual native size (i.e. some built-in |
724 |
|
* script variables are internally using a native int size of 64 bit or 32 |
725 |
|
* bit or 8 bit). The virtual machine is using this interface class instead |
726 |
|
* of its implementing descendants (VMInt64RelPtr, VMInt32RelPtr, |
727 |
|
* VMInt8RelPtr) in order for the virtual machine for not being required to |
728 |
|
* handle each of them differently. |
729 |
|
*/ |
730 |
|
struct VMIntPtr { |
731 |
|
virtual vmint evalInt() = 0; |
732 |
|
virtual void assign(vmint i) = 0; |
733 |
|
virtual bool isAssignable() const = 0; |
734 |
|
}; |
735 |
|
|
736 |
|
/** @brief Pointer to built-in VM integer variable (of C/C++ type int64_t). |
737 |
|
* |
738 |
|
* Used for defining built-in 64 bit integer script variables. |
739 |
|
* |
740 |
|
* @b CAUTION: You may only use this class for pointing to C/C++ variables |
741 |
|
* of type "int64_t" (thus being exactly 64 bit in size). If the C/C++ int |
742 |
|
* variable you want to reference is only 32 bit in size then you @b must |
743 |
|
* use VMInt32RelPtr instead! Respectively for a referenced native variable |
744 |
|
* with only 8 bit in size you @b must use VMInt8RelPtr instead! |
745 |
|
* |
746 |
|
* For efficiency reasons the actual native C/C++ int variable is referenced |
747 |
|
* by two components here. The actual native int C/C++ variable in memory |
748 |
|
* is dereferenced at VM run-time by taking the @c base pointer dereference |
749 |
|
* and adding @c offset bytes. This has the advantage that for a large |
750 |
|
* number of built-in int variables, only one (or few) base pointer need |
751 |
|
* to be re-assigned before running a script, instead of updating each |
752 |
|
* built-in variable each time before a script is executed. |
753 |
|
* |
754 |
|
* Refer to DECLARE_VMINT() for example code. |
755 |
|
* |
756 |
|
* @see VMInt32RelPtr, VMInt8RelPtr, DECLARE_VMINT() |
757 |
|
*/ |
758 |
|
struct VMInt64RelPtr : VMRelPtr, VMIntPtr { |
759 |
|
VMInt64RelPtr() { |
760 |
|
base = NULL; |
761 |
|
offset = 0; |
762 |
|
readonly = false; |
763 |
|
} |
764 |
|
VMInt64RelPtr(const VMRelPtr& data) { |
765 |
|
base = data.base; |
766 |
|
offset = data.offset; |
767 |
|
readonly = false; |
768 |
|
} |
769 |
|
vmint evalInt() OVERRIDE { |
770 |
|
return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset]; |
771 |
|
} |
772 |
|
void assign(vmint i) OVERRIDE { |
773 |
|
*(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i; |
774 |
|
} |
775 |
|
bool isAssignable() const OVERRIDE { return !readonly; } |
776 |
|
}; |
777 |
|
|
778 |
|
/** @brief Pointer to built-in VM integer variable (of C/C++ type int32_t). |
779 |
* |
* |
780 |
* Used for defining built-in 32 bit integer script variables. |
* Used for defining built-in 32 bit integer script variables. |
781 |
* |
* |
782 |
* @b CAUTION: You may only use this class for pointing to C/C++ variables |
* @b CAUTION: You may only use this class for pointing to C/C++ variables |
783 |
* of type "int" (which on most systems is 32 bit in size). If the C/C++ int |
* of type "int32_t" (thus being exactly 32 bit in size). If the C/C++ int |
784 |
* variable you want to reference is only 8 bit in size, then you @b must |
* variable you want to reference is 64 bit in size then you @b must use |
785 |
* use VMInt8RelPtr instead! |
* VMInt64RelPtr instead! Respectively for a referenced native variable with |
786 |
|
* only 8 bit in size you @b must use VMInt8RelPtr instead! |
787 |
* |
* |
788 |
* For efficiency reasons the actual native C/C++ int variable is referenced |
* For efficiency reasons the actual native C/C++ int variable is referenced |
789 |
* by two components here. The actual native int C/C++ variable in memory |
* by two components here. The actual native int C/C++ variable in memory |
795 |
* |
* |
796 |
* Refer to DECLARE_VMINT() for example code. |
* Refer to DECLARE_VMINT() for example code. |
797 |
* |
* |
798 |
* @see VMInt8RelPtr, DECLARE_VMINT() |
* @see VMInt64RelPtr, VMInt8RelPtr, DECLARE_VMINT() |
799 |
*/ |
*/ |
800 |
struct VMIntRelPtr : VMRelPtr { |
struct VMInt32RelPtr : VMRelPtr, VMIntPtr { |
801 |
VMIntRelPtr() { |
VMInt32RelPtr() { |
802 |
base = NULL; |
base = NULL; |
803 |
offset = 0; |
offset = 0; |
804 |
readonly = false; |
readonly = false; |
805 |
} |
} |
806 |
VMIntRelPtr(const VMRelPtr& data) { |
VMInt32RelPtr(const VMRelPtr& data) { |
807 |
base = data.base; |
base = data.base; |
808 |
offset = data.offset; |
offset = data.offset; |
809 |
readonly = false; |
readonly = false; |
810 |
} |
} |
811 |
virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; } |
vmint evalInt() OVERRIDE { |
812 |
virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; } |
return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset]; |
813 |
|
} |
814 |
|
void assign(vmint i) OVERRIDE { |
815 |
|
*(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i; |
816 |
|
} |
817 |
|
bool isAssignable() const OVERRIDE { return !readonly; } |
818 |
}; |
}; |
819 |
|
|
820 |
/** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t). |
/** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t). |
823 |
* |
* |
824 |
* @b CAUTION: You may only use this class for pointing to C/C++ variables |
* @b CAUTION: You may only use this class for pointing to C/C++ variables |
825 |
* of type "int8_t" (8 bit integer). If the C/C++ int variable you want to |
* of type "int8_t" (8 bit integer). If the C/C++ int variable you want to |
826 |
* reference is an "int" type (which is 32 bit on most systems), then you |
* reference is not exactly 8 bit in size then you @b must respectively use |
827 |
* @b must use VMIntRelPtr instead! |
* either VMInt32RelPtr for native 32 bit variables or VMInt64RelPtrl for |
828 |
|
* native 64 bit variables instead! |
829 |
* |
* |
830 |
* For efficiency reasons the actual native C/C++ int variable is referenced |
* For efficiency reasons the actual native C/C++ int variable is referenced |
831 |
* by two components here. The actual native int C/C++ variable in memory |
* by two components here. The actual native int C/C++ variable in memory |
837 |
* |
* |
838 |
* Refer to DECLARE_VMINT() for example code. |
* Refer to DECLARE_VMINT() for example code. |
839 |
* |
* |
840 |
* @see VMIntRelPtr, DECLARE_VMINT() |
* @see VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT() |
841 |
*/ |
*/ |
842 |
struct VMInt8RelPtr : VMIntRelPtr { |
struct VMInt8RelPtr : VMRelPtr, VMIntPtr { |
843 |
VMInt8RelPtr() : VMIntRelPtr() {} |
VMInt8RelPtr() { |
844 |
VMInt8RelPtr(const VMRelPtr& data) : VMIntRelPtr(data) {} |
base = NULL; |
845 |
virtual int evalInt() OVERRIDE { |
offset = 0; |
846 |
return *(uint8_t*)&(*(uint8_t**)base)[offset]; |
readonly = false; |
847 |
|
} |
848 |
|
VMInt8RelPtr(const VMRelPtr& data) { |
849 |
|
base = data.base; |
850 |
|
offset = data.offset; |
851 |
|
readonly = false; |
852 |
|
} |
853 |
|
vmint evalInt() OVERRIDE { |
854 |
|
return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset]; |
855 |
} |
} |
856 |
virtual void assign(int i) OVERRIDE { |
void assign(vmint i) OVERRIDE { |
857 |
*(uint8_t*)&(*(uint8_t**)base)[offset] = i; |
*(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i; |
858 |
} |
} |
859 |
|
bool isAssignable() const OVERRIDE { return !readonly; } |
860 |
}; |
}; |
861 |
|
|
862 |
|
/** @brief Pointer to built-in VM integer variable (of C/C++ type vmint). |
863 |
|
* |
864 |
|
* Use this typedef if the native variable to be pointed to is using the |
865 |
|
* typedef vmint. If the native C/C++ variable to be pointed to is using |
866 |
|
* another C/C++ type then better use one of VMInt64RelPtr or VMInt32RelPtr |
867 |
|
* instead. |
868 |
|
*/ |
869 |
|
typedef VMInt64RelPtr VMIntRelPtr; |
870 |
|
|
871 |
|
#if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS |
872 |
|
# define COMPILER_DISABLE_OFFSETOF_WARNING \ |
873 |
|
_Pragma("GCC diagnostic push") \ |
874 |
|
_Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"") |
875 |
|
# define COMPILER_RESTORE_OFFSETOF_WARNING \ |
876 |
|
_Pragma("GCC diagnostic pop") |
877 |
|
#else |
878 |
|
# define COMPILER_DISABLE_OFFSETOF_WARNING |
879 |
|
# define COMPILER_RESTORE_OFFSETOF_WARNING |
880 |
|
#endif |
881 |
|
|
882 |
/** |
/** |
883 |
* Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr |
* Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr and |
884 |
* structures. Usage example: |
* VMInt8RelPtr structures. Usage example: |
885 |
* @code |
* @code |
886 |
* struct Foo { |
* struct Foo { |
887 |
* uint8_t a; // native representation of a built-in integer script variable |
* uint8_t a; // native representation of a built-in integer script variable |
888 |
* int b; // native representation of another built-in integer script variable |
* int64_t b; // native representation of another built-in integer script variable |
889 |
* int c; // native representation of another built-in integer script variable |
* int64_t c; // native representation of another built-in integer script variable |
890 |
* uint8_t d; // native representation of another built-in integer script variable |
* uint8_t d; // native representation of another built-in integer script variable |
891 |
* }; |
* }; |
892 |
* |
* |
897 |
* Foo* pFoo; |
* Foo* pFoo; |
898 |
* |
* |
899 |
* VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a); |
* VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a); |
900 |
* VMIntRelPtr varB = DECLARE_VMINT(pFoo, class Foo, b); |
* VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b); |
901 |
* VMIntRelPtr varC = DECLARE_VMINT(pFoo, class Foo, c); |
* VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c); |
902 |
* VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d); |
* VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d); |
903 |
* |
* |
904 |
* pFoo = &foo1; |
* pFoo = &foo1; |
921 |
* complexity inside the sampler engines which provide the actual script |
* complexity inside the sampler engines which provide the actual script |
922 |
* functionalities. |
* functionalities. |
923 |
*/ |
*/ |
924 |
#define DECLARE_VMINT(basePtr, T_struct, T_member) ( \ |
#define DECLARE_VMINT(basePtr, T_struct, T_member) ( \ |
925 |
(VMRelPtr) { \ |
/* Disable offsetof warning, trust us, we are cautios. */ \ |
926 |
(void**) &basePtr, \ |
COMPILER_DISABLE_OFFSETOF_WARNING \ |
927 |
offsetof(T_struct, T_member), \ |
(VMRelPtr) { \ |
928 |
false \ |
(void**) &basePtr, \ |
929 |
} \ |
offsetof(T_struct, T_member), \ |
930 |
) \ |
false \ |
931 |
|
} \ |
932 |
|
COMPILER_RESTORE_OFFSETOF_WARNING \ |
933 |
|
) \ |
934 |
|
|
935 |
/** |
/** |
936 |
* Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and |
* Same as DECLARE_VMINT(), but this one defines the VMInt64RelPtr, |
937 |
* VMInt8RelPtr structures to be of read-only type. That means the script |
* VMInt32RelPtr and VMInt8RelPtr structures to be of read-only type. |
938 |
* parser will abort any script at parser time if the script is trying to |
* That means the script parser will abort any script at parser time if the |
939 |
* modify such a read-only built-in variable. |
* script is trying to modify such a read-only built-in variable. |
940 |
* |
* |
941 |
* @b NOTE: this is only intended for built-in read-only variables that |
* @b NOTE: this is only intended for built-in read-only variables that |
942 |
* may change during runtime! If your built-in variable's data is rather |
* may change during runtime! If your built-in variable's data is rather |
946 |
* @see ScriptVM::builtInConstIntVariables() |
* @see ScriptVM::builtInConstIntVariables() |
947 |
*/ |
*/ |
948 |
#define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \ |
#define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \ |
949 |
(VMRelPtr) { \ |
/* Disable offsetof warning, trust us, we are cautios. */ \ |
950 |
(void**) &basePtr, \ |
COMPILER_DISABLE_OFFSETOF_WARNING \ |
951 |
offsetof(T_struct, T_member), \ |
(VMRelPtr) { \ |
952 |
true \ |
(void**) &basePtr, \ |
953 |
} \ |
offsetof(T_struct, T_member), \ |
954 |
) \ |
true \ |
955 |
|
} \ |
956 |
|
COMPILER_RESTORE_OFFSETOF_WARNING \ |
957 |
|
) \ |
958 |
|
|
959 |
/** @brief Built-in VM 8 bit integer array variable. |
/** @brief Built-in VM 8 bit integer array variable. |
960 |
* |
* |
964 |
*/ |
*/ |
965 |
struct VMInt8Array { |
struct VMInt8Array { |
966 |
int8_t* data; |
int8_t* data; |
967 |
int size; |
vmint size; |
968 |
|
bool readonly; ///< Whether the array data may be modified or just be read. |
969 |
|
|
970 |
VMInt8Array() : data(NULL), size(0) {} |
VMInt8Array() : data(NULL), size(0), readonly(false) {} |
971 |
}; |
}; |
972 |
|
|
973 |
/** @brief Virtual machine script variable. |
/** @brief Virtual machine script variable. |
1055 |
* @param expr - new value to be assigned to this variable |
* @param expr - new value to be assigned to this variable |
1056 |
*/ |
*/ |
1057 |
void assignExpr(VMExpr* expr) OVERRIDE {} |
void assignExpr(VMExpr* expr) OVERRIDE {} |
1058 |
|
|
1059 |
|
virtual ~VMDynVar() {} |
1060 |
}; |
}; |
1061 |
|
|
1062 |
/** @brief Dynamically executed variable (of integer data type). |
/** @brief Dynamically executed variable (of integer data type). |
1067 |
*/ |
*/ |
1068 |
class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr { |
class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr { |
1069 |
public: |
public: |
1070 |
|
MetricPrefix_t unitPrefix(vmuint i) const OVERRIDE { return VM_NO_PREFIX; } |
1071 |
|
StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; } |
1072 |
|
bool isFinal() const OVERRIDE { return false; } |
1073 |
}; |
}; |
1074 |
|
|
1075 |
/** @brief Dynamically executed variable (of string data type). |
/** @brief Dynamically executed variable (of string data type). |
1082 |
public: |
public: |
1083 |
}; |
}; |
1084 |
|
|
1085 |
|
/** @brief Dynamically executed variable (of integer array data type). |
1086 |
|
* |
1087 |
|
* This is the base class for all built-in integer array script variables |
1088 |
|
* whose variable content needs to be provided dynamically by executable |
1089 |
|
* native code on each script variable access. |
1090 |
|
*/ |
1091 |
|
class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr { |
1092 |
|
public: |
1093 |
|
}; |
1094 |
|
|
1095 |
/** @brief Provider for built-in script functions and variables. |
/** @brief Provider for built-in script functions and variables. |
1096 |
* |
* |
1097 |
* Abstract base class defining the high-level interface for all classes |
* Abstract base class defining the high-level interface for all classes |
1110 |
virtual VMFunction* functionByName(const String& name) = 0; |
virtual VMFunction* functionByName(const String& name) = 0; |
1111 |
|
|
1112 |
/** |
/** |
1113 |
|
* Returns @c true if the passed built-in function is disabled and |
1114 |
|
* should be ignored by the parser. This method is called by the |
1115 |
|
* parser on preprocessor level for each built-in function call within |
1116 |
|
* a script. Accordingly if this method returns @c true, then the |
1117 |
|
* respective function call is completely filtered out on preprocessor |
1118 |
|
* level, so that built-in function won't make into the result virtual |
1119 |
|
* machine representation, nor would expressions of arguments passed to |
1120 |
|
* that built-in function call be evaluated, nor would any check |
1121 |
|
* regarding correct usage of the built-in function be performed. |
1122 |
|
* In other words: a disabled function call ends up as a comment block. |
1123 |
|
* |
1124 |
|
* @param fn - built-in function to be checked |
1125 |
|
* @param ctx - parser context at the position where the built-in |
1126 |
|
* function call is located within the script |
1127 |
|
*/ |
1128 |
|
virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0; |
1129 |
|
|
1130 |
|
/** |
1131 |
* Returns a variable name indexed map of all built-in script variables |
* Returns a variable name indexed map of all built-in script variables |
1132 |
* which point to native "int" scalar (usually 32 bit) variables. |
* which point to native "int" scalar (usually 32 bit) variables. |
1133 |
*/ |
*/ |
1134 |
virtual std::map<String,VMIntRelPtr*> builtInIntVariables() = 0; |
virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0; |
1135 |
|
|
1136 |
/** |
/** |
1137 |
* Returns a variable name indexed map of all built-in script integer |
* Returns a variable name indexed map of all built-in script integer |
1143 |
* Returns a variable name indexed map of all built-in constant script |
* Returns a variable name indexed map of all built-in constant script |
1144 |
* variables, which never change their value at runtime. |
* variables, which never change their value at runtime. |
1145 |
*/ |
*/ |
1146 |
virtual std::map<String,int> builtInConstIntVariables() = 0; |
virtual std::map<String,vmint> builtInConstIntVariables() = 0; |
1147 |
|
|
1148 |
/** |
/** |
1149 |
* Returns a variable name indexed map of all built-in dynamic variables, |
* Returns a variable name indexed map of all built-in dynamic variables, |
1192 |
* |
* |
1193 |
* @see ScriptVM::exec() |
* @see ScriptVM::exec() |
1194 |
*/ |
*/ |
1195 |
virtual int suspensionTimeMicroseconds() const = 0; |
virtual vmint suspensionTimeMicroseconds() const = 0; |
1196 |
|
|
1197 |
|
/** |
1198 |
|
* Causes all polyphonic variables to be reset to zero values. A |
1199 |
|
* polyphonic variable is expected to be zero when entering a new event |
1200 |
|
* handler instance. As an exception the values of polyphonic variables |
1201 |
|
* shall only be preserved from an note event handler instance to its |
1202 |
|
* correspending specific release handler instance. So in the latter |
1203 |
|
* case the script author may pass custom data from the note handler to |
1204 |
|
* the release handler, but only for the same specific note! |
1205 |
|
*/ |
1206 |
|
virtual void resetPolyphonicData() = 0; |
1207 |
|
|
1208 |
|
/** |
1209 |
|
* Returns amount of virtual machine instructions which have been |
1210 |
|
* performed the last time when this execution context was executing a |
1211 |
|
* script. So in case you need the overall amount of instructions |
1212 |
|
* instead, then you need to add them by yourself after each |
1213 |
|
* ScriptVM::exec() call. |
1214 |
|
*/ |
1215 |
|
virtual size_t instructionsPerformed() const = 0; |
1216 |
|
|
1217 |
|
/** |
1218 |
|
* Sends a signal to this script execution instance to abort its script |
1219 |
|
* execution as soon as possible. This method is called i.e. when one |
1220 |
|
* script execution instance intends to stop another script execution |
1221 |
|
* instance. |
1222 |
|
*/ |
1223 |
|
virtual void signalAbort() = 0; |
1224 |
|
|
1225 |
|
/** |
1226 |
|
* Copies the current entire execution state from this object to the |
1227 |
|
* given object. So this can be used to "fork" a new script thread which |
1228 |
|
* then may run independently with its own polyphonic data for instance. |
1229 |
|
*/ |
1230 |
|
virtual void forkTo(VMExecContext* ectx) const = 0; |
1231 |
|
|
1232 |
|
/** |
1233 |
|
* In case the script called the built-in exit() function and passed a |
1234 |
|
* value as argument to the exit() function, then this method returns |
1235 |
|
* the value that had been passed as argument to the exit() function. |
1236 |
|
* Otherwise if the exit() function has not been called by the script |
1237 |
|
* or no argument had been passed to the exit() function, then this |
1238 |
|
* method returns NULL instead. |
1239 |
|
* |
1240 |
|
* Currently this is only used for automated test cases against the |
1241 |
|
* script engine, which return some kind of value in the individual |
1242 |
|
* test case scripts to check their behaviour in automated way. There |
1243 |
|
* is no purpose for this mechanism in production use. Accordingly this |
1244 |
|
* exit result value is @b always completely ignored by the sampler |
1245 |
|
* engines. |
1246 |
|
* |
1247 |
|
* Officially the built-in exit() function does not expect any arguments |
1248 |
|
* to be passed to its function call, and by default this feature is |
1249 |
|
* hence disabled and will yield in a parser error unless |
1250 |
|
* ScriptVM::setExitResultEnabled() was explicitly set. |
1251 |
|
* |
1252 |
|
* @see ScriptVM::setExitResultEnabled() |
1253 |
|
*/ |
1254 |
|
virtual VMExpr* exitResult() = 0; |
1255 |
}; |
}; |
1256 |
|
|
1257 |
/** @brief Script callback for a certain event. |
/** @brief Script callback for a certain event. |
1283 |
}; |
}; |
1284 |
|
|
1285 |
/** |
/** |
1286 |
|
* Reflects the precise position and span of a specific code block within |
1287 |
|
* a script. This is currently only used for the locations of commented |
1288 |
|
* code blocks due to preprocessor statements, and for parser errors and |
1289 |
|
* parser warnings. |
1290 |
|
* |
1291 |
|
* @see ParserIssue for code locations of parser errors and parser warnings |
1292 |
|
* |
1293 |
|
* @see VMParserContext::preprocessorComments() for locations of code which |
1294 |
|
* have been filtered out by preprocessor statements |
1295 |
|
*/ |
1296 |
|
struct CodeBlock { |
1297 |
|
int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line). |
1298 |
|
int lastLine; ///< The last line number of this code block within the script. |
1299 |
|
int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column). |
1300 |
|
int lastColumn; ///< The last column of this code block within the script. |
1301 |
|
}; |
1302 |
|
|
1303 |
|
/** |
1304 |
* Encapsulates a noteworty parser issue. This encompasses the type of the |
* Encapsulates a noteworty parser issue. This encompasses the type of the |
1305 |
* issue (either a parser error or parser warning), a human readable |
* issue (either a parser error or parser warning), a human readable |
1306 |
* explanation text of the error or warning and the location of the |
* explanation text of the error or warning and the location of the |
1307 |
* encountered parser issue within the script. |
* encountered parser issue within the script. |
1308 |
|
* |
1309 |
|
* @see VMSourceToken for processing syntax highlighting instead. |
1310 |
*/ |
*/ |
1311 |
struct ParserIssue { |
struct ParserIssue : CodeBlock { |
1312 |
String txt; ///< Human readable explanation text of the parser issue. |
String txt; ///< Human readable explanation text of the parser issue. |
|
int firstLine; ///< The first line number within the script where this issue was encountered (indexed with 1 being the very first line). |
|
|
int lastLine; ///< The last line number within the script where this issue was encountered. |
|
|
int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column). |
|
|
int lastColumn; ///< The last column within the script where this issue was encountered. |
|
1313 |
ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning. |
ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning. |
1314 |
|
|
1315 |
/** |
/** |
1355 |
return "invalid"; |
return "invalid"; |
1356 |
} |
} |
1357 |
|
|
1358 |
|
/** |
1359 |
|
* Convenience function used for converting an StdUnit_t constant to a |
1360 |
|
* string, i.e. for generating error message by the parser. |
1361 |
|
*/ |
1362 |
|
inline String unitTypeStr(const StdUnit_t& type) { |
1363 |
|
switch (type) { |
1364 |
|
case VM_NO_UNIT: return "none"; |
1365 |
|
case VM_SECOND: return "seconds"; |
1366 |
|
case VM_HERTZ: return "Hz"; |
1367 |
|
case VM_BEL: return "Bel"; |
1368 |
|
} |
1369 |
|
return "invalid"; |
1370 |
|
} |
1371 |
|
|
1372 |
/** @brief Virtual machine representation of a script. |
/** @brief Virtual machine representation of a script. |
1373 |
* |
* |
1374 |
* An instance of this abstract base class represents a parsed script, |
* An instance of this abstract base class represents a parsed script, |
1403 |
virtual std::vector<ParserIssue> warnings() const = 0; |
virtual std::vector<ParserIssue> warnings() const = 0; |
1404 |
|
|
1405 |
/** |
/** |
1406 |
|
* Returns all code blocks of the script which were filtered out by the |
1407 |
|
* preprocessor. |
1408 |
|
*/ |
1409 |
|
virtual std::vector<CodeBlock> preprocessorComments() const = 0; |
1410 |
|
|
1411 |
|
/** |
1412 |
* Returns the translated virtual machine representation of an event |
* Returns the translated virtual machine representation of an event |
1413 |
* handler block (i.e. "on note ... end on" code block) within the |
* handler block (i.e. "on note ... end on" code block) within the |
1414 |
* parsed script. This translated representation of the event handler |
* parsed script. This translated representation of the event handler |
1441 |
* This class is not actually used by the sampler itself. It is rather |
* This class is not actually used by the sampler itself. It is rather |
1442 |
* provided for external script editor applications. Primary purpose of |
* provided for external script editor applications. Primary purpose of |
1443 |
* this class is syntax highlighting for external script editors. |
* this class is syntax highlighting for external script editors. |
1444 |
|
* |
1445 |
|
* @see ParserIssue for processing compile errors and warnings instead. |
1446 |
*/ |
*/ |
1447 |
class VMSourceToken { |
class VMSourceToken { |
1448 |
public: |
public: |
1455 |
String text() const; |
String text() const; |
1456 |
|
|
1457 |
// position of token in script |
// position of token in script |
1458 |
int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line). |
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. |
1459 |
int firstColumn() const; ///< Last line this source token is located at in script source code. |
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(). |
1460 |
|
|
1461 |
// base types |
// base types |
1462 |
bool isEOF() const; |
bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file. |
1463 |
bool isNewLine() const; |
bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems). |
1464 |
bool isKeyword() const; |
bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.). |
1465 |
bool isVariableName() const; |
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. |
1466 |
bool isIdentifier() const; |
bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name. |
1467 |
bool isNumberLiteral() const; |
bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123). |
1468 |
bool isStringLiteral() const; |
bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text"). |
1469 |
bool isComment() const; |
bool isComment() const; ///< Returns true in case this source token represents a source code comment. |
1470 |
bool isPreprocessor() const; |
bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement. |
1471 |
bool isOther() const; |
bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above. |
1472 |
|
|
1473 |
// extended types |
// extended types |
1474 |
bool isIntegerVariable() const; |
bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable"). |
1475 |
bool isStringVariable() const; |
bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable"). |
1476 |
bool isArrayVariable() const; |
bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable"). |
1477 |
bool isEventHandlerName() const; |
bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller"). |
1478 |
|
|
1479 |
VMSourceToken& operator=(const VMSourceToken& other); |
VMSourceToken& operator=(const VMSourceToken& other); |
1480 |
|
|