/[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 2942 by schoenebeck, Wed Jul 13 15:51:06 2016 UTC revision 3293 by schoenebeck, Tue Jun 27 22:19:19 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 9  Line 9 
9    
10  // This header defines data types shared between the VM core implementation  // This header defines data types shared between the VM core implementation
11  // (inside the current source directory) and other parts of the sampler  // (inside the current source directory) and other parts of the sampler
12  // (located at other source directories).  // (located at other source directories). It also acts as public API of the
13    // Real-Time script engine for other applications.
14    
15  #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H  #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H
16  #define LS_INSTR_SCRIPT_PARSER_COMMON_H  #define LS_INSTR_SCRIPT_PARSER_COMMON_H
# Line 157  namespace LinuxSampler { Line 158  namespace LinuxSampler {
158           * expressions to an array expression for you, instead this method will           * expressions to an array expression for you, instead this method will
159           * simply return NULL!           * simply return NULL!
160           *           *
161             * @b Note: this method is currently, and in contrast to its other
162             * counter parts, declared as virtual method. Some deriving classes are
163             * currently using this to override this default implementation in order
164             * to implement an "evaluate now as integer array" behavior. This has
165             * efficiency reasons, however this also currently makes this part of
166             * the API less clean and should thus be addressed in future with
167             * appropriate changes to the API.
168             *
169           * @see exprType()           * @see exprType()
170           */           */
171          VMIntArrayExpr* asIntArray() const;          virtual VMIntArrayExpr* asIntArray() const;
172    
173            /**
174             * Returns true in case this expression can be considered to be a
175             * constant expression. A constant expression will retain the same
176             * value throughout the entire life time of a script and the
177             * expression's constant value may be evaluated already at script
178             * parse time, which may result in performance benefits during script
179             * runtime.
180             *
181             * @b NOTE: A constant expression is per se always also non modifyable.
182             * But a non modifyable expression may not necessarily be a constant
183             * expression!
184             *
185             * @see isModifyable()
186             */
187            virtual bool isConstExpr() const = 0;
188    
189            /**
190             * Returns true in case this expression is allowed to be modified.
191             * If this method returns @c false then this expression must be handled
192             * as read-only expression, which means that assigning a new value to it
193             * is either not possible or not allowed.
194             *
195             * @b NOTE: A constant expression is per se always also non modifyable.
196             * But a non modifyable expression may not necessarily be a constant
197             * expression!
198             *
199             * @see isConstExpr()
200             */
201            bool isModifyable() const;
202      };      };
203    
204      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
# Line 366  namespace LinuxSampler { Line 405  namespace LinuxSampler {
405          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(int iArg) const = 0;
406    
407          /**          /**
408           * This function is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
409           * passed in scripts to this function are accepted by this function. If           * passed in scripts to this function are accepted by this function. If
410           * a script calls this function with an argument's data type not           * a script calls this function with an argument's data type not
411           * 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 384  namespace LinuxSampler { Line 423  namespace LinuxSampler {
423          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;
424    
425          /**          /**
426             * This method is called by the parser to check whether some arguments
427             * (and if yes which ones) passed to this script function will be
428             * modified by this script function. Most script functions simply use
429             * their arguments as inputs, that is they only read the argument's
430             * values. However some script function may also use passed
431             * argument(s) as output variables. In this case the function
432             * implementation must return @c true for the respective argument
433             * index here.
434             *
435             * @param iArg - index of the function argument in question
436             *               (must be between 0 .. maxAllowedArgs() - 1)
437             */
438            virtual bool modifiesArg(int iArg) const = 0;
439    
440            /**
441           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
442           * called by the VM whenever this function implementation shall be           * called by the VM whenever this function implementation shall be
443           * executed at script runtime. This method blocks until the function           * executed at script runtime. This method blocks until the function
# Line 423  namespace LinuxSampler { Line 477  namespace LinuxSampler {
477      struct VMRelPtr {      struct VMRelPtr {
478          void** base; ///< Base pointer.          void** base; ///< Base pointer.
479          int offset;  ///< Offset (in bytes) relative to base pointer.          int offset;  ///< Offset (in bytes) relative to base pointer.
480            bool readonly; ///< Whether the pointed data may be modified or just be read.
481      };      };
482    
483      /** @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 450  namespace LinuxSampler { Line 505  namespace LinuxSampler {
505          VMIntRelPtr() {          VMIntRelPtr() {
506              base   = NULL;              base   = NULL;
507              offset = 0;              offset = 0;
508                readonly = false;
509          }          }
510          VMIntRelPtr(const VMRelPtr& data) {          VMIntRelPtr(const VMRelPtr& data) {
511              base   = data.base;              base   = data.base;
512              offset = data.offset;              offset = data.offset;
513                readonly = false;
514          }          }
515          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }
516          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }
# Line 491  namespace LinuxSampler { Line 548  namespace LinuxSampler {
548          }          }
549      };      };
550    
551        #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
552        # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
553            _Pragma("GCC diagnostic push")                            \
554            _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"")
555        # define COMPILER_RESTORE_OFFSETOF_WARNING \
556            _Pragma("GCC diagnostic pop")
557        #else
558        # define COMPILER_DISABLE_OFFSETOF_WARNING
559        # define COMPILER_RESTORE_OFFSETOF_WARNING
560        #endif
561    
562      /**      /**
563       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr
564       * structures. Usage example:       * structures. Usage example:
# Line 533  namespace LinuxSampler { Line 601  namespace LinuxSampler {
601       * complexity inside the sampler engines which provide the actual script       * complexity inside the sampler engines which provide the actual script
602       * functionalities.       * functionalities.
603       */       */
604      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT(basePtr, T_struct, T_member) (          \
605          (VMRelPtr) {                                     \          /* Disable offsetof warning, trust us, we are cautios. */ \
606              (void**) &basePtr,                           \          COMPILER_DISABLE_OFFSETOF_WARNING                         \
607              offsetof(T_struct, T_member)                 \          (VMRelPtr) {                                              \
608          }                                                \              (void**) &basePtr,                                    \
609      )                                                    \              offsetof(T_struct, T_member),                         \
610                false                                                 \
611            }                                                         \
612            COMPILER_RESTORE_OFFSETOF_WARNING                         \
613        )                                                             \
614    
615        /**
616         * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
617         * VMInt8RelPtr structures to be of read-only type. That means the script
618         * parser will abort any script at parser time if the script is trying to
619         * modify such a read-only built-in variable.
620         *
621         * @b NOTE: this is only intended for built-in read-only variables that
622         * may change during runtime! If your built-in variable's data is rather
623         * already available at parser time and won't change during runtime, then
624         * you should rather register a built-in constant in your VM class instead!
625         *
626         * @see ScriptVM::builtInConstIntVariables()
627         */
628        #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
629            /* Disable offsetof warning, trust us, we are cautios. */ \
630            COMPILER_DISABLE_OFFSETOF_WARNING                         \
631            (VMRelPtr) {                                              \
632                (void**) &basePtr,                                    \
633                offsetof(T_struct, T_member),                         \
634                true                                                  \
635            }                                                         \
636            COMPILER_RESTORE_OFFSETOF_WARNING                         \
637        )                                                             \
638    
639      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
640       *       *
# Line 549  namespace LinuxSampler { Line 645  namespace LinuxSampler {
645      struct VMInt8Array {      struct VMInt8Array {
646          int8_t* data;          int8_t* data;
647          int size;          int size;
648            bool readonly; ///< Whether the array data may be modified or just be read.
649    
650          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
651      };      };
652    
653        /** @brief Virtual machine script variable.
654         *
655         * Common interface for all variables accessed in scripts.
656         */
657        class VMVariable : virtual public VMExpr {
658        public:
659            /**
660             * Whether a script may modify the content of this variable by
661             * assigning a new value to it.
662             *
663             * @see isConstExpr(), assign()
664             */
665            virtual bool isAssignable() const = 0;
666    
667            /**
668             * In case this variable is assignable, this method will be called to
669             * perform the value assignment to this variable with @a expr
670             * reflecting the new value to be assigned.
671             *
672             * @param expr - new value to be assigned to this variable
673             */
674            virtual void assignExpr(VMExpr* expr) = 0;
675        };
676        
677      /** @brief Dynamically executed variable (abstract base class).      /** @brief Dynamically executed variable (abstract base class).
678       *       *
679       * Interface for the implementation of a dynamically generated content of       * Interface for the implementation of a dynamically generated content of
# Line 563  namespace LinuxSampler { Line 684  namespace LinuxSampler {
684       * to a dynamic variable some native code is executed to actually generate       * to a dynamic variable some native code is executed to actually generate
685       * and provide the content (value) of this type of variable.       * and provide the content (value) of this type of variable.
686       */       */
687      class VMDynVar : virtual public VMExpr {      class VMDynVar : public VMVariable {
688      public:      public:
689          /**          /**
          * Whether a script may modify the content of this dynamic variable by  
          * assigning a new value to it.  
          *  
          * @see isConstExpr(), assign()  
          */  
         virtual bool isAssignable() const = 0;  
   
         /**  
690           * Returns true in case this dynamic variable can be considered to be a           * Returns true in case this dynamic variable can be considered to be a
691           * constant expression. A constant expression will retain the same value           * constant expression. A constant expression will retain the same value
692           * throughout the entire life time of a script and the expression's           * throughout the entire life time of a script and the expression's
# Line 609  namespace LinuxSampler { Line 722  namespace LinuxSampler {
722           *           *
723           * @see isAssignable()           * @see isAssignable()
724           */           */
725          virtual bool isConstExpr() const { return false; }          bool isConstExpr() const OVERRIDE { return false; }
726    
727          /**          /**
728           * In case this dynamic variable is assignable, the new value (content)           * In case this dynamic variable is assignable, the new value (content)
# Line 621  namespace LinuxSampler { Line 734  namespace LinuxSampler {
734           *           *
735           * @param expr - new value to be assigned to this variable           * @param expr - new value to be assigned to this variable
736           */           */
737          virtual void assign(VMExpr* expr) {}          void assignExpr(VMExpr* expr) OVERRIDE {}
738    
739            virtual ~VMDynVar() {}
740      };      };
741    
742      /** @brief Dynamically executed variable (of integer data type).      /** @brief Dynamically executed variable (of integer data type).
# Line 644  namespace LinuxSampler { Line 759  namespace LinuxSampler {
759      public:      public:
760      };      };
761    
762        /** @brief Dynamically executed variable (of integer array data type).
763         *
764         * This is the base class for all built-in integer array script variables
765         * whose variable content needs to be provided dynamically by executable
766         * native code on each script variable access.
767         */
768        class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr {
769        public:
770        };
771    
772      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
773       *       *
774       * Abstract base class defining the high-level interface for all classes       * Abstract base class defining the high-level interface for all classes
# Line 727  namespace LinuxSampler { Line 852  namespace LinuxSampler {
852           * @see ScriptVM::exec()           * @see ScriptVM::exec()
853           */           */
854          virtual int suspensionTimeMicroseconds() const = 0;          virtual int suspensionTimeMicroseconds() const = 0;
855    
856            /**
857             * Causes all polyphonic variables to be reset to zero values. A
858             * polyphonic variable is expected to be zero when entering a new event
859             * handler instance. As an exception the values of polyphonic variables
860             * shall only be preserved from an note event handler instance to its
861             * correspending specific release handler instance. So in the latter
862             * case the script author may pass custom data from the note handler to
863             * the release handler, but only for the same specific note!
864             */
865            virtual void resetPolyphonicData() = 0;
866    
867            /**
868             * Returns amount of virtual machine instructions which have been
869             * performed the last time when this execution context was executing a
870             * script. So in case you need the overall amount of instructions
871             * instead, then you need to add them by yourself after each
872             * ScriptVM::exec() call.
873             */
874            virtual size_t instructionsPerformed() const = 0;
875    
876            /**
877             * Sends a signal to this script execution instance to abort its script
878             * execution as soon as possible. This method is called i.e. when one
879             * script execution instance intends to stop another script execution
880             * instance.
881             */
882            virtual void signalAbort() = 0;
883    
884            /**
885             * Copies the current entire execution state from this object to the
886             * given object. So this can be used to "fork" a new script thread which
887             * then may run independently with its own polyphonic data for instance.
888             */
889            virtual void forkTo(VMExecContext* ectx) const = 0;
890      };      };
891    
892      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 758  namespace LinuxSampler { Line 918  namespace LinuxSampler {
918      };      };
919    
920      /**      /**
921         * Reflects the precise position and span of a specific code block within
922         * a script. This is currently only used for the locations of commented
923         * code blocks due to preprocessor statements, and for parser errors and
924         * parser warnings.
925         *
926         * @see ParserIssue for code locations of parser errors and parser warnings
927         *
928         * @see VMParserContext::preprocessorComments() for locations of code which
929         *      have been filtered out by preprocessor statements
930         */
931        struct CodeBlock {
932            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
933            int lastLine; ///< The last line number of this code block within the script.
934            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
935            int lastColumn; ///< The last column of this code block within the script.
936        };
937    
938        /**
939       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
940       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
941       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
942       * encountered parser issue within the script.       * encountered parser issue within the script.
943         *
944         * @see VMSourceToken for processing syntax highlighting instead.
945       */       */
946      struct ParserIssue {      struct ParserIssue : CodeBlock {
947          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
         int firstLine; ///< The first line number within the script where this issue was encountered (indexed with 1 being the very first line).  
         int lastLine; ///< The last line number within the script where this issue was encountered.  
         int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).  
         int lastColumn; ///< The last column within the script where this issue was encountered.  
948          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.
949    
950          /**          /**
# Line 848  namespace LinuxSampler { Line 1024  namespace LinuxSampler {
1024          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1025    
1026          /**          /**
1027             * Returns all code blocks of the script which were filtered out by the
1028             * preprocessor.
1029             */
1030            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1031    
1032            /**
1033           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1034           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1035           * parsed script. This translated representation of the event handler           * parsed script. This translated representation of the event handler
# Line 880  namespace LinuxSampler { Line 1062  namespace LinuxSampler {
1062       * This class is not actually used by the sampler itself. It is rather       * This class is not actually used by the sampler itself. It is rather
1063       * provided for external script editor applications. Primary purpose of       * provided for external script editor applications. Primary purpose of
1064       * this class is syntax highlighting for external script editors.       * this class is syntax highlighting for external script editors.
1065         *
1066         * @see ParserIssue for processing compile errors and warnings instead.
1067       */       */
1068      class VMSourceToken {      class VMSourceToken {
1069      public:      public:
# Line 892  namespace LinuxSampler { Line 1076  namespace LinuxSampler {
1076          String text() const;          String text() const;
1077    
1078          // position of token in script          // position of token in script
1079          int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line).          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.
1080          int firstColumn() const; ///< Last line this source token is located at in script source code.          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().
1081    
1082          // base types          // base types
1083          bool isEOF() const;          bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1084          bool isNewLine() const;          bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1085          bool isKeyword() const;          bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1086          bool isVariableName() const;          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.
1087          bool isIdentifier() const;          bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1088          bool isNumberLiteral() const;          bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1089          bool isStringLiteral() const;          bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1090          bool isComment() const;          bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1091          bool isPreprocessor() const;          bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1092          bool isOther() const;          bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1093    
1094          // extended types          // extended types
1095          bool isIntegerVariable() const;          bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1096          bool isStringVariable() const;          bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1097          bool isArrayVariable() const;          bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1098          bool isEventHandlerName() const;          bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1099    
1100          VMSourceToken& operator=(const VMSourceToken& other);          VMSourceToken& operator=(const VMSourceToken& other);
1101    
Legend:
Removed from v.2942  
changed lines
  Added in v.3293
  ViewVC Help
Powered by ViewVC