/[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 3311 by schoenebeck, Sat Jul 15 16:24:59 2017 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014-2016 Christian Schoenebeck   * Copyright (c) 2014-2017 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      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 826  namespace LinuxSampler { Line 937  namespace LinuxSampler {
937      };      };
938    
939      /**      /**
940         * Reflects the precise position and span of a specific code block within
941         * a script. This is currently only used for the locations of commented
942         * code blocks due to preprocessor statements, and for parser errors and
943         * parser warnings.
944         *
945         * @see ParserIssue for code locations of parser errors and parser warnings
946         *
947         * @see VMParserContext::preprocessorComments() for locations of code which
948         *      have been filtered out by preprocessor statements
949         */
950        struct CodeBlock {
951            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
952            int lastLine; ///< The last line number of this code block within the script.
953            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
954            int lastColumn; ///< The last column of this code block within the script.
955        };
956    
957        /**
958       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
959       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
960       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
961       * encountered parser issue within the script.       * encountered parser issue within the script.
962         *
963         * @see VMSourceToken for processing syntax highlighting instead.
964       */       */
965      struct ParserIssue {      struct ParserIssue : CodeBlock {
966          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.  
967          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.
968    
969          /**          /**
# Line 916  namespace LinuxSampler { Line 1043  namespace LinuxSampler {
1043          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1044    
1045          /**          /**
1046             * Returns all code blocks of the script which were filtered out by the
1047             * preprocessor.
1048             */
1049            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1050    
1051            /**
1052           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1053           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1054           * parsed script. This translated representation of the event handler           * parsed script. This translated representation of the event handler
# Line 948  namespace LinuxSampler { Line 1081  namespace LinuxSampler {
1081       * 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
1082       * provided for external script editor applications. Primary purpose of       * provided for external script editor applications. Primary purpose of
1083       * this class is syntax highlighting for external script editors.       * this class is syntax highlighting for external script editors.
1084         *
1085         * @see ParserIssue for processing compile errors and warnings instead.
1086       */       */
1087      class VMSourceToken {      class VMSourceToken {
1088      public:      public:
# Line 960  namespace LinuxSampler { Line 1095  namespace LinuxSampler {
1095          String text() const;          String text() const;
1096    
1097          // position of token in script          // position of token in script
1098          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.
1099          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().
1100    
1101          // base types          // base types
1102          bool isEOF() const;          bool isEOF() const; ///< Returns true in case this source token represents the end of the source code file.
1103          bool isNewLine() const;          bool isNewLine() const; ///< Returns true in case this source token represents a line feed character (i.e. "\n" on Unix systems).
1104          bool isKeyword() const;          bool isKeyword() const; ///< Returns true in case this source token represents a language keyword (i.e. "while", "function", "declare", "on", etc.).
1105          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.
1106          bool isIdentifier() const;          bool isIdentifier() const; ///< Returns true in case this source token represents an identifier, which currently always means a function name.
1107          bool isNumberLiteral() const;          bool isNumberLiteral() const; ///< Returns true in case this source token represents a number literal (i.e. 123).
1108          bool isStringLiteral() const;          bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1109          bool isComment() const;          bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1110          bool isPreprocessor() const;          bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1111          bool isOther() const;          bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1112    
1113          // extended types          // extended types
1114          bool isIntegerVariable() const;          bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1115          bool isStringVariable() const;          bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1116          bool isArrayVariable() const;          bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").
1117          bool isEventHandlerName() const;          bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1118    
1119          VMSourceToken& operator=(const VMSourceToken& other);          VMSourceToken& operator=(const VMSourceToken& other);
1120    
Legend:
Removed from v.2948  
changed lines
  Added in v.3311
  ViewVC Help
Powered by ViewVC