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

Diff of /linuxsampler/trunk/src/scriptvm/common.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2727 by schoenebeck, Tue Mar 31 17:46:11 2015 UTC revision 3012 by schoenebeck, Wed Oct 12 12:50:37 2016 UTC
# Line 1  Line 1 
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   *   *
# Line 76  namespace LinuxSampler { Line 76  namespace LinuxSampler {
76          VM_EXEC_ERROR = (1<<2), ///< A runtime error occurred while executing the script (i.e. a call to some built-in script function failed).          VM_EXEC_ERROR = (1<<2), ///< A runtime error occurred while executing the script (i.e. a call to some built-in script function failed).
77      };      };
78    
79        /** @brief Script event handler type.
80         *
81         * Identifies one of the possible event handler callback types defined by
82         * the NKSP script language.
83         */
84        enum VMEventHandlerType_t {
85            VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block.
86            VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block.
87            VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block.
88            VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block.
89        };
90    
91      // just symbol prototyping      // just symbol prototyping
92      class VMIntExpr;      class VMIntExpr;
93      class VMStringExpr;      class VMStringExpr;
# Line 148  namespace LinuxSampler { Line 160  namespace LinuxSampler {
160           * @see exprType()           * @see exprType()
161           */           */
162          VMIntArrayExpr* asIntArray() const;          VMIntArrayExpr* asIntArray() const;
163    
164            /**
165             * Returns true in case this expression can be considered to be a
166             * constant expression. A constant expression will retain the same
167             * value throughout the entire life time of a script and the
168             * expression's constant value may be evaluated already at script
169             * parse time, which may result in performance benefits during script
170             * runtime.
171             *
172             * @b NOTE: A constant expression is per se always also non modifyable.
173             * But a non modifyable expression may not necessarily be a constant
174             * expression!
175             *
176             * @see isModifyable()
177             */
178            virtual bool isConstExpr() const = 0;
179    
180            /**
181             * Returns true in case this expression is allowed to be modified.
182             * If this method returns @c false then this expression must be handled
183             * as read-only expression, which means that assigning a new value to it
184             * is either not possible or not allowed.
185             *
186             * @b NOTE: A constant expression is per se always also non modifyable.
187             * But a non modifyable expression may not necessarily be a constant
188             * expression!
189             *
190             * @see isConstExpr()
191             */
192            bool isModifyable() const;
193      };      };
194    
195      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
# Line 341  namespace LinuxSampler { Line 383  namespace LinuxSampler {
383           * Script data type of the function's @c iArg 'th function argument.           * Script data type of the function's @c iArg 'th function argument.
384           * The information provided here is less strong than acceptsArgType().           * The information provided here is less strong than acceptsArgType().
385           * The parser will compare argument data types provided in scripts by           * The parser will compare argument data types provided in scripts by
386           * calling cceptsArgType(). The return value of argType() is used by the           * calling acceptsArgType(). The return value of argType() is used by the
387           * parser instead to show an appropriate parser error which data type           * parser instead to show an appropriate parser error which data type
388           * this function usually expects as "default" data type. Reason: a           * this function usually expects as "default" data type. Reason: a
389           * function may accept multiple data types for a certain function           * function may accept multiple data types for a certain function
# Line 354  namespace LinuxSampler { Line 396  namespace LinuxSampler {
396          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(int iArg) const = 0;
397    
398          /**          /**
399           * This function is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
400           * passed in scripts to this function are accepted by this function. If           * passed in scripts to this function are accepted by this function. If
401           * a script calls this function with an argument's data type not           * a script calls this function with an argument's data type not
402           * accepted by this function, the parser will throw a parser error. On           * accepted by this function, the parser will throw a parser error. On
# Line 372  namespace LinuxSampler { Line 414  namespace LinuxSampler {
414          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;
415    
416          /**          /**
417             * This method is called by the parser to check whether some arguments
418             * (and if yes which ones) passed to this script function will be
419             * modified by this script function. Most script functions simply use
420             * their arguments as inputs, that is they only read the argument's
421             * values. However some script function may also use passed
422             * argument(s) as output variables. In this case the function
423             * implementation must return @c true for the respective argument
424             * index here.
425             *
426             * @param iArg - index of the function argument in question
427             *               (must be between 0 .. maxAllowedArgs() - 1)
428             */
429            virtual bool modifiesArg(int iArg) const = 0;
430    
431            /**
432           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
433           * called by the VM whenever this function implementation shall be           * called by the VM whenever this function implementation shall be
434           * executed at script runtime. This method blocks until the function           * executed at script runtime. This method blocks until the function
# Line 411  namespace LinuxSampler { Line 468  namespace LinuxSampler {
468      struct VMRelPtr {      struct VMRelPtr {
469          void** base; ///< Base pointer.          void** base; ///< Base pointer.
470          int offset;  ///< Offset (in bytes) relative to base pointer.          int offset;  ///< Offset (in bytes) relative to base pointer.
471            bool readonly; ///< Whether the pointed data may be modified or just be read.
472      };      };
473    
474      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).
# Line 438  namespace LinuxSampler { Line 496  namespace LinuxSampler {
496          VMIntRelPtr() {          VMIntRelPtr() {
497              base   = NULL;              base   = NULL;
498              offset = 0;              offset = 0;
499                readonly = false;
500          }          }
501          VMIntRelPtr(const VMRelPtr& data) {          VMIntRelPtr(const VMRelPtr& data) {
502              base   = data.base;              base   = data.base;
503              offset = data.offset;              offset = data.offset;
504                readonly = false;
505          }          }
506          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }
507          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }
# Line 524  namespace LinuxSampler { Line 584  namespace LinuxSampler {
584      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \
585          (VMRelPtr) {                                     \          (VMRelPtr) {                                     \
586              (void**) &basePtr,                           \              (void**) &basePtr,                           \
587              offsetof(T_struct, T_member)                 \              offsetof(T_struct, T_member),                \
588                false                                        \
589          }                                                \          }                                                \
590      )                                                    \      )                                                    \
591    
592        /**
593         * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
594         * VMInt8RelPtr structures to be of read-only type. That means the script
595         * parser will abort any script at parser time if the script is trying to
596         * modify such a read-only built-in variable.
597         *
598         * @b NOTE: this is only intended for built-in read-only variables that
599         * may change during runtime! If your built-in variable's data is rather
600         * already available at parser time and won't change during runtime, then
601         * you should rather register a built-in constant in your VM class instead!
602         *
603         * @see ScriptVM::builtInConstIntVariables()
604         */
605        #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
606            (VMRelPtr) {                                          \
607                (void**) &basePtr,                                \
608                offsetof(T_struct, T_member),                     \
609                true                                              \
610            }                                                     \
611        )                                                         \
612    
613      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
614       *       *
615       * Used for defining built-in integer array script variables (8 bit per       * Used for defining built-in integer array script variables (8 bit per
# Line 541  namespace LinuxSampler { Line 623  namespace LinuxSampler {
623          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0) {}
624      };      };
625    
626        /** @brief Virtual machine script variable.
627         *
628         * Common interface for all variables accessed in scripts.
629         */
630        class VMVariable : virtual public VMExpr {
631        public:
632            /**
633             * Whether a script may modify the content of this variable by
634             * assigning a new value to it.
635             *
636             * @see isConstExpr(), assign()
637             */
638            virtual bool isAssignable() const = 0;
639    
640            /**
641             * In case this variable is assignable, this method will be called to
642             * perform the value assignment to this variable with @a expr
643             * reflecting the new value to be assigned.
644             *
645             * @param expr - new value to be assigned to this variable
646             */
647            virtual void assignExpr(VMExpr* expr) = 0;
648        };
649        
650        /** @brief Dynamically executed variable (abstract base class).
651         *
652         * Interface for the implementation of a dynamically generated content of
653         * a built-in script variable. Most built-in variables are simply pointers
654         * to some native location in memory. So when a script reads them, the
655         * memory location is simply read to get the value of the variable. A
656         * dynamic variable however is not simply a memory location. For each access
657         * to a dynamic variable some native code is executed to actually generate
658         * and provide the content (value) of this type of variable.
659         */
660        class VMDynVar : public VMVariable {
661        public:
662            /**
663             * Returns true in case this dynamic variable can be considered to be a
664             * constant expression. A constant expression will retain the same value
665             * throughout the entire life time of a script and the expression's
666             * constant value may be evaluated already at script parse time, which
667             * may result in performance benefits during script runtime.
668             *
669             * However due to the "dynamic" behavior of dynamic variables, almost
670             * all dynamic variables are probably not constant expressions. That's
671             * why this method returns @c false by default. If you are really sure
672             * that your dynamic variable implementation can be considered a
673             * constant expression then you may override this method and return
674             * @c true instead. Note that when you return @c true here, your
675             * dynamic variable will really just be executed once; and exectly
676             * already when the script is loaded!
677             *
678             * As an example you may implement a "constant" built-in dynamic
679             * variable that checks for a certain operating system feature and
680             * returns the result of that OS feature check as content (value) of
681             * this dynamic variable. Since the respective OS feature might become
682             * available/unavailable after OS updates, software migration, etc. the
683             * OS feature check should at least be performed once each time the
684             * application is launched. And since the OS feature check might take a
685             * certain amount of execution time, it might make sense to only
686             * perform the check if the respective variable name is actually
687             * referenced at all in the script to be loaded. Note that the dynamic
688             * variable will still be evaluated again though if the script is
689             * loaded again. So it is up to you to probably cache the result in the
690             * implementation of your dynamic variable.
691             *
692             * On doubt, please rather consider to use a constant built-in script
693             * variable instead of implementing a "constant" dynamic variable, due
694             * to the runtime overhead a dynamic variable may cause.
695             *
696             * @see isAssignable()
697             */
698            bool isConstExpr() const OVERRIDE { return false; }
699    
700            /**
701             * In case this dynamic variable is assignable, the new value (content)
702             * to be assigned to this dynamic variable.
703             *
704             * By default this method does nothing. Override and implement this
705             * method in your subclass in case your dynamic variable allows to
706             * assign a new value by script.
707             *
708             * @param expr - new value to be assigned to this variable
709             */
710            void assignExpr(VMExpr* expr) OVERRIDE {}
711        };
712    
713        /** @brief Dynamically executed variable (of integer data type).
714         *
715         * This is the base class for all built-in integer script variables whose
716         * variable content needs to be provided dynamically by executable native
717         * code on each script variable access.
718         */
719        class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
720        public:
721        };
722    
723        /** @brief Dynamically executed variable (of string data type).
724         *
725         * This is the base class for all built-in string script variables whose
726         * variable content needs to be provided dynamically by executable native
727         * code on each script variable access.
728         */
729        class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
730        public:
731        };
732    
733      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
734       *       *
735       * Abstract base class defining the high-level interface for all classes       * Abstract base class defining the high-level interface for all classes
# Line 575  namespace LinuxSampler { Line 764  namespace LinuxSampler {
764           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
765           */           */
766          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,int> builtInConstIntVariables() = 0;
767    
768            /**
769             * Returns a variable name indexed map of all built-in dynamic variables,
770             * which are not simply data stores, rather each one of them executes
771             * natively to provide or alter the respective script variable data.
772             */
773            virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
774      };      };
775    
776      /** @brief Execution state of a virtual machine.      /** @brief Execution state of a virtual machine.
# Line 604  namespace LinuxSampler { Line 800  namespace LinuxSampler {
800           * engine) which is using the virtual machine classes here, must take           * engine) which is using the virtual machine classes here, must take
801           * care by itself about taking time stamps, determining the script           * care by itself about taking time stamps, determining the script
802           * handlers that shall be put aside for the requested amount of           * handlers that shall be put aside for the requested amount of
803           * microseconds indicated by this method by comparing the time stamps in           * microseconds, indicated by this method by comparing the time stamps in
804           * real-time, and to continue passing the respective handler to           * real-time, and to continue passing the respective handler to
805           * ScriptVM::exec() as soon as its suspension exceeded, etc. Or in other           * ScriptVM::exec() as soon as its suspension exceeded, etc. Or in other
806           * words: all classes in this directory never have an idea what time it           * words: all classes in this directory never have an idea what time it
# Line 627  namespace LinuxSampler { Line 823  namespace LinuxSampler {
823      class VMEventHandler {      class VMEventHandler {
824      public:      public:
825          /**          /**
826             * Type of this event handler, which identifies its purpose. For example
827             * for a "on note ... end on" script callback block,
828             * @c VM_EVENT_HANDLER_NOTE would be returned here.
829             */
830            virtual VMEventHandlerType_t eventHandlerType() const = 0;
831    
832            /**
833           * Name of the event handler which identifies its purpose. For example           * Name of the event handler which identifies its purpose. For example
834           * for a "on note ... end on" script callback block, the name "note"           * for a "on note ... end on" script callback block, the name "note"
835           * would be returned here.           * would be returned here.
# Line 645  namespace LinuxSampler { Line 848  namespace LinuxSampler {
848       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
849       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
850       * encountered parser issue within the script.       * encountered parser issue within the script.
851         *
852         * @see VMSourceToken for processing syntax highlighting instead.
853       */       */
854      struct ParserIssue {      struct ParserIssue {
855          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
856          int line; ///< Line number within the script where this issue was encountered.          int firstLine; ///< The first line number within the script where this issue was encountered (indexed with 1 being the very first line).
857            int lastLine; ///< The last line number within the script where this issue was encountered.
858            int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).
859            int lastColumn; ///< The last column within the script where this issue was encountered.
860          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.
861    
862          /**          /**
# Line 657  namespace LinuxSampler { Line 865  namespace LinuxSampler {
865          inline void dump() {          inline void dump() {
866              switch (type) {              switch (type) {
867                  case PARSER_ERROR:                  case PARSER_ERROR:
868                      printf("[ERROR] line %d: %s\n", line, txt.c_str());                      printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
869                      break;                      break;
870                  case PARSER_WARNING:                  case PARSER_WARNING:
871                      printf("[Warning] line %d: %s\n", line, txt.c_str());                      printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
872                      break;                      break;
873              }              }
874          }          }
# Line 748  namespace LinuxSampler { Line 956  namespace LinuxSampler {
956          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
957      };      };
958    
959        class SourceToken;
960    
961        /** @brief Recognized token of a script's source code.
962         *
963         * Represents one recognized token of a script's source code, for example
964         * a keyword, variable name, etc. and it provides further informations about
965         * that particular token, i.e. the precise location (line and column) of the
966         * token within the original script's source code.
967         *
968         * This class is not actually used by the sampler itself. It is rather
969         * provided for external script editor applications. Primary purpose of
970         * this class is syntax highlighting for external script editors.
971         *
972         * @see ParserIssue for processing compile errors and warnings instead.
973         */
974        class VMSourceToken {
975        public:
976            VMSourceToken();
977            VMSourceToken(SourceToken* ct);
978            VMSourceToken(const VMSourceToken& other);
979            virtual ~VMSourceToken();
980    
981            // original text of this token as it is in the script's source code
982            String text() const;
983    
984            // position of token in script
985            int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line). Most source code tokens are not spanning over multiple lines, the only current exception are comments, in the latter case you need to process text() to get the last line and last column for the comment.
986            int firstColumn() const; ///< First column on the first line this source token is located at in script source code (indexed with 0 being the very first column). To get the length of this token use text().length().
987    
988            // base types
989            bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
990            bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
991            bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
992            bool isVariableName() const; ///< Returns true in case this source token represents a variable name (i.e. "$someIntVariable", "%someArrayVariable", "\@someStringVariable"). @see isIntegerVariable(), isStringVariable(), isArrayVariable() for the precise variable type.
993            bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
994            bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
995            bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
996            bool isComment() const; ///< Returns true in case this source token represents a source code comment.
997            bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
998            bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
999    
1000            // extended types
1001            bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1002            bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1003            bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1004            bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1005    
1006            VMSourceToken& operator=(const VMSourceToken& other);
1007    
1008        private:
1009            SourceToken* m_token;
1010        };
1011    
1012  } // namespace LinuxSampler  } // namespace LinuxSampler
1013    
1014  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H
Legend:
Removed from v.2727  
changed lines
  Added in v.3012
  ViewVC Help
Powered by ViewVC