From: gk5g+@ANDREW.CMU.EDU (Gary Keim)
Newsgroups: comp.soft-sys.andrew
Subject: Re: AMS Filtering
Date: 3 Sep 92 16:04:45 GMT
Distribution: world
Organization: The Internet

Excerpts from misc: 3-Sep-92 AMS Filtering swh2y@gingko.cs.Virginia (165)

> I need some more information on Andrew Message System
> filtering. Do you know of any papers, tech reports, etc.
that specifically talks about filtering?

Here the help file for the flames language:
FLAMES: 
Filtering Language for the Andrew Message System

What is FLAMES?

    FLAMES is an "extension language" for the Andrew Message System. 
    You can use FLAMES to write a LISP-like program that will
    automatically classify your incoming mail.

    What can FLAMES do?  FLAMES can act on any message that arrives in
    your Mailbox.  It acts on them as you read your mail--as messages in
    your Mailbox are moved into appropriate folders.  For example, you
    can write a FLAMES file that will sort mail from certain people into
    certain folders, or you can automatically post messages with special
    addresses that arrive in your Mailbox to a private bulletin board
    you maintain.  You can also reject mail--that is, bounce it back to
    the sender--if you consider it "junk" mail, or you can automatically
    resend mail to additional destinations.

    What can't FLAMES do?  Eventually, FLAMES will support all kinds of
    actions on the message database, but now it can only classify
    incoming mail as it is processed while reading it out of your
    Mailbox.  This means that you can't use FLAMES to manipulate
    messages on bulletin boards (because the messages don't go through
    your Mailbox), and that you have to read your mail for the messages
    in your Mailbox to be processed.

Do I need to be a programmer to use FLAMES?

    No.  This help file contains several useful "cookbook" programs, as
    well as instructions and examples illustrating how to modify them,
    so even if you are not a programmer, you, too, can automatically
    classify your incoming mail.  The programs (A and B) in this file
    will let you do the following:

    A.  Classify mail into any folder (a top level folder, like
    "friends," or a sub-folder, like "friends.foo") by defining keywords
    that FLAMES will search for in the message headers.  The keywords
    can be anything, such as portions of an address, like "userid+foo."

    B.  Classify mail into a sub-folder (like "friends.foo") by the
    incoming address (userid+foo@andrew.cmu.edu) with the capability of
    sending rejection messages and folder creation notices.

    Both of these programs will let you process mail for a private
    bboard.  See  privatebb  for more information about creating a
    private bboard.

What if I am a programmer?

    If you are a programmer and want to learn about FLAMES, you will
    need to know how to program in LISP.   None of the help files on
    Andrew will teach you how to program in LISP.  In order to learn
    about LISP, you will have to get yourself a good book about LISP and
    learn from there.  There are many available.

    In addition to LISP, there is programming information specific to
    FLAMES that you should know about in:

    /usr/andrew/doc/ams/Flames.pgr

    You may also want to look at the simple program examples below; they
    could save you the trouble of "reinventing the wheel."

Program A: Classifying incoming mail by keyword

    It is very easy to use FLAMES to classify your new mail into folders
    according to keywords you define and apply to headers in your mail. 
    For example, the "keywords" you define can be people's names (or
    user ids), which you would apply to the "From" header.   Then, any
    mail from the person you specify would be automatically classified
    into a particular personal folder.

    Note that for the example program in this section, the folder(s) you
    want to classify messages into need not already exist; the folder(s)
    will be created for you automatically.  See the  messages-folders 
    help file for more information on folders.

    Copy the program.  Complete the following steps carefully to copy
    the program.

    1.  Edit a file in your home directory called:

        .AMS.flames

    This is your FLAMES file.  Once this file is created, every time you
    start an Andrew Message System program (Messages, CUI, VUI, or
    batmail), or read your new mail from within one of these programs
    that is already running, this file will be read.  

    2.  Copy the following code between the lines of semi-colons into
    your .AMS.flames file using Copy and Paste from the menus.  Make
    sure there is a blank line at the end of the file.

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

    (defun my-mail-hook (msg)
      (post-by-keyword
       msg
       "mail"
       '(
         (("header1")("keyword1" "keyword2")("folder"))
         )))

    (load "flib") ; The standard flames library

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

    Make sure there are no styles in the file by selecting the whole
    text and choosing Plainest from the pop-up menus..

    Modify the program.  To make the program work, you need to change
    four parts of the program.

    Note that whenever you change your .AMS.flames file and Save it, you
    do not need to restart the Andrew Message System program you are
    using for the changes you have made to take effect.

    1.  You need to change "my-mail-hook" in the first line to a unique
    name.  For example, you might substitute your user id for "my".

        Example.  The following line would make the flames file unique
        for Jello Biafra, whose user id is jbRo.

        (defun jbRo-mail-hook (msg)

    2.  You need to change "header" to be the mail header you want
    FLAMES to scan for keywords.  The header you specify must be
    lowercase.  For example, you might want FLAMES to scan the "from"
    header.  (See the Example after step 4, below.)

    3.  You need to change "keyword1" and "keyword2" to the keywords you
    want FLAMES to look for.  These keywords are regular expressions.  
    Among other things, this means that the keywords are case sensitive
    ("a" is not the same as "A").  They can be a substring of a longer
    string.  For example, you might want FLAMES to look for user ids, or
    names of people who send mail to you.  You would not need to include
    their whole mail address as a keyword ("jbRo+@andrew.cmu.edu"), but
    only a unique part ("jbRo").  

    Note that the "+" character in these regular expressions is "magic";
    it means "match 1 or more of the expressions immediately preceding
    me."  So, the regular expression "jbRo+carbons" used as a keyword,
    matches the strings "jbRocarbons", "jbRoocarbons", "jbRooocarbons",
    etc.  It does not match the string "jbRo+carbons", which is often
    what is desired.  In order to remove the magic significance of the
    "+", precede it with 2 backslashes, as in "jbRo\\+carbons".  If you
    want to know why there are two backslashes instead of one, see the
    documentation in

        /usr/andrew/doc/eli/regexp.doc

    See the Examples after number 4, below, for example lines that do a
    number of these things.

    4.  You need to change "folder" to be the name of a personal mail
    folder into which you want the messages placed.  Folder names are
    also case sensitive.  (See the  messages-folders  help file if you
    do not already have folders.)  For example, you might want messages
    placed in a folder called "friends."

        Example.  The following line in the program would put messages
        from jbRo and eeKr into a folder called friends.

        (("from" "sender") ("jbRo" "eeKr") ("friends"))

    You can have messages with a folder address (userid+foldername)
    filed into a folder by preceeding the + sign in the keyword with 2
    backslashes.

        Example.  The following line in the program would put messages
        addressed to jbRo+dictionary@andrew.cmu.edu into your folder
        called dictionary.

        (("to" "cc" "received") ("jbRo\\+dictionary") ("dictionary"))

        Example.  The following line in the program would put messages
        addressed to jbRo+dictionary.round2@andrew.cmu.edu into your
        folder called dictionary.round2.

        (("to" "cc" "received") ("jbRo\\+dictionary.round2")
        ("dictionary.round2"))

    You can have different numbers of headers, keywords or folders in
    this line from the program.  If you want to add more headers,
    keywords or folders, make sure that they are quoted, have spaces
    between them and other elements, but no spaces next to the
    parentheses.

        Example.  The following line in the program would put messages
        from zz1z into a folder called junk.

        (("from" "sender") ("zz1z") ("junk"))

    You can add several lines like the one above if you want to have
    multiple classifications.   Make sure you have parentheses in the
    right places.

        Example. The following example of the program would put messages
        from jbRo and eeKr into friends, and messages from zz1z into
        junk.  

        (defun flames-key-personal-mail (msg)
          (post-by-keyword
             msg
             "mail"
             '(
               (("from" "sender") ("jbRo" "eeKr") ("friends"))
               (("from" "sender") ("zz1z") ("junk"))
               )))

        (load "flib") ; The standard flames library

    You can also search other headers for keywords.

        Example.  The following example searches the "subject" header
        for the keywords "business," "boredom," and "tedium" and files
        messages it finds with those keywords into the folder called
        work, as well as doing what the example above does with messages
        from jbRo, eeKr, and zz1z.

        (defun flames-key-personal-mail (msg)
          (post-by-keyword
             msg
             "mail"
             '(
               (("subject") ("business" "boredom" "tedium") ("work"))
               (("from" "sender") ("jbRo" "eeKr") ("friends"))
               (("from" "sender") ("zz1z") ("junk"))
               )))

        (load "flib") ; The standard flames library

Program B: Classifying incoming mail by address

    If you get mail with an address that looks like 

        userid+foldername@andrew.cmu.edu

    it probably comes to your Mailbox.  That is because the AMS delivery
    system completely ignores anything in an address between the "+" and
    the "@".  Thus, user Jello Biafra (user id "jbRo") can have mail
    sent to "jbRo+movies@andrew.cmu.edu" and it will show up in his
    Mailbox.

    Using FLAMES, you can exploit this fact.  For example, if you
    maintain a private bulletin board, you can have the messages that
    are sent to the bulletin board via your Mailbox be placed in the
    folder (posted there) automatically every time you read your mail. 
    Or, if you subscribe to a mailing list, you can subscribe using a
    certain address (e.g. "userid+list-name@site-domain") and then,
    using FLAMES, automatically classify messages from that mailinglist
    into a separate folder.

    Note that classifying mail by address does not work for users on
    systems not running the AMS Delivery System.

    Copy the program.  Complete the following steps carefully to copy
    the program.

    1.  Edit a file in your home directory called:

        .AMS.flames

    This is your FLAMES file.  Once it is created, every time you start
    an Andrew Message System program (e.g., Messages, CUI, VUI, or
    batmail), or read your new mail from within one of these programs
    that is already running, this file will be read in and executed over
    each of your new messages in turn.

    2.  Copy the following code between the lines of semi-colons into
    your .AMS.flames file using Copy and Paste from the menus.  Make
    sure there is a carriage return at the end of the file.

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

    (defun my-mail-hook (msg)
      (standard-mapping 
        msg 
        "treeroot" 
        "defaultfolder" 
        "rejectto" 
        "rejectcc" 
        "rejectmessage"))

    (load "flib") ; standard flames library

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

    Make sure there are no styles in the file by selecting the whole
    text and choosing Plainest from the pop-up menus.

    Modify the program.  To make the program work, you need to change
    six parts of the program. 

    Note that when ever you change your .AMS.flames file and Save it,
    you do not need to restart the Andrew Message System program you are
    using for the  changes you have made to take effect.

    1.  You need to change "my-mail-hook" in the first line to a unique
    name.  For example, you might substitute your user id for "my".

    2.  You need to change "treeroot" to be the folder which is the
    parent for the suffix of your address.  For example, if you specify
    the folder "bboard" as the treeroot, then messages that come to you
    addressed to "userid+foo@andrew.cmu.edu" would be filed into a
    folder called "bboard.foo".  If "bboard.foo" does not exist, it will
    be created, and a folder creation announcement will be put into the
    parent folder, "bboard".  However, you must create the treeroot
    folder yourself.

    3.  You need to change "defaultfolder" to the folder where all
    messages without a suffix in the address should go.  The standard
    default folder is "mail".

    The last three things you need to change are to tell FLAMES what to
    do if a suffix names a folder that does not exist and can't be
    created.  In such cases, the mail will be rejected.  This means that
    a message will be composed and sent to someone saying that the mail
    could not be placed in the folder where it was requested to go.  

    4.  You need to change "rejectto" to an address which the rejection
    message will be sent to.  There are several options for this field:

        NIL (without quotes) sends the rejection message back to the sender,
        "" sends no rejection message at all,
        an address sends the rejection message to the address.

    5.  You need to change "rejectcc" to an address which a copy of the
    rejection message will be sent to.  There are several options for
    this field:

        NIL (without quotes) sends a copy of the rejection message
            to the user "BBoard.Maintainer".
        "" sends sends a copy of the rejection message to the user
            "BBoard.Maintainer".
        an address sends a copy of the rejection message to that address.

    6.  You need to change "rejectmessage" to be the text of the
    rejection message.  For example, you might use the following as a
    rejection message "Illegal personal folder name for userid."

        Example.  This function will take messages addressed to 

            jbRo+round2@andrew.cmu.edu

        and put them into Jello's folder called "dictionary.round2". 
        Rejection messages are sent back to the sender, and to Jello's
        folder called "dictionary.rejections".

        (defun jbRo-mail-hook (msg)
          (standard-mapping 
            msg 
            "dictionary"
            "mail"
            NIL
            "jbRo+rejections@andrew.cmu.edu" 
            "Illegal personal folder name for Jello Biafra"))

        (load "flib") ; standard flames library

Program Author

    Bob Glickstein, Nathaniel Borenstein

Related tools  

The following document is available on Flames.  You can use EZ to view it.

    /usr/andrew/doc/ams/Flames.pgr

Select (highlight) one of the italicized names and choose "Show Help on
Selected Word" from the pop-up menu to see the help file for:

    +
    eli                 an Embedded LISP Interpreter
    privatebb           create a private bboard
    Messages
    messages-folders
    ams                 some technical aspects of the AMS