temp

bbp_ng/tools/bme_relatives.py

@@ -1,6 +1,5 @@
 import typing
-import collections
+import simple_po, bme_utils
-import simple_po
 
 #region Translation Constant
 
@@ -60,85 +59,84 @@ TOKEN_INSTANCES_TRANSFORM: str = 'transform'
 
 #endregion
 
-class Reporter():
+class ReporterWithHierarchy():
     """
-    General reporter commonly used by BME validator.
+    BME validator and extractor specifically used reporter
+    which auotmatically use hierarchy as its context when outputing.
     """
 
-    def __init__(self):
+    __mReporter: bme_utils.Reporter
-        pass
+    __mHierarchy: bme_utils.Hierarchy
 
-    def __report(self, type: str, msg: str, context: str | None) -> None:
+    def __init__(self, reporter: bme_utils.Reporter, hierarchy: bme_utils.Hierarchy):
-        strl: str = f'[{type}]'
+        self.__mReporter = reporter
-        if context is not None:
+        self.__mHierarchy = hierarchy
-            strl += f'[{context}]'
-        strl += ' ' + msg
-        print(strl)
 
-    def error(self, msg: str, context: str | None = None) -> None:
+    def error(self, msg: str) -> None:
-        """
+        self.__mReporter.error(msg, self.__mHierarchy.build_hierarchy_string())
-        @brief Report an error.
+    def warning(self, msg: str) -> None:
-        @param[in] msg The message to show.
+        self.__mReporter.warning(msg, self.__mHierarchy.build_hierarchy_string())
-        @param[in] context The context of this message, e.g. the file path. None if no context.
+    def info(self, msg: str) -> None:
-        """
+        self.__mReporter.info(msg, self.__mHierarchy.build_hierarchy_string())
-        self.__report('Error', msg, context)
 
-    def warning(self, msg: str, context: str | None = None) -> None:
+class UniqueField():
-        """
-        @brief Report a warning.
-        @param[in] msg The message to show.
-        @param[in] context The context of this message, e.g. the file path. None if no context.
-        """
-        self.__report('Warning', msg, context)
-
-    def info(self, msg: str, context: str | None = None) -> None:
-        """
-        @brief Report a info.
-        @param[in] msg The message to show.
-        @param[in] context The context of this message, e.g. the file path. None if no context.
-        """
-        self.__report('Info', msg, context)
-
-class Hierarchy():
     """
-    The hierarchy builder for BME validator to build context string representing the location where error happen.
+    Some BME prototype fields should be unique in globl scope.
-    And it can be utilized by BME extractor to generate the context of translation.
+    So BME validator should check this. That's the feature this class provided.
+
+    This class is an abstract class and should not be used directly.
+    Use child class please.
     """
 
-    __mStack: collections.deque[str]
+    __mUniques: set[str]
+    __mReporter: ReporterWithHierarchy
 
-    def __init__(self):
+    def __init__(self, reporter: ReporterWithHierarchy):
-        self.__mStack = collections.deque()
+        self.__mUniques = set()
+        self.__mReporter = reporter
 
-    def push(self, item: str) -> None:
+    def register(self, entry: str) -> bool:
         """
-        @brief Add an item into this hierarchy.
+        @brief Try to register given entry in unique.
-        @param[in] item New added item.
-        """
-        self.__mStack.append(item)
-
-    def push_index(self, index: int) -> None:
-        """
-        @brief Add an integral index into this hierarchy.
         @details
-        The difference between this and normal push function is that added item is integral index.
+        If given entry is not presented in unique set, given entry will be inserted and return True.
-        This function will automatically convert it to string with a special format first, then push it into hierarchy.
+        If given entry is already available in unique set, this function will use reporter to output an error message and return False.
-        @param[in] item New added index.
+        @param[in] entry The entry to be checked and inserted.
+        @return True if entry is unique, otherwise false.
         """
-        self.__mStack.append(f'[{index}]')
+        if entry in self.__mUniques:
+            self.__mReporter.error(self._get_error_msg(entry))
+            return False
+        else:
+            self.__mUniques.add(entry)
+            return True
 
-    def pop(self) -> None:
+    def clear(self) -> None:
         """
-        @brief Remove the top item from hierarchy
+        @brief Clear this unique set for further using.
         """
-        self.__mStack.pop()
+        self.__mUniques.clear()
 
-    def build_hierarchy_string(self) -> str:
+    def _get_error_msg(self, err_entry: str) -> str:
         """
-        Build the string which can represent this hierarchy.
+        @brief Get the error message when error occurs.
-        @return The built string representing this hierarchy.
+        @details
+        This is internal used function to get the error message which will be passed to reporter.
+        This message is generated by given entry which cause the non-unique issue.
+        Outer caller should not call this function and every child class should override this function.
+        @param[in] err_entry The entry cause the error.
+        @return The error message generated from given error entry.
         """
-        return '/'.join(self.__mStack)
+        raise NotImplementedError()
+
+class UniqueIdentifier(UniqueField):
+    """Specific UniqueField for unique prototype identifier."""
+    def _get_error_msg(self, err_entry: str) -> str:
+        return f'Trying to register multiple prototype with same name: "{err_entry}".'
+class UniqueVariable(UniqueField):
+    """Specific UniqueField for unique variable names within prototype."""
+    def _get_error_msg(self, err_entry: str) -> str:
+        return f'Trying to define multiple variable with same name: "{err_entry}" in the same prototype.'
 
 class BMEValidator():
     """
@@ -147,19 +145,168 @@ class BMEValidator():
     to check then whether have all essential fields BME standard required and whether have any unknown fields.
     """
 
-    __mPrototypeSet: set[str]
+    __mHierarchy: bme_utils.Hierarchy
-    __mHierarchy: Hierarchy
+    __mReporter: ReporterWithHierarchy
-    __mReporter: Reporter
 
-    def __init__(self, reporter: Reporter):
+    __mUniqueIdentifier: UniqueIdentifier
-        self.__mPrototypeSet = set()
+    __mUniqueVariable: UniqueVariable
-        self.__mHierarchy = Hierarchy()
+
-        self.__mReporter = reporter
+    def __init__(self, reporter: bme_utils.Reporter):
+        self.__mHierarchy = bme_utils.Hierarchy()
+        self.__mReporter = ReporterWithHierarchy(reporter, self.__mHierarchy)
+
+        self.__mUniqueIdentifier = UniqueIdentifier(self.__mReporter)
+        self.__mUniqueVariable = UniqueVariable(self.__mReporter)
+
+    _TCheckKey = typing.TypeVar('_TCheckKey')
+    def __check_key(self, data: dict[str, typing.Any], key: str, expected_type: type[_TCheckKey]) -> _TCheckKey | None:
+        """
+        @brief Check the existance and tyoe of value stored in given dict and key.
+        @param[in] data The dict need to be checked
+        @param[in] key The key for fetching value.
+        @param[in] expected_type The expected type of fetched value.
+        @return None if error occurs, otherwise the value stored in given dict and key.
+        """
+        gotten_value = data[key]
+        if gotten_value is None:
+            # report no key error
+            self.__mReporter.error(f'Can not find key "{key}". Did you forget it?')
+        elif not isinstance(gotten_value, expected_type):
+            # get the type of value
+            value_type = type(gotten_value)
+            # format normal error message
+            err_msg: str = f'The type of value stored inside key "{key}" is incorrect. '
+            err_msg += f'Expect "{expected_type.__name__}" got "{value_type.__name__}". '
+            # add special note for easily confusing types
+            # e.g. forget quote number (number literal are recognise as number accidently)
+            if issubclass(expected_type, str) and issubclass(type(data), (int, float)):
+                err_msg +=  'Did you forgot quote the number?'
+            # report type error
+            self.__mReporter.error(err_msg)
+        else:
+            # no error, return value
+            return gotten_value
+        # error occurs, return null
+        return None
+
+    def __check_self(self, data: typing.Any, expected_type: type) -> bool:
+        """
+        @brief Check the type of given data.
+        @return True if type matched, otherwise false.
+        """
+        if data is None:
+            self.__mReporter.error('Data is unexpected null.')
+        elif not isinstance(data, expected_type):
+            # usually this function is checking list or dict, so no scenario that user forget quote literal number.
+            self.__mReporter.error(f'The type of given data is not expected. Expect "{expected_type.__name__}" got "{type(data).__name__}".')
+        else:
+            # no error, return okey
+            return True
+        # error occurs, return failed
+        return False
+
+    # 按层次递归调用检查。
+    # 每个层次只负责当前层次的检查。
+    # 如果值为列表，字典，则在当前层次检查完其类型（容器本身，对每一项不检查），然后对每一项调用对应层次检查。
+    # 如果值不是上述类型（例如整数，浮点数，字符串等），在当前层次检查。
 
     def validate(self, assoc_file: str, prototypes: typing.Any) -> None:
-        self.__mHierarchy.push(assoc_file)
+        # reset hierarchy
+        self.__mHierarchy.clear()
+        # start to validate
+        with self.__mHierarchy.safe_push(assoc_file):
+            self.__validate_prototypes(prototypes)
+
+    def __validate_prototypes(self, prototypes: typing.Any) -> None:
+        # the most outer structure must be a list
+        if not self.__check_self(prototypes, list): return
+        cast_prototypes = typing.cast(list[typing.Any], prototypes)
+        # iterate prototype
+        for prototype_index, prototype in enumerate(cast_prototypes):
+            with self.__mHierarchy.safe_push(prototype_index) as layer:
+                self.__validate_prototype(layer, prototype)
+
+    def __validate_prototype(self, layer: bme_utils.HierarchyLayer, prototype: typing.Any) -> None:
+        # check whether self is a dict
+        if not self.__check_self(prototype, dict): return
+        cast_prototype = typing.cast(dict[str, typing.Any], prototype)
+
+        # check identifier
+        identifier = self.__check_key(cast_prototype, TOKEN_IDENTIFIER, str)
+        if identifier is not None:
+            # replace hierarchy
+            layer.emplace(identifier)
+            # check unique
+            self.__mUniqueIdentifier.register(identifier)
+
+        # check showcase but don't use check function
+        # because it is optional.
+        showcase = cast_prototype[TOKEN_SHOWCASE]
+        if showcase is not None:
+            # we only check non-template prototype
+            with self.__mHierarchy.safe_push(TOKEN_SHOWCASE):
+                self.__validate_showcase(typing.cast(dict[str, typing.Any], showcase))
+
+        # check params, vars, vertices, faces, instances
+        # they are all list
+        params = self.__check_key(cast_prototype, TOKEN_PARAMS, list)
+        if params is not None:
+            cast_params = typing.cast(list[typing.Any], params)
+            with self.__mHierarchy.safe_push(TOKEN_PARAMS):
+                for param_index, param in enumerate(cast_params):
+                    with self.__mHierarchy.safe_push(param_index):
+                        self.__validate_param(param)
+        
+        vars = self.__check_key(cast_prototype, TOKEN_VARS, list)
+        if vars is not None:
+            cast_vars = typing.cast(list[typing.Any], vars)
+            with self.__mHierarchy.safe_push(TOKEN_VARS):
+                for var_index, var in enumerate(cast_vars):
+                    with self.__mHierarchy.safe_push(var_index):
+                        self.__validate_var(var)
+
+        vertices = self.__check_key(cast_prototype, TOKEN_VERTICES, list)
+        if vertices is not None:
+            cast_vertices = typing.cast(list[typing.Any], vertices)
+            with self.__mHierarchy.safe_push(TOKEN_VERTICES):
+                for vertex_index, vertex in enumerate(cast_vertices):
+                    with self.__mHierarchy.safe_push(vertex_index):
+                        self.__validate_vertex(vertex)
+
+        faces = self.__check_key(cast_prototype, TOKEN_FACES, list)
+        if faces is not None:
+            cast_faces = typing.cast(list[typing.Any], faces)
+            with self.__mHierarchy.safe_push(TOKEN_FACES):
+                for face_index, face in enumerate(cast_faces):
+                    with self.__mHierarchy.safe_push(face_index):
+                        self.__validate_face(face)
+
+        instances = self.__check_key(cast_prototype, TOKEN_INSTANCES, list)
+        if instances is not None:
+            cast_instances = typing.cast(list[typing.Any], instances)
+            with self.__mHierarchy.safe_push(TOKEN_INSTANCES):
+                for instance_index, instance in enumerate(cast_instances):
+                    with self.__mHierarchy.safe_push(instance_index):
+                        self.__validate_instance(instance)
+
+    def __validate_showcase(self, showcase: dict[str, typing.Any]) -> None:
+        pass
+
+    def __validate_param(self, param: typing.Any) -> None:
+        pass
+
+    def __validate_var(self, param: typing.Any) -> None:
+        pass
+
+    def __validate_vertex(self, param: typing.Any) -> None:
+        pass
+
+    def __validate_face(self, param: typing.Any) -> None:
+        pass
+
+    def __validate_instance(self, param: typing.Any) -> None:
+        pass
 
-        self.__mHierarchy.pop()
 
 class BMEExtractor():
     """
@@ -175,12 +322,12 @@ class BMEExtractor():
     """
 
     __mAssocFile: str
-    __mHierarchy: Hierarchy
+    __mHierarchy: bme_utils.Hierarchy
     __mPoWriter: simple_po.PoWriter
 
     def __init__(self, po_writer: simple_po.PoWriter):
         self.__mAssocFile = ''
-        self.__mHierarchy = Hierarchy()
+        self.__mHierarchy = bme_utils.Hierarchy()
         self.__mPoWriter = po_writer
 
     def extract(self, assoc_file: str, prototypes: list[dict[str, typing.Any]]) -> None:
@@ -198,14 +345,11 @@ class BMEExtractor():
     def __extract_prototype(self, prototype: dict[str, typing.Any]) -> None:
         # get identifier first
         identifier: str = prototype[TOKEN_IDENTIFIER]
-        self.__mHierarchy.push(identifier)
+        with self.__mHierarchy.safe_push(identifier):
-
+            # get showcase node and only write PO file if it is not template prototype
-        # get showcase node and only write PO file if it is not template prototype
+            showcase: dict[str, typing.Any] | None = prototype[TOKEN_SHOWCASE]
-        showcase: dict[str, typing.Any] | None = prototype[TOKEN_SHOWCASE]
+            if showcase is not None:
-        if showcase is not None:
+                self.__extract_showcase(showcase)
-            self.__extract_showcase(showcase)
-
-        self.__mHierarchy.pop()
 
     def __extract_showcase(self, showcase: dict[str, typing.Any]) -> None:
         # export self name first
@@ -217,14 +361,13 @@ class BMEExtractor():
             self.__extract_showcase_cfg(cfg_index, cfg)
 
     def __extract_showcase_cfg(self, index: int, cfg: dict[str, typing.Any]) -> None:
-        self.__mHierarchy.push_index(index)
+        # push cfg index
+        with self.__mHierarchy.safe_push(index):
+            # extract field title and description
+            title: str = cfg[TOKEN_SHOWCASE_CFGS_TITLE]
+            desc: str = cfg[TOKEN_SHOWCASE_CFGS_DESC]
 
-        # extract field title and description
+            # and export them respectively
-        title: str = cfg[TOKEN_SHOWCASE_CFGS_TITLE]
+            self.__add_translation(title)
-        desc: str = cfg[TOKEN_SHOWCASE_CFGS_DESC]
+            self.__add_translation(desc)
 
-        # and export them respectively
-        self.__add_translation(title)
-        self.__add_translation(desc)
-
-        self.__mHierarchy.pop()

bbp_ng/tools/bme_utils.py

@@ -0,0 +1,141 @@
+import typing
+import collections
+
+class Reporter():
+    """
+    General reporter with context support for convenient logging.
+    """
+
+    def __init__(self):
+        pass
+
+    def __report(self, type: str, msg: str, context: str | None) -> None:
+        strl: str = f'[{type}]'
+        if context is not None:
+            strl += f'[{context}]'
+        strl += ' ' + msg
+        print(strl)
+
+    def error(self, msg: str, context: str | None = None) -> None:
+        """
+        @brief Report an error.
+        @param[in] msg The message to show.
+        @param[in] context The context of this message, e.g. the file path. None if no context.
+        """
+        self.__report('Error', msg, context)
+
+    def warning(self, msg: str, context: str | None = None) -> None:
+        """
+        @brief Report a warning.
+        @param[in] msg The message to show.
+        @param[in] context The context of this message, e.g. the file path. None if no context.
+        """
+        self.__report('Warning', msg, context)
+
+    def info(self, msg: str, context: str | None = None) -> None:
+        """
+        @brief Report a info.
+        @param[in] msg The message to show.
+        @param[in] context The context of this message, e.g. the file path. None if no context.
+        """
+        self.__report('Info', msg, context)
+
+class Hierarchy():
+    """
+    The hierarchy for BME validator and BME extractor.
+    In BME validator, it build human-readable string representing the location where error happen.
+    In BME extractor, it build the string used as the context of translation.
+    """
+
+    __mStack: collections.deque[str]
+
+    def __init__(self):
+        self.__mStack = collections.deque()
+
+    def push(self, item: str | int) -> None:
+        """
+        @brief Add an item into the top of this hierarchy.
+        @details
+        If given item is string, it will be push into hierarchy directly.
+        If given item is integer, this function will treat it as a special case, the index.
+        Function will push it into hierarchy after formatting it (add a pair of bracket around it).
+        @param[in] item New added item.
+        """
+        if isinstance(item, str):
+            self.__mStack.append(item)
+        elif isinstance(item, int):
+            self.__mStack.append(f'[{item}]')
+        else:
+            raise Exception('Unexpected type of item when pushing into hierarchy.')
+
+    def pop(self) -> None:
+        """
+        @brief Remove the top item from hierarchy
+        """
+        self.__mStack.pop()
+
+    def safe_push(self, item: str | int) -> 'HierarchyLayer':
+        """
+        @brief The safe version of push function.
+        @return A with-context-supported instance which can make sure pushed item popped when leaving scope.
+        """
+        return HierarchyLayer(self, item)
+
+    def clear(self) -> None:
+        """
+        @brief Clear this hierarchy.
+        """
+        self.__mStack.clear()
+
+    def depth(self) -> int:
+        """
+        @brief Return the depth of this hierarchy.
+        @return The depth of this hierarchy.
+        """
+        return len(self.__mStack)
+
+    def build_hierarchy_string(self) -> str:
+        """
+        @brief Build the string which can represent this hierarchy.
+        @details It just join every items with `/` as separator.
+        @return The built string representing this hierarchy.
+        """
+        return '/'.join(self.__mStack)
+
+class HierarchyLayer():
+    """
+    An with-context-supported class for Hierarchy which can automatically pop item when leaving scope.
+    This is convenient for keeping the balance of Hierarchy (avoid programmer accidently forgetting to pop item).
+    """
+    
+    __mHasPop: bool
+    __mAssocHierarchy: Hierarchy
+
+    def __init__(self, assoc_hierarchy: Hierarchy, item: str | int):
+        self.__mAssocHierarchy = assoc_hierarchy
+        self.__mHasPop = False
+        self.__mAssocHierarchy.push(item)
+
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+    
+    def close(self) -> None:
+        if not self.__mHasPop:
+            self.__mAssocHierarchy.pop()
+            self.__mHasPop = True
+
+    def emplace(self, new_item: str | int) -> None:
+        """
+        @brief Replace the content of top item in-place.
+        @details
+        In some cases, caller need to replace the content of top item.
+        For example, at the beginning, we only have index info.
+        After validating something, we can fetching a more human-readable info, such as name,
+        now we need replace the content of top item.
+        @param[in] new_item The new content of top item.
+        """
+        self.__mAssocHierarchy.pop()
+        self.__mAssocHierarchy.push(new_item)