/[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 2948 by schoenebeck, Fri Jul 15 15:29:04 2016 UTC revision 3551 by schoenebeck, Thu Aug 1 10:22:56 2019 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014-2016 Christian Schoenebeck   * Copyright (c) 2014-2019 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 93  namespace LinuxSampler { Line 94  namespace LinuxSampler {
94      class VMStringExpr;      class VMStringExpr;
95      class VMIntArrayExpr;      class VMIntArrayExpr;
96      class VMStringArrayExpr;      class VMStringArrayExpr;
97        class VMParserContext;
98    
99      /** @brief Virtual machine expression      /** @brief Virtual machine expression
100       *       *
# Line 157  namespace LinuxSampler { Line 159  namespace LinuxSampler {
159           * expressions to an array expression for you, instead this method will           * expressions to an array expression for you, instead this method will
160           * simply return NULL!           * simply return NULL!
161           *           *
162             * @b Note: this method is currently, and in contrast to its other
163             * counter parts, declared as virtual method. Some deriving classes are
164             * currently using this to override this default implementation in order
165             * to implement an "evaluate now as integer array" behavior. This has
166             * efficiency reasons, however this also currently makes this part of
167             * the API less clean and should thus be addressed in future with
168             * appropriate changes to the API.
169             *
170           * @see exprType()           * @see exprType()
171           */           */
172          VMIntArrayExpr* asIntArray() const;          virtual VMIntArrayExpr* asIntArray() const;
173    
174          /**          /**
175           * Returns true in case this expression can be considered to be a           * Returns true in case this expression can be considered to be a
# Line 168  namespace LinuxSampler { Line 178  namespace LinuxSampler {
178           * expression's constant value may be evaluated already at script           * expression's constant value may be evaluated already at script
179           * parse time, which may result in performance benefits during script           * parse time, which may result in performance benefits during script
180           * runtime.           * runtime.
181             *
182             * @b NOTE: A constant expression is per se always also non modifyable.
183             * But a non modifyable expression may not necessarily be a constant
184             * expression!
185             *
186             * @see isModifyable()
187           */           */
188          virtual bool isConstExpr() const = 0;          virtual bool isConstExpr() const = 0;
189    
190            /**
191             * Returns true in case this expression is allowed to be modified.
192             * If this method returns @c false then this expression must be handled
193             * as read-only expression, which means that assigning a new value to it
194             * is either not possible or not allowed.
195             *
196             * @b NOTE: A constant expression is per se always also non modifyable.
197             * But a non modifyable expression may not necessarily be a constant
198             * expression!
199             *
200             * @see isConstExpr()
201             */
202          bool isModifyable() const;          bool isModifyable() const;
203      };      };
204    
# Line 521  namespace LinuxSampler { Line 549  namespace LinuxSampler {
549          }          }
550      };      };
551    
552        #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
553        # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
554            _Pragma("GCC diagnostic push")                            \
555            _Pragma("GCC diagnostic ignored \"-Winvalid-offsetof\"")
556        # define COMPILER_RESTORE_OFFSETOF_WARNING \
557            _Pragma("GCC diagnostic pop")
558        #else
559        # define COMPILER_DISABLE_OFFSETOF_WARNING
560        # define COMPILER_RESTORE_OFFSETOF_WARNING
561        #endif
562    
563      /**      /**
564       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr
565       * structures. Usage example:       * structures. Usage example:
# Line 563  namespace LinuxSampler { Line 602  namespace LinuxSampler {
602       * complexity inside the sampler engines which provide the actual script       * complexity inside the sampler engines which provide the actual script
603       * functionalities.       * functionalities.
604       */       */
605      #define DECLARE_VMINT(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT(basePtr, T_struct, T_member) (          \
606          (VMRelPtr) {                                     \          /* Disable offsetof warning, trust us, we are cautios. */ \
607              (void**) &basePtr,                           \          COMPILER_DISABLE_OFFSETOF_WARNING                         \
608              offsetof(T_struct, T_member),                \          (VMRelPtr) {                                              \
609              false                                        \              (void**) &basePtr,                                    \
610          }                                                \              offsetof(T_struct, T_member),                         \
611      )                                                    \              false                                                 \
612            }                                                         \
613            COMPILER_RESTORE_OFFSETOF_WARNING                         \
614        )                                                             \
615    
616      /**      /**
617       * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and       * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and
# Line 585  namespace LinuxSampler { Line 627  namespace LinuxSampler {
627       * @see ScriptVM::builtInConstIntVariables()       * @see ScriptVM::builtInConstIntVariables()
628       */       */
629      #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \      #define DECLARE_VMINT_READONLY(basePtr, T_struct, T_member) ( \
630          (VMRelPtr) {                                          \          /* Disable offsetof warning, trust us, we are cautios. */ \
631              (void**) &basePtr,                                \          COMPILER_DISABLE_OFFSETOF_WARNING                         \
632              offsetof(T_struct, T_member),                     \          (VMRelPtr) {                                              \
633              true                                              \              (void**) &basePtr,                                    \
634          }                                                     \              offsetof(T_struct, T_member),                         \
635      )                                                         \              true                                                  \
636            }                                                         \
637            COMPILER_RESTORE_OFFSETOF_WARNING                         \
638        )                                                             \
639    
640      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
641       *       *
# Line 601  namespace LinuxSampler { Line 646  namespace LinuxSampler {
646      struct VMInt8Array {      struct VMInt8Array {
647          int8_t* data;          int8_t* data;
648          int size;          int size;
649            bool readonly; ///< Whether the array data may be modified or just be read.
650    
651          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
652      };      };
653    
654      /** @brief Virtual machine script variable.      /** @brief Virtual machine script variable.
# Line 690  namespace LinuxSampler { Line 736  namespace LinuxSampler {
736           * @param expr - new value to be assigned to this variable           * @param expr - new value to be assigned to this variable
737           */           */
738          void assignExpr(VMExpr* expr) OVERRIDE {}          void assignExpr(VMExpr* expr) OVERRIDE {}
739    
740            virtual ~VMDynVar() {}
741      };      };
742    
743      /** @brief Dynamically executed variable (of integer data type).      /** @brief Dynamically executed variable (of integer data type).
# Line 712  namespace LinuxSampler { Line 760  namespace LinuxSampler {
760      public:      public:
761      };      };
762    
763        /** @brief Dynamically executed variable (of integer array data type).
764         *
765         * This is the base class for all built-in integer array script variables
766         * whose variable content needs to be provided dynamically by executable
767         * native code on each script variable access.
768         */
769        class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr {
770        public:
771        };
772    
773      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
774       *       *
775       * Abstract base class defining the high-level interface for all classes       * Abstract base class defining the high-level interface for all classes
# Line 730  namespace LinuxSampler { Line 788  namespace LinuxSampler {
788          virtual VMFunction* functionByName(const String& name) = 0;          virtual VMFunction* functionByName(const String& name) = 0;
789    
790          /**          /**
791             * Returns @c true if the passed built-in function is disabled and
792             * should be ignored by the parser. This method is called by the
793             * parser on preprocessor level for each built-in function call within
794             * a script. Accordingly if this method returns @c true, then the
795             * respective function call is completely filtered out on preprocessor
796             * level, so that built-in function won't make into the result virtual
797             * machine representation, nor would expressions of arguments passed to
798             * that built-in function call be evaluated, nor would any check
799             * regarding correct usage of the built-in function be performed.
800             * In other words: a disabled function call ends up as a comment block.
801             *
802             * @param fn - built-in function to be checked
803             * @param ctx - parser context at the position where the built-in
804             *              function call is located within the script
805             */
806            virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0;
807    
808            /**
809           * Returns a variable name indexed map of all built-in script variables           * Returns a variable name indexed map of all built-in script variables
810           * which point to native "int" scalar (usually 32 bit) variables.           * which point to native "int" scalar (usually 32 bit) variables.
811           */           */
# Line 795  namespace LinuxSampler { Line 871  namespace LinuxSampler {
871           * @see ScriptVM::exec()           * @see ScriptVM::exec()
872           */           */
873          virtual int suspensionTimeMicroseconds() const = 0;          virtual int suspensionTimeMicroseconds() const = 0;
874    
875            /**
876             * Causes all polyphonic variables to be reset to zero values. A
877             * polyphonic variable is expected to be zero when entering a new event
878             * handler instance. As an exception the values of polyphonic variables
879             * shall only be preserved from an note event handler instance to its
880             * correspending specific release handler instance. So in the latter
881             * case the script author may pass custom data from the note handler to
882             * the release handler, but only for the same specific note!
883             */
884            virtual void resetPolyphonicData() = 0;
885    
886            /**
887             * Returns amount of virtual machine instructions which have been
888             * performed the last time when this execution context was executing a
889             * script. So in case you need the overall amount of instructions
890             * instead, then you need to add them by yourself after each
891             * ScriptVM::exec() call.
892             */
893            virtual size_t instructionsPerformed() const = 0;
894    
895            /**
896             * Sends a signal to this script execution instance to abort its script
897             * execution as soon as possible. This method is called i.e. when one
898             * script execution instance intends to stop another script execution
899             * instance.
900             */
901            virtual void signalAbort() = 0;
902    
903            /**
904             * Copies the current entire execution state from this object to the
905             * given object. So this can be used to "fork" a new script thread which
906             * then may run independently with its own polyphonic data for instance.
907             */
908            virtual void forkTo(VMExecContext* ectx) const = 0;
909    
910            /**
911             * In case the script called the built-in exit() function and passed a
912             * value as argument to the exit() function, then this method returns
913             * the value that had been passed as argument to the exit() function.
914             * Otherwise if the exit() function has not been called by the script
915             * or no argument had been passed to the exit() function, then this
916             * method returns NULL instead.
917             *
918             * Currently this is only used for automated test cases against the
919             * script engine, which return some kind of value in the individual
920             * test case scripts to check their behaviour in automated way. There
921             * is no purpose for this mechanism in production use. Accordingly this
922             * exit result value is @b always completely ignored by the sampler
923             * engines.
924             *
925             * Officially the built-in exit() function does not expect any arguments
926             * to be passed to its function call, and by default this feature is
927             * hence disabled and will yield in a parser error unless
928             * ScriptVM::setExitResultEnabled() was explicitly set.
929             *
930             * @see ScriptVM::setExitResultEnabled()
931             */
932            virtual VMExpr* exitResult() = 0;
933      };      };
934    
935      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 826  namespace LinuxSampler { Line 961  namespace LinuxSampler {
961      };      };
962    
963      /**      /**
964         * Reflects the precise position and span of a specific code block within
965         * a script. This is currently only used for the locations of commented
966         * code blocks due to preprocessor statements, and for parser errors and
967         * parser warnings.
968         *
969         * @see ParserIssue for code locations of parser errors and parser warnings
970         *
971         * @see VMParserContext::preprocessorComments() for locations of code which
972         *      have been filtered out by preprocessor statements
973         */
974        struct CodeBlock {
975            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
976            int lastLine; ///< The last line number of this code block within the script.
977            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
978            int lastColumn; ///< The last column of this code block within the script.
979        };
980    
981        /**
982       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
983       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
984       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
985       * encountered parser issue within the script.       * encountered parser issue within the script.
986         *
987         * @see VMSourceToken for processing syntax highlighting instead.
988       */       */
989      struct ParserIssue {      struct ParserIssue : CodeBlock {
990          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.  
991          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.
992    
993          /**          /**
# Line 916  namespace LinuxSampler { Line 1067  namespace LinuxSampler {
1067          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1068    
1069          /**          /**
1070             * Returns all code blocks of the script which were filtered out by the
1071             * preprocessor.
1072             */
1073            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1074    
1075            /**
1076           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1077           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1078           * parsed script. This translated representation of the event handler           * parsed script. This translated representation of the event handler
# Line 948  namespace LinuxSampler { Line 1105  namespace LinuxSampler {
1105       * 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
1106       * provided for external script editor applications. Primary purpose of       * provided for external script editor applications. Primary purpose of
1107       * this class is syntax highlighting for external script editors.       * this class is syntax highlighting for external script editors.
1108         *
1109         * @see ParserIssue for processing compile errors and warnings instead.
1110       */       */
1111      class VMSourceToken {      class VMSourceToken {
1112      public:      public:
# Line 960  namespace LinuxSampler { Line 1119  namespace LinuxSampler {
1119          String text() const;          String text() const;
1120    
1121          // position of token in script          // position of token in script
1122          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.
1123          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().
1124    
1125          // base types          // base types
1126          bool isEOF() const;          bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1127          bool isNewLine() const;          bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1128          bool isKeyword() const;          bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1129          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.
1130          bool isIdentifier() const;          bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1131          bool isNumberLiteral() const;          bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1132          bool isStringLiteral() const;          bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1133          bool isComment() const;          bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1134          bool isPreprocessor() const;          bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1135          bool isOther() const;          bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1136    
1137          // extended types          // extended types
1138          bool isIntegerVariable() const;          bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1139          bool isStringVariable() const;          bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1140          bool isArrayVariable() const;          bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1141          bool isEventHandlerName() const;          bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1142    
1143          VMSourceToken& operator=(const VMSourceToken& other);          VMSourceToken& operator=(const VMSourceToken& other);
1144    
Legend:
Removed from v.2948  
changed lines
  Added in v.3551
  ViewVC Help
Powered by ViewVC