\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}
