/[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 2889 by schoenebeck, Mon Apr 25 17:28:23 2016 UTC revision 3035 by schoenebeck, Mon Oct 31 12:00:00 2016 UTC
# Line 160  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 366  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 384  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 423  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 450  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 491  namespace LinuxSampler { Line 539  namespace LinuxSampler {
539          }          }
540      };      };
541    
542        #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
543        # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
544            _Pragma("GCC diagnostic push")                            \
545            _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"")
546        # define COMPILER_RESTORE_OFFSETOF_WARNING \
547            _Pragma("GCC diagnostic pop")
548        #else
549        # define COMPILER_DISABLE_OFFSETOF_WARNING
550        # define COMPILER_RESTORE_OFFSETOF_WARNING
551        #endif
552    
553      /**      /**
554       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr
555       * structures. Usage example:       * structures. Usage example:
# Line 533  namespace LinuxSampler { Line 592  namespace LinuxSampler {
592       * complexity inside the sampler engines which provide the actual script       * complexity inside the sampler engines which provide the actual script
593       * functionalities.       * functionalities.
594       */       */
595      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT(basePtr, T_struct, T_member) (          \
596          (VMRelPtr) {                                     \          /* Disable offsetof warning, trust us, we are cautios. */ \
597              (void**) &basePtr,                           \          COMPILER_DISABLE_OFFSETOF_WARNING                         \
598              offsetof(T_struct, T_member)                 \          (VMRelPtr) {                                              \
599          }                                                \              (void**) &basePtr,                                    \
600      )                                                    \              offsetof(T_struct, T_member),                         \
601                false                                                 \
602            }                                                         \
603            COMPILER_RESTORE_OFFSETOF_WARNING                         \
604        )                                                             \
605    
606        /**
607         * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
608         * VMInt8RelPtr structures to be of read-only type. That means the script
609         * parser will abort any script at parser time if the script is trying to
610         * modify such a read-only built-in variable.
611         *
612         * @b NOTE: this is only intended for built-in read-only variables that
613         * may change during runtime! If your built-in variable's data is rather
614         * already available at parser time and won't change during runtime, then
615         * you should rather register a built-in constant in your VM class instead!
616         *
617         * @see ScriptVM::builtInConstIntVariables()
618         */
619        #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
620            /* Disable offsetof warning, trust us, we are cautios. */ \
621            COMPILER_DISABLE_OFFSETOF_WARNING                         \
622            (VMRelPtr) {                                              \
623                (void**) &basePtr,                                    \
624                offsetof(T_struct, T_member),                         \
625                true                                                  \
626            }                                                         \
627            COMPILER_RESTORE_OFFSETOF_WARNING                         \
628        )                                                             \
629    
630      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
631       *       *
# Line 553  namespace LinuxSampler { Line 640  namespace LinuxSampler {
640          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0) {}
641      };      };
642    
643        /** @brief Virtual machine script variable.
644         *
645         * Common interface for all variables accessed in scripts.
646         */
647        class VMVariable : virtual public VMExpr {
648        public:
649            /**
650             * Whether a script may modify the content of this variable by
651             * assigning a new value to it.
652             *
653             * @see isConstExpr(), assign()
654             */
655            virtual bool isAssignable() const = 0;
656    
657            /**
658             * In case this variable is assignable, this method will be called to
659             * perform the value assignment to this variable with @a expr
660             * reflecting the new value to be assigned.
661             *
662             * @param expr - new value to be assigned to this variable
663             */
664            virtual void assignExpr(VMExpr* expr) = 0;
665        };
666        
667        /** @brief Dynamically executed variable (abstract base class).
668         *
669         * Interface for the implementation of a dynamically generated content of
670         * a built-in script variable. Most built-in variables are simply pointers
671         * to some native location in memory. So when a script reads them, the
672         * memory location is simply read to get the value of the variable. A
673         * dynamic variable however is not simply a memory location. For each access
674         * to a dynamic variable some native code is executed to actually generate
675         * and provide the content (value) of this type of variable.
676         */
677        class VMDynVar : public VMVariable {
678        public:
679            /**
680             * Returns true in case this dynamic variable can be considered to be a
681             * constant expression. A constant expression will retain the same value
682             * throughout the entire life time of a script and the expression's
683             * constant value may be evaluated already at script parse time, which
684             * may result in performance benefits during script runtime.
685             *
686             * However due to the "dynamic" behavior of dynamic variables, almost
687             * all dynamic variables are probably not constant expressions. That's
688             * why this method returns @c false by default. If you are really sure
689             * that your dynamic variable implementation can be considered a
690             * constant expression then you may override this method and return
691             * @c true instead. Note that when you return @c true here, your
692             * dynamic variable will really just be executed once; and exectly
693             * already when the script is loaded!
694             *
695             * As an example you may implement a "constant" built-in dynamic
696             * variable that checks for a certain operating system feature and
697             * returns the result of that OS feature check as content (value) of
698             * this dynamic variable. Since the respective OS feature might become
699             * available/unavailable after OS updates, software migration, etc. the
700             * OS feature check should at least be performed once each time the
701             * application is launched. And since the OS feature check might take a
702             * certain amount of execution time, it might make sense to only
703             * perform the check if the respective variable name is actually
704             * referenced at all in the script to be loaded. Note that the dynamic
705             * variable will still be evaluated again though if the script is
706             * loaded again. So it is up to you to probably cache the result in the
707             * implementation of your dynamic variable.
708             *
709             * On doubt, please rather consider to use a constant built-in script
710             * variable instead of implementing a "constant" dynamic variable, due
711             * to the runtime overhead a dynamic variable may cause.
712             *
713             * @see isAssignable()
714             */
715            bool isConstExpr() const OVERRIDE { return false; }
716    
717            /**
718             * In case this dynamic variable is assignable, the new value (content)
719             * to be assigned to this dynamic variable.
720             *
721             * By default this method does nothing. Override and implement this
722             * method in your subclass in case your dynamic variable allows to
723             * assign a new value by script.
724             *
725             * @param expr - new value to be assigned to this variable
726             */
727            void assignExpr(VMExpr* expr) OVERRIDE {}
728    
729            virtual ~VMDynVar() {}
730        };
731    
732        /** @brief Dynamically executed variable (of integer data type).
733         *
734         * This is the base class for all built-in integer script variables whose
735         * variable content needs to be provided dynamically by executable native
736         * code on each script variable access.
737         */
738        class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
739        public:
740        };
741    
742        /** @brief Dynamically executed variable (of string data type).
743         *
744         * This is the base class for all built-in string script variables whose
745         * variable content needs to be provided dynamically by executable native
746         * code on each script variable access.
747         */
748        class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
749        public:
750        };
751    
752      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
753       *       *
754       * Abstract base class defining the high-level interface for all classes       * Abstract base class defining the high-level interface for all classes
# Line 587  namespace LinuxSampler { Line 783  namespace LinuxSampler {
783           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
784           */           */
785          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,int> builtInConstIntVariables() = 0;
786    
787            /**
788             * Returns a variable name indexed map of all built-in dynamic variables,
789             * which are not simply data stores, rather each one of them executes
790             * natively to provide or alter the respective script variable data.
791             */
792            virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
793      };      };
794    
795      /** @brief Execution state of a virtual machine.      /** @brief Execution state of a virtual machine.
# Line 664  namespace LinuxSampler { Line 867  namespace LinuxSampler {
867       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
868       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
869       * encountered parser issue within the script.       * encountered parser issue within the script.
870         *
871         * @see VMSourceToken for processing syntax highlighting instead.
872       */       */
873      struct ParserIssue {      struct ParserIssue {
874          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
# Line 782  namespace LinuxSampler { Line 987  namespace LinuxSampler {
987       * 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
988       * provided for external script editor applications. Primary purpose of       * provided for external script editor applications. Primary purpose of
989       * this class is syntax highlighting for external script editors.       * this class is syntax highlighting for external script editors.
990         *
991         * @see ParserIssue for processing compile errors and warnings instead.
992       */       */
993      class VMSourceToken {      class VMSourceToken {
994      public:      public:
# Line 794  namespace LinuxSampler { Line 1001  namespace LinuxSampler {
1001          String text() const;          String text() const;
1002    
1003          // position of token in script          // position of token in script
1004          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.
1005          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().
1006    
1007          // base types          // base types
1008          bool isEOF() const;          bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1009          bool isNewLine() const;          bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1010          bool isKeyword() const;          bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1011          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.
1012          bool isIdentifier() const;          bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1013          bool isNumberLiteral() const;          bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1014          bool isStringLiteral() const;          bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1015          bool isComment() const;          bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1016          bool isPreprocessor() const;          bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1017          bool isOther() const;          bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1018    
1019          // extended types          // extended types
1020          bool isIntegerVariable() const;          bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1021          bool isStringVariable() const;          bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1022          bool isArrayVariable() const;          bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1023          bool isEventHandlerName() const;          bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1024    
1025          VMSourceToken& operator=(const VMSourceToken& other);          VMSourceToken& operator=(const VMSourceToken& other);
1026    
Legend:
Removed from v.2889  
changed lines
  Added in v.3035
  ViewVC Help
Powered by ViewVC