From ddd3cd088822d03bd0c7e9ae7b87070fc7d7de6a Mon Sep 17 00:00:00 2001
From: grungies1138 <grungies1138@gmail.com>
Date: Tue, 20 Dec 2016 11:53:37 -0600
Subject: [PATCH] Update mail.py

---
 evennia/contrib/mail.py | 66 ++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 20 deletions(-)

diff --git a/evennia/contrib/mail.py b/evennia/contrib/mail.py
index a0c590fac0..3b2e2d610a 100644
--- a/evennia/contrib/mail.py
+++ b/evennia/contrib/mail.py
@@ -6,7 +6,7 @@ Evennia Contribution - grungies1138 2016
 A simple Brandymail style @mail system that uses the Msg class from Evennia Core.
 
 Installation:
-    Import this module into the default Player or Character commandset.
+    import MailCommand from this module into the default Player or Character command set
 """
 
 from evennia import default_cmds, search_object
@@ -14,14 +14,15 @@ from evennia.utils import create, utils, evtable, evform
 from evennia.comms.models import Msg
 
 
-HEAD_CHAR = "|015-|n"
-SUB_HEAD_CHAR = "-"
+_HEAD_CHAR = "|015-|n"
+_SUB_HEAD_CHAR = "-"
+_WIDTH = 78
 
-class MailCommand(default_cmds.MuxCommand):
+class CmdMail(default_cmds.MuxCommand):
     """
     Commands that allow either IC or OOC communications
 
-    Usage:
+    Usage:    
         {w@mail{n
                 - Displays all the mail a player has in their mailbox
 
@@ -41,13 +42,23 @@ class MailCommand(default_cmds.MuxCommand):
         {w@mail/reply <#>=<message>{n
                 - Replies to a message #.  Prepends message to the original
                   message text.
-
+    Switches:
+        delete  - deletes a message
+        forward - forward a received message to another object with an optional message attached.
+        reply   - Replies to a received message, appending the original message to the bottom.
 
     Status Legend:
-        '{wU{n' = Unread/New message
-        '{wO{n' = Read/Old message
-        '{wR{n' = Replied to
-        '{wF{n' = Forwarded
+        '|wU|n' = Unread/New message
+        '|wO|n' = Read/Old message
+        '|wR|n' = Replied to
+        '|wF|n' = Forwarded
+        
+    Examples:
+        @mail 2
+        @mail Griatch=New mail/Hey man, I am sending you a message!
+        @mail/delete 6
+        @mail/forward feend78 Griatch=You guys should read this.
+        @mail/reply 9=Thanks for the info!
     """
     key = "@mail"
     aliases = ["mail"]
@@ -131,13 +142,13 @@ class MailCommand(default_cmds.MuxCommand):
 
                     messageForm = []
                     if message:
-                        messageForm.append(HEAD_CHAR * 78)
-                        messageForm.append("{wFrom:{n %s" % (message.senders[0].key))
-                        messageForm.append("{wSent:{n %s" % message.db_date_created.strftime("%m/%d/%Y %H:%M:%S"))
-                        messageForm.append("{wSubject:{n %s" % message.header)
-                        messageForm.append(SUB_HEAD_CHAR * 78)
+                        messageForm.append(HEAD_CHAR * _WIDTH)
+                        messageForm.append("|wFrom:|n %s" % (message.senders[0].key))
+                        messageForm.append("|wSent:|n %s" % message.db_date_created.strftime("%m/%d/%Y %H:%M:%S"))
+                        messageForm.append("|wSubject:|n %s" % message.header)
+                        messageForm.append(SUB_HEAD_CHAR * _WIDTH)
                         messageForm.append(message.message)
-                        messageForm.append(HEAD_CHAR * 78)
+                        messageForm.append(HEAD_CHAR * _WIDTH)
                     self.caller.msg("\n".join(messageForm))
                     message.tags.remove("u", category="mail")
                     message.tags.add("o", category="mail")
@@ -146,8 +157,8 @@ class MailCommand(default_cmds.MuxCommand):
             messages = self.get_all_mail()
 
             if messages:
-                table = evtable.EvTable("{wID:", "{wFrom:", "{wSubject:", "{wDate:{n", "{wSta:{n",
-                                        table=None, border="header", header_line_char=SUB_HEAD_CHAR, width=78)
+                table = evtable.EvTable("|wID:|n", "|wFrom:|n", "|wSubject:|n", "|wDate:|n", "|wSta:|n",
+                                        table=None, border="header", header_line_char=SUB_HEAD_CHAR, width=_WIDTH)
                 index = 1
                 for message in messages:
                     table.add_row(index, message.senders[0], message.header,
@@ -161,19 +172,34 @@ class MailCommand(default_cmds.MuxCommand):
                 table.reformat_column(3, width=13)
                 table.reformat_column(4, width=7)
 
-                self.caller.msg(HEAD_CHAR * 78)
+                self.caller.msg(HEAD_CHAR * _WIDTH)
                 self.caller.msg(table)
-                self.caller.msg(HEAD_CHAR * 78)
+                self.caller.msg(HEAD_CHAR * _WIDTH)
             else:
                 self.caller.msg("Sorry, you don't have any messages.  What a pathetic loser!")
 
     def get_all_mail(self):
+        """
+        Returns a list of all the messages where the caller is a recipient.
+        
+        Returns:
+            messages (list): list of Msg objects.
+        """
         mail_messages = Msg.objects.get_by_tag(category="mail")
         messages = []
         messages = [m for m in mail_messages if self.caller.player in m.receivers]
         return messages
 
     def send_mail(self, recipients, subject, message, caller):
+        """
+        Function for sending new mail.  Also useful for sending notifications from objects or systems.
+        
+        Args:
+            recipients (list): list of Player or character objects to receive the newly created mails.
+            subject (str): The header or subject of the message to be delivered.
+            message (str): The body of the message being sent.
+            caller (obj): The object (or Player or Character) that is sending the message.
+        """
         recobjs = []
         for char in recipients: