/[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 2885 by schoenebeck, Fri Apr 22 15:37:45 2016 UTC revision 2945 by schoenebeck, Thu Jul 14 00:22:26 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            virtual bool isConstExpr() const = 0;
173    
174            bool isModifyable() const;
175      };      };
176    
177      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
# Line 366  namespace LinuxSampler { Line 378  namespace LinuxSampler {
378          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(int iArg) const = 0;
379    
380          /**          /**
381           * This function is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
382           * passed in scripts to this function are accepted by this function. If           * passed in scripts to this function are accepted by this function. If
383           * a script calls this function with an argument's data type not           * a script calls this function with an argument's data type not
384           * 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 396  namespace LinuxSampler {
396          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;
397    
398          /**          /**
399             * This method is called by the parser to check whether some arguments
400             * (and if yes which ones) passed to this script function will be
401             * modified by this script function. Most script functions simply use
402             * their arguments as inputs, that is they only read the argument's
403             * values. However some script function may also use passed
404             * argument(s) as output variables. In this case the function
405             * implementation must return @c true for the respective argument
406             * index here.
407             *
408             * @param iArg - index of the function argument in question
409             *               (must be between 0 .. maxAllowedArgs() - 1)
410             */
411            virtual bool modifiesArg(int iArg) const = 0;
412    
413            /**
414           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
415           * called by the VM whenever this function implementation shall be           * called by the VM whenever this function implementation shall be
416           * executed at script runtime. This method blocks until the function           * executed at script runtime. This method blocks until the function
# Line 553  namespace LinuxSampler { Line 580  namespace LinuxSampler {
580          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0) {}
581      };      };
582    
583        /** @brief Virtual machine script variable.
584         *
585         * Common interface for all variables accessed in scripts.
586         */
587        class VMVariable : virtual public VMExpr {
588        public:
589            /**
590             * Whether a script may modify the content of this variable by
591             * assigning a new value to it.
592             *
593             * @see isConstExpr(), assign()
594             */
595            virtual bool isAssignable() const = 0;
596    
597            /**
598             * In case this variable is assignable, this method will be called to
599             * perform the value assignment to this variable with @a expr
600             * reflecting the new value to be assigned.
601             *
602             * @param expr - new value to be assigned to this variable
603             */
604            virtual void assignExpr(VMExpr* expr) = 0;
605        };
606        
607        /** @brief Dynamically executed variable (abstract base class).
608         *
609         * Interface for the implementation of a dynamically generated content of
610         * a built-in script variable. Most built-in variables are simply pointers
611         * to some native location in memory. So when a script reads them, the
612         * memory location is simply read to get the value of the variable. A
613         * dynamic variable however is not simply a memory location. For each access
614         * to a dynamic variable some native code is executed to actually generate
615         * and provide the content (value) of this type of variable.
616         */
617        class VMDynVar : public VMVariable {
618        public:
619            /**
620             * Returns true in case this dynamic variable can be considered to be a
621             * constant expression. A constant expression will retain the same value
622             * throughout the entire life time of a script and the expression's
623             * constant value may be evaluated already at script parse time, which
624             * may result in performance benefits during script runtime.
625             *
626             * However due to the "dynamic" behavior of dynamic variables, almost
627             * all dynamic variables are probably not constant expressions. That's
628             * why this method returns @c false by default. If you are really sure
629             * that your dynamic variable implementation can be considered a
630             * constant expression then you may override this method and return
631             * @c true instead. Note that when you return @c true here, your
632             * dynamic variable will really just be executed once; and exectly
633             * already when the script is loaded!
634             *
635             * As an example you may implement a "constant" built-in dynamic
636             * variable that checks for a certain operating system feature and
637             * returns the result of that OS feature check as content (value) of
638             * this dynamic variable. Since the respective OS feature might become
639             * available/unavailable after OS updates, software migration, etc. the
640             * OS feature check should at least be performed once each time the
641             * application is launched. And since the OS feature check might take a
642             * certain amount of execution time, it might make sense to only
643             * perform the check if the respective variable name is actually
644             * referenced at all in the script to be loaded. Note that the dynamic
645             * variable will still be evaluated again though if the script is
646             * loaded again. So it is up to you to probably cache the result in the
647             * implementation of your dynamic variable.
648             *
649             * On doubt, please rather consider to use a constant built-in script
650             * variable instead of implementing a "constant" dynamic variable, due
651             * to the runtime overhead a dynamic variable may cause.
652             *
653             * @see isAssignable()
654             */
655            bool isConstExpr() const OVERRIDE { return false; }
656    
657            /**
658             * In case this dynamic variable is assignable, the new value (content)
659             * to be assigned to this dynamic variable.
660             *
661             * By default this method does nothing. Override and implement this
662             * method in your subclass in case your dynamic variable allows to
663             * assign a new value by script.
664             *
665             * @param expr - new value to be assigned to this variable
666             */
667            void assignExpr(VMExpr* expr) OVERRIDE {}
668        };
669    
670        /** @brief Dynamically executed variable (of integer data type).
671         *
672         * This is the base class for all built-in integer script variables whose
673         * variable content needs to be provided dynamically by executable native
674         * code on each script variable access.
675         */
676        class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
677        public:
678        };
679    
680        /** @brief Dynamically executed variable (of string data type).
681         *
682         * This is the base class for all built-in string script variables whose
683         * variable content needs to be provided dynamically by executable native
684         * code on each script variable access.
685         */
686        class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
687        public:
688        };
689    
690      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
691       *       *
692       * 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 721  namespace LinuxSampler {
721           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
722           */           */
723          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,int> builtInConstIntVariables() = 0;
724    
725            /**
726             * Returns a variable name indexed map of all built-in dynamic variables,
727             * which are not simply data stores, rather each one of them executes
728             * natively to provide or alter the respective script variable data.
729             */
730            virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
731      };      };
732    
733      /** @brief Execution state of a virtual machine.      /** @brief Execution state of a virtual machine.
# Line 667  namespace LinuxSampler { Line 808  namespace LinuxSampler {
808       */       */
809      struct ParserIssue {      struct ParserIssue {
810          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
811          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).
812            int lastLine; ///< The last line number within the script where this issue was encountered.
813            int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).
814            int lastColumn; ///< The last column within the script where this issue was encountered.
815          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.
816    
817          /**          /**
# Line 676  namespace LinuxSampler { Line 820  namespace LinuxSampler {
820          inline void dump() {          inline void dump() {
821              switch (type) {              switch (type) {
822                  case PARSER_ERROR:                  case PARSER_ERROR:
823                      printf("[ERROR] line %d: %s\n", line, txt.c_str());                      printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
824                      break;                      break;
825                  case PARSER_WARNING:                  case PARSER_WARNING:
826                      printf("[Warning] line %d: %s\n", line, txt.c_str());                      printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
827                      break;                      break;
828              }              }
829          }          }
# Line 791  namespace LinuxSampler { Line 935  namespace LinuxSampler {
935          String text() const;          String text() const;
936    
937          // position of token in script          // position of token in script
938          int firstLine() const;          int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line).
939          int firstColumn() const;          int firstColumn() const; ///< Last line this source token is located at in script source code.
940    
941          // base types          // base types
942          bool isEOF() const;          bool isEOF() const;
Legend:
Removed from v.2885  
changed lines
  Added in v.2945
  ViewVC Help
Powered by ViewVC