/[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 2871 by schoenebeck, Sun Apr 10 18:22:23 2016 UTC revision 3277 by schoenebeck, Mon Jun 5 18:40:18 2017 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014-2016 Christian Schoenebeck   * Copyright (c) 2014-2017 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 145  namespace LinuxSampler { Line 157  namespace LinuxSampler {
157           * expressions to an array expression for you, instead this method will           * expressions to an array expression for you, instead this method will
158           * simply return NULL!           * simply return NULL!
159           *           *
160             * @b Note: this method is currently, and in contrast to its other
161             * counter parts, declared as virtual method. Some deriving classes are
162             * currently using this to override this default implementation in order
163             * to implement an "evaluate now as integer array" behavior. This has
164             * efficiency reasons, however this also currently makes this part of
165             * the API less clean and should thus be addressed in future with
166             * appropriate changes to the API.
167             *
168           * @see exprType()           * @see exprType()
169           */           */
170          VMIntArrayExpr* asIntArray() const;          virtual VMIntArrayExpr* asIntArray() const;
171    
172            /**
173             * Returns true in case this expression can be considered to be a
174             * constant expression. A constant expression will retain the same
175             * value throughout the entire life time of a script and the
176             * expression's constant value may be evaluated already at script
177             * parse time, which may result in performance benefits during script
178             * runtime.
179             *
180             * @b NOTE: A constant expression is per se always also non modifyable.
181             * But a non modifyable expression may not necessarily be a constant
182             * expression!
183             *
184             * @see isModifyable()
185             */
186            virtual bool isConstExpr() const = 0;
187    
188            /**
189             * Returns true in case this expression is allowed to be modified.
190             * If this method returns @c false then this expression must be handled
191             * as read-only expression, which means that assigning a new value to it
192             * is either not possible or not allowed.
193             *
194             * @b NOTE: A constant expression is per se always also non modifyable.
195             * But a non modifyable expression may not necessarily be a constant
196             * expression!
197             *
198             * @see isConstExpr()
199             */
200            bool isModifyable() const;
201      };      };
202    
203      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
# Line 354  namespace LinuxSampler { Line 404  namespace LinuxSampler {
404          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(int iArg) const = 0;
405    
406          /**          /**
407           * This function is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
408           * passed in scripts to this function are accepted by this function. If           * passed in scripts to this function are accepted by this function. If
409           * a script calls this function with an argument's data type not           * a script calls this function with an argument's data type not
410           * 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 422  namespace LinuxSampler {
422          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;
423    
424          /**          /**
425             * This method is called by the parser to check whether some arguments
426             * (and if yes which ones) passed to this script function will be
427             * modified by this script function. Most script functions simply use
428             * their arguments as inputs, that is they only read the argument's
429             * values. However some script function may also use passed
430             * argument(s) as output variables. In this case the function
431             * implementation must return @c true for the respective argument
432             * index here.
433             *
434             * @param iArg - index of the function argument in question
435             *               (must be between 0 .. maxAllowedArgs() - 1)
436             */
437            virtual bool modifiesArg(int iArg) const = 0;
438    
439            /**
440           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
441           * called by the VM whenever this function implementation shall be           * called by the VM whenever this function implementation shall be
442           * 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 476  namespace LinuxSampler {
476      struct VMRelPtr {      struct VMRelPtr {
477          void** base; ///< Base pointer.          void** base; ///< Base pointer.
478          int offset;  ///< Offset (in bytes) relative to base pointer.          int offset;  ///< Offset (in bytes) relative to base pointer.
479            bool readonly; ///< Whether the pointed data may be modified or just be read.
480      };      };
481    
482      /** @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 504  namespace LinuxSampler {
504          VMIntRelPtr() {          VMIntRelPtr() {
505              base   = NULL;              base   = NULL;
506              offset = 0;              offset = 0;
507                readonly = false;
508          }          }
509          VMIntRelPtr(const VMRelPtr& data) {          VMIntRelPtr(const VMRelPtr& data) {
510              base   = data.base;              base   = data.base;
511              offset = data.offset;              offset = data.offset;
512                readonly = false;
513          }          }
514          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }
515          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }
# Line 479  namespace LinuxSampler { Line 547  namespace LinuxSampler {
547          }          }
548      };      };
549    
550        #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
551        # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
552            _Pragma("GCC diagnostic push")                            \
553            _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"")
554        # define COMPILER_RESTORE_OFFSETOF_WARNING \
555            _Pragma("GCC diagnostic pop")
556        #else
557        # define COMPILER_DISABLE_OFFSETOF_WARNING
558        # define COMPILER_RESTORE_OFFSETOF_WARNING
559        #endif
560    
561      /**      /**
562       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr
563       * structures. Usage example:       * structures. Usage example:
# Line 521  namespace LinuxSampler { Line 600  namespace LinuxSampler {
600       * complexity inside the sampler engines which provide the actual script       * complexity inside the sampler engines which provide the actual script
601       * functionalities.       * functionalities.
602       */       */
603      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT(basePtr, T_struct, T_member) (          \
604          (VMRelPtr) {                                     \          /* Disable offsetof warning, trust us, we are cautios. */ \
605              (void**) &basePtr,                           \          COMPILER_DISABLE_OFFSETOF_WARNING                         \
606              offsetof(T_struct, T_member)                 \          (VMRelPtr) {                                              \
607          }                                                \              (void**) &basePtr,                                    \
608      )                                                    \              offsetof(T_struct, T_member),                         \
609                false                                                 \
610            }                                                         \
611            COMPILER_RESTORE_OFFSETOF_WARNING                         \
612        )                                                             \
613    
614        /**
615         * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
616         * VMInt8RelPtr structures to be of read-only type. That means the script
617         * parser will abort any script at parser time if the script is trying to
618         * modify such a read-only built-in variable.
619         *
620         * @b NOTE: this is only intended for built-in read-only variables that
621         * may change during runtime! If your built-in variable's data is rather
622         * already available at parser time and won't change during runtime, then
623         * you should rather register a built-in constant in your VM class instead!
624         *
625         * @see ScriptVM::builtInConstIntVariables()
626         */
627        #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
628            /* Disable offsetof warning, trust us, we are cautios. */ \
629            COMPILER_DISABLE_OFFSETOF_WARNING                         \
630            (VMRelPtr) {                                              \
631                (void**) &basePtr,                                    \
632                offsetof(T_struct, T_member),                         \
633                true                                                  \
634            }                                                         \
635            COMPILER_RESTORE_OFFSETOF_WARNING                         \
636        )                                                             \
637    
638      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
639       *       *
# Line 537  namespace LinuxSampler { Line 644  namespace LinuxSampler {
644      struct VMInt8Array {      struct VMInt8Array {
645          int8_t* data;          int8_t* data;
646          int size;          int size;
647            bool readonly; ///< Whether the array data may be modified or just be read.
648    
649          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
650        };
651    
652        /** @brief Virtual machine script variable.
653         *
654         * Common interface for all variables accessed in scripts.
655         */
656        class VMVariable : virtual public VMExpr {
657        public:
658            /**
659             * Whether a script may modify the content of this variable by
660             * assigning a new value to it.
661             *
662             * @see isConstExpr(), assign()
663             */
664            virtual bool isAssignable() const = 0;
665    
666            /**
667             * In case this variable is assignable, this method will be called to
668             * perform the value assignment to this variable with @a expr
669             * reflecting the new value to be assigned.
670             *
671             * @param expr - new value to be assigned to this variable
672             */
673            virtual void assignExpr(VMExpr* expr) = 0;
674        };
675        
676        /** @brief Dynamically executed variable (abstract base class).
677         *
678         * Interface for the implementation of a dynamically generated content of
679         * a built-in script variable. Most built-in variables are simply pointers
680         * to some native location in memory. So when a script reads them, the
681         * memory location is simply read to get the value of the variable. A
682         * dynamic variable however is not simply a memory location. For each access
683         * to a dynamic variable some native code is executed to actually generate
684         * and provide the content (value) of this type of variable.
685         */
686        class VMDynVar : public VMVariable {
687        public:
688            /**
689             * Returns true in case this dynamic variable can be considered to be a
690             * constant expression. A constant expression will retain the same value
691             * throughout the entire life time of a script and the expression's
692             * constant value may be evaluated already at script parse time, which
693             * may result in performance benefits during script runtime.
694             *
695             * However due to the "dynamic" behavior of dynamic variables, almost
696             * all dynamic variables are probably not constant expressions. That's
697             * why this method returns @c false by default. If you are really sure
698             * that your dynamic variable implementation can be considered a
699             * constant expression then you may override this method and return
700             * @c true instead. Note that when you return @c true here, your
701             * dynamic variable will really just be executed once; and exectly
702             * already when the script is loaded!
703             *
704             * As an example you may implement a "constant" built-in dynamic
705             * variable that checks for a certain operating system feature and
706             * returns the result of that OS feature check as content (value) of
707             * this dynamic variable. Since the respective OS feature might become
708             * available/unavailable after OS updates, software migration, etc. the
709             * OS feature check should at least be performed once each time the
710             * application is launched. And since the OS feature check might take a
711             * certain amount of execution time, it might make sense to only
712             * perform the check if the respective variable name is actually
713             * referenced at all in the script to be loaded. Note that the dynamic
714             * variable will still be evaluated again though if the script is
715             * loaded again. So it is up to you to probably cache the result in the
716             * implementation of your dynamic variable.
717             *
718             * On doubt, please rather consider to use a constant built-in script
719             * variable instead of implementing a "constant" dynamic variable, due
720             * to the runtime overhead a dynamic variable may cause.
721             *
722             * @see isAssignable()
723             */
724            bool isConstExpr() const OVERRIDE { return false; }
725    
726            /**
727             * In case this dynamic variable is assignable, the new value (content)
728             * to be assigned to this dynamic variable.
729             *
730             * By default this method does nothing. Override and implement this
731             * method in your subclass in case your dynamic variable allows to
732             * assign a new value by script.
733             *
734             * @param expr - new value to be assigned to this variable
735             */
736            void assignExpr(VMExpr* expr) OVERRIDE {}
737    
738            virtual ~VMDynVar() {}
739        };
740    
741        /** @brief Dynamically executed variable (of integer data type).
742         *
743         * This is the base class for all built-in integer script variables whose
744         * variable content needs to be provided dynamically by executable native
745         * code on each script variable access.
746         */
747        class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
748        public:
749        };
750    
751        /** @brief Dynamically executed variable (of string data type).
752         *
753         * This is the base class for all built-in string script variables whose
754         * variable content needs to be provided dynamically by executable native
755         * code on each script variable access.
756         */
757        class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
758        public:
759        };
760    
761        /** @brief Dynamically executed variable (of integer array data type).
762         *
763         * This is the base class for all built-in integer array script variables
764         * whose variable content needs to be provided dynamically by executable
765         * native code on each script variable access.
766         */
767        class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr {
768        public:
769      };      };
770    
771      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
# Line 575  namespace LinuxSampler { Line 802  namespace LinuxSampler {
802           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
803           */           */
804          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,int> builtInConstIntVariables() = 0;
805    
806            /**
807             * Returns a variable name indexed map of all built-in dynamic variables,
808             * which are not simply data stores, rather each one of them executes
809             * natively to provide or alter the respective script variable data.
810             */
811            virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
812      };      };
813    
814      /** @brief Execution state of a virtual machine.      /** @brief Execution state of a virtual machine.
# Line 617  namespace LinuxSampler { Line 851  namespace LinuxSampler {
851           * @see ScriptVM::exec()           * @see ScriptVM::exec()
852           */           */
853          virtual int suspensionTimeMicroseconds() const = 0;          virtual int suspensionTimeMicroseconds() const = 0;
854    
855            /**
856             * Causes all polyphonic variables to be reset to zero values. A
857             * polyphonic variable is expected to be zero when entering a new event
858             * handler instance. As an exception the values of polyphonic variables
859             * shall only be preserved from an note event handler instance to its
860             * correspending specific release handler instance. So in the latter
861             * case the script author may pass custom data from the note handler to
862             * the release handler, but only for the same specific note!
863             */
864            virtual void resetPolyphonicData() = 0;
865    
866            /**
867             * Returns amount of virtual machine instructions which have been
868             * performed the last time when this execution context was executing a
869             * script. So in case you need the overall amount of instructions
870             * instead, then you need to add them by yourself after each
871             * ScriptVM::exec() call.
872             */
873            virtual size_t instructionsPerformed() const = 0;
874    
875            /**
876             * Sends a signal to this script execution instance to abort its script
877             * execution as soon as possible. This method is called i.e. when one
878             * script execution instance intends to stop another script execution
879             * instance.
880             */
881            virtual void signalAbort() = 0;
882      };      };
883    
884      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 627  namespace LinuxSampler { Line 889  namespace LinuxSampler {
889      class VMEventHandler {      class VMEventHandler {
890      public:      public:
891          /**          /**
892             * Type of this event handler, which identifies its purpose. For example
893             * for a "on note ... end on" script callback block,
894             * @c VM_EVENT_HANDLER_NOTE would be returned here.
895             */
896            virtual VMEventHandlerType_t eventHandlerType() const = 0;
897    
898            /**
899           * Name of the event handler which identifies its purpose. For example           * Name of the event handler which identifies its purpose. For example
900           * for a "on note ... end on" script callback block, the name "note"           * for a "on note ... end on" script callback block, the name "note"
901           * would be returned here.           * would be returned here.
# Line 645  namespace LinuxSampler { Line 914  namespace LinuxSampler {
914       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
915       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
916       * encountered parser issue within the script.       * encountered parser issue within the script.
917         *
918         * @see VMSourceToken for processing syntax highlighting instead.
919       */       */
920      struct ParserIssue {      struct ParserIssue {
921          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
922          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).
923            int lastLine; ///< The last line number within the script where this issue was encountered.
924            int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).
925            int lastColumn; ///< The last column within the script where this issue was encountered.
926          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.
927    
928          /**          /**
# Line 657  namespace LinuxSampler { Line 931  namespace LinuxSampler {
931          inline void dump() {          inline void dump() {
932              switch (type) {              switch (type) {
933                  case PARSER_ERROR:                  case PARSER_ERROR:
934                      printf("[ERROR] line %d: %s\n", line, txt.c_str());                      printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
935                      break;                      break;
936                  case PARSER_WARNING:                  case PARSER_WARNING:
937                      printf("[Warning] line %d: %s\n", line, txt.c_str());                      printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
938                      break;                      break;
939              }              }
940          }          }
# Line 748  namespace LinuxSampler { Line 1022  namespace LinuxSampler {
1022          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
1023      };      };
1024    
1025        class SourceToken;
1026    
1027        /** @brief Recognized token of a script's source code.
1028         *
1029         * Represents one recognized token of a script's source code, for example
1030         * a keyword, variable name, etc. and it provides further informations about
1031         * that particular token, i.e. the precise location (line and column) of the
1032         * token within the original script's source code.
1033         *
1034         * This class is not actually used by the sampler itself. It is rather
1035         * provided for external script editor applications. Primary purpose of
1036         * this class is syntax highlighting for external script editors.
1037         *
1038         * @see ParserIssue for processing compile errors and warnings instead.
1039         */
1040        class VMSourceToken {
1041        public:
1042            VMSourceToken();
1043            VMSourceToken(SourceToken* ct);
1044            VMSourceToken(const VMSourceToken& other);
1045            virtual ~VMSourceToken();
1046    
1047            // original text of this token as it is in the script's source code
1048            String text() const;
1049    
1050            // position of token in script
1051            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.
1052            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().
1053    
1054            // base types
1055            bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1056            bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1057            bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1058            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.
1059            bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1060            bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1061            bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1062            bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1063            bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1064            bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1065    
1066            // extended types
1067            bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1068            bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1069            bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1070            bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1071    
1072            VMSourceToken& operator=(const VMSourceToken& other);
1073    
1074        private:
1075            SourceToken* m_token;
1076        };
1077    
1078  } // namespace LinuxSampler  } // namespace LinuxSampler
1079    
1080  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H
Legend:
Removed from v.2871  
changed lines
  Added in v.3277
  ViewVC Help
Powered by ViewVC