=item attach PART

=item attach PARAMHASH...

I<Instance method.>
Add a new part to this message, and return the new part.

If you supply a single PART argument, it will be regarded
as a MIME::Lite object to be attached.  Otherwise, this
method assumes that you are giving in the pairs of a PARAMHASH
which will be sent into C<new()> to create the new part.

One of the possibly-quite-useful hacks thrown into this is the
"attach-to-singlepart" hack: if you attempt to attach a part (let's
call it "part 1") to a message that doesn't have a content-type
of "multipart" or "message", the following happens:

=over 4

=item *

A new part (call it "part 0") is made.

=item *

The MIME attributes and data (but I<not> the other headers)
are cut from the "self" message, and pasted into "part 0".

=item *

The "self" is turned into a "multipart/mixed" message.

=item *

The new "part 0" is added to the "self", and I<then> "part 1" is added.

=back

One of the nice side-effects is that you can create a text message
and then add zero or more attachments to it, much in the same way
that a user agent like Netscape allows you to do.

=cut

sub attach {
    my $self = shift;
    my $attrs = $self->{Attrs};
    my $sub_attrs = $self->{SubAttrs};

    ### Create new part, if necessary:
    my $part1 = ( ( @_ == 1 ) ? shift: ref($self)->new( Top => 0, @_ ) );

    ### Do the "attach-to-singlepart" hack:
    if ( $attrs->{'content-type'} !~ m{^(multipart|message)/}i ) {

        ### Create part zero:
        my $part0 = ref($self)->new;

        ### Cut MIME stuff from self, and paste into part zero:
        foreach (qw(SubAttrs Attrs Data Path FH)) {
            $part0->{$_} = $self->{$_};
            delete( $self->{$_} );
        }
        $part0->top_level(0);    ### clear top-level attributes

        ### Make self a top-level multipart:
        $attrs = $self->{Attrs} ||= {};       ### reset (sam: bug?  this doesn't
 reset anything since Attrs is already a hash-ref)
        $sub_attrs = $self->{SubAttrs} ||= {};    ### reset
        $attrs->{'content-type'}              = 'multipart/mixed';
        $sub_attrs->{'content-type'}{'boundary'}      = gen_boundary();
        $attrs->{'content-transfer-encoding'} = '7bit';
        $self->top_level(1);      ### activate top-level attributes

        ### Add part 0:
        push @{ $self->{Parts} }, $part0;
    }

    ### Add the new part:
    push @{ $self->{Parts} }, $part1;
    $part1;
}