missed this part of the patch, added doc

Author: Richard Jones

doc/user_guide.txt

@@ -2,7 +2,7 @@
 User Guide
 ==========
 
-:Version: $Revision: 1.12 $
+:Version: $Revision: 1.13 $
 
 .. contents::
 
@@ -302,6 +302,51 @@ message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
 to determine if they get a nosy list copy of the message too.
 
 
+Mail gateway script command line
+--------------------------------
+
+The roundup mail gateway may be called in one of three ways:
+
+ . with an instance home as the only argument,
+ . with both an instance home and a mail spool file, or
+ . with both an instance home and a pop server account.
+ 
+It also supports optional -C and -S arguments that allows you to set a
+fields for a class created by the roundup-mailgw. The default class if
+not specified is msg, but the other classes: issue, file, user can
+also be used. The -S or --set options uses the same
+property=value[;property=value] notation accepted by the command line
+roundup command or the commands that can be given on the Subject line
+of an email message.
+
+It can let you set the type of the message on a per email address basis.
+
+PIPE:
+ In the first case, the mail gateway reads a single message from the
+ standard input and submits the message to the roundup.mailgw module.
+
+UNIX mailbox:
+ In the second case, the gateway reads all messages from the mail spool
+ file and submits each in turn to the roundup.mailgw module. The file is
+ emptied once all messages have been successfully handled. The file is
+ specified as::
+
+   mailbox /path/to/mailbox
+
+POP:
+ In the third case, the gateway reads all messages from the POP server
+ specified and submits each in turn to the roundup.mailgw module. The
+ server is specified as::
+    pop username:password@server
+
+ The username and password may be omitted::
+    pop username@server
+    pop server
+
+ are both valid. The username and/or password will be prompted for if
+ not supplied on the command-line.
+
+
 Command Line Tool
 =================
 

roundup/mailgw.py

@@ -73,7 +73,7 @@ class node. Any parts of other types are each stored in separate files
 an exception, the original message is bounced back to the sender with the
 explanatory message given in the exception. 
 
-$Id: mailgw.py,v 1.105 2003-01-11 23:52:27 richard Exp $
+$Id: mailgw.py,v 1.106 2003-01-12 00:03:10 richard Exp $
 '''
 
 import string, re, os, mimetools, cStringIO, smtplib, socket, binascii, quopri
@@ -139,9 +139,10 @@ def getPart(self):
     r'\s*(?P<title>[^[]+)?"?(\[(?P<args>.+?)\])?', re.I)
 
 class MailGW:
-    def __init__(self, instance, db):
+    def __init__(self, instance, db, arguments={}):
         self.instance = instance
         self.db = db
+        self.arguments = {}
 
         # should we trap exceptions (normal usage) or pass them through
         # (for testing)
@@ -496,21 +497,18 @@ def handle_message(self, message):
 Subject was: "%s"
 '''%(nodeid, subject)
 
-        #
-        # Handle the options specified by the email gateway
-        # command line. I do this by looping over the list of
-        # self.options looking for a -C to tell me what class
-        # I add the -S setting string to.
-        #
+
+        # Handle the arguments specified by the email gateway command line.
+        # We do this by looping over the list of self.arguments looking for
+        # a -C to tell us what class then the -S setting string.
         msg_props = {}
         user_props = {}
         file_props = {}
         issue_props = {}
-        # this should be true if options are set on command
-        # line
-        if hasattr(self, 'options'):
+        # so, if we have any arguments, use them
+        if self.arguments:
             current_class = 'msg'
-            for option, propstring in self.options:
+            for option, propstring in self.arguments:
                 if option in ( '-C', '--class'):
                     current_class = propstring.strip()
                     if current_class not in ('msg', 'file', 'user', 'issue'):

roundup/scripts/roundup_mailgw.py

@@ -14,26 +14,37 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: roundup_mailgw.py,v 1.6 2002-09-13 00:08:44 richard Exp $
+# $Id: roundup_mailgw.py,v 1.7 2003-01-12 00:03:11 richard Exp $
 
 # python version check
 from roundup import version_check
 
-import sys, os, re, cStringIO
+import sys, os, re, cStringIO, getopt
 
 from roundup.mailgw import Message
 from roundup.i18n import _
 
 def usage(args, message=None):
     if message is not None:
         print message
-    print _('Usage: %(program)s <instance home> [method]')%{'program': args[0]}
+    print _('Usage: %(program)s [[-C class] -S field=value]* <instance '
+        'home> [method]')%{'program': args[0]}
     print _('''
 
 The roundup mail gateway may be called in one of three ways:
  . with an instance home as the only argument,
  . with both an instance home and a mail spool file, or
  . with both an instance home and a pop server account.
+ 
+It also supports optional -C and -S arguments that allows you to set a
+fields for a class created by the roundup-mailgw. The default class if
+not specified is msg, but the other classes: issue, file, user can
+also be used. The -S or --set options uses the same
+property=value[;property=value] notation accepted by the command line
+roundup command or the commands that can be given on the Subject line
+of an email message.
+
+It can let you set the type of the message on a per email address basis.
 
 PIPE:
  In the first case, the mail gateway reads a single message from the
@@ -59,16 +70,25 @@ def usage(args, message=None):
 ''')
     return 1
 
-def main(args):
+def main(argv):
     '''Handle the arguments to the program and initialise environment.
     '''
+    # take the argv array and parse it leaving the non-option
+    # arguments in the args array.
+    try:
+        optionsList, args = getopt.getopt(argv[1:], 'C:S:', ['set=', 'class='])
+    except getopt.GetoptError:
+        # print help information and exit:
+        usage(argv)
+        sys.exit(2)
+
     # figure the instance home
-    if len(args) > 1:
-        instance_home = args[1]
+    if len(args) > 0:
+        instance_home = args[0]
     else:
         instance_home = os.environ.get('ROUNDUP_INSTANCE', '')
     if not instance_home:
-        return usage(args)
+        return usage(argv)
 
     # get the instance
     import roundup.instance
@@ -79,16 +99,16 @@ def main(args):
 
     # now wrap in try/finally so we always close the database
     try:
-        handler = instance.MailGW(instance, db)
+        handler = instance.MailGW(instance, db, optionsList)
 
         # if there's no more arguments, read a single message from stdin
-        if len(args) == 2:
+        if len(args) == 1:
             return handler.do_pipe()
 
         # otherwise, figure what sort of mail source to handle
-        if len(args) < 4:
-            return usage(args, _('Error: not enough source specification information'))
-        source, specification = args[2:]
+        if len(args) < 3:
+            return usage(argv, _('Error: not enough source specification information'))
+        source, specification = args[1:]
         if source == 'mailbox':
             return handler.do_mailbox(specification)
         elif source == 'pop':
@@ -97,9 +117,9 @@ def main(args):
             if m:
                 return handler.do_pop(m.group('server'), m.group('user'),
                     m.group('pass'))
-            return usage(args, _('Error: pop specification not valid'))
+            return usage(argv, _('Error: pop specification not valid'))
 
-        return usage(args, _('Error: The source must be either "mailbox" or "pop"'))
+        return usage(argv, _('Error: The source must be either "mailbox" or "pop"'))
     finally:
         db.close()