.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Mail::Message::Body::Construct 3pm"
.TH Mail::Message::Body::Construct 3pm "2016-12-27" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Message::Body::Construct \- adds functionality to Mail::Message::Body
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SH "DESCRIPTION"
.IX Header "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.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructing a body"
.IX Subsection "Constructing a body"
.ie n .IP "$obj\->\fBattach\fR($messages, %options)" 4
.el .IP "\f(CW$obj\fR\->\fBattach\fR($messages, \f(CW%options\fR)" 4
.IX Item "$obj->attach($messages, %options)"
Make a multipart containing this body and the specified \f(CW$messages\fR. The
options are passed to the constructor of the multi-part body.  If you
need more control, create the multi-part body yourself.  At least
take a look at Mail::Message::Body::Multipart.
.Sp
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
\&\fIMail::Message::coerce()\fR.  A new body with attached messages is
returned.
.Sp
example:
.Sp
.Vb 3
\& my $pgpkey = Mail::Message::Body::File\->new(file => \*(Aqa.pgp\*(Aq);
\& my $msg    = Mail::Message\->buildFromBody(
\&    $message\->decoded\->attach($pgpkey));
\&
\& # The last message of the $multi multiparted body becomes a coerced $entity.
\& my $entity  = MIME::Entity\->new;
\& my $multi   = $msg\->body\->attach($entity);
\&
\& # Now create a new message
\& my $msg     = Mail::Message\->new(head => ..., body => $multi);
.Ve
.ie n .IP "$obj\->\fBconcatenate\fR($components)" 4
.el .IP "\f(CW$obj\fR\->\fBconcatenate\fR($components)" 4
.IX Item "$obj->concatenate($components)"
Concatenate a list of elements into one new body.
.Sp
Specify a list of text \f(CW$components\fR.  Each component can be
a message (Mail::Message, the body of the message is used),
a plain body (Mail::Message::Body), 
\&\f(CW\*(C`undef\*(C'\fR (which will be skipped),
a scalar (which is split into lines), or
an array of scalars (each providing one line).
.Sp
example:
.Sp
.Vb 2
\& # all arguments are Mail::Message::Body\*(Aqs.
\& my $sum = $body\->concatenate($preamble, $body, $epilogue, "\-\- \en" , $sig);
.Ve
.ie n .IP "$obj\->\fBforeachLine\fR(\s-1CODE\s0)" 4
.el .IP "\f(CW$obj\fR\->\fBforeachLine\fR(\s-1CODE\s0)" 4
.IX Item "$obj->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.
.Sp
The \s-1CODE\s0 refers to a subroutine which is called, where \f(CW$_\fR contains
body's original line.  \s-1DO NOT CHANGE \s0\f(CW$_\fR!!!  The result of the routine
is taken as new line.  When the routine returns \f(CW\*(C`undef\*(C'\fR, the line will be
skipped.
.Sp
example:
.Sp
.Vb 3
\& my $content  = $msg\->decoded;
\& my $reply    = $content\->foreachLine( sub { \*(Aq> \*(Aq.$_ } );
\& my $rev      = $content\->foreachLine( sub {reverse} );
\&
\& sub filled() { length $_ > 1 ? $_ : undef }
\& my $nonempty = $content\->foreachLine( \e&filled );
\&
\& my $wrong    = $content\->foreachLine( sub {s/a/A/} );  # WRONG!!!
\& my $right    = $content\->foreachLine(
\&        sub {(my $x=$_) =~ s/a/A/; $x} );
.Ve
.ie n .IP "$obj\->\fBstripSignature\fR(%options)" 4
.el .IP "\f(CW$obj\fR\->\fBstripSignature\fR(%options)" 4
.IX Item "$obj->stripSignature(%options)"
Strip the signature from the body.  The body must already be decoded
otherwise the wrong lines may get stripped.  Returned is the stripped
version body, and in list context also the signature, encapsulated in
its own body object.  The signature separator is the first line of the
returned signature body.
.Sp
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.
.Sp
If the body had no signature, the original body object is returned,
and \f(CW\*(C`undef\*(C'\fR for the signature body.
.Sp
.Vb 4
\& \-Option     \-\-Default
\&  max_lines    10
\&  pattern      qr/^\-\-\es?$/
\&  result_type  <same as current>
.Ve
.RS 4
.IP "max_lines => INTEGER|undef" 2
.IX Item "max_lines => INTEGER|undef"
The maximum number of lines which can be the length of a signature.
Specify \f(CW\*(C`undef\*(C'\fR to remove the limit.
.IP "pattern => REGEX|STRING|CODE" 2
.IX Item "pattern => REGEX|STRING|CODE"
Which pattern defines the line which indicates the separator between
the message and the signature.  In case of a \s-1STRING,\s0 this is matched
to the beginning of the line, and \s-1REGEX\s0 is a full regular expression.
.Sp
In case of \s-1CODE,\s0 each line (from last to front) is passed to the
specified subroutine as first argument.  The subroutine must return
\&\s-1TRUE\s0 when the separator is found.
.IP "result_type => \s-1CLASS\s0" 2
.IX Item "result_type => CLASS"
The type of body to be created for the stripped body (and maybe also to
contain the stripped signature)
.RE
.RS 4
.Sp
example:
.Sp
.Vb 2
\& my $start = $message\->decoded;
\& my $start = $body\->decoded;
\&
\& my $stripped = $start\->stripSignature;
\&
\& my ($stripped, $sign) = $start\->stripSignature
\&     (max_lines => 5, pattern => \*(Aq\-*\-*\-\*(Aq);
.Ve
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Mail-Box distribution version 2.120,
built on September 21, 2016. Website: \fIhttp://perl.overmeer.net/mailbox/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2001\-2016 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR