src/scriptvm/ScriptVM.h

/*
 * Copyright (c) 2014-2016 Christian Schoenebeck
 *
 * http://www.linuxsampler.org
 *
 * This file is part of LinuxSampler and released under the same terms.
 * See README file for details.
 */

#ifndef LS_SCRIPTVM_H
#define LS_SCRIPTVM_H

#include <iostream>
#include <vector>

#include "../common/global.h"
#include "common.h"

namespace LinuxSampler {

    class ParserContext;
    class ExecContext;
    class CoreVMFunction_message;
    class CoreVMFunction_exit;
    class CoreVMFunction_wait;
    class CoreVMFunction_abs;
    class CoreVMFunction_random;
    class CoreVMFunction_num_elements;

    /** @brief Core virtual machine for real-time instrument scripts.
     *
     * This is the core of the virtual machine and main entry class, used for
     * running real-time instrument scripts. This VM core encompasses the
     * instrument script parser, generalized virtual machine and very generic
     * built-in script functions. Thus this class only provides functionalities
     * which are yet independent of the actual purpose the virtual machine is
     * going to be used for.
     *
     * The actual use case specific functionalites (i.e. MIDI processing) is
     * then implemented by sampler engines' VM classes which are derived from
     * this generalized ScriptVM class.
     *
     * Typical usage of this class:
     *
     * - 1. Create an instance of this ScriptVM class (or of one of its deriving
     *      classes).
     * - 2. Load a script by passing its source code to method loadScript(),
     *      which will return the parsed representation of the script.
     * - 3. Create a VM execution context by calling createExecContext().
     * - 4. Execute the script by calling method exec().
     *
     * This class is re-entrant safe, but not thread safe. So you can share one
     * instance of this class between multiple (native) threads, but you @b must
     * @b not execute methods of the same class instance simultaniously from
     * different (native) threads. If you want to execute scripts simultaniously
     * multi threaded, then create a separate ScriptVM instance for each
     * (native) thread. Also note that one VMParserContext instance is tied to
     * exactly one ScriptVM instance. So you @b must @b not create a
     * VMParserContext with one ScriptVM instance and run it with a different
     * ScriptVM instance!
     */
    class ScriptVM : public VMFunctionProvider {
    public:
        ScriptVM();
        virtual ~ScriptVM();

        /**
         * Loads a script given by its source code (passed as argument @a s to
         * this method) and returns the parsed representation of that script.
         * After calling this method you must check the returned VMParserContext
         * object whether there had been any parser errors. If there were no
         * parser errors, you may pass the VMParserContext object to method
         * exec() for actually executing the script.
         *
         * It is your responsibility to free the returned VMParserContext
         * object once you don't need it anymore.
         *
         * @param s - entire source code of the script to be loaded
         * @returns parsed representation of the script
         */
        VMParserContext* loadScript(const String& s);

        /**
         * Same as above's loadScript() method, but this one reads the script's
         * source code from an input stream object (i.e. stdin or a file).
         *
         * @param is - input stream from which the entire source code of the
         *             script is to be read and loaded from
         * @returns parsed representation of the script
         */
        VMParserContext* loadScript(std::istream* is);

        /**
         * Parses a script's source code (passed as argument @a s to this
         * method), splits that input up in its individual tokens (i.e.
         * keyword, variable name, event name, etc.) and returns all those
         * tokens, for the purpose that the caller can provide syntax syntax
         * highlighting for the passed script.
         *
         * This method is actually not used by the sampler at all, it is rather
         * provided for external script editor applications, to provide them a
         * convenient backend for parsing scripts and providing syntax
         * highlighting.
         *
         * @returns recognized tokens of passed script's source code
         */
        std::vector<VMSourceToken> syntaxHighlighting(const String& s);

        /**
         * Same as above's syntaxHighlighting() method, but this one reads the
         * script's source code from an input stream object (i.e. stdin or a
         * file).
         *
         * @param is - input stream from which the entire source code of the
         *             script is to be read and loaded from
         * @returns recognized tokens of passed script's source code
         */
        std::vector<VMSourceToken> syntaxHighlighting(std::istream* is);

        /**
         * Dumps the translated tree of the already parsed script, given by
         * argument @a context, to stdout. This method is for debugging purposes
         * only.
         *
         * @param context - parsed representation of the script
         * @see loadScript()
         */
        void dumpParsedScript(VMParserContext* context);

        /**
         * Creates a so called VM exceution context for a specific, already
         * parsed script (provided by argument @a parserContext). Due to the
         * general real-time design of this virtual machine, the VM execution
         * context differs for every script. So you must (re)create the
         * execution context for each script being loaded.
         *
         * @param parserContext - parsed representation of the script
         * @see loadScript()
         */
        VMExecContext* createExecContext(VMParserContext* parserContext);

        /**
         * Execute a script by virtual machine. Since scripts are event-driven,
         * you actually execute only one specific event handler block (i.e. a
         * "on note ... end on" code block) by calling this method (not the
         * entire script), and hence you must provide one precise handler of the
         * script to be executed by this method.
         *
         * This method usually blocks until the entire script event handler
         * block has been executed completely. It may however also return before
         * completion if either a) a script runtime error occurred or b) the
         * script was suspended by the VM (either because script execution
         * exceeded a certain limit of time or the script called the built-in
         * wait() function). You must check the return value of this method to
         * find out which case applies.
         *
         * @param parserContext - parsed representation of the script (see loadScript())
         * @param execContext - VM execution context (see createExecContext())
         * @param handler - precise event handler (i.e. "on note ... end on"
         *                  code block) to be executed
         *                  (see VMParserContext::eventHandlerByName())
         * @returns current status of the vitual machine (i.e. script succeeded,
         *          script runtime error occurred or script was suspended for
         *          some reason).
         */
        VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);

        /**
         * Returns built-in script function for the given function @a name. To
         * get the implementation of the built-in message() script function for
         * example, you would pass "message" here).
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in functions.
         *
         * @param name - name of the function to be retrieved (i.e. "wait" for the 
         *               built-in wait() function).
         */
        VMFunction* functionByName(const String& name) OVERRIDE;

        /**
         * Returns all built-in integer script variables. This method returns a
         * STL map, where the map's key is the variable name and the map's value
         * is the native pointer to the actual built-in variable.
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in variables.
         */
        std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;

        /**
         * Returns all built-in (8 bit) integer array script variables. This
         * method returns a STL map, where the map's key is the array variable
         * name and the map's value is the native pointer to the actual built-in
         * array variable.
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in array variables.
         */
        std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;

        /**
         * Returns all built-in constant integer script variables, which can
         * only be read, but not be altered by scripts. This method returns a
         * STL map, where the map's key is the variable name and the map's value
         * is the native pointer to the actual built-in constant variable.
         *
         * This method is re-implemented by deriving classes to add more use
         * case specific built-in constant integers.
         *
         * @b Note: the term "constant" is a bit misleading here, since
         * built-in constant integer variables may indeed change, i.e. for
         * built-in constant integers which i.e. reflect some kind of status of
         * the sampler. So rather see them as "read only" variables, not as
         * being actually consistent in time.
         */
        std::map<String,int> builtInConstIntVariables() OVERRIDE;

        VMEventHandler* currentVMEventHandler(); //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)
        VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)

    protected:
        VMEventHandler* m_eventHandler;
        ParserContext* m_parserContext;
        CoreVMFunction_message* m_fnMessage;
        CoreVMFunction_exit* m_fnExit;
        CoreVMFunction_wait* m_fnWait;
        CoreVMFunction_abs* m_fnAbs;
        CoreVMFunction_random* m_fnRandom;
        CoreVMFunction_num_elements* m_fnNumElements;
    };

} // namespace LinuxSampler

#endif // LS_INSTRUMENTSCRIPTVM_H
1	schoenebeck	2581	/*
2	schoenebeck	2871	* Copyright (c) 2014-2016 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			#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	schoenebeck	2588	class ExecContext;
23	schoenebeck	2885	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	schoenebeck	2581
30	schoenebeck	2594	/** @brief Core virtual machine for real-time instrument scripts.
31			*
32	schoenebeck	2727	* 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	schoenebeck	2594	*
39			* The actual use case specific functionalites (i.e. MIDI processing) is
40	schoenebeck	2727	* then implemented by sampler engines' VM classes which are derived from
41			* this generalized ScriptVM class.
42	schoenebeck	2594	*
43	schoenebeck	2727	* 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	schoenebeck	2729	* which will return the parsed representation of the script.
49	schoenebeck	2727	* - 3. Create a VM execution context by calling createExecContext().
50			* - 4. Execute the script by calling method exec().
51			*
52	schoenebeck	2594	* 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	schoenebeck	2581	class ScriptVM : public VMFunctionProvider {
63			public:
64			ScriptVM();
65			virtual ~ScriptVM();
66	schoenebeck	2727
67			/**
68			* Loads a script given by its source code (passed as argument @a s to
69	schoenebeck	2729	* this method) and returns the parsed representation of that script.
70	schoenebeck	2727	* 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	schoenebeck	2889	* It is your responsibility to free the returned VMParserContext
76			* object once you don't need it anymore.
77			*
78	schoenebeck	2727	* @param s - entire source code of the script to be loaded
79	schoenebeck	2729	* @returns parsed representation of the script
80	schoenebeck	2727	*/
81	schoenebeck	2588	VMParserContext* loadScript(const String& s);
82	schoenebeck	2727
83			/**
84			* Same as above's loadScript() method, but this one reads the script's
85			* source code from an input stream object (i.e. stdin or a file).
86			*
87			* @param is - input stream from which the entire source code of the
88			* script is to be read and loaded from
89	schoenebeck	2729	* @returns parsed representation of the script
90	schoenebeck	2727	*/
91	schoenebeck	2588	VMParserContext* loadScript(std::istream* is);
92	schoenebeck	2727
93			/**
94	schoenebeck	2885	* Parses a script's source code (passed as argument @a s to this
95			* method), splits that input up in its individual tokens (i.e.
96			* keyword, variable name, event name, etc.) and returns all those
97			* tokens, for the purpose that the caller can provide syntax syntax
98			* highlighting for the passed script.
99			*
100			* This method is actually not used by the sampler at all, it is rather
101			* provided for external script editor applications, to provide them a
102			* convenient backend for parsing scripts and providing syntax
103			* highlighting.
104			*
105			* @returns recognized tokens of passed script's source code
106			*/
107			std::vector<VMSourceToken> syntaxHighlighting(const String& s);
108
109			/**
110			* Same as above's syntaxHighlighting() method, but this one reads the
111			* script's source code from an input stream object (i.e. stdin or a
112			* file).
113			*
114			* @param is - input stream from which the entire source code of the
115			* script is to be read and loaded from
116			* @returns recognized tokens of passed script's source code
117			*/
118			std::vector<VMSourceToken> syntaxHighlighting(std::istream* is);
119
120			/**
121	schoenebeck	2727	* Dumps the translated tree of the already parsed script, given by
122			* argument @a context, to stdout. This method is for debugging purposes
123			* only.
124			*
125	schoenebeck	2729	* @param context - parsed representation of the script
126	schoenebeck	2728	* @see loadScript()
127	schoenebeck	2727	*/
128	schoenebeck	2588	void dumpParsedScript(VMParserContext* context);
129	schoenebeck	2727
130			/**
131			* Creates a so called VM exceution context for a specific, already
132			* parsed script (provided by argument @a parserContext). Due to the
133			* general real-time design of this virtual machine, the VM execution
134			* context differs for every script. So you must (re)create the
135			* execution context for each script being loaded.
136	schoenebeck	2728	*
137	schoenebeck	2729	* @param parserContext - parsed representation of the script
138	schoenebeck	2728	* @see loadScript()
139	schoenebeck	2727	*/
140	schoenebeck	2588	VMExecContext* createExecContext(VMParserContext* parserContext);
141	schoenebeck	2727
142			/**
143			* Execute a script by virtual machine. Since scripts are event-driven,
144			* you actually execute only one specific event handler block (i.e. a
145			* "on note ... end on" code block) by calling this method (not the
146			* entire script), and hence you must provide one precise handler of the
147			* script to be executed by this method.
148			*
149			* This method usually blocks until the entire script event handler
150			* block has been executed completely. It may however also return before
151			* completion if either a) a script runtime error occurred or b) the
152	schoenebeck	2871	* script was suspended by the VM (either because script execution
153	schoenebeck	2727	* exceeded a certain limit of time or the script called the built-in
154			* wait() function). You must check the return value of this method to
155			* find out which case applies.
156			*
157	schoenebeck	2729	* @param parserContext - parsed representation of the script (see loadScript())
158	schoenebeck	2727	* @param execContext - VM execution context (see createExecContext())
159			* @param handler - precise event handler (i.e. "on note ... end on"
160			* code block) to be executed
161			* (see VMParserContext::eventHandlerByName())
162			* @returns current status of the vitual machine (i.e. script succeeded,
163			* script runtime error occurred or script was suspended for
164			* some reason).
165			*/
166			VMExecStatus_t exec(VMParserContext* parserContext, VMExecContext* execContext, VMEventHandler* handler);
167
168			/**
169			* Returns built-in script function for the given function @a name. To
170			* get the implementation of the built-in message() script function for
171			* example, you would pass "message" here).
172			*
173			* This method is re-implemented by deriving classes to add more use
174			* case specific built-in functions.
175			*
176			* @param name - name of the function to be retrieved (i.e. "wait" for the
177			* built-in wait() function).
178			*/
179	schoenebeck	2594	VMFunction* functionByName(const String& name) OVERRIDE;
180	schoenebeck	2727
181			/**
182			* Returns all built-in integer script variables. This method returns a
183			* STL map, where the map's key is the variable name and the map's value
184			* is the native pointer to the actual built-in variable.
185			*
186			* This method is re-implemented by deriving classes to add more use
187			* case specific built-in variables.
188			*/
189	schoenebeck	2594	std::map<String,VMIntRelPtr*> builtInIntVariables() OVERRIDE;
190	schoenebeck	2727
191			/**
192			* Returns all built-in (8 bit) integer array script variables. This
193			* method returns a STL map, where the map's key is the array variable
194			* name and the map's value is the native pointer to the actual built-in
195			* array variable.
196			*
197			* This method is re-implemented by deriving classes to add more use
198			* case specific built-in array variables.
199			*/
200	schoenebeck	2594	std::map<String,VMInt8Array*> builtInIntArrayVariables() OVERRIDE;
201	schoenebeck	2727
202			/**
203			* Returns all built-in constant integer script variables, which can
204			* only be read, but not be altered by scripts. This method returns a
205			* STL map, where the map's key is the variable name and the map's value
206			* is the native pointer to the actual built-in constant variable.
207			*
208			* This method is re-implemented by deriving classes to add more use
209			* case specific built-in constant integers.
210			*
211			* @b Note: the term "constant" is a bit misleading here, since
212			* built-in constant integer variables may indeed change, i.e. for
213			* built-in constant integers which i.e. reflect some kind of status of
214			* the sampler. So rather see them as "read only" variables, not as
215			* being actually consistent in time.
216			*/
217	schoenebeck	2594	std::map<String,int> builtInConstIntVariables() OVERRIDE;
218	schoenebeck	2588
219	schoenebeck	2879	VMEventHandler* currentVMEventHandler(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
220	schoenebeck	2588	VMParserContext* currentVMParserContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
221			VMExecContext* currentVMExecContext(); //TODO: should be protected (only usable during exec() calls, intended only for VMFunctions)
222	schoenebeck	2727
223	schoenebeck	2581	protected:
224	schoenebeck	2879	VMEventHandler* m_eventHandler;
225	schoenebeck	2588	ParserContext* m_parserContext;
226	schoenebeck	2885	CoreVMFunction_message* m_fnMessage;
227			CoreVMFunction_exit* m_fnExit;
228			CoreVMFunction_wait* m_fnWait;
229			CoreVMFunction_abs* m_fnAbs;
230			CoreVMFunction_random* m_fnRandom;
231			CoreVMFunction_num_elements* m_fnNumElements;
232	schoenebeck	2581	};
233
234			} // namespace LinuxSampler
235
236			#endif // LS_INSTRUMENTSCRIPTVM_H