/[svn]/linuxsampler/trunk/src/scriptvm/ScriptVM.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/scriptvm/ScriptVM.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2885 - (show annotations) (download) (as text)
Fri Apr 22 15:37:45 2016 UTC (7 years, 11 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 10697 byte(s)
* Instrument script classes now exported with the liblinuxsampler C++ API.
* Added new API method ScriptVM::syntaxHighlighting() which provides
  a convenient syntax highlighting backend for external instrument
  script editor applications.
* Bumped version (2.0.0.svn5).

1 /*
2 * Copyright (c) 2014-2016 Christian Schoenebeck
3 *
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 #ifndef LS_SCRIPTVM_H
11 #define LS_SCRIPTVM_H
12
13 #include <iostream>
14 #include <vector>
15
16 #include "../common/global.h"
17 #include "common.h"
18
19 namespace LinuxSampler {
20
21 class ParserContext;
22 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.
31 *
32 * This is the core of the virtual machine and main entry class, used for
33 * running real-time instrument scripts. This VM core encompasses the
34 * instrument script parser, generalized virtual machine and very generic
35 * built-in script functions. Thus this class only provides functionalities
36 * which are yet independent of the actual purpose the virtual machine is
37 * going to be used for.
38 *
39 * The actual use case specific functionalites (i.e. MIDI processing) is
40 * then implemented by sampler engines' VM classes which are derived from
41 * this generalized ScriptVM class.
42 *
43 * Typical usage of this class:
44 *
45 * - 1. Create an instance of this ScriptVM class (or of one of its deriving
46 * classes).
47 * - 2. Load a script by passing its source code to method loadScript(),
48 * which will return the parsed representation of the script.
49 * - 3. Create a VM execution context by calling createExecContext().
50 * - 4. Execute the script by calling method exec().
51 *
52 * This class is re-entrant safe, but not thread safe. So you can share one
53 * instance of this class between multiple (native) threads, but you @b must
54 * @b not execute methods of the same class instance simultaniously from
55 * different (native) threads. If you want to execute scripts simultaniously
56 * multi threaded, then create a separate ScriptVM instance for each
57 * (native) thread. Also note that one VMParserContext instance is tied to
58 * exactly one ScriptVM instance. So you @b must @b not create a
59 * VMParserContext with one ScriptVM instance and run it with a different
60 * ScriptVM instance!
61 */
62 class ScriptVM : public VMFunctionProvider {
63 public:
64 ScriptVM();
65 virtual ~ScriptVM();
66
67 /**
68 * Loads a script given by its source code (passed as argument @a s to
69 * this method) and returns the parsed representation of that script.
70 * After calling this method you must check the returned VMParserContext
71 * object whether there had been any parser errors. If there were no
72 * parser errors, you may pass the VMParserContext object to method
73 * exec() for actually executing the script.
74 *
75 * @param s - entire source code of the script to be loaded
76 * @returns parsed representation of the script
77 */
78 VMParserContext* loadScript(const String& s);
79
80 /**
81 * Same as above's loadScript() method, but this one reads the script's
82 * source code from an input stream object (i.e. stdin or a file).
83 *
84 * @param is - input stream from which the entire source code of the
85 * script is to be read and loaded from
86 * @returns parsed representation of the script
87 */
88 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
119 * argument @a context, to stdout. This method is for debugging purposes
120 * only.
121 *
122 * @param context - parsed representation of the script
123 * @see loadScript()
124 */
125 void dumpParsedScript(VMParserContext* context);
126
127 /**
128 * Creates a so called VM exceution context for a specific, already
129 * parsed script (provided by argument @a parserContext). Due to the
130 * general real-time design of this virtual machine, the VM execution
131 * context differs for every script. So you must (re)create the
132 * 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);
138
139 /**
140 * Execute a script by virtual machine. Since scripts are event-driven,
141 * you actually execute only one specific event handler block (i.e. a
142 * "on note ... end on" code block) by calling this method (not the
143 * entire script), and hence you must provide one precise handler of the
144 * script to be executed by this method.
145 *
146 * This method usually blocks until the entire script event handler
147 * block has been executed completely. It may however also return before
148 * completion if either a) a script runtime error occurred or b) the
149 * script was suspended by the VM (either because script execution
150 * 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
152 * find out which case applies.
153 *
154 * @param parserContext - parsed representation of the script (see loadScript())
155 * @param execContext - VM execution context (see createExecContext())
156 * @param handler - precise event handler (i.e. "on note ... end on"
157 * code block) to be executed
158 * (see VMParserContext::eventHandlerByName())
159 * @returns current status of the vitual machine (i.e. script succeeded,
160 * script runtime error occurred or script was suspended for
161 * some reason).
162 */
163 VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);
164
165 /**
166 * Returns built-in script function for the given function @a name. To
167 * get the implementation of the built-in message() script function for
168 * example, you would pass "message" here).
169 *
170 * This method is re-implemented by deriving classes to add more use
171 * case specific built-in functions.
172 *
173 * @param name - name of the function to be retrieved (i.e. "wait" for the
174 * built-in wait() function).
175 */
176 VMFunction* functionByName(const String& name) OVERRIDE;
177
178 /**
179 * Returns all built-in integer script variables. This method returns a
180 * STL map, where the map's key is the variable name and the map's value
181 * is the native pointer to the actual built-in variable.
182 *
183 * This method is re-implemented by deriving classes to add more use
184 * case specific built-in variables.
185 */
186 std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;
187
188 /**
189 * Returns all built-in (8 bit) integer array script variables. This
190 * method returns a STL map, where the map's key is the array variable
191 * name and the map's value is the native pointer to the actual built-in
192 * array variable.
193 *
194 * This method is re-implemented by deriving classes to add more use
195 * case specific built-in array variables.
196 */
197 std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
198
199 /**
200 * Returns all built-in constant integer script variables, which can
201 * only be read, but not be altered by scripts. This method returns a
202 * STL map, where the map's key is the variable name and the map's value
203 * is the native pointer to the actual built-in constant variable.
204 *
205 * This method is re-implemented by deriving classes to add more use
206 * case specific built-in constant integers.
207 *
208 * @b Note: the term "constant" is a bit misleading here, since
209 * built-in constant integer variables may indeed change, i.e. for
210 * built-in constant integers which i.e. reflect some kind of status of
211 * the sampler. So rather see them as "read only" variables, not as
212 * being actually consistent in time.
213 */
214 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)
218 VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
219
220 protected:
221 VMEventHandler* m_eventHandler;
222 ParserContext* m_parserContext;
223 CoreVMFunction_message* m_fnMessage;
224 CoreVMFunction_exit* m_fnExit;
225 CoreVMFunction_wait* m_fnWait;
226 CoreVMFunction_abs* m_fnAbs;
227 CoreVMFunction_random* m_fnRandom;
228 CoreVMFunction_num_elements* m_fnNumElements;
229 };
230
231 } // namespace LinuxSampler
232
233 #endif // LS_INSTRUMENTSCRIPTVM_H

  ViewVC Help
Powered by ViewVC