$Id: README,v 1.13 2002/02/21 08:56:19 parkerpine Exp $

There are now packages for PPM available as well! See below the bits on 
installation to learn how to install those.

--------------------------------------------------------------------------------

Mail::MboxParser is a module for working with UNIX-flavoured mailboxes.
This document describes version 0.34.

Its purpose is to _easily_ extract messages from a mailbox with _simple_ 
access to header fields, body and MIME-parts. It is for those people who 
find the above two module-sets too confusing and heavy-weighted. See the 
list of provided methods below.
It is particularly easy to deal with any kind of attached files. See the 
supplied store_att.pl script for an example. 

Prerequisites:
--------------
    
    + MIME::Tools (probably >= 5.0)
    + MIME::QuotedPrint (don't know which version)
    
    optional:
    + URI::Find if you want to use Mail::MboxParser::Mail::Body->extract_urls

Installation:
-------------

    'make'-enabled systems:
    -----------------------
    Un'tar xfz' the module and 'cd' into the new directory 
    Mail-MboxParser-$VERSION.

    Then install:
        perl Makefile.PL
        make
        make test
        make install

    Win-users having an 'nmake' installed can also do the above, given the
    fact they replace 'make' with 'nmake' in the above list.

    Win-systems:
    ------------
    On request there is now also a PPM-version of each new package 
    available (unless I forget to make one;-). Start ppm and do the 
    following:
    
    ppm> set repository sourceforge http://mail-mboxparser.sourceforge.net/ 
    ppm> search Mail-MboxParser             <== optional!
    ppm> install Mail-MboxParser-$VERSION
         [or possibly just:
         install Mail-MboxParser
         ]

Autoloader:
-----------
Read the Mail::MboxParser::Mail docs for invoking external methods.
The autoloading-mechanism will take care that the below and other things
will work:

	$mail->effective_type; # from MIME::Entity

Methods:
--------

Mail::MboxParser::Base (not to be instantiated)
	::error (error of last operation if any)
	::log (logs internal errors in rare cases)
	
Mail::MboxParser
	::new (of course)
	::open
	::get_messages  (all in array)
    ::get_message(n) 
    ::next_message
    ::rewind
    ::set_pos
    ::current_pos
    ::get_pos(n)    (of message n)
    ::make_index
	::nmsgs (num of messages in mailbox)
	
Mail::MboxParser::Mail
	::new (usually internally called by Mail::MboxParser::get_messages)
	::header (hash-ref with all header-fields)
    ::from_line
    ::trace (received-lines as list) 
	::body (Mail::MboxParser::Mail::Body object)
	::find_body (index number that should be the main-body of email)
    ::get_field 
	::from (hash-ref)
	::to (array of hash-refs)
    ::cc (same as to())
	::id
	::num_entities (no of MIME-entities)
	::get_entities (array or scalar if called with a number)
	::get_entity_body (body of the n-th entity as single string)
	::store_attachement 
	::store_all_attachements (just save all saveable attachements to filehandle)
    ::make_convertable (create a Mail::MboxParser::Mail::Convertable)

Mail::MboxParser::Mail::Body
	::new (done internally)
    ::as_string
    ::as_lines
	::signature (signature of the body if any)
	::extract_urls (hash-ref with url and context)
    ::quotes (hash-ref of array-refs)
    
Mail::MboxParser::Mail::Convertable
    ::new 
    ::delete_from_header
    ::replace_in_header
    ::add_to_header
    ::send
    
Have a look into the eg-directory of the package for some (or one) example(s).

Contact:
--------
Bugs, feature requests, questions, comments etc. should be directly 
mailed to me.

Tassilo v. Parseval
<tassilo.parseval@post.rwth-aachen.de>

