Trunk: Merged the Devel-branch (branches/griatch) into /trunk. This constitutes a major refactoring of Evennia. Development will now continue in trunk. See the wiki and the past posts to the mailing list for info. /Griatch

src/help/admin.py

@@ -0,0 +1,12 @@
+from django.contrib import admin
+from src.help.models import HelpEntry
+
+class HelpEntryAdmin(admin.ModelAdmin):
+    list_display = ('id', 'db_key', 'db_help_category', 'db_permissions')
+    list_display_links = ('id', 'db_key')
+    search_fields = ['^db_key', 'db_entrytext']
+    ordering = ['db_help_category', 'db_key']
+    save_as = True 
+    save_on_top = True   
+    list_select_related = True 
+admin.site.register(HelpEntry, HelpEntryAdmin)

src/help/manager.py

@@ -0,0 +1,86 @@
+"""
+Custom manager for HelpEntry objects.
+"""
+from django.db import models
+from src.utils import logger
+
+class HelpEntryManager(models.Manager):
+    """
+    This implements different ways to search for help entries.
+    """
+    def find_topicmatch(self, topicstr, exact=False):
+        """
+        Searches for matching topics based on player's input.
+        """        
+        if topicstr.isdigit():
+            return self.filter(id=topicstr)
+        topics = self.filter(db_key__iexact=topicstr)
+        if not topics and not exact: 
+            topics = self.filter(db_key__istartswith=topicstr)            
+            if not topics:
+                topics = self.filter(db_key__icontains=topicstr)            
+        return topics
+
+    def find_apropos(self, topicstr):
+        """
+        Do a very loose search, returning all help entries containing
+        the search criterion in their titles. 
+        """
+        return self.filter(db_key__icontains=topicstr)
+        
+    def find_topicsuggestions(self, topicstr):
+        """
+        Do a fuzzy match, preferably within the category of the
+        current topic.
+        """                
+        topics = self.find_apropos(topicstr)       
+        # we need to clean away the given help entry.
+        return [topic for topic in topics
+                if topic.key.lower() != topicstr.lower()]
+                    
+    def find_topics_with_category(self, help_category):
+        """
+        Search topics having a particular category
+        """
+        topics = self.filter(db_help_category__iexact=help_category)
+        return topics
+
+    def get_all_topics(self):
+        """
+        Return all topics.
+        """
+        return self.all()
+
+    def get_all_categories(self, pobject):
+        """
+        Return all defined category names with at least one
+        topic in them.
+        """
+        return list(set(topic.help_category for topic in self.all()))
+
+    def all_to_category(self, default_category):
+        """
+        Shifts all help entries in database to default_category.
+        This action cannot be reverted. It is used primarily by
+        the engine when importing a default help database, making
+        sure this ends up in one easily separated category. 
+        """
+        topics = self.all()
+        for topic in topics:
+            topic.help_category = default_category
+            topic.save()
+        string = "Help database moved to category %s" % default_category
+        logger.log_infomsg(string)
+
+    def search_help(self, ostring, help_category=None):
+        """
+        Retrieve a search entry object.
+
+        ostring - the help topic to look for
+        category - limit the search to a particular help topic
+        """
+        ostring = ostring.strip().lower() 
+        help_entries = self.filter(db_topicstr=ostring)
+        if help_category:
+            help_entries.filter(db_help_category=help_category)
+        return help_entries

src/help/models.py

@@ -0,0 +1,158 @@
+"""
+Models for the help system.
+
+The database-tied help system is only half of Evennia's help
+functionality, the other one being the auto-generated command help
+that is created on the fly from each command's __doc__ string. The
+persistent database system defined here is intended for all other
+forms of help that do not concern commands, like information about the
+game world, policy info, rules and similar.
+
+"""
+from django.db import models
+from src.utils.idmapper.models import SharedMemoryModel
+from src.help.manager import HelpEntryManager
+from src.utils import ansi
+from src.utils.utils import is_iter
+
+#------------------------------------------------------------
+#
+# HelpEntry
+#
+#------------------------------------------------------------
+
+class HelpEntry(SharedMemoryModel):
+    """
+    A generic help entry.
+
+    An HelpEntry object has the following properties defined:
+      key - main name of entry
+      help_category - which category entry belongs to (defaults to General)
+      entrytext - the actual help text
+      permissions - perm strings
+
+    """
+    
+
+    #
+    # HelpEntry Database Model setup
+    #
+    #
+    # These database fields are all set using their corresponding properties,
+    # named same as the field, but withtout the db_* prefix.
+
+    # title of the help 
+    db_key = models.CharField(max_length=255, unique=True)
+    # help category 
+    db_help_category = models.CharField(max_length=255, default="General")
+    # the actual help entry text, in any formatting. 
+    db_entrytext = models.TextField(blank=True)  
+    # a string of permissionstrings, separated by commas. 
+    db_permissions = models.CharField(max_length=255, blank=True)    
+
+    # (deprecated, only here to allow MUX helpfile load (don't use otherwise)).
+    # TODO: remove this when not needed anymore. 
+    db_staff_only = models.BooleanField(default=False) 
+
+    # Database manager
+    objects = HelpEntryManager()
+        
+    class Meta:
+        "Define Django meta options"
+        verbose_name = "Help Entry"
+        verbose_name_plural = "Help Entries"
+
+    # Wrapper properties to easily set database fields. These are
+    # @property decorators that allows to access these fields using
+    # normal python operations (without having to remember to save()
+    # etc). So e.g. a property 'attr' has a get/set/del decorator
+    # defined that allows the user to do self.attr = value, 
+    # value = self.attr and del self.attr respectively (where self 
+    # is the object in question).
+        
+    # key property (wraps db_key)
+    #@property
+    def key_get(self):
+        "Getter. Allows for value = self.key"
+        return self.db_key
+    #@key.setter
+    def key_set(self, value):
+        "Setter. Allows for self.key = value"
+        self.db_key = value
+        self.save()
+    #@key.deleter
+    def key_del(self):
+        "Deleter. Allows for del self.key. Deletes entry."
+        self.delete()
+    key = property(key_get, key_set, key_del)
+
+    # help_category property (wraps db_help_category)
+    #@property
+    def help_category_get(self):
+        "Getter. Allows for value = self.help_category"
+        return self.db_help_category
+    #@help_category.setter
+    def help_category_set(self, value):
+        "Setter. Allows for self.help_category = value"
+        self.db_help_category = value
+        self.save()
+    #@help_category.deleter
+    def help_category_del(self):
+        "Deleter. Allows for del self.help_category"
+        self.db_help_category = "General"
+        self.save()
+    help_category = property(help_category_get, help_category_set, help_category_del)
+
+    # entrytext property (wraps db_entrytext)
+    #@property
+    def entrytext_get(self):
+        "Getter. Allows for value = self.entrytext"
+        return self.db_entrytext
+    #@entrytext.setter
+    def entrytext_set(self, value):
+        "Setter. Allows for self.entrytext = value"
+        self.db_entrytext = value
+        self.save()
+    #@entrytext.deleter
+    def entrytext_del(self):
+        "Deleter. Allows for del self.entrytext"
+        self.db_entrytext = ""
+        self.save()
+    entrytext = property(entrytext_get, entrytext_set, entrytext_del)
+
+    # permissions property
+    #@property
+    def permissions_get(self):
+        "Getter. Allows for value = self.permissions. Returns a list of permissions."
+        return [perm.strip() for perm in self.db_permissions.split(',')]
+    #@permissions.setter
+    def permissions_set(self, value):
+        "Setter. Allows for self.permissions = value. Stores as a comma-separated string."
+        if is_iter(value):
+            value = ",".join([str(val).strip().lower() for val in value])
+        self.db_permissions = value
+        self.save()        
+    #@permissions.deleter
+    def permissions_del(self):
+        "Deleter. Allows for del self.permissions"
+        self.db_permissions = ""
+        self.save()
+    permissions = property(permissions_get, permissions_set, permissions_del)
+
+    #
+    #
+    # HelpEntry main class methods
+    #
+    #
+        
+    def __str__(self):
+        return self.key
+
+    def __unicode__(self):
+        return u'%s' % self.key
+                
+    def get_entrytext_ingame(self):
+        """
+        Gets the entry text for in-game viewing.
+        """
+        return ansi.parse_ansi(self.entrytext)