/[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 3277 - (hide annotations) (download) (as text)
Mon Jun 5 18:40:18 2017 UTC (6 years, 9 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 49651 byte(s)
* NKSP: Implemented built-in script function "abort()" which allows
  to abort another script handler by passing its callback ID.
* Bumped version (2.0.0.svn61).

1 schoenebeck 2581 /*
2 schoenebeck 3073 * Copyright (c) 2014-2017 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     // (located at other source directories).
13    
14     #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H
15     #define LS_INSTR_SCRIPT_PARSER_COMMON_H
16    
17     #include "../common/global.h"
18 schoenebeck 2588 #include <vector>
19 schoenebeck 2594 #include <map>
20     #include <stddef.h> // offsetof()
21 schoenebeck 2581
22     namespace LinuxSampler {
23 schoenebeck 2727
24     /**
25     * Identifies the type of a noteworthy issue identified by the script
26     * parser. That's either a parser error or parser warning.
27     */
28 schoenebeck 2581 enum ParserIssueType_t {
29 schoenebeck 2727 PARSER_ERROR, ///< Script parser encountered an error, the script cannot be executed.
30     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.
31 schoenebeck 2581 };
32    
33 schoenebeck 2727 /** @brief Expression's data type.
34     *
35     * Identifies to which data type an expression within a script evaluates to.
36     * This can for example reflect the data type of script function arguments,
37     * script function return values, but also the resulting data type of some
38     * mathematical formula within a script.
39     */
40 schoenebeck 2581 enum ExprType_t {
41 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)
42     INT_EXPR, ///< integer (scalar) expression
43     INT_ARR_EXPR, ///< integer array expression
44     STRING_EXPR, ///< string expression
45     STRING_ARR_EXPR, ///< string array expression
46 schoenebeck 2581 };
47    
48 schoenebeck 2727 /** @brief Result flags of a script statement or script function call.
49     *
50     * A set of bit flags which provide informations about the success or
51     * failure of a statement within a script. That's also especially used for
52     * providing informations about success / failure of a call to a built-in
53     * script function. The virtual machine evaluates these flags during runtime
54     * to decide whether it should i.e. stop or suspend execution of a script.
55     *
56     * Since these are bit flags, these constants are bitwise combined.
57     */
58 schoenebeck 2581 enum StmtFlags_t {
59     STMT_SUCCESS = 0, ///< Function / statement was executed successfully, no error occurred.
60 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).
61     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
62     STMT_ERROR_OCCURRED = (1<<2), ///< VM stopped execution due to some script runtime error that occurred
63 schoenebeck 2581 };
64    
65 schoenebeck 2727 /** @brief Virtual machine execution status.
66     *
67     * A set of bit flags which reflect the current overall execution status of
68     * the virtual machine concerning a certain script execution instance.
69     *
70     * Since these are bit flags, these constants are bitwise combined.
71     */
72 schoenebeck 2581 enum VMExecStatus_t {
73 schoenebeck 2727 VM_EXEC_NOT_RUNNING = 0, ///< Script is currently not executed by the VM.
74     VM_EXEC_RUNNING = 1, ///< The VM is currently executing the script.
75     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.
76     VM_EXEC_ERROR = (1<<2), ///< A runtime error occurred while executing the script (i.e. a call to some built-in script function failed).
77 schoenebeck 2581 };
78    
79 schoenebeck 2879 /** @brief Script event handler type.
80     *
81     * Identifies one of the possible event handler callback types defined by
82     * the NKSP script language.
83     */
84     enum VMEventHandlerType_t {
85     VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block.
86     VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block.
87     VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block.
88     VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block.
89     };
90    
91 schoenebeck 2727 // just symbol prototyping
92 schoenebeck 2596 class VMIntExpr;
93     class VMStringExpr;
94 schoenebeck 2619 class VMIntArrayExpr;
95     class VMStringArrayExpr;
96 schoenebeck 2596
97 schoenebeck 2727 /** @brief Virtual machine expression
98     *
99     * This is the abstract base class for all expressions of scripts.
100     * Deriving classes must implement the abstract method exprType().
101     *
102     * An expression within a script is translated into one instance of this
103     * class. It allows a high level access for the virtual machine to evaluate
104     * and handle expressions appropriately during execution. Expressions are
105     * for example all kinds of formulas, function calls, statements or a
106     * combination of them. Most of them evaluate to some kind of value, which
107     * might be further processed as part of encompassing expressions to outer
108     * expression results and so forth.
109     */
110 schoenebeck 2581 class VMExpr {
111     public:
112 schoenebeck 2727 /**
113     * Identifies the data type to which the result of this expression
114     * evaluates to. This abstract method must be implemented by deriving
115     * classes.
116     */
117 schoenebeck 2581 virtual ExprType_t exprType() const = 0;
118 schoenebeck 2727
119     /**
120     * In case this expression is an integer expression, then this method
121     * returns a casted pointer to that VMIntExpr object. It returns NULL
122     * if this expression is not an integer expression.
123     *
124     * @b Note: type casting performed by this method is strict! That means
125     * if this expression is i.e. actually a string expression like "12",
126     * calling asInt() will @b not cast that numerical string expression to
127     * an integer expression 12 for you, instead this method will simply
128     * return NULL!
129     *
130     * @see exprType()
131     */
132 schoenebeck 2596 VMIntExpr* asInt() const;
133 schoenebeck 2727
134     /**
135     * In case this expression is a string expression, then this method
136     * returns a casted pointer to that VMStringExpr object. It returns NULL
137     * if this expression is not a string expression.
138     *
139     * @b Note: type casting performed by this method is strict! That means
140     * if this expression is i.e. actually an integer expression like 120,
141     * calling asString() will @b not cast that integer expression to a
142     * string expression "120" for you, instead this method will simply
143     * return NULL!
144     *
145     * @see exprType()
146     */
147 schoenebeck 2596 VMStringExpr* asString() const;
148 schoenebeck 2727
149     /**
150     * In case this expression is an integer array expression, then this
151     * method returns a casted pointer to that VMIntArrayExpr object. It
152     * returns NULL if this expression is not an integer array expression.
153     *
154     * @b Note: type casting performed by this method is strict! That means
155     * if this expression is i.e. an integer expression or a string
156     * expression, calling asIntArray() will @b not cast those scalar
157     * expressions to an array expression for you, instead this method will
158     * simply return NULL!
159     *
160 schoenebeck 3056 * @b Note: this method is currently, and in contrast to its other
161     * counter parts, declared as virtual method. Some deriving classes are
162     * currently using this to override this default implementation in order
163     * to implement an "evaluate now as integer array" behavior. This has
164     * efficiency reasons, however this also currently makes this part of
165     * the API less clean and should thus be addressed in future with
166     * appropriate changes to the API.
167     *
168 schoenebeck 2727 * @see exprType()
169     */
170 schoenebeck 3056 virtual VMIntArrayExpr* asIntArray() const;
171 schoenebeck 2945
172     /**
173     * Returns true in case this expression can be considered to be a
174     * constant expression. A constant expression will retain the same
175     * value throughout the entire life time of a script and the
176     * expression's constant value may be evaluated already at script
177     * parse time, which may result in performance benefits during script
178     * runtime.
179 schoenebeck 2960 *
180     * @b NOTE: A constant expression is per se always also non modifyable.
181     * But a non modifyable expression may not necessarily be a constant
182     * expression!
183     *
184     * @see isModifyable()
185 schoenebeck 2945 */
186     virtual bool isConstExpr() const = 0;
187    
188 schoenebeck 2960 /**
189     * Returns true in case this expression is allowed to be modified.
190     * If this method returns @c false then this expression must be handled
191     * as read-only expression, which means that assigning a new value to it
192     * is either not possible or not allowed.
193     *
194     * @b NOTE: A constant expression is per se always also non modifyable.
195     * But a non modifyable expression may not necessarily be a constant
196     * expression!
197     *
198     * @see isConstExpr()
199     */
200 schoenebeck 2945 bool isModifyable() const;
201 schoenebeck 2581 };
202    
203 schoenebeck 2727 /** @brief Virtual machine integer expression
204     *
205     * This is the abstract base class for all expressions inside scripts which
206     * evaluate to an integer (scalar) value. Deriving classes implement the
207     * abstract method evalInt() to return the actual integer result value of
208     * the expression.
209     */
210 schoenebeck 2581 class VMIntExpr : virtual public VMExpr {
211     public:
212 schoenebeck 2727 /**
213     * Returns the result of this expression as integer (scalar) value.
214     * This abstract method must be implemented by deriving classes.
215     */
216 schoenebeck 2581 virtual int evalInt() = 0;
217 schoenebeck 2727
218     /**
219     * Returns always INT_EXPR for instances of this class.
220     */
221     ExprType_t exprType() const OVERRIDE { return INT_EXPR; }
222 schoenebeck 2581 };
223    
224 schoenebeck 2727 /** @brief Virtual machine string expression
225     *
226     * This is the abstract base class for all expressions inside scripts which
227     * evaluate to a string value. Deriving classes implement the abstract
228     * method evalStr() to return the actual string result value of the
229     * expression.
230     */
231 schoenebeck 2581 class VMStringExpr : virtual public VMExpr {
232     public:
233 schoenebeck 2727 /**
234     * Returns the result of this expression as string value. This abstract
235     * method must be implemented by deriving classes.
236     */
237 schoenebeck 2581 virtual String evalStr() = 0;
238 schoenebeck 2727
239     /**
240     * Returns always STRING_EXPR for instances of this class.
241     */
242     ExprType_t exprType() const OVERRIDE { return STRING_EXPR; }
243 schoenebeck 2581 };
244    
245 schoenebeck 2727 /** @brief Virtual Machine Array Value Expression
246     *
247     * This is the abstract base class for all expressions inside scripts which
248     * evaluate to some kind of array value. Deriving classes implement the
249     * abstract method arraySize() to return the amount of elements within the
250     * array.
251     */
252 schoenebeck 2619 class VMArrayExpr : virtual public VMExpr {
253     public:
254 schoenebeck 2727 /**
255     * Returns amount of elements in this array. This abstract method must
256     * be implemented by deriving classes.
257     */
258 schoenebeck 2619 virtual int arraySize() const = 0;
259     };
260    
261 schoenebeck 2727 /** @brief Virtual Machine Integer Array Expression
262     *
263     * This is the abstract base class for all expressions inside scripts which
264     * evaluate to an array of integer values. Deriving classes implement the
265     * abstract methods arraySize(), evalIntElement() and assignIntElement() to
266     * access the individual integer array values.
267     */
268 schoenebeck 2619 class VMIntArrayExpr : virtual public VMArrayExpr {
269     public:
270 schoenebeck 2727 /**
271     * Returns the (scalar) integer value of the array element given by
272     * element index @a i.
273     *
274     * @param i - array element index (must be between 0 .. arraySize() - 1)
275     */
276 schoenebeck 2619 virtual int evalIntElement(uint i) = 0;
277 schoenebeck 2727
278     /**
279     * Changes the current value of an element (given by array element
280     * index @a i) of this integer array.
281     *
282     * @param i - array element index (must be between 0 .. arraySize() - 1)
283     * @param value - new integer scalar value to be assigned to that array element
284     */
285 schoenebeck 2619 virtual void assignIntElement(uint i, int value) = 0;
286 schoenebeck 2727
287     /**
288     * Returns always INT_ARR_EXPR for instances of this class.
289     */
290     ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }
291 schoenebeck 2619 };
292    
293 schoenebeck 2727 /** @brief Arguments (parameters) for being passed to a built-in script function.
294     *
295     * An argument or a set of arguments passed to a script function are
296     * translated by the parser to an instance of this class. This abstract
297     * interface class is used by implementations of built-in functions to
298     * obtain the individual function argument values being passed to them at
299     * runtime.
300     */
301 schoenebeck 2581 class VMFnArgs {
302     public:
303 schoenebeck 2727 /**
304     * Returns the amount of arguments going to be passed to the script
305     * function.
306     */
307 schoenebeck 2581 virtual int argsCount() const = 0;
308 schoenebeck 2727
309     /**
310     * Returns the respective argument (requested by argument index @a i) of
311     * this set of arguments. This method is called by implementations of
312     * built-in script functions to obtain the value of each function
313     * argument passed to the function at runtime.
314     *
315     * @param i - function argument index (indexed from left to right)
316     */
317 schoenebeck 2581 virtual VMExpr* arg(int i) = 0;
318     };
319    
320 schoenebeck 2727 /** @brief Result value returned from a call to a built-in script function.
321     *
322     * Implementations of built-in script functions return an instance of this
323     * object to let the virtual machine obtain the result value of the function
324     * call, which might then be further processed by the virtual machine
325     * according to the script. It also provides informations about the success
326     * or failure of the function call.
327     */
328 schoenebeck 2581 class VMFnResult {
329     public:
330 schoenebeck 2727 /**
331     * Returns the result value of the function call, represented by a high
332     * level expression object.
333     */
334 schoenebeck 2581 virtual VMExpr* resultValue() = 0;
335 schoenebeck 2727
336     /**
337     * Provides detailed informations of the success / failure of the
338     * function call. The virtual machine is evaluating the flags returned
339     * here to decide whether it must abort or suspend execution of the
340     * script at this point.
341     */
342 schoenebeck 2581 virtual StmtFlags_t resultFlags() { return STMT_SUCCESS; }
343     };
344    
345 schoenebeck 2727 /** @brief Virtual machine built-in function.
346 schoenebeck 2612 *
347     * Abstract base class for built-in script functions, defining the interface
348 schoenebeck 2727 * for all built-in script function implementations. All built-in script
349     * functions are deriving from this abstract interface class in order to
350     * provide their functionality to the virtual machine with this unified
351     * interface.
352     *
353     * The methods of this interface class provide two purposes:
354     *
355     * 1. When a script is loaded, the script parser uses the methods of this
356     * interface to check whether the script author was calling the
357     * respective built-in script function in a correct way. For example
358     * the parser checks whether the required amount of parameters were
359     * passed to the function and whether the data types passed match the
360     * data types expected by the function. If not, loading the script will
361     * be aborted with a parser error, describing to the user (i.e. script
362     * author) the precise misusage of the respective function.
363     * 2. After the script was loaded successfully and the script is executed,
364     * the virtual machine calls the exec() method of the respective built-in
365     * function to provide the actual functionality of the built-in function
366     * call.
367 schoenebeck 2612 */
368 schoenebeck 2581 class VMFunction {
369     public:
370 schoenebeck 2612 /**
371     * Script data type of the function's return value. If the function does
372 schoenebeck 2727 * not return any value (void), then it returns EMPTY_EXPR here.
373 schoenebeck 2612 */
374 schoenebeck 2581 virtual ExprType_t returnType() = 0;
375 schoenebeck 2612
376     /**
377     * Minimum amount of function arguments this function accepts. If a
378     * script is calling this function with less arguments, the script
379     * parser will throw a parser error.
380     */
381 schoenebeck 2581 virtual int minRequiredArgs() const = 0;
382 schoenebeck 2612
383     /**
384     * Maximum amount of function arguments this functions accepts. If a
385     * script is calling this function with more arguments, the script
386     * parser will throw a parser error.
387     */
388 schoenebeck 2581 virtual int maxAllowedArgs() const = 0;
389 schoenebeck 2612
390     /**
391     * Script data type of the function's @c iArg 'th function argument.
392     * The information provided here is less strong than acceptsArgType().
393     * The parser will compare argument data types provided in scripts by
394 schoenebeck 2871 * calling acceptsArgType(). The return value of argType() is used by the
395 schoenebeck 2612 * parser instead to show an appropriate parser error which data type
396     * this function usually expects as "default" data type. Reason: a
397     * function may accept multiple data types for a certain function
398     * argument and would automatically cast the passed argument value in
399     * that case to the type it actually needs.
400     *
401     * @param iArg - index of the function argument in question
402 schoenebeck 2727 * (must be between 0 .. maxAllowedArgs() - 1)
403 schoenebeck 2612 */
404 schoenebeck 2581 virtual ExprType_t argType(int iArg) const = 0;
405 schoenebeck 2612
406     /**
407 schoenebeck 2945 * This method is called by the parser to check whether arguments
408 schoenebeck 2612 * passed in scripts to this function are accepted by this function. If
409     * a script calls this function with an argument's data type not
410 schoenebeck 2727 * accepted by this function, the parser will throw a parser error. On
411     * such errors the data type returned by argType() will be used to
412     * assemble an appropriate error message regarding the precise misusage
413     * of the built-in function.
414 schoenebeck 2612 *
415     * @param iArg - index of the function argument in question
416 schoenebeck 2727 * (must be between 0 .. maxAllowedArgs() - 1)
417 schoenebeck 2612 * @param type - script data type used for this function argument by
418     * currently parsed script
419 schoenebeck 2727 * @return true if the given data type would be accepted for the
420     * respective function argument by the function
421 schoenebeck 2612 */
422 schoenebeck 2581 virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;
423 schoenebeck 2612
424     /**
425 schoenebeck 2945 * This method is called by the parser to check whether some arguments
426     * (and if yes which ones) passed to this script function will be
427     * modified by this script function. Most script functions simply use
428     * their arguments as inputs, that is they only read the argument's
429     * values. However some script function may also use passed
430     * argument(s) as output variables. In this case the function
431     * implementation must return @c true for the respective argument
432     * index here.
433     *
434     * @param iArg - index of the function argument in question
435     * (must be between 0 .. maxAllowedArgs() - 1)
436     */
437     virtual bool modifiesArg(int iArg) const = 0;
438    
439     /**
440 schoenebeck 2727 * Implements the actual function execution. This exec() method is
441     * called by the VM whenever this function implementation shall be
442     * executed at script runtime. This method blocks until the function
443     * call completed.
444 schoenebeck 2612 *
445     * @param args - function arguments for executing this built-in function
446 schoenebeck 2727 * @returns function's return value (if any) and general status
447     * informations (i.e. whether the function call caused a
448     * runtime error)
449 schoenebeck 2612 */
450 schoenebeck 2581 virtual VMFnResult* exec(VMFnArgs* args) = 0;
451 schoenebeck 2612
452     /**
453 schoenebeck 2727 * Convenience method for function implementations to show warning
454     * messages during actual execution of the built-in function.
455 schoenebeck 2612 *
456 schoenebeck 2727 * @param txt - runtime warning text to be shown to user
457 schoenebeck 2612 */
458 schoenebeck 2598 void wrnMsg(const String& txt);
459 schoenebeck 2612
460     /**
461 schoenebeck 2727 * Convenience method for function implementations to show error
462     * messages during actual execution of the built-in function.
463 schoenebeck 2612 *
464 schoenebeck 2727 * @param txt - runtime error text to be shown to user
465 schoenebeck 2612 */
466 schoenebeck 2598 void errMsg(const String& txt);
467 schoenebeck 2581 };
468    
469 schoenebeck 2727 /** @brief Virtual machine relative pointer.
470     *
471 schoenebeck 2594 * POD base of VMIntRelPtr and VMInt8RelPtr structures. Not intended to be
472     * used directly. Use VMIntRelPtr or VMInt8RelPtr instead.
473 schoenebeck 2727 *
474     * @see VMIntRelPtr, VMInt8RelPtr
475 schoenebeck 2594 */
476     struct VMRelPtr {
477     void** base; ///< Base pointer.
478 schoenebeck 2727 int offset; ///< Offset (in bytes) relative to base pointer.
479 schoenebeck 2948 bool readonly; ///< Whether the pointed data may be modified or just be read.
480 schoenebeck 2594 };
481    
482     /** @brief Pointer to built-in VM integer variable (of C/C++ type int).
483     *
484 schoenebeck 2727 * Used for defining built-in 32 bit integer script variables.
485 schoenebeck 2594 *
486     * @b CAUTION: You may only use this class for pointing to C/C++ variables
487     * of type "int" (which on most systems is 32 bit in size). If the C/C++ int
488     * variable you want to reference is only 8 bit in size, then you @b must
489     * use VMInt8RelPtr instead!
490     *
491     * For efficiency reasons the actual native C/C++ int variable is referenced
492     * by two components here. The actual native int C/C++ variable in memory
493     * is dereferenced at VM run-time by taking the @c base pointer dereference
494     * and adding @c offset bytes. This has the advantage that for a large
495     * number of built-in int variables, only one (or few) base pointer need
496     * to be re-assigned before running a script, instead of updating each
497     * built-in variable each time before a script is executed.
498     *
499     * Refer to DECLARE_VMINT() for example code.
500     *
501     * @see VMInt8RelPtr, DECLARE_VMINT()
502     */
503     struct VMIntRelPtr : VMRelPtr {
504     VMIntRelPtr() {
505     base = NULL;
506     offset = 0;
507 schoenebeck 2948 readonly = false;
508 schoenebeck 2594 }
509     VMIntRelPtr(const VMRelPtr& data) {
510     base = data.base;
511     offset = data.offset;
512 schoenebeck 2948 readonly = false;
513 schoenebeck 2594 }
514     virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }
515     virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }
516     };
517    
518     /** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t).
519     *
520 schoenebeck 2727 * Used for defining built-in 8 bit integer script variables.
521 schoenebeck 2594 *
522     * @b CAUTION: You may only use this class for pointing to C/C++ variables
523     * of type "int8_t" (8 bit integer). If the C/C++ int variable you want to
524     * reference is an "int" type (which is 32 bit on most systems), then you
525     * @b must use VMIntRelPtr instead!
526     *
527     * For efficiency reasons the actual native C/C++ int variable is referenced
528     * by two components here. The actual native int C/C++ variable in memory
529     * is dereferenced at VM run-time by taking the @c base pointer dereference
530     * and adding @c offset bytes. This has the advantage that for a large
531     * number of built-in int variables, only one (or few) base pointer need
532     * to be re-assigned before running a script, instead of updating each
533     * built-in variable each time before a script is executed.
534     *
535     * Refer to DECLARE_VMINT() for example code.
536     *
537     * @see VMIntRelPtr, DECLARE_VMINT()
538     */
539     struct VMInt8RelPtr : VMIntRelPtr {
540     VMInt8RelPtr() : VMIntRelPtr() {}
541     VMInt8RelPtr(const VMRelPtr& data) : VMIntRelPtr(data) {}
542     virtual int evalInt() OVERRIDE {
543     return *(uint8_t*)&(*(uint8_t**)base)[offset];
544     }
545     virtual void assign(int i) OVERRIDE {
546     *(uint8_t*)&(*(uint8_t**)base)[offset] = i;
547     }
548     };
549    
550 schoenebeck 3035 #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
551     # define COMPILER_DISABLE_OFFSETOF_WARNING \
552     _Pragma("GCC diagnostic push") \
553     _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"")
554     # define COMPILER_RESTORE_OFFSETOF_WARNING \
555     _Pragma("GCC diagnostic pop")
556     #else
557     # define COMPILER_DISABLE_OFFSETOF_WARNING
558     # define COMPILER_RESTORE_OFFSETOF_WARNING
559     #endif
560    
561 schoenebeck 2594 /**
562     * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr
563 schoenebeck 2727 * structures. Usage example:
564 schoenebeck 2594 * @code
565     * struct Foo {
566 schoenebeck 2727 * uint8_t a; // native representation of a built-in integer script variable
567     * int b; // native representation of another built-in integer script variable
568     * int c; // native representation of another built-in integer script variable
569     * uint8_t d; // native representation of another built-in integer script variable
570 schoenebeck 2594 * };
571     *
572 schoenebeck 2727 * // initializing the built-in script variables to some values
573     * Foo foo1 = (Foo) { 1, 2000, 3000, 4 };
574     * Foo foo2 = (Foo) { 5, 6000, 7000, 8 };
575 schoenebeck 2594 *
576     * Foo* pFoo;
577     *
578 schoenebeck 2727 * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);
579     * VMIntRelPtr varB = DECLARE_VMINT(pFoo, class Foo, b);
580     * VMIntRelPtr varC = DECLARE_VMINT(pFoo, class Foo, c);
581     * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);
582 schoenebeck 2594 *
583     * pFoo = &foo1;
584 schoenebeck 2727 * printf("%d\n", varA->evalInt()); // will print 1
585     * printf("%d\n", varB->evalInt()); // will print 2000
586     * printf("%d\n", varC->evalInt()); // will print 3000
587     * printf("%d\n", varD->evalInt()); // will print 4
588 schoenebeck 2594 *
589 schoenebeck 2727 * // same printf() code, just with pFoo pointer being changed ...
590     *
591 schoenebeck 2594 * pFoo = &foo2;
592 schoenebeck 2727 * printf("%d\n", varA->evalInt()); // will print 5
593     * printf("%d\n", varB->evalInt()); // will print 6000
594     * printf("%d\n", varC->evalInt()); // will print 7000
595     * printf("%d\n", varD->evalInt()); // will print 8
596 schoenebeck 2594 * @endcode
597 schoenebeck 2727 * As you can see above, by simply changing one single pointer, you can
598     * remap a huge bunch of built-in integer script variables to completely
599     * different native values/native variables. Which especially reduces code
600     * complexity inside the sampler engines which provide the actual script
601     * functionalities.
602 schoenebeck 2594 */
603 schoenebeck 3034 #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \
604     /* Disable offsetof warning, trust us, we are cautios. */ \
605 schoenebeck 3035 COMPILER_DISABLE_OFFSETOF_WARNING \
606 schoenebeck 3034 (VMRelPtr) { \
607     (void**) &basePtr, \
608     offsetof(T_struct, T_member), \
609     false \
610     } \
611 schoenebeck 3035 COMPILER_RESTORE_OFFSETOF_WARNING \
612 schoenebeck 3034 ) \
613 schoenebeck 2594
614 schoenebeck 2948 /**
615     * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
616     * VMInt8RelPtr structures to be of read-only type. That means the script
617     * parser will abort any script at parser time if the script is trying to
618     * modify such a read-only built-in variable.
619     *
620     * @b NOTE: this is only intended for built-in read-only variables that
621     * may change during runtime! If your built-in variable's data is rather
622     * already available at parser time and won't change during runtime, then
623     * you should rather register a built-in constant in your VM class instead!
624     *
625     * @see ScriptVM::builtInConstIntVariables()
626     */
627     #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
628 schoenebeck 3034 /* Disable offsetof warning, trust us, we are cautios. */ \
629 schoenebeck 3035 COMPILER_DISABLE_OFFSETOF_WARNING \
630 schoenebeck 3034 (VMRelPtr) { \
631     (void**) &basePtr, \
632     offsetof(T_struct, T_member), \
633     true \
634     } \
635 schoenebeck 3035 COMPILER_RESTORE_OFFSETOF_WARNING \
636 schoenebeck 3034 ) \
637 schoenebeck 2948
638 schoenebeck 2594 /** @brief Built-in VM 8 bit integer array variable.
639     *
640 schoenebeck 2727 * Used for defining built-in integer array script variables (8 bit per
641     * array element). Currently there is no support for any other kind of array
642     * type. So all integer arrays of scripts use 8 bit data types.
643 schoenebeck 2594 */
644     struct VMInt8Array {
645     int8_t* data;
646     int size;
647 schoenebeck 3253 bool readonly; ///< Whether the array data may be modified or just be read.
648 schoenebeck 2594
649 schoenebeck 3253 VMInt8Array() : data(NULL), size(0), readonly(false) {}
650 schoenebeck 2594 };
651    
652 schoenebeck 2945 /** @brief Virtual machine script variable.
653     *
654     * Common interface for all variables accessed in scripts.
655     */
656     class VMVariable : virtual public VMExpr {
657     public:
658     /**
659     * Whether a script may modify the content of this variable by
660     * assigning a new value to it.
661     *
662     * @see isConstExpr(), assign()
663     */
664     virtual bool isAssignable() const = 0;
665    
666     /**
667     * In case this variable is assignable, this method will be called to
668     * perform the value assignment to this variable with @a expr
669     * reflecting the new value to be assigned.
670     *
671     * @param expr - new value to be assigned to this variable
672     */
673     virtual void assignExpr(VMExpr* expr) = 0;
674     };
675    
676 schoenebeck 2942 /** @brief Dynamically executed variable (abstract base class).
677     *
678     * Interface for the implementation of a dynamically generated content of
679     * a built-in script variable. Most built-in variables are simply pointers
680     * to some native location in memory. So when a script reads them, the
681     * memory location is simply read to get the value of the variable. A
682     * dynamic variable however is not simply a memory location. For each access
683     * to a dynamic variable some native code is executed to actually generate
684     * and provide the content (value) of this type of variable.
685     */
686 schoenebeck 2945 class VMDynVar : public VMVariable {
687 schoenebeck 2942 public:
688     /**
689     * Returns true in case this dynamic variable can be considered to be a
690     * constant expression. A constant expression will retain the same value
691     * throughout the entire life time of a script and the expression's
692     * constant value may be evaluated already at script parse time, which
693     * may result in performance benefits during script runtime.
694     *
695     * However due to the "dynamic" behavior of dynamic variables, almost
696     * all dynamic variables are probably not constant expressions. That's
697     * why this method returns @c false by default. If you are really sure
698     * that your dynamic variable implementation can be considered a
699     * constant expression then you may override this method and return
700     * @c true instead. Note that when you return @c true here, your
701     * dynamic variable will really just be executed once; and exectly
702     * already when the script is loaded!
703     *
704     * As an example you may implement a "constant" built-in dynamic
705     * variable that checks for a certain operating system feature and
706     * returns the result of that OS feature check as content (value) of
707     * this dynamic variable. Since the respective OS feature might become
708     * available/unavailable after OS updates, software migration, etc. the
709     * OS feature check should at least be performed once each time the
710     * application is launched. And since the OS feature check might take a
711     * certain amount of execution time, it might make sense to only
712     * perform the check if the respective variable name is actually
713     * referenced at all in the script to be loaded. Note that the dynamic
714     * variable will still be evaluated again though if the script is
715     * loaded again. So it is up to you to probably cache the result in the
716     * implementation of your dynamic variable.
717     *
718     * On doubt, please rather consider to use a constant built-in script
719     * variable instead of implementing a "constant" dynamic variable, due
720     * to the runtime overhead a dynamic variable may cause.
721     *
722     * @see isAssignable()
723     */
724 schoenebeck 2945 bool isConstExpr() const OVERRIDE { return false; }
725 schoenebeck 2942
726     /**
727     * In case this dynamic variable is assignable, the new value (content)
728     * to be assigned to this dynamic variable.
729     *
730     * By default this method does nothing. Override and implement this
731     * method in your subclass in case your dynamic variable allows to
732     * assign a new value by script.
733     *
734     * @param expr - new value to be assigned to this variable
735     */
736 schoenebeck 2945 void assignExpr(VMExpr* expr) OVERRIDE {}
737 schoenebeck 3034
738     virtual ~VMDynVar() {}
739 schoenebeck 2942 };
740    
741     /** @brief Dynamically executed variable (of integer data type).
742     *
743     * This is the base class for all built-in integer script variables whose
744     * variable content needs to be provided dynamically by executable native
745     * code on each script variable access.
746     */
747     class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
748     public:
749     };
750    
751     /** @brief Dynamically executed variable (of string data type).
752     *
753     * This is the base class for all built-in string script variables whose
754     * variable content needs to be provided dynamically by executable native
755     * code on each script variable access.
756     */
757     class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
758     public:
759     };
760    
761 schoenebeck 3073 /** @brief Dynamically executed variable (of integer array data type).
762     *
763     * This is the base class for all built-in integer array script variables
764     * whose variable content needs to be provided dynamically by executable
765     * native code on each script variable access.
766     */
767     class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr {
768     public:
769     };
770    
771 schoenebeck 2612 /** @brief Provider for built-in script functions and variables.
772     *
773 schoenebeck 2727 * Abstract base class defining the high-level interface for all classes
774     * which add and implement built-in script functions and built-in script
775     * variables.
776 schoenebeck 2612 */
777 schoenebeck 2581 class VMFunctionProvider {
778     public:
779 schoenebeck 2612 /**
780     * Returns pointer to the built-in function with the given function
781 schoenebeck 2727 * @a name, or NULL if there is no built-in function with that function
782     * name.
783 schoenebeck 2612 *
784 schoenebeck 2727 * @param name - function name (i.e. "wait" or "message" or "exit", etc.)
785 schoenebeck 2612 */
786 schoenebeck 2581 virtual VMFunction* functionByName(const String& name) = 0;
787 schoenebeck 2612
788     /**
789     * Returns a variable name indexed map of all built-in script variables
790 schoenebeck 2727 * which point to native "int" scalar (usually 32 bit) variables.
791 schoenebeck 2612 */
792 schoenebeck 2594 virtual std::map<String,VMIntRelPtr*> builtInIntVariables() = 0;
793 schoenebeck 2612
794     /**
795 schoenebeck 2727 * Returns a variable name indexed map of all built-in script integer
796     * array variables with array element type "int8_t" (8 bit).
797 schoenebeck 2612 */
798 schoenebeck 2594 virtual std::map<String,VMInt8Array*> builtInIntArrayVariables() = 0;
799 schoenebeck 2612
800     /**
801     * Returns a variable name indexed map of all built-in constant script
802     * variables, which never change their value at runtime.
803     */
804 schoenebeck 2594 virtual std::map<String,int> builtInConstIntVariables() = 0;
805 schoenebeck 2942
806     /**
807     * Returns a variable name indexed map of all built-in dynamic variables,
808     * which are not simply data stores, rather each one of them executes
809     * natively to provide or alter the respective script variable data.
810     */
811     virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
812 schoenebeck 2581 };
813    
814 schoenebeck 2594 /** @brief Execution state of a virtual machine.
815     *
816     * An instance of this abstract base class represents exactly one execution
817     * state of a virtual machine. This encompasses most notably the VM
818 schoenebeck 2612 * execution stack, and VM polyphonic variables. It does not contain global
819 schoenebeck 2727 * variables. Global variables are contained in the VMParserContext object.
820 schoenebeck 2612 * You might see a VMExecContext object as one virtual thread of the virtual
821     * machine.
822 schoenebeck 2594 *
823 schoenebeck 2612 * In contrast to a VMParserContext, a VMExecContext is not tied to a
824     * ScriptVM instance. Thus you can use a VMExecContext with different
825     * ScriptVM instances, however not concurrently at the same time.
826     *
827 schoenebeck 2594 * @see VMParserContext
828     */
829 schoenebeck 2581 class VMExecContext {
830     public:
831     virtual ~VMExecContext() {}
832 schoenebeck 2727
833     /**
834     * In case the script was suspended for some reason, this method returns
835     * the amount of microseconds before the script shall continue its
836     * execution. Note that the virtual machine itself does never put its
837     * own execution thread(s) to sleep. So the respective class (i.e. sampler
838     * engine) which is using the virtual machine classes here, must take
839     * care by itself about taking time stamps, determining the script
840     * handlers that shall be put aside for the requested amount of
841 schoenebeck 2871 * microseconds, indicated by this method by comparing the time stamps in
842 schoenebeck 2727 * real-time, and to continue passing the respective handler to
843     * ScriptVM::exec() as soon as its suspension exceeded, etc. Or in other
844     * words: all classes in this directory never have an idea what time it
845     * is.
846     *
847     * You should check the return value of ScriptVM::exec() to determine
848     * whether the script was actually suspended before calling this method
849     * here.
850     *
851     * @see ScriptVM::exec()
852     */
853 schoenebeck 2581 virtual int suspensionTimeMicroseconds() const = 0;
854 schoenebeck 3207
855     /**
856     * Causes all polyphonic variables to be reset to zero values. A
857     * polyphonic variable is expected to be zero when entering a new event
858     * handler instance. As an exception the values of polyphonic variables
859     * shall only be preserved from an note event handler instance to its
860     * correspending specific release handler instance. So in the latter
861     * case the script author may pass custom data from the note handler to
862     * the release handler, but only for the same specific note!
863     */
864     virtual void resetPolyphonicData() = 0;
865 schoenebeck 3221
866     /**
867     * Returns amount of virtual machine instructions which have been
868     * performed the last time when this execution context was executing a
869     * script. So in case you need the overall amount of instructions
870     * instead, then you need to add them by yourself after each
871     * ScriptVM::exec() call.
872     */
873     virtual size_t instructionsPerformed() const = 0;
874 schoenebeck 3277
875     /**
876     * Sends a signal to this script execution instance to abort its script
877     * execution as soon as possible. This method is called i.e. when one
878     * script execution instance intends to stop another script execution
879     * instance.
880     */
881     virtual void signalAbort() = 0;
882 schoenebeck 2581 };
883    
884 schoenebeck 2645 /** @brief Script callback for a certain event.
885     *
886     * Represents a script callback for a certain event, i.e.
887 schoenebeck 2727 * "on note ... end on" code block.
888 schoenebeck 2645 */
889 schoenebeck 2581 class VMEventHandler {
890     public:
891 schoenebeck 2645 /**
892 schoenebeck 2879 * Type of this event handler, which identifies its purpose. For example
893     * for a "on note ... end on" script callback block,
894     * @c VM_EVENT_HANDLER_NOTE would be returned here.
895     */
896     virtual VMEventHandlerType_t eventHandlerType() const = 0;
897    
898     /**
899 schoenebeck 2645 * Name of the event handler which identifies its purpose. For example
900     * for a "on note ... end on" script callback block, the name "note"
901     * would be returned here.
902     */
903 schoenebeck 2581 virtual String eventHandlerName() const = 0;
904 schoenebeck 2645
905     /**
906     * Whether or not the event handler makes any use of so called
907     * "polyphonic" variables.
908     */
909     virtual bool isPolyphonic() const = 0;
910 schoenebeck 2581 };
911    
912 schoenebeck 2727 /**
913     * Encapsulates a noteworty parser issue. This encompasses the type of the
914     * issue (either a parser error or parser warning), a human readable
915     * explanation text of the error or warning and the location of the
916     * encountered parser issue within the script.
917 schoenebeck 3012 *
918     * @see VMSourceToken for processing syntax highlighting instead.
919 schoenebeck 2727 */
920 schoenebeck 2581 struct ParserIssue {
921 schoenebeck 2727 String txt; ///< Human readable explanation text of the parser issue.
922 schoenebeck 2889 int firstLine; ///< The first line number within the script where this issue was encountered (indexed with 1 being the very first line).
923     int lastLine; ///< The last line number within the script where this issue was encountered.
924     int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).
925     int lastColumn; ///< The last column within the script where this issue was encountered.
926 schoenebeck 2727 ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning.
927 schoenebeck 2581
928 schoenebeck 2727 /**
929     * Print this issue out to the console (stdio).
930     */
931 schoenebeck 2581 inline void dump() {
932     switch (type) {
933     case PARSER_ERROR:
934 schoenebeck 2889 printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
935 schoenebeck 2581 break;
936     case PARSER_WARNING:
937 schoenebeck 2889 printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
938 schoenebeck 2581 break;
939     }
940     }
941 schoenebeck 2727
942     /**
943     * Returns true if this issue is a parser error. In this case the parsed
944     * script may not be executed!
945     */
946 schoenebeck 2581 inline bool isErr() const { return type == PARSER_ERROR; }
947 schoenebeck 2727
948     /**
949     * Returns true if this issue is just a parser warning. A parsed script
950     * that only raises warnings may be executed if desired, however the
951     * script may not behave exactly as intended by the script author.
952     */
953 schoenebeck 2581 inline bool isWrn() const { return type == PARSER_WARNING; }
954     };
955    
956 schoenebeck 2727 /**
957     * Convenience function used for converting an ExprType_t constant to a
958     * string, i.e. for generating error message by the parser.
959     */
960 schoenebeck 2581 inline String typeStr(const ExprType_t& type) {
961     switch (type) {
962     case EMPTY_EXPR: return "empty";
963     case INT_EXPR: return "integer";
964     case INT_ARR_EXPR: return "integer array";
965     case STRING_EXPR: return "string";
966     case STRING_ARR_EXPR: return "string array";
967     }
968     return "invalid";
969     }
970    
971 schoenebeck 2594 /** @brief Virtual machine representation of a script.
972     *
973     * An instance of this abstract base class represents a parsed script,
974 schoenebeck 2727 * translated into a virtual machine tree. You should first check if there
975     * were any parser errors. If there were any parser errors, you should
976     * refrain from executing the virtual machine. Otherwise if there were no
977     * parser errors (i.e. only warnings), then you might access one of the
978     * script's event handlers by i.e. calling eventHandlerByName() and pass the
979     * respective event handler to the ScriptVM class (or to one of the ScriptVM
980 schoenebeck 2594 * descendants) for execution.
981     *
982 schoenebeck 2727 * @see VMExecContext, ScriptVM
983 schoenebeck 2594 */
984 schoenebeck 2588 class VMParserContext {
985     public:
986     virtual ~VMParserContext() {}
987 schoenebeck 2727
988     /**
989     * Returns all noteworthy issues encountered when the script was parsed.
990     * These are parser errors and parser warnings.
991     */
992 schoenebeck 2588 virtual std::vector<ParserIssue> issues() const = 0;
993 schoenebeck 2727
994     /**
995     * Same as issues(), but this method only returns parser errors.
996     */
997 schoenebeck 2588 virtual std::vector<ParserIssue> errors() const = 0;
998 schoenebeck 2727
999     /**
1000     * Same as issues(), but this method only returns parser warnings.
1001     */
1002 schoenebeck 2588 virtual std::vector<ParserIssue> warnings() const = 0;
1003 schoenebeck 2727
1004     /**
1005     * Returns the translated virtual machine representation of an event
1006     * handler block (i.e. "on note ... end on" code block) within the
1007     * parsed script. This translated representation of the event handler
1008     * can be executed by the virtual machine.
1009     *
1010     * @param index - index of the event handler within the script
1011     */
1012 schoenebeck 2588 virtual VMEventHandler* eventHandler(uint index) = 0;
1013 schoenebeck 2727
1014     /**
1015     * Same as eventHandler(), but this method returns the event handler by
1016     * its name. So for a "on note ... end on" code block of the parsed
1017     * script you would pass "note" for argument @a name here.
1018     *
1019     * @param name - name of the event handler (i.e. "init", "note",
1020     * "controller", "release")
1021     */
1022 schoenebeck 2588 virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
1023     };
1024    
1025 schoenebeck 2885 class SourceToken;
1026    
1027     /** @brief Recognized token of a script's source code.
1028     *
1029     * Represents one recognized token of a script's source code, for example
1030     * a keyword, variable name, etc. and it provides further informations about
1031     * that particular token, i.e. the precise location (line and column) of the
1032     * token within the original script's source code.
1033     *
1034     * This class is not actually used by the sampler itself. It is rather
1035     * provided for external script editor applications. Primary purpose of
1036     * this class is syntax highlighting for external script editors.
1037 schoenebeck 3012 *
1038     * @see ParserIssue for processing compile errors and warnings instead.
1039 schoenebeck 2885 */
1040     class VMSourceToken {
1041     public:
1042     VMSourceToken();
1043     VMSourceToken(SourceToken* ct);
1044     VMSourceToken(const VMSourceToken& other);
1045     virtual ~VMSourceToken();
1046    
1047     // original text of this token as it is in the script's source code
1048     String text() const;
1049    
1050     // position of token in script
1051 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.
1052     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().
1053 schoenebeck 2885
1054     // base types
1055 schoenebeck 3012 bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1056     bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1057     bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1058     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.
1059     bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1060     bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1061     bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1062     bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1063     bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1064     bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1065 schoenebeck 2885
1066     // extended types
1067 schoenebeck 3012 bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1068     bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1069     bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1070     bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1071 schoenebeck 2885
1072     VMSourceToken& operator=(const VMSourceToken& other);
1073    
1074     private:
1075     SourceToken* m_token;
1076     };
1077    
1078 schoenebeck 2581 } // namespace LinuxSampler
1079    
1080     #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H

  ViewVC Help
Powered by ViewVC