/[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 2942 by schoenebeck, Wed Jul 13 15:51:06 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 541  namespace LinuxSampler { Line 553  namespace LinuxSampler {
553          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0) {}
554      };      };
555    
556        /** @brief Dynamically executed variable (abstract base class).
557         *
558         * Interface for the implementation of a dynamically generated content of
559         * a built-in script variable. Most built-in variables are simply pointers
560         * to some native location in memory. So when a script reads them, the
561         * memory location is simply read to get the value of the variable. A
562         * dynamic variable however is not simply a memory location. For each access
563         * to a dynamic variable some native code is executed to actually generate
564         * and provide the content (value) of this type of variable.
565         */
566        class VMDynVar : virtual public VMExpr {
567        public:
568            /**
569             * Whether a script may modify the content of this dynamic variable by
570             * assigning a new value to it.
571             *
572             * @see isConstExpr(), assign()
573             */
574            virtual bool isAssignable() const = 0;
575    
576            /**
577             * Returns true in case this dynamic variable can be considered to be a
578             * constant expression. A constant expression will retain the same value
579             * throughout the entire life time of a script and the expression's
580             * constant value may be evaluated already at script parse time, which
581             * may result in performance benefits during script runtime.
582             *
583             * However due to the "dynamic" behavior of dynamic variables, almost
584             * all dynamic variables are probably not constant expressions. That's
585             * why this method returns @c false by default. If you are really sure
586             * that your dynamic variable implementation can be considered a
587             * constant expression then you may override this method and return
588             * @c true instead. Note that when you return @c true here, your
589             * dynamic variable will really just be executed once; and exectly
590             * already when the script is loaded!
591             *
592             * As an example you may implement a "constant" built-in dynamic
593             * variable that checks for a certain operating system feature and
594             * returns the result of that OS feature check as content (value) of
595             * this dynamic variable. Since the respective OS feature might become
596             * available/unavailable after OS updates, software migration, etc. the
597             * OS feature check should at least be performed once each time the
598             * application is launched. And since the OS feature check might take a
599             * certain amount of execution time, it might make sense to only
600             * perform the check if the respective variable name is actually
601             * referenced at all in the script to be loaded. Note that the dynamic
602             * variable will still be evaluated again though if the script is
603             * loaded again. So it is up to you to probably cache the result in the
604             * implementation of your dynamic variable.
605             *
606             * On doubt, please rather consider to use a constant built-in script
607             * variable instead of implementing a "constant" dynamic variable, due
608             * to the runtime overhead a dynamic variable may cause.
609             *
610             * @see isAssignable()
611             */
612            virtual bool isConstExpr() const { return false; }
613    
614            /**
615             * In case this dynamic variable is assignable, the new value (content)
616             * to be assigned to this dynamic variable.
617             *
618             * By default this method does nothing. Override and implement this
619             * method in your subclass in case your dynamic variable allows to
620             * assign a new value by script.
621             *
622             * @param expr - new value to be assigned to this variable
623             */
624            virtual void assign(VMExpr* expr) {}
625        };
626    
627        /** @brief Dynamically executed variable (of integer data type).
628         *
629         * This is the base class for all built-in integer script variables whose
630         * variable content needs to be provided dynamically by executable native
631         * code on each script variable access.
632         */
633        class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
634        public:
635        };
636    
637        /** @brief Dynamically executed variable (of string data type).
638         *
639         * This is the base class for all built-in string script variables whose
640         * variable content needs to be provided dynamically by executable native
641         * code on each script variable access.
642         */
643        class VMDynStringVar : virtual public VMDynVar, virtual public VMStringExpr {
644        public:
645        };
646    
647      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
648       *       *
649       * 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 678  namespace LinuxSampler {
678           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
679           */           */
680          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,int> builtInConstIntVariables() = 0;
681    
682            /**
683             * Returns a variable name indexed map of all built-in dynamic variables,
684             * which are not simply data stores, rather each one of them executes
685             * natively to provide or alter the respective script variable data.
686             */
687            virtual std::map<String,VMDynVar*> builtInDynamicVariables() = 0;
688      };      };
689    
690      /** @brief Execution state of a virtual machine.      /** @brief Execution state of a virtual machine.
# Line 627  namespace LinuxSampler { Line 737  namespace LinuxSampler {
737      class VMEventHandler {      class VMEventHandler {
738      public:      public:
739          /**          /**
740             * Type of this event handler, which identifies its purpose. For example
741             * for a "on note ... end on" script callback block,
742             * @c VM_EVENT_HANDLER_NOTE would be returned here.
743             */
744            virtual VMEventHandlerType_t eventHandlerType() const = 0;
745    
746            /**
747           * Name of the event handler which identifies its purpose. For example           * Name of the event handler which identifies its purpose. For example
748           * for a "on note ... end on" script callback block, the name "note"           * for a "on note ... end on" script callback block, the name "note"
749           * would be returned here.           * would be returned here.
# Line 648  namespace LinuxSampler { Line 765  namespace LinuxSampler {
765       */       */
766      struct ParserIssue {      struct ParserIssue {
767          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
768          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).
769            int lastLine; ///< The last line number within the script where this issue was encountered.
770            int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).
771            int lastColumn; ///< The last column within the script where this issue was encountered.
772          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.
773    
774          /**          /**
# Line 657  namespace LinuxSampler { Line 777  namespace LinuxSampler {
777          inline void dump() {          inline void dump() {
778              switch (type) {              switch (type) {
779                  case PARSER_ERROR:                  case PARSER_ERROR:
780                      printf("[ERROR] line %d: %s\n", line, txt.c_str());                      printf("[ERROR] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
781                      break;                      break;
782                  case PARSER_WARNING:                  case PARSER_WARNING:
783                      printf("[Warning] line %d: %s\n", line, txt.c_str());                      printf("[Warning] line %d, column %d: %s\n", firstLine, firstColumn, txt.c_str());
784                      break;                      break;
785              }              }
786          }          }
# Line 748  namespace LinuxSampler { Line 868  namespace LinuxSampler {
868          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;          virtual VMEventHandler* eventHandlerByName(const String& name) = 0;
869      };      };
870    
871        class SourceToken;
872    
873        /** @brief Recognized token of a script's source code.
874         *
875         * Represents one recognized token of a script's source code, for example
876         * a keyword, variable name, etc. and it provides further informations about
877         * that particular token, i.e. the precise location (line and column) of the
878         * token within the original script's source code.
879         *
880         * This class is not actually used by the sampler itself. It is rather
881         * provided for external script editor applications. Primary purpose of
882         * this class is syntax highlighting for external script editors.
883         */
884        class VMSourceToken {
885        public:
886            VMSourceToken();
887            VMSourceToken(SourceToken* ct);
888            VMSourceToken(const VMSourceToken& other);
889            virtual ~VMSourceToken();
890    
891            // original text of this token as it is in the script's source code
892            String text() const;
893    
894            // position of token in script
895            int firstLine() const; ///< First line this source token is located at in script source code (indexed with 0 being the very first line).
896            int firstColumn() const; ///< Last line this source token is located at in script source code.
897    
898            // base types
899            bool isEOF() const;
900            bool isNewLine() const;
901            bool isKeyword() const;
902            bool isVariableName() const;
903            bool isIdentifier() const;
904            bool isNumberLiteral() const;
905            bool isStringLiteral() const;
906            bool isComment() const;
907            bool isPreprocessor() const;
908            bool isOther() const;
909    
910            // extended types
911            bool isIntegerVariable() const;
912            bool isStringVariable() const;
913            bool isArrayVariable() const;
914            bool isEventHandlerName() const;
915    
916            VMSourceToken& operator=(const VMSourceToken& other);
917    
918        private:
919            SourceToken* m_token;
920        };
921    
922  } // namespace LinuxSampler  } // namespace LinuxSampler
923    
924  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H  #endif // LS_INSTR_SCRIPT_PARSER_COMMON_H
Legend:
Removed from v.2871  
changed lines
  Added in v.2942
  ViewVC Help
Powered by ViewVC