Mercurial > ldcheck / changeset

--- a/header.py	Tue Aug 25 21:31:41 2020 +0300
+++ b/header.py	Tue Aug 25 21:58:09 2020 +0300
@@ -3,6 +3,10 @@
 import datetime
 
 class Header:
+    '''
+        Result type of header processing, this contains all the header
+        information.
+    '''
     def __init__(self):
         self.description = None
         self.name = None
@@ -23,12 +27,20 @@
         return True
     @property
     def effective_filetype(self):
+        '''
+            What's the effective file type? The "Unofficial_" prefix is
+            left out.
+        '''
         if self.filetype.startswith('Unofficial_'):
             return self.filetype.rsplit('Unofficial_')[1]
         else:
             return self.filetype
     @property
     def effective_category(self):
+        '''
+            Returns the category of the part. Leading punctuation marks
+            are ignored.
+        '''
         if self.category:
             return self.category
         else:
@@ -39,6 +51,11 @@
             return category
 
 class BadHeader:
+    '''
+        If header processing fails this object is returned as the resulting
+        header instead. It contains the details of where the header could not
+        be understood and why.
+    '''
     def __init__(self, index, reason):
         self.index = index
         self.reason = reason
@@ -57,9 +74,14 @@
         and entry.text == "BFC INVERTNEXT"
 
 def is_suitable_header_object(entry):
+    '''
+        Is the given object something that we can consider to be
+        part of the header?
+    '''
     if is_invertnext(entry):
-        # BFC INVERTNEXT is not a header command anymore.
+        # It's BFC INVERTNEXT, that's not a header command.
         return False
+    # Check if it's one of the functional linetypes
     return not any(
         isinstance(entry, linetype)
         for linetype in [
@@ -74,6 +96,9 @@
     )
 
 class HeaderError(Exception):
+    '''
+        An error raised during header parsing
+    '''
     def __init__(self, index, reason):
         self.index, self.reason = index, reason
     def __repr__(self):
@@ -86,6 +111,9 @@
         return reason
 
 class HistoryEntry:
+    '''
+        Represents a single !HISTORY entry
+    '''
     def __init__(self, date, user, text):
         self.date, self.user, self.text = date, user, text
     def __repr__(self):
@@ -111,9 +139,14 @@
         self.skip_to_next()
         result.name = self.parse_pattern(r'^Name: (.+)$', 'name')[0]
         self.skip_to_next()
-        result.author, result.username = self.parse_pattern(r'^Author: (?:([^ \[]*[^\[]+) )?(?:\[([^\]]+)\])?', 'author')
+        # Parse author line
+        result.author, result.username = self.parse_pattern(r'^Author: (?:([^\[]+))?(?:\[([^\]]+)\])?', 'author')
+        if isinstance(result.author, str):
+            # clean leading spaces
+            result.author = str.strip(result.author)
         if not result.author and not result.username:
             self.parse_error('author line does not contain a name nor username')
+        # use more patterns to parse the rest of the header
         for header_entry in self.get_more_header_stuff():
             if self.try_to_match(
                 r'^!LDRAW_ORG ' \
@@ -179,24 +212,33 @@
             self.parse_error('LDRAW_ORG line is missing')
         return {
             'header': result,
-            'end-index': self.cursor + 1,
+            'end-index': self.cursor + 1, # record where the header ended
         }
     def parse_error(self, message):
         raise HeaderError(index = self.cursor, reason = message)
     def get_more_header_stuff(self):
+        '''
+            Iterates through the header and yields metacommand entries
+            one after the other.
+        '''
         self.cursor += 1
         new_cursor = self.cursor
         while new_cursor < len(self.model_body):
             entry = self.model_body[new_cursor]
             if not is_suitable_header_object(entry):
+                # looks like the header ended
                 break
             if isinstance(entry, linetypes.MetaCommand):
                 self.cursor = new_cursor
                 yield entry
             new_cursor += 1
     def skip_to_next(self, *, spaces_expected = 0):
+        '''
+            Skip to the next header line.
+        '''
         while True:
             if self.cursor + 1 >= len(self.model_body):
+                # wound up past the end of model
                 self.parse_error('file does not have a proper header')
             self.cursor += 1
             entry = self.model_body[self.cursor]
@@ -205,16 +247,28 @@
             if isinstance(entry, linetypes.MetaCommand):
                 return
     def try_to_match(self, pattern, patterntype):
+        '''
+            Tries to parse the specified pattern and to store the groups in
+            self.groups. Returns whether or not this succeeded.
+        '''
         try:
             self.groups = self.parse_pattern(pattern, patterntype)
             return True
         except:
             return False
     def current(self):
+        '''
+            Returns the text of the header line we're currently processing.
+        '''
         entry = self.model_body[self.cursor]
         assert isinstance(entry, linetypes.MetaCommand)
         return entry.text
     def parse_pattern(self, pattern, description):
+        '''
+            Matches the current header line against the specified pattern.
+            If not, raises an exception. See try_to_match for a softer wrapper
+            that does not raise exceptions.
+        '''
         match = re.search(pattern, self.current())
         if match:
             self.order.append(description)