\begindata{text,539016412} \textdsversion{12} \template{help} \define{global } \chapter{FLAMES: Filtering Language for the Andrew MEssage System } \section{What is FLAMES? }\leftindent{ 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. \bold{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. \bold{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. } \section{Do I need to be a programmer to use FLAMES?}\section{ } \leftindent{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: \bold{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." \bold{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 \italic{\helptopic{privatebb}} for more information about creating a private bboard. } \section{What if I am a programmer?} \leftindent{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."} \section{Program A: Classifying incoming mail by keyword} \leftindent{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 \italic{\helptopic{messages-folders}} help file for more information on folders. \bold{Copy the program.} Complete the following steps carefully to copy the program. \bold{1}. Edit a file in your home directory called: \leftindent{.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. \bold{2}. Copy the following code between the lines of semi-colons into your .AMS.flames file using \bold{Copy} and \bold{Paste} from the menus. Make sure there is a blank line at the end of the file. \typewriter{\smaller{;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (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 \bold{Plainest} from the pop-up menus.. \bold{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 \bold{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. \bold{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". \leftindent{\bold{\bold{Example. }} The following line would make the flames file unique for Jello Biafra, whose user id is jbRo. \typewriter{\smaller{(defun jbRo-mail-hook (msg)}}} \bold{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.) \bold{3}. You need to change "keyword1" and "keyword2" to the keywords you want FLAMES to look for. These keywords are \italic{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 \italic{not} match the string "jbRo+carbons", which is often what is desired. In order to remove the magic significance of the "+", precede it with \bold{2 backslashes, }as in "jbRo\\\\+carbons". If you want to know why there are two backslashes instead of one, see the documentation in \leftindent{/usr/andrew/doc/eli/regexp.doc} See the Examples after number 4, below, for example lines that do a number of these things. \bold{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 \italic{\helptopic{messages-folders}} help file if you do not already have folders.) For example, you might want messages placed in a folder called "friends." \leftindent{\bold{Example.} The following line in the program would put messages from jbRo and eeKr into a folder called friends. }}\leftindent{\leftindent{\typewriter{\smaller{(("from" "sender") ("jbRo" "eeKr") ("friends"))}}}}\smaller{\smaller{ }} \leftindent{You can have messages with a folder address (userid+foldername) filed into a folder by preceeding the + sign in the keyword with 2 backslashes. \leftindent{\bold{Example. } The following line in the program would put messages addressed to jbRo+dictionary@andrew.cmu.edu into your folder called dictionary. \typewriter{\smaller{(("to" "cc" "received") ("jbRo\\\\+dictionary") ("dictionary")) }} \bold{Example.} The following line in the program would put messages addressed to jbRo+dictionary.round2@andrew.cmu.edu into your folder called dictionary.round2. \typewriter{\smaller{(("to" "cc" "received") ("jbRo\\\\+dictionary.round2") ("dictionary.round2"))}}}} \leftindent{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.}\leftindent{\leftindent{ \bold{Example. }The following line in the program would put messages from zz1z into a folder called junk. \typewriter{\smaller{(("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. \leftindent{\bold{Example.} The following example of the program would put messages from jbRo and eeKr into friends, \italic{and} messages from zz1z into junk. \typewriter{\smaller{(defun flames-key-personal-mail (msg) (post-by-keyword msg "mail" '( (("from" "sender") ("jbRo" "eeKr") ("friends")) \typewriter{\indent{(("from" "sender") ("zz1z") ("junk"))}} ))) (load "flib") ; The standard flames library}}} You can also search other headers for keywords. \leftindent{ \bold{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. \smaller{ \typewriter{\bigger{(defun flames-key-personal-mail (msg) (post-by-keyword msg "mail" '( (("subject") ("business" "boredom" "tedium") ("work")) (("from" "sender") ("jbRo" "eeKr") ("friends")) \typewriter{\indent{(("from" "sender") ("zz1z") ("junk"))}} ))) (load "flib") ; The standard flames library}}}}} \section{Program B: Classifying incoming mail by address} \leftindent{If you get mail with an address that looks like \leftindent{\typewriter{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. \bold{Copy the program. } Complete the following steps carefully to copy the program. \bold{1}. Edit a file in your home directory called: \leftindent{.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. \bold{2}. Copy the following code between the lines of semi-colons into your .AMS.flames file using \bold{Copy} and \bold{Paste} from the menus. Make sure there is a carriage return at the end of the file. \typewriter{;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun my-mail-hook (msg) (standard-mapping msg "treeroot" "defaultfolder" "rejectto" "rejectcc" "rejectmessage")) (load "flib") ; standard flames library ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;}\typewriter{ } Make sure there are no styles in the file by selecting the whole text and choosing \bold{Plainest} from the pop-up menus. \bold{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 \bold{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. \bold{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". \bold{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. \bold{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. \bold{4}. You need to change "rejectto" to an address which the rejection message will be sent to. There are several options for this field: \leftindent{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.} \bold{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: \leftindent{\description{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.} } \bold{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." \leftindent{\bold{Example. } This function will take messages addressed to \leftindent{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". }}\smaller{\leftindent{\leftindent{\typewriter{(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}}} } \section{Program Author} \leftindent{ Bob Glickstein, Nathaniel Borenstein } \section{Related tools} The following document is available on Flames. You can use EZ to view it. \leftindent{/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: \leftindent{\italic{\helptopic{+} \helptopic{eli}} an Embedded LISP Interpreter\italic{ \helptopic{privatebb}} create a private bboard\italic{ \helptopic{Messages} \helptopic{messages-folders} \helptopic{ams}} some technical aspects of the AMS}\italic{ } \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,1582,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,539016412}