From 64b3a79282be5f75dbb2d34432a8a40270eaac64 Mon Sep 17 00:00:00 2001
From: Greg Taylor <snagglepants@gmail.com>
Date: Thu, 22 Jan 2009 17:07:33 +0000
Subject: [PATCH] Should be the finishing touches on MUX help importer.

---
 tools/mux_help_importer.py | 49 +++++++++++++++++++++++++-------------
 1 file changed, 32 insertions(+), 17 deletions(-)

diff --git a/tools/mux_help_importer.py b/tools/mux_help_importer.py
index 6d45bf7258..3054eec1ee 100755
--- a/tools/mux_help_importer.py
+++ b/tools/mux_help_importer.py
@@ -16,9 +16,7 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'game.settings'
 from django.conf import settings
 from src.helpsys.models import HelpEntry
 
-# If true, when found, duplicate entries are replaced.
-replace_duplicates = False
-
+# Globally available help entry temp values
 topic_name = ''
 entry_text = ''
 
@@ -36,22 +34,28 @@ def _is_function_entry(topic_name):
         pass
     return False
 
-def _create_db_entry():
+def _create_db_entry(replace_duplicates):
     """
     Creates a HelpFile object in the database from the currently stored values.
     """
     global topic_name, entry_text
     
+    # See if an existing topic matches the new topic's name
     existing_matches = HelpEntry.objects.filter(topicname__iexact=topic_name)
+    
+    # If this becomes false, the entry is not saved
     save_entry = True
     
     if existing_matches and not replace_duplicates:
+        # Duplicate, ignore this one
         print "IGNORING DUPLICATE:", topic_name
         save_entry = False
     elif existing_matches and replace_duplicates:
+        # Replace an existing entry
         print "REPLACING:", topic_name
         help = existing_matches[0]
     else:
+        # New blank entry
         print "CREATING:", topic_name
         help = HelpEntry()
     
@@ -63,43 +67,54 @@ def _create_db_entry():
         else:
             print "IGNORING FUNCTION:", topic_name
     
+    # Reset for the next help entry
     topic_name = ''
     entry_text = ''
     
-def _start_new_helpentry(first_line):
+def _start_new_helpentry(first_line, replace_duplicates):
     """
     Given a line, start storing stuff in a new help entry.
     """
     global topic_name
     
+    # Before starting a new help entry, save the old one that was previously
+    # being worked on (if applicable)
     if topic_name.strip() != '' and entry_text.strip() != '':
-        _create_db_entry()
+        _create_db_entry(replace_duplicates)
     
     topic_name = first_line[1:].strip()
+    # Handle the default topic
     if topic_name == '' or topic_name.lower() == 'help':
         topic_name = 'Help Index'
 
-def import_helpfiles(file):
+def import_helpfiles(file, replace_duplicates=False):
     """
     Given a file-like object, imports the help files within.
     """
     global topic_name, entry_text
     
+    # One list entry per line
     line_list = file.readlines()
     
     for line in line_list:
+        """
+        If the first character of the line is an ampersand, this line is the
+        start of a new help entry. Save the previous one we were working on
+        and start a new one.
+        """
         if line[0] == '&':
-            _start_new_helpentry(line)
+            _start_new_helpentry(line, replace_duplicates)
         else:
-            #print "+%s" % line
+            # Otherwise, keep cramming the lines into the entry text attrib
             entry_text += line
+            
+    # End the last topic
+    _start_new_helpentry('', replace_duplicates)
 
 def main():
     """
     Beginning of the program logic.
     """
-    global replace_duplicates
-    
     parser = OptionParser(usage="%prog [options] <helpfile.txt>",
         description="This command imports MUX and MUSH-style help files. By " \
         "default, if a duplicate entry is found, the existing entry is " \
@@ -110,7 +125,7 @@ def main():
                       help='Replace duplicate entries')
     (options, args) = parser.parse_args()
     
-    # A filename must be provided
+    # A filename must be provided, show help if not
     filename = " ".join(args)
     if filename.strip() == "":
         parser.print_help()
@@ -122,11 +137,11 @@ def main():
         print "Specified file cannot be found."
         return
     
-    # Make this globally available for lazyness
-    replace_duplicates = options.replace_duplicates
-    
     # Import the help files
-    import_helpfiles(file)
+    import_helpfiles(file, replace_duplicates=options.replace_duplicates)
         
 if __name__ == '__main__':
-    main()
\ No newline at end of file
+    try:
+        main()
+    except KeyboardInterrupt:
+        print "Import Aborted."
\ No newline at end of file