1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Body::Construct - adds functionality to Mail::Message::Body
6
7=head1 SYNOPSIS
8
9=head1 DESCRIPTION
10
11This package adds complex functionality to the L<Mail::Message::Body|Mail::Message::Body>
12class.  This functions less often used, so many programs will not
13compile this package.
14
15=head1 METHODS
16
17=head2 Constructing a body
18
19=over 4
20
21=item $obj-E<gt>B<attach>($messages, %options)
22
23Make a multipart containing this body and the specified $messages. The
24options are passed to the constructor of the multi-part body.  If you
25need more control, create the multi-part body yourself.  At least
26take a look at L<Mail::Message::Body::Multipart|Mail::Message::Body::Multipart>.
27
28The message-parts will be coerced into a L<Mail::Message::Part|Mail::Message::Part>, so you
29may attach L<Mail::Internet|Mail::Internet> or MIME::Entity objects if you want --see
30L<Mail::Message::coerce()|Mail::Message/"Internals">.  A new body with attached messages is
31returned.
32
33example:
34
35 my $pgpkey = Mail::Message::Body::File->new(file => 'a.pgp');
36 my $msg    = Mail::Message->buildFromBody(
37    $message->decoded->attach($pgpkey));
38
39 # The last message of the $multi multiparted body becomes a coerced $entity.
40 my $entity  = MIME::Entity->new;
41 my $multi   = $msg->body->attach($entity);
42
43 # Now create a new message
44 my $msg     = Mail::Message->new(head => ..., body => $multi);
45
46=item $obj-E<gt>B<concatenate>($components)
47
48Concatenate a list of elements into one new body.
49
50Specify a list of text $components.  Each component can be
51a message (L<Mail::Message|Mail::Message>, the body of the message is used),
52a plain body (L<Mail::Message::Body|Mail::Message::Body>),
53C<undef> (which will be skipped),
54a scalar (which is split into lines), or
55an array of scalars (each providing one line).
56
57example:
58
59 # all arguments are Mail::Message::Body's.
60 my $sum = $body->concatenate($preamble, $body, $epilogue, "-- \n" , $sig);
61
62=item $obj-E<gt>B<foreachLine>(CODE)
63
64Create a new body by performing an action on each of its lines.  If none
65of the lines change, the current body will be returned, otherwise a new
66body is created of the same type as the current.
67
68The CODE refers to a subroutine which is called, where C<$_> contains
69body's original line.  DO NOT CHANGE C<$_>!!!  The result of the routine
70is taken as new line.  When the routine returns C<undef>, the line will be
71skipped.
72
73example:
74
75 my $content  = $msg->decoded;
76 my $reply    = $content->foreachLine( sub { '> '.$_ } );
77 my $rev      = $content->foreachLine( sub {reverse} );
78
79 sub filled() { length $_ > 1 ? $_ : undef }
80 my $nonempty = $content->foreachLine( \&filled );
81
82 my $wrong    = $content->foreachLine( sub {s/a/A/} );  # WRONG!!!
83 my $right    = $content->foreachLine(
84        sub {(my $x=$_) =~ s/a/A/; $x} );
85
86=item $obj-E<gt>B<stripSignature>(%options)
87
88Strip the signature from the body.  The body must already be decoded
89otherwise the wrong lines may get stripped.  Returned is the stripped
90version body, and in list context also the signature, encapsulated in
91its own body object.  The signature separator is the first line of the
92returned signature body.
93
94The signature is added by the sender to tell about him- or herself.
95It is superfluous in some situations, for instance if you want to create
96a reply to the person's message you do not need to include that signature.
97
98If the body had no signature, the original body object is returned,
99and C<undef> for the signature body.
100
101 -Option     --Default
102  max_lines    10
103  pattern      qr/^--\s?$/
104  result_type  <same as current>
105
106=over 2
107
108=item max_lines => INTEGER|undef
109
110The maximum number of lines which can be the length of a signature.
111Specify C<undef> to remove the limit.
112
113=item pattern => REGEX|STRING|CODE
114
115Which pattern defines the line which indicates the separator between
116the message and the signature.  In case of a STRING, this is matched
117to the beginning of the line, and REGEX is a full regular expression.
118
119In case of CODE, each line (from last to front) is passed to the
120specified subroutine as first argument.  The subroutine must return
121TRUE when the separator is found.
122
123=item result_type => CLASS
124
125The type of body to be created for the stripped body (and maybe also to
126contain the stripped signature)
127
128=back
129
130example:
131
132 my $start = $message->decoded;
133 my $start = $body->decoded;
134
135 my $stripped = $start->stripSignature;
136
137 my ($stripped, $sign) = $start->stripSignature
138     (max_lines => 5, pattern => '-*-*-');
139
140=back
141
142=head1 SEE ALSO
143
144This module is part of Mail-Message distribution version 3.011,
145built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
146
147=head1 LICENSE
148
149Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
150
151This program is free software; you can redistribute it and/or modify it
152under the same terms as Perl itself.
153See F<http://dev.perl.org/licenses/>
154
155