MIME::Entity

- NAME
- DESCRIPTION
- PUBLIC INTERFACE
  - Constructors and converters
  - Instance methods
- UNDER THE HOOD
- DESIGN ISSUES
  - To subclass or not to subclass?
  - Some things just can't be ignored
- SEE ALSO
- AUTHOR
- VERSION

# NAME

MIME::Entity - class for parsed-and-decoded MIME message

WARNING: This code is in an evaluation phase until 1 August 1996. Depending on any comments/complaints received before this cutoff date, the interface may change in a non-backwards-compatible manner.

# DESCRIPTION

This package provides a class for representing MIME message entities, as specified in RFC 1521, Multipurpose Internet Mail Extensions .

Here are some excerpts from RFC-1521 explaining the terminology: each is accompanied by the equivalent in MIME:: terms:

Message
  From RFC-1521:

          The term "message", when not further qualified, means either the
          (complete or "top-level") message being transferred on a network, or
          a message encapsulated in a body of type "message".

  There currently is no explicit package for messages; under MIME::, messages may be read in from readable files or filehandles. A future extension will allow them to be read from any object reference that responds to a special ``next line'' method.

Body part
  From RFC-1521:

          The term "body part", in this document, means one of the parts of the
          body of a multipart entity. A body part has a header and a body, so
          it makes sense to speak about the body of a body part.

  Since a body part is just a kind of entity (see below), a body part is represented by an instance of MIME::Entity.

Entity
  From RFC-1521:

          The term "entity", in this document, means either a message or a body
          part.  All kinds of entities share the property that they have a
          header and a body.

  An entity is represented by an instance of MIME::Entity. There are instance methods for recovering the header (a MIME::Head) and the body (see below).

Body
  From RFC-1521:

          The term "body", when not further qualified, means the body of an
          entity, that is the body of either a message or of a body part.

  Well, this is a toughie. Both Mail::Internet (1.17) and Mail::MIME (1.03) represent message bodies in-core; unfortunately, this is not always the best way to handle things, especially for MIME streams that contain multi-megabyte tar files.

# PUBLIC INTERFACE

## Constructors and converters

new
  Class method. Create a new, empty MIME entity.

from_mail MAIL
  Class method. Create a new MIME entity from a MAIL::Internet object. Currently unimplemented .

to_mail
  Instance method. Convert a MIME entity to a MAIL::Internet object. Currently unimplemented .

## Instance methods

add_part
  Assuming we are a multipart message, add a body part (a MIME::Entity) to the array of body parts. Do not call this for single-part messages; i.e., don't call it unless the header has a `"multipart"` content-type.

body OPTVALUE
  Get or set the path to the file containing the body.

  If `OPTVALUE` is not given, the current body file is returned. If `OPTVALUE` is given, the body file is set to the new value, and the previous value is returned.

head OPTVALUE
  Get or set the head.

  If `OPTVALUE` is not given, the current head is returned. If `OPTVALUE` is given, the head is set to the new value, and the previous value is returned.

is_multipart
  Does this entity's MIME type indicate that it's a multipart entity? Returns undef (false) if the answer couldn't be determined, 0 (false) if it was determined to be false, and true otherwise.

  Note that this says nothing about whether or not parts were extracted.

mime_type
  A purely-for-convenience method. This simply relays the request to the associated MIME::Head object. The following are identical:

          $x = $entity->mime_type;

          $x = $entity->head->mime_type;

  If there is no head, returns undef in a scalar context and the empty array in a list context.

  Note that, while parsed entities still have MIME types, they do not have MIME encodings, or MIME versions, or fields, etc., etc... for those attributes, you still have to go to the head explicitly.

parts
  Return an array of all sub parts (each of which is a MIME::Entity), or the empty array if there are none.

  For single-part messages, the empty array will be returned. For multipart messages, the preamble and epilogue parts are not in the list! If you want them, use `all_parts()` instead.

dump_skeleton FILEHANDLE
  Dump the skeleton of the entity to the given FILEHANDLE, or to the currently-selected one if none given.

# UNDER THE HOOD

A MIME::Entity is composed of the following elements:

- A head , which is a reference to a MIME::Head object.

- A body , which (currently) is a path to a file containing the decoded body. It is possible for a multipart entity to have a body; this simply means that the body file contains a MIME message that hasn't yet been split into its component parts.

- A list of zero or more parts , each of which is a MIME::Entity object. The number of parts will only be nonzero if the content-type is some subtype of `"multipart"`.

# DESIGN ISSUES

## To subclass or not to subclass?

When I rewrote this module for the CPAN, I agonized for a long time about whether or not it really should just be a subclass of Mail::Internet (or the experimental Mail::MIME ). There were plusses:

- Software reuse.

- Inheritance of the mail-sending utilities.

- Elimination and stamping out of repetitive redundancies.

And, unfortunately, minuses:

- The Mail::Internet model of messages as being short enough to fit into in-core arrays is excellent for most email applications; however, it seemed ill-suited for generic MIME applications, where MIME streams could be megabytes long.

- The current implementation of Mail::Internet (version 1.17) is excellent for certain kinds of header manipulation; however, the `get()` method (for retrieveing a field's value) does a brute-force, regexp-based search through a linear array of the field values - worse, with a dynamically-compiled search pattern. Even given small headers, I was simply too uncomfortable with this approach for the MIME header applications, which could be fairly `get()-intensive.`

- In my heart of hearts, I honestly feel that the head should be encapsulated as a first-class object, separate from any attached body. Notice that this approach allows the head to be folded into the entity in the future; that is:

          $entity->head->get('subject');

  ...can work even if `MIME::Head` objects are eliminated, and `MIME::Entity` objects become the ones that handle the `get()` method. To do this, we'd simply define `MIME::Entity::head()` to return the ``self'' object, which would ``pretend'' to be the ``header'' object. Like this:

          sub head { $_[0] }

- While MIME streams follow RFC-822 syntax, they are not, strictly speaking, limited to email messages: HTTP is an excellent example of non-email-based MIME. So the inheritance from Mail::Internet was not without question anyway.

The compromise. Currently, MIME::Head is its own module. However:

- When a MIME::Head is constructed using `read()` (or `from_file()`), the original parsed header is stored, in all its flat-text glory, in the MIME::Head object, and may be recovered via the `original_text()` method.

- The conversion methods `from_mail()` and to_mail are provided in MIME::Entity class.

## Some things just can't be ignored

In multipart messages, the "preamble" is the portion that precedes the first encapsulation boundary, and the "epilogue" is the portion that follows the last encapsulation boundary.

According to RFC-1521:

        There appears to be room for additional information prior to the
        first encapsulation boundary and following the final boundary.  These
        areas should generally be left blank, and implementations must ignore
        anything that appears before the first boundary or after the last
        one.

        NOTE: These "preamble" and "epilogue" areas are generally not used
        because of the lack of proper typing of these parts and the lack
        of clear semantics for handling these areas at gateways,
        particularly X.400 gateways.  However, rather than leaving the
        preamble area blank, many MIME implementations have found this to
        be a convenient place to insert an explanatory note for recipients
        who read the message with pre-MIME software, since such notes will
        be ignored by MIME-compliant software.

In the world of standards-and-practices, that's the standard. Now for the practice:

Some MIME mailers may incorrectly put a "part" in the preamble , Since we have to parse over the stuff anyway , in the future I will allow the parser option of creating special MIME::Entity objects for the preamble and epilogue, with bogus MIME::Head objects.

# SEE ALSO

MIME::Decoder, MIME::Entity, MIME::Head, MIME::Parser.

# AUTHOR

Copyright (c) 1996 by Eryq / eryq@rhine.gsfc.nasa.gov

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

# VERSION

$Revision: 1.12 $ $Date: 1996/06/27 01:26:26 $