Message::Body::Construct(3)

NAME
Mail::Message::Body::Construct - adds functionality to Mail::Message::Body

CLASS HIERARCHY
 Mail::Message::Body::String
 is a Mail::Message::Body
 is a Mail::Reporter

SYNOPSIS

DESCRIPTION
This package adds complex functionality to the "Mail::Message::Body" class. This functions less often used, so many programs will not compile this package.

METHOD INDEX
The general methods for "Mail::Message::Body::Construct" objects:

      attach MESSAGES, OPTIONS             foreachLine CODE
      concatenate COMPONENTS               stripSignature OPTIONS

METHODS

foreachLine CODE
    Create a new body by performing an action on each of its lines. If none of the lines change, the current body will be returned, otherwise a new body is created of the same type as the current.

    The CODE refers to a subroutine which is called, where $_ contains body's original line. DO NOT CHANGE $_!!! The result of the routine is taken as new line. When the routine returns "undef", the line will be skipped.

    Examples:

     my $content  = $msg->decoded;
     my $reply    = $content->foreachLine( sub { '> '.$_ } );
     my $rev      = $content->foreachLine( sub {reverse} );

     sub filled() { length $_ > 1 ? $_ : undef }
     my $nonempty = $content->foreachLine( \&filled );

     my $wrong    = $content->foreachLine( sub {s/a/A/} );  # WRONG!!!
     my $right    = $content->foreachLine( sub {(my $x=$_) =~ s/a/A/} );

concatenate COMPONENTS
    Concatenate a list of elements into one new body. The encoding is defined by the body where this method is called upon (and which does not need to be included in the result).

    Specify a list of COMPONENTS. Each component can be

    a message ("Mail::Message"), the body of the message is used,
    a body ("Mail::Message::Body"),
    "undef", which will be skipped,
    a scalar, which is split on new-lines,
    an array of scalars, each providing one line.

    Example:

     # all arguments are C<Mail::Message::Body>'s.
     my $sum = $body->concatenate($preamble, $body, $epilogue, "--\n" , $sig);

attach MESSAGES, OPTIONS
    Make a multipart containing this body and the specified MESSAGES. The options are passed to the constructor of the multi-part body. If you need more controle, create the multi-part body yourself. At least take a look at Mail::Message::Body::Multipart.

    The message-parts will be coerced into a "Mail::Message::Part", so you may attach "Mail::Internet" or "MIME::Entity" objects if you want --see "Mail::Message::coerce()". A new body with attached messages is returned.

    Examples:

     my $pgpkey = Mail::Message::Body::File->new(file => '.pgp');
     my $msg    = Mail::Message->buildFromBody(
        $message->decoded->attach($pgpkey));

     my $entity  = MIME::Entity->new;
     my $multi   = $msg->body->attach($entity);
     # The last message of the $multi multiparted body is the coerced $entity.

stripSignature OPTIONS
    Strip the signature from the body. The body must already be decoded otherwise the wrong lines may get stripped.

    The signature is added by the sender to tell about him- or herself. It is superfluous in some situations, for instance if you want to create a reply to the person's message you do not need to include that signature.

    <stripSignature> returns the stripped version body, and in list context also the signature, encapsulated in its own body object. If the body had no signature, the original body object is returned, and "undef" for the signature body. The signature separator is the first line of the returned signature body.

     OPTIONS     DESCRIBED IN                   DEFAULT
     result_type Mail::Message::Body::Construct <same as current>
     pattern     Mail::Message::Body::Construct <same as current>
     max_lines   Mail::Message::Body::Construct 10

    * result_type => CLASS
        The type of body to be created for the stripped body (and maybe also to contain the stripped signature)

    * pattern => REGEX|STRING|CODE
        Which pattern defines the line which indicates the separator between the message and the signature. In case of a STRING, this is matched to the beginning of the line, and REGEX is a full regular expression.

        In case of CODE, each line (from last to front) is passed to the specified subroutine as first argument. The subroutine must return TRUE when the separator is found.

        By default, the scan is for the regular expression "qr/^--(\s|$)/".

    * max_lines => INTEGER
        The maximum number of lines which can be the length of a signature, which defaults to 10. Specify "undef" to remove the limit.

    Examples:

     my $stripped = $message->decoded;
     my $stripped = $body->decoded;
     my ($stripped, $signature) = $message->decoded
        ->stripSignature(max_lines => 5, pattern => '-*-*-');

METHODS for extension writers

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.