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 |
94 |
class VMStringExpr; |
class VMStringExpr; |
95 |
class VMIntArrayExpr; |
class VMIntArrayExpr; |
96 |
class VMStringArrayExpr; |
class VMStringArrayExpr; |
97 |
|
class VMParserContext; |
98 |
|
|
99 |
/** @brief Virtual machine expression |
/** @brief Virtual machine expression |
100 |
* |
* |
159 |
* expressions to an array expression for you, instead this method will |
* expressions to an array expression for you, instead this method will |
160 |
* simply return NULL! |
* simply return NULL! |
161 |
* |
* |
162 |
|
* @b Note: this method is currently, and in contrast to its other |
163 |
|
* counter parts, declared as virtual method. Some deriving classes are |
164 |
|
* currently using this to override this default implementation in order |
165 |
|
* to implement an "evaluate now as integer array" behavior. This has |
166 |
|
* efficiency reasons, however this also currently makes this part of |
167 |
|
* the API less clean and should thus be addressed in future with |
168 |
|
* appropriate changes to the API. |
169 |
|
* |
170 |
* @see exprType() |
* @see exprType() |
171 |
*/ |
*/ |
172 |
VMIntArrayExpr* asIntArray() const; |
virtual VMIntArrayExpr* asIntArray() const; |
173 |
|
|
174 |
/** |
/** |
175 |
* Returns true in case this expression can be considered to be a |
* Returns true in case this expression can be considered to be a |
549 |
} |
} |
550 |
}; |
}; |
551 |
|
|
552 |
|
#if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS |
553 |
|
# define COMPILER_DISABLE_OFFSETOF_WARNING \ |
554 |
|
_Pragma("GCC diagnostic push") \ |
555 |
|
_Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"") |
556 |
|
# define COMPILER_RESTORE_OFFSETOF_WARNING \ |
557 |
|
_Pragma("GCC diagnostic pop") |
558 |
|
#else |
559 |
|
# define COMPILER_DISABLE_OFFSETOF_WARNING |
560 |
|
# define COMPILER_RESTORE_OFFSETOF_WARNING |
561 |
|
#endif |
562 |
|
|
563 |
/** |
/** |
564 |
* Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr |
* Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr |
565 |
* structures. Usage example: |
* structures. Usage example: |
602 |
* complexity inside the sampler engines which provide the actual script |
* complexity inside the sampler engines which provide the actual script |
603 |
* functionalities. |
* functionalities. |
604 |
*/ |
*/ |
605 |
#define DECLARE_VMINT(basePtr, T_struct, T_member) ( \ |
#define DECLARE_VMINT(basePtr, T_struct, T_member) ( \ |
606 |
(VMRelPtr) { \ |
/* Disable offsetof warning, trust us, we are cautios. */ \ |
607 |
(void**) &basePtr, \ |
COMPILER_DISABLE_OFFSETOF_WARNING \ |
608 |
offsetof(T_struct, T_member), \ |
(VMRelPtr) { \ |
609 |
false \ |
(void**) &basePtr, \ |
610 |
} \ |
offsetof(T_struct, T_member), \ |
611 |
) \ |
false \ |
612 |
|
} \ |
613 |
|
COMPILER_RESTORE_OFFSETOF_WARNING \ |
614 |
|
) \ |
615 |
|
|
616 |
/** |
/** |
617 |
* Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and |
* Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and |
627 |
* @see ScriptVM::builtInConstIntVariables() |
* @see ScriptVM::builtInConstIntVariables() |
628 |
*/ |
*/ |
629 |
#define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \ |
#define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \ |
630 |
(VMRelPtr) { \ |
/* Disable offsetof warning, trust us, we are cautios. */ \ |
631 |
(void**) &basePtr, \ |
COMPILER_DISABLE_OFFSETOF_WARNING \ |
632 |
offsetof(T_struct, T_member), \ |
(VMRelPtr) { \ |
633 |
true \ |
(void**) &basePtr, \ |
634 |
} \ |
offsetof(T_struct, T_member), \ |
635 |
) \ |
true \ |
636 |
|
} \ |
637 |
|
COMPILER_RESTORE_OFFSETOF_WARNING \ |
638 |
|
) \ |
639 |
|
|
640 |
/** @brief Built-in VM 8 bit integer array variable. |
/** @brief Built-in VM 8 bit integer array variable. |
641 |
* |
* |
646 |
struct VMInt8Array { |
struct VMInt8Array { |
647 |
int8_t* data; |
int8_t* data; |
648 |
int size; |
int size; |
649 |
|
bool readonly; ///< Whether the array data may be modified or just be read. |
650 |
|
|
651 |
VMInt8Array() : data(NULL), size(0) {} |
VMInt8Array() : data(NULL), size(0), readonly(false) {} |
652 |
}; |
}; |
653 |
|
|
654 |
/** @brief Virtual machine script variable. |
/** @brief Virtual machine script variable. |
736 |
* @param expr - new value to be assigned to this variable |
* @param expr - new value to be assigned to this variable |
737 |
*/ |
*/ |
738 |
void assignExpr(VMExpr* expr) OVERRIDE {} |
void assignExpr(VMExpr* expr) OVERRIDE {} |
739 |
|
|
740 |
|
virtual ~VMDynVar() {} |
741 |
}; |
}; |
742 |
|
|
743 |
/** @brief Dynamically executed variable (of integer data type). |
/** @brief Dynamically executed variable (of integer data type). |
760 |
public: |
public: |
761 |
}; |
}; |
762 |
|
|
763 |
|
/** @brief Dynamically executed variable (of integer array data type). |
764 |
|
* |
765 |
|
* This is the base class for all built-in integer array script variables |
766 |
|
* whose variable content needs to be provided dynamically by executable |
767 |
|
* native code on each script variable access. |
768 |
|
*/ |
769 |
|
class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr { |
770 |
|
public: |
771 |
|
}; |
772 |
|
|
773 |
/** @brief Provider for built-in script functions and variables. |
/** @brief Provider for built-in script functions and variables. |
774 |
* |
* |
775 |
* Abstract base class defining the high-level interface for all classes |
* Abstract base class defining the high-level interface for all classes |
788 |
virtual VMFunction* functionByName(const String& name) = 0; |
virtual VMFunction* functionByName(const String& name) = 0; |
789 |
|
|
790 |
/** |
/** |
791 |
|
* Returns @c true if the passed built-in function is disabled and |
792 |
|
* should be ignored by the parser. This method is called by the |
793 |
|
* parser on preprocessor level for each built-in function call within |
794 |
|
* a script. Accordingly if this method returns @c true, then the |
795 |
|
* respective function call is completely filtered out on preprocessor |
796 |
|
* level, so that built-in function won't make into the result virtual |
797 |
|
* machine representation, nor would expressions of arguments passed to |
798 |
|
* that built-in function call be evaluated, nor would any check |
799 |
|
* regarding correct usage of the built-in function be performed. |
800 |
|
* In other words: a disabled function call ends up as a comment block. |
801 |
|
* |
802 |
|
* @param fn - built-in function to be checked |
803 |
|
* @param ctx - parser context at the position where the built-in |
804 |
|
* function call is located within the script |
805 |
|
*/ |
806 |
|
virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0; |
807 |
|
|
808 |
|
/** |
809 |
* Returns a variable name indexed map of all built-in script variables |
* Returns a variable name indexed map of all built-in script variables |
810 |
* which point to native "int" scalar (usually 32 bit) variables. |
* which point to native "int" scalar (usually 32 bit) variables. |
811 |
*/ |
*/ |
871 |
* @see ScriptVM::exec() |
* @see ScriptVM::exec() |
872 |
*/ |
*/ |
873 |
virtual int suspensionTimeMicroseconds() const = 0; |
virtual int suspensionTimeMicroseconds() const = 0; |
874 |
|
|
875 |
|
/** |
876 |
|
* Causes all polyphonic variables to be reset to zero values. A |
877 |
|
* polyphonic variable is expected to be zero when entering a new event |
878 |
|
* handler instance. As an exception the values of polyphonic variables |
879 |
|
* shall only be preserved from an note event handler instance to its |
880 |
|
* correspending specific release handler instance. So in the latter |
881 |
|
* case the script author may pass custom data from the note handler to |
882 |
|
* the release handler, but only for the same specific note! |
883 |
|
*/ |
884 |
|
virtual void resetPolyphonicData() = 0; |
885 |
|
|
886 |
|
/** |
887 |
|
* Returns amount of virtual machine instructions which have been |
888 |
|
* performed the last time when this execution context was executing a |
889 |
|
* script. So in case you need the overall amount of instructions |
890 |
|
* instead, then you need to add them by yourself after each |
891 |
|
* ScriptVM::exec() call. |
892 |
|
*/ |
893 |
|
virtual size_t instructionsPerformed() const = 0; |
894 |
|
|
895 |
|
/** |
896 |
|
* Sends a signal to this script execution instance to abort its script |
897 |
|
* execution as soon as possible. This method is called i.e. when one |
898 |
|
* script execution instance intends to stop another script execution |
899 |
|
* instance. |
900 |
|
*/ |
901 |
|
virtual void signalAbort() = 0; |
902 |
|
|
903 |
|
/** |
904 |
|
* Copies the current entire execution state from this object to the |
905 |
|
* given object. So this can be used to "fork" a new script thread which |
906 |
|
* then may run independently with its own polyphonic data for instance. |
907 |
|
*/ |
908 |
|
virtual void forkTo(VMExecContext* ectx) const = 0; |
909 |
|
|
910 |
|
/** |
911 |
|
* In case the script called the built-in exit() function and passed a |
912 |
|
* value as argument to the exit() function, then this method returns |
913 |
|
* the value that had been passed as argument to the exit() function. |
914 |
|
* Otherwise if the exit() function has not been called by the script |
915 |
|
* or no argument had been passed to the exit() function, then this |
916 |
|
* method returns NULL instead. |
917 |
|
* |
918 |
|
* Currently this is only used for automated test cases against the |
919 |
|
* script engine, which return some kind of value in the individual |
920 |
|
* test case scripts to check their behaviour in automated way. There |
921 |
|
* is no purpose for this mechanism in production use. Accordingly this |
922 |
|
* exit result value is @b always completely ignored by the sampler |
923 |
|
* engines. |
924 |
|
* |
925 |
|
* Officially the built-in exit() function does not expect any arguments |
926 |
|
* to be passed to its function call, and by default this feature is |
927 |
|
* hence disabled and will yield in a parser error unless |
928 |
|
* ScriptVM::setExitResultEnabled() was explicitly set. |
929 |
|
* |
930 |
|
* @see ScriptVM::setExitResultEnabled() |
931 |
|
*/ |
932 |
|
virtual VMExpr* exitResult() = 0; |
933 |
}; |
}; |
934 |
|
|
935 |
/** @brief Script callback for a certain event. |
/** @brief Script callback for a certain event. |
961 |
}; |
}; |
962 |
|
|
963 |
/** |
/** |
964 |
|
* Reflects the precise position and span of a specific code block within |
965 |
|
* a script. This is currently only used for the locations of commented |
966 |
|
* code blocks due to preprocessor statements, and for parser errors and |
967 |
|
* parser warnings. |
968 |
|
* |
969 |
|
* @see ParserIssue for code locations of parser errors and parser warnings |
970 |
|
* |
971 |
|
* @see VMParserContext::preprocessorComments() for locations of code which |
972 |
|
* have been filtered out by preprocessor statements |
973 |
|
*/ |
974 |
|
struct CodeBlock { |
975 |
|
int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line). |
976 |
|
int lastLine; ///< The last line number of this code block within the script. |
977 |
|
int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column). |
978 |
|
int lastColumn; ///< The last column of this code block within the script. |
979 |
|
}; |
980 |
|
|
981 |
|
/** |
982 |
* Encapsulates a noteworty parser issue. This encompasses the type of the |
* Encapsulates a noteworty parser issue. This encompasses the type of the |
983 |
* issue (either a parser error or parser warning), a human readable |
* issue (either a parser error or parser warning), a human readable |
984 |
* explanation text of the error or warning and the location of the |
* explanation text of the error or warning and the location of the |
986 |
* |
* |
987 |
* @see VMSourceToken for processing syntax highlighting instead. |
* @see VMSourceToken for processing syntax highlighting instead. |
988 |
*/ |
*/ |
989 |
struct ParserIssue { |
struct ParserIssue : CodeBlock { |
990 |
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. |
|
991 |
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. |
992 |
|
|
993 |
/** |
/** |
1067 |
virtual std::vector<ParserIssue> warnings() const = 0; |
virtual std::vector<ParserIssue> warnings() const = 0; |
1068 |
|
|
1069 |
/** |
/** |
1070 |
|
* Returns all code blocks of the script which were filtered out by the |
1071 |
|
* preprocessor. |
1072 |
|
*/ |
1073 |
|
virtual std::vector<CodeBlock> preprocessorComments() const = 0; |
1074 |
|
|
1075 |
|
/** |
1076 |
* Returns the translated virtual machine representation of an event |
* Returns the translated virtual machine representation of an event |
1077 |
* handler block (i.e. "on note ... end on" code block) within the |
* handler block (i.e. "on note ... end on" code block) within the |
1078 |
* parsed script. This translated representation of the event handler |
* parsed script. This translated representation of the event handler |