ch16_02.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

Calls <tt class="literal">die</tt></p>
</dd>


<dt><b><tt class="literal">COERCE</tt></b></dt>
<dd>
Renames headers to <tt class="literal">Mail-From</tt></p>
</dd>


<dt><b><tt class="literal">KEEP</tt></b></dt>
<dd>
Keeps headers as they are</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">FoldLength</tt></b></dt>
<dd>
Value is default line length for folding headers. Mail::Header option.</p>
</dd>

</dl></div>

<a name="INDEX-2147" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>add_signature</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;add_signature([<em class="replaceable">file</em>])
</pre><p><a name="INDEX-2147" />Appends a signature to the
message. <em class="replaceable"><tt>file</tt></em> is a file that contains the
signature; if not specified, the file
<em class="filename">$ENV{HOME}/.signature</em> is checked for a
signature.
</p></div>

<a name="INDEX-2148" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>body</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;body(  )
</pre><p><a name="INDEX-2148" />Returns the body of the message as a
reference to an array. Each entry in the array represents one line of
the message.
</p></div>

<a name="INDEX-2149" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>escape_from</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;escape_from(  )
</pre><p><a name="INDEX-2149" />Inserts a leading
<tt class="literal">&gt;</tt> on any line that starts with <tt class="literal">"From
"</tt> to avoid the problems that some applications have if a
message contains a line starting with <tt class="literal">"From "</tt>.
</p></div>

<a name="INDEX-2150" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>head</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">headobj</em> = $<em class="replaceable">mail</em>-&gt;head(  )
</pre><p><a name="INDEX-2150" />Returns the Mail::Header object that
holds the headers for the current message.
</p></div>

<a name="INDEX-2151" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>nntppost</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;nntppost([<em class="replaceable">options</em>])
</pre><p><a name="INDEX-2151" />Posts an article via NNTP;
requires Net::NNTP. Options are passed as key/value pairs. Available
options are:
</p><dl>
<dt><b><tt class="literal">Debug</tt></b></dt>
<dd>
Debug value to pass to Net::NNTP</p>
</dd>


<dt><b><tt class="literal">Host</tt></b></dt>
<dd>
Name of NNTP server to connect to</p>
</dd>


<dt><b><tt class="literal">Port</tt></b></dt>
<dd>
Port number to connect to on remote host</p>
</dd>

</dl></div>

<a name="INDEX-2152" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>print_header</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">mail</em>-&gt;print_header([\*<em class="replaceable">fd</em>])
$<em class="replaceable">mail</em>-&gt;print_body([\*<em class="replaceable">fd</em>])
$<em class="replaceable"><tt>mail</em>-&gt;print([\*<em class="replaceable">fd</tt></em>])
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-2152" />Prints the header, body, or
whole message to file descriptor
<tt class="literal">\*</tt><em class="emphasis">f</em><em class="replaceable"><tt>d</tt></em>,
which should be a reference to a glob. If the file descriptor is not
given, the output is sent to STDOUT:
</p><blockquote><pre class="code">$mail-&gt;print(\*STDOUT);  # Print message to STDOUT</pre></blockquote></div>

<a name="INDEX-2153" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>remove_sig</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;remove_sig([<em class="replaceable">nlines</em>])
</pre><p><a name="INDEX-2153" />Removes a
user's signature from the body of a message. Looks
for a line equal to <tt class="literal">"-- "</tt> within the last
<em class="replaceable"><tt>nlines</tt></em> lines of the message and removes
that line and all lines after it. <em class="replaceable"><tt>nlines</tt></em>defaults to <tt class="literal">10</tt>.
</p></div>

<a name="INDEX-2154" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>reply</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$reply = $<em class="replaceable">mail</em>-&gt;reply(  )
</pre><p><a name="INDEX-2154" />Creates a new object with
headers initialized for a reply to the current object and with a body
that is an indented copy of the current message.
</p></div>

<a name="INDEX-2155" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>smtpsend</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;smtpsend(  )
</pre><p><a name="INDEX-2155" />Sends the Mail::Internet
message via SMTP to all addresses on the <tt class="literal">To</tt>,
<tt class="literal">Cc</tt>, and <tt class="literal">Bcc</tt> lines. Finds the
SMTP host by trying to connect first to hosts specified in
<tt class="literal">$ENV{SMTPHOSTS}</tt>, then to
<tt class="literal">mailhost</tt>, and then to
<tt class="literal">localhost</tt>.
</p><p>In a future release of Mail::Internet, <tt class="literal">smtpsend</tt>
will be able to take the hostname as a parameter, as
<tt class="literal">nntppost</tt> does.
</p></div>

<a name="INDEX-2156" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>tidy_body</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;tidy_body(  )
</pre><p><a name="INDEX-2156" />Removes all leading and
trailing lines that contain only whitespace from the message body.
</p></div>

<a name="INDEX-2157" /><a name="INDEX-2158" /><a name="INDEX-2159" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>unescape_from</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">mail</em>-&gt;unescape_from(  )
</pre><p><a name="INDEX-2157" />Removes the escaping added by
<tt class="literal">escape_from</tt>.<a name="INDEX-2158" /><a name="INDEX-2159" /> 
</p></div>

</div>
<a name="perlnut2-CHP-16-SECT-2.6" /><div class="sect2">
<h3 class="sect2">16.2.6. Parse Email Addresses with Mail::Address</h3>

<p><a name="INDEX-2160" /><a name="INDEX-2161" /><a name="INDEX-2162" /><a name="INDEX-2163" />Mail::Address parses RFC 822-compliant
mail addresses of the form:
</p>

<blockquote><pre class="code">"Full Name or Phrase" &lt;username@host&gt; (Comment Area)</pre></blockquote>

<p>For example, under RFC 822, an address might be represented as: </p>

<blockquote><pre class="code">"Nathan V. Patwardhan" &lt;[e-mail]&gt; (No Comment)</pre></blockquote>

<p>or: </p>

<blockquote><pre class="code">"Nathan V. Patwardhan" &lt;[e-mail]&gt;</pre></blockquote>

<p>The Mail::Address constructor parses an email address into three
parts based on the categories shown above:
</p>

<blockquote><pre class="code">$addr = Mail::Address-&gt;new("Full Name or Phrase",
                           "username@host",
                           "(Comment Area)");</pre></blockquote>

<p>Mail::Address also outputs portions of the mail address with the
functions <tt class="literal">phrase</tt>, <tt class="literal">address</tt>,
<tt class="literal">comment</tt>, <tt class="literal">format</tt>,
<tt class="literal">name</tt>, <tt class="literal">host</tt>, and
<tt class="literal">user</tt>. The <tt class="literal">phrase</tt>,
<tt class="literal">address</tt>, and <tt class="literal">comment</tt> functions
represent the first, second, and third entities that were passed to
the Mail::Address constructor, in which the <tt class="literal">phrase</tt>
function<a name="INDEX-2164" />:
</p>

<blockquote><pre class="code">print $addr-&gt;phrase( );</pre></blockquote>

<p>outputs: </p>

<blockquote><pre class="code">Nathan V. Patwardhan</pre></blockquote>

<p>the <tt class="literal">address</tt> function: </p>

<blockquote><pre class="code">print $addr-&gt;address( );</pre></blockquote>

<p>outputs: </p>

<blockquote><pre class="code">[e-mail]</pre></blockquote>

<p>and the <tt class="literal">comment</tt> function: </p>

<blockquote><pre class="code">print $addr-&gt;comment( );</pre></blockquote>

<p>outputs: </p>

<blockquote><pre class="code">No Comment</pre></blockquote>

<p><a name="INDEX-2165" /><a name="INDEX-2166" />A real mail address can be
"unmangled," or parsed from its
<em class="emphasis">[e-mail]</em> format, with the
<tt class="literal">user</tt> and <tt class="literal">host</tt> functions. The
<tt class="literal">user</tt> function removes everything starting with the
<tt class="literal">@</tt> to the end of the address, and
<tt class="literal">host</tt> removes everything up to and including the
<tt class="literal">@</tt>. Using the previous example of
<em class="emphasis">[e-mail]</em>, the following line:
</p>

<blockquote><pre class="code">print $addr-&gt;user;</pre></blockquote>

<p>outputs: </p>

<blockquote><pre class="code">nvp</pre></blockquote>

<p>And the following line using the <tt class="literal">host</tt> function: </p>

<blockquote><pre class="code">print $addr-&gt;host;</pre></blockquote>

<p>outputs: </p>

<blockquote><pre class="code">[e-mail]</pre></blockquote>

</div>
<a name="perlnut2-CHP-16-SECT-2.7" /><div class="sect2">
<h3 class="sect2">16.2.7. Mail::Address Reference</h3>


<a name="INDEX-2167" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>new</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">addr</em> = Mail::Address-&gt;new(<em class="replaceable">phrase</em>, <em class="replaceable">address</em>[, <em class="replaceable">comment</em>])
</pre><p><a name="INDEX-2167" />Constructor. Creates new Mail::Address
object representing an address with the specified elements. In a
message, these three elements show up as:
</p><blockquote><pre class="code">phrase &lt;address&gt; (comment)
address (comment)</pre></blockquote></div>

<a name="INDEX-2168" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>parse</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
Mail::Address-&gt;parse(<em class="replaceable">line</em>)
</pre><p><a name="INDEX-2168" />Constructor. Parses the specified line,
usually a <tt class="literal">To</tt>, <tt class="literal">Cc</tt>, or
<tt class="literal">Bcc</tt> line, and returns a list of extracted
Mail::Address objects.
</p></div>

<a name="INDEX-2169" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>address</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" co