1 |
/* |
/* |
2 |
* Copyright (c) 2014-2017 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 |
* |
* |
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 |
*/ |
*/ |
899 |
* instance. |
* instance. |
900 |
*/ |
*/ |
901 |
virtual void signalAbort() = 0; |
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 |