1 |
/* |
/* |
2 |
* Copyright (c) 2014-2015 Christian Schoenebeck |
* Copyright (c) 2014-2016 Christian Schoenebeck |
3 |
* |
* |
4 |
* http://www.linuxsampler.org |
* http://www.linuxsampler.org |
5 |
* |
* |
15 |
|
|
16 |
#include "../common/global.h" |
#include "../common/global.h" |
17 |
#include "common.h" |
#include "common.h" |
|
#include "CoreVMFunctions.h" |
|
18 |
|
|
19 |
namespace LinuxSampler { |
namespace LinuxSampler { |
20 |
|
|
21 |
class ParserContext; |
class ParserContext; |
22 |
class ExecContext; |
class ExecContext; |
23 |
|
class CoreVMFunction_message; |
24 |
|
class CoreVMFunction_exit; |
25 |
|
class CoreVMFunction_wait; |
26 |
|
class CoreVMFunction_abs; |
27 |
|
class CoreVMFunction_random; |
28 |
|
class CoreVMFunction_num_elements; |
29 |
|
|
30 |
/** @brief Core virtual machine for real-time instrument scripts. |
/** @brief Core virtual machine for real-time instrument scripts. |
31 |
* |
* |
45 |
* - 1. Create an instance of this ScriptVM class (or of one of its deriving |
* - 1. Create an instance of this ScriptVM class (or of one of its deriving |
46 |
* classes). |
* classes). |
47 |
* - 2. Load a script by passing its source code to method loadScript(), |
* - 2. Load a script by passing its source code to method loadScript(), |
48 |
* which will return the parsed represenation of the script. |
* which will return the parsed representation of the script. |
49 |
* - 3. Create a VM execution context by calling createExecContext(). |
* - 3. Create a VM execution context by calling createExecContext(). |
50 |
* - 4. Execute the script by calling method exec(). |
* - 4. Execute the script by calling method exec(). |
51 |
* |
* |
66 |
|
|
67 |
/** |
/** |
68 |
* Loads a script given by its source code (passed as argument @a s to |
* Loads a script given by its source code (passed as argument @a s to |
69 |
* this method) and returns the parsed represenation of that script. |
* this method) and returns the parsed representation of that script. |
70 |
* After calling this method you must check the returned VMParserContext |
* After calling this method you must check the returned VMParserContext |
71 |
* object whether there had been any parser errors. If there were no |
* object whether there had been any parser errors. If there were no |
72 |
* parser errors, you may pass the VMParserContext object to method |
* parser errors, you may pass the VMParserContext object to method |
73 |
* exec() for actually executing the script. |
* exec() for actually executing the script. |
74 |
* |
* |
75 |
* @param s - entire source code of the script to be loaded |
* @param s - entire source code of the script to be loaded |
76 |
* @returns parsed represenation of the script |
* @returns parsed representation of the script |
77 |
*/ |
*/ |
78 |
VMParserContext* loadScript(const String& s); |
VMParserContext* loadScript(const String& s); |
79 |
|
|
83 |
* |
* |
84 |
* @param is - input stream from which the entire source code of the |
* @param is - input stream from which the entire source code of the |
85 |
* script is to be read and loaded from |
* script is to be read and loaded from |
86 |
* @returns parsed represenation of the script |
* @returns parsed representation of the script |
87 |
*/ |
*/ |
88 |
VMParserContext* loadScript(std::istream* is); |
VMParserContext* loadScript(std::istream* is); |
89 |
|
|
90 |
/** |
/** |
91 |
|
* Parses a script's source code (passed as argument @a s to this |
92 |
|
* method), splits that input up in its individual tokens (i.e. |
93 |
|
* keyword, variable name, event name, etc.) and returns all those |
94 |
|
* tokens, for the purpose that the caller can provide syntax syntax |
95 |
|
* highlighting for the passed script. |
96 |
|
* |
97 |
|
* This method is actually not used by the sampler at all, it is rather |
98 |
|
* provided for external script editor applications, to provide them a |
99 |
|
* convenient backend for parsing scripts and providing syntax |
100 |
|
* highlighting. |
101 |
|
* |
102 |
|
* @returns recognized tokens of passed script's source code |
103 |
|
*/ |
104 |
|
std::vector<VMSourceToken> syntaxHighlighting(const String& s); |
105 |
|
|
106 |
|
/** |
107 |
|
* Same as above's syntaxHighlighting() method, but this one reads the |
108 |
|
* script's source code from an input stream object (i.e. stdin or a |
109 |
|
* file). |
110 |
|
* |
111 |
|
* @param is - input stream from which the entire source code of the |
112 |
|
* script is to be read and loaded from |
113 |
|
* @returns recognized tokens of passed script's source code |
114 |
|
*/ |
115 |
|
std::vector<VMSourceToken> syntaxHighlighting(std::istream* is); |
116 |
|
|
117 |
|
/** |
118 |
* Dumps the translated tree of the already parsed script, given by |
* Dumps the translated tree of the already parsed script, given by |
119 |
* argument @a context, to stdout. This method is for debugging purposes |
* argument @a context, to stdout. This method is for debugging purposes |
120 |
* only. |
* only. |
121 |
* |
* |
122 |
* @param context - parsed represenation of the script |
* @param context - parsed representation of the script |
123 |
|
* @see loadScript() |
124 |
*/ |
*/ |
125 |
void dumpParsedScript(VMParserContext* context); |
void dumpParsedScript(VMParserContext* context); |
126 |
|
|
130 |
* general real-time design of this virtual machine, the VM execution |
* general real-time design of this virtual machine, the VM execution |
131 |
* context differs for every script. So you must (re)create the |
* context differs for every script. So you must (re)create the |
132 |
* execution context for each script being loaded. |
* execution context for each script being loaded. |
133 |
|
* |
134 |
|
* @param parserContext - parsed representation of the script |
135 |
|
* @see loadScript() |
136 |
*/ |
*/ |
137 |
VMExecContext* createExecContext(VMParserContext* parserContext); |
VMExecContext* createExecContext(VMParserContext* parserContext); |
138 |
|
|
146 |
* This method usually blocks until the entire script event handler |
* This method usually blocks until the entire script event handler |
147 |
* block has been executed completely. It may however also return before |
* block has been executed completely. It may however also return before |
148 |
* completion if either a) a script runtime error occurred or b) the |
* completion if either a) a script runtime error occurred or b) the |
149 |
* script was suspened by the VM (either because script execution |
* script was suspended by the VM (either because script execution |
150 |
* exceeded a certain limit of time or the script called the built-in |
* exceeded a certain limit of time or the script called the built-in |
151 |
* wait() function). You must check the return value of this method to |
* wait() function). You must check the return value of this method to |
152 |
* find out which case applies. |
* find out which case applies. |
153 |
* |
* |
154 |
* @param parserContext - parsed represenation of the script |
* @param parserContext - parsed representation of the script (see loadScript()) |
155 |
* @param execContext - VM execution context (see createExecContext()) |
* @param execContext - VM execution context (see createExecContext()) |
156 |
* @param handler - precise event handler (i.e. "on note ... end on" |
* @param handler - precise event handler (i.e. "on note ... end on" |
157 |
* code block) to be executed |
* code block) to be executed |
213 |
*/ |
*/ |
214 |
std::map<String,int> builtInConstIntVariables() OVERRIDE; |
std::map<String,int> builtInConstIntVariables() OVERRIDE; |
215 |
|
|
216 |
|
VMEventHandler* currentVMEventHandler(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) |
217 |
VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) |
VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) |
218 |
VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) |
VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions) |
219 |
|
|
220 |
protected: |
protected: |
221 |
|
VMEventHandler* m_eventHandler; |
222 |
ParserContext* m_parserContext; |
ParserContext* m_parserContext; |
223 |
CoreVMFunction_message fnMessage; |
CoreVMFunction_message* m_fnMessage; |
224 |
CoreVMFunction_exit fnExit; |
CoreVMFunction_exit* m_fnExit; |
225 |
CoreVMFunction_wait fnWait; |
CoreVMFunction_wait* m_fnWait; |
226 |
CoreVMFunction_abs fnAbs; |
CoreVMFunction_abs* m_fnAbs; |
227 |
CoreVMFunction_random fnRandom; |
CoreVMFunction_random* m_fnRandom; |
228 |
CoreVMFunction_num_elements fnNumElements; |
CoreVMFunction_num_elements* m_fnNumElements; |
229 |
}; |
}; |
230 |
|
|
231 |
} // namespace LinuxSampler |
} // namespace LinuxSampler |