/[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 2945 by schoenebeck, Thu Jul 14 00:22:26 2016 UTC
# Line 76  namespace LinuxSampler { Line 76  namespace LinuxSampler {
76          VM_EXEC_ERROR = (1<<2), ///< A runtime error occurred while executing the script (i.e. a call to some built-in script function failed).          VM_EXEC_ERROR = (1<<2), ///< A runtime error occurred while executing the script (i.e. a call to some built-in script function failed).
77      };      };
78    
79        /** @brief Script event handler type.
80         *
81         * Identifies one of the possible event handler callback types defined by
82         * the NKSP script language.
83         */
84        enum VMEventHandlerType_t {
85            VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block.
86            VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block.
87            VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block.
88            VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block.
89        };
90    
91      // just symbol prototyping      // just symbol prototyping
92      class VMIntExpr;      class VMIntExpr;
93      class VMStringExpr;      class VMStringExpr;
# Line 148  namespace LinuxSampler { Line 160  namespace LinuxSampler {
160           * @see exprType()           * @see exprType()
161           */           */
162          VMIntArrayExpr* asIntArray() const;          VMIntArrayExpr* asIntArray() const;
163    
164            /**
165             * Returns true in case this expression can be considered to be a
166             * constant expression. A constant expression will retain the same
167             * value throughout the entire life time of a script and the
168             * expression's constant value may be evaluated already at script
169             * parse time, which may result in performance benefits during script
170             * runtime.
171             */
172            virtual bool isConstExpr() const = 0;
173    
174            bool isModifyable() const;
175      };      };
176    
177      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
# Line 354  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 372  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 541  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 575  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 627  namespace LinuxSampler { Line 780  namespace LinuxSampler {
780      class VMEventHandler {      class VMEventHandler {
781      public:      public:
782          /**          /**
783             * Type of this event handler, which identifies its purpose. For example
784             * for a "on note ... end on" script callback block,
785             * @c VM_EVENT_HANDLER_NOTE would be returned here.
786             */
787            virtual VMEventHandlerType_t eventHandlerType() const = 0;
788    
789            /**
790           * Name of the event handler which identifies its purpose. For example           * Name of the event handler which identifies its purpose. For example
791           * for a "on note ... end on" script callback block, the name "note"           * for a "on note ... end on" script callback block, the name "note"
792           * would be returned here.           * would be returned here.
# Line 648  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 657  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 748  namespace LinuxSampler { Line 911  namespace LinuxSampler {
911          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
912      };      };
913    
914        class SourceToken;
915    
916        /** @brief Recognized token of a script's source code.
917         *
918         * Represents one recognized token of a script's source code, for example
919         * a keyword, variable name, etc. and it provides further informations about
920         * that particular token, i.e. the precise location (line and column) of the
921         * token within the original script's source code.
922         *
923         * This class is not actually used by the sampler itself. It is rather
924         * provided for external script editor applications. Primary purpose of
925         * this class is syntax highlighting for external script editors.
926         */
927        class VMSourceToken {
928        public:
929            VMSourceToken();
930            VMSourceToken(SourceToken* ct);
931            VMSourceToken(const VMSourceToken& other);
932            virtual ~VMSourceToken();
933    
934            // original text of this token as it is in the script's source code
935            String text() const;
936    
937            // position of token in script
938            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; ///< Last line this source token is located at in script source code.
940    
941            // base types
942            bool isEOF() const;
943            bool isNewLine() const;
944            bool isKeyword() const;
945            bool isVariableName() const;
946            bool isIdentifier() const;
947            bool isNumberLiteral() const;
948            bool isStringLiteral() const;
949            bool isComment() const;
950            bool isPreprocessor() const;
951            bool isOther() const;
952    
953            // extended types
954            bool isIntegerVariable() const;
955            bool isStringVariable() const;
956            bool isArrayVariable() const;
957            bool isEventHandlerName() const;
958    
959            VMSourceToken& operator=(const VMSourceToken& other);
960    
961        private:
962            SourceToken* m_token;
963        };
964    
965  } // namespace LinuxSampler  } // namespace LinuxSampler
966    
967  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H
Legend:
Removed from v.2871  
changed lines
  Added in v.2945
  ViewVC Help
Powered by ViewVC