ch16_02.htm

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

<a name="INDEX-2124" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>message_list</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">folder</em>-&gt;message_list
</pre><p><a name="INDEX-2124" />Returns a list of the message
numbers in the folder, in no specific order. The syntax is:
</p><blockquote><pre class="code">print $folder-&gt;message_list."\n"</pre></blockquote></div>

<a name="INDEX-2125" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>next_labeled_message</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">folder</em>-&gt;next_labeled_message(<em class="replaceable">msg_num</em>, <em class="replaceable">label</em>)
</pre><p><a name="INDEX-2125" />Returns the message number of
the next message in the folder relative to
<em class="replaceable"><tt>msg_number</tt></em> that has the label
<em class="replaceable"><tt>label</tt></em> associated with it, or
<tt class="literal">0</tt> if there is no such message.
</p></div>

<a name="INDEX-2126" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>next_message</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">folder</em>-&gt;next_message([<em class="replaceable">msg_num</em>])
</pre><p><a name="INDEX-2126" />Returns the number of the next
message in the folder relative to <em class="replaceable"><tt>msg_num</tt></em>if it is specified; otherwise, relative to the current message.
Returns <tt class="literal">0</tt> if at end of folder.
</p></div>

<a name="INDEX-2127" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>open</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">folder</em>-&gt;open(<em class="replaceable">foldername</em>)
</pre><p><a name="INDEX-2127" />If you didn't specify
a folder name in the constructor, you need to call the
<tt class="literal">open</tt> method, which takes the folder name as an
argument and opens the folder. Also sets <tt class="literal">readonly</tt>
if the folder is determined to be read-only.
</p></div>

<a name="INDEX-2128" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>pack</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">folder</em>-&gt;pack
</pre><p><a name="INDEX-2128" />For formats that allow message number
sequences to have gaps, renames the files in the folders to eliminate
any such gaps. May result in renumbering some messages.
</p></div>

<a name="INDEX-2129" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>prev_labeled_message</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">folder</em>-&gt;prev_labeled_message(<em class="replaceable">msg_num</em>, <em class="replaceable">label</em>)
</pre><p><a name="INDEX-2129" />Returns the message number of
the previous message in the folder relative to
<em class="replaceable"><tt>msg_num</tt></em> that has the label
<em class="replaceable"><tt>label</tt></em> associated with it, or
<tt class="literal">0</tt> if there is no such message.
</p></div>

<a name="INDEX-2130" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>prev_message</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">folder</em>-&gt;prev_message([<em class="replaceable">msg_num</em>])
</pre><p><a name="INDEX-2130" />Returns the number of the
previous message in the folder relative to
<em class="replaceable"><tt>msg_num</tt></em> if it is specified; otherwise,
relative to the current message. Returns <tt class="literal">0</tt> if at
the beginning of the folder.
</p></div>

<a name="INDEX-2131" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>qty</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">folder</em>-&gt;qty
</pre><p><a name="INDEX-2131" />Returns the number of messages
in the folder. The syntax is:
</p><blockquote><pre class="code">print "There are ".$folder-&gt;qty." messages in your 
folder\n";</pre></blockquote></div>

<a name="INDEX-2132" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>refile</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">folder</em>-&gt;refile(<em class="replaceable">msg_num</em>, \$<em class="replaceable">fldr_ref</em>)
</pre><p><a name="INDEX-2132" />Moves messages between folders.
Takes a message number and folder reference as arguments.
</p></div>

<a name="INDEX-2133" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>select</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">folder</em>-&gt;select(\$<em class="replaceable">func_ref</em>)
</pre><p><a name="INDEX-2133" />Returns a list of messages that meet a
set of criteria. The argument,
<tt class="literal">\$</tt><em class="replaceable"><tt>func_ref</tt></em>, is a
reference to a function used to determine the criteria. The function
is passed a reference to a Mail::Internet object containing only a
header. The list is returned in no specific order.
</p></div>

<a name="INDEX-2134" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>select_label</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">folder</em>-&gt;select_label(<em class="replaceable">label</em>)
</pre><p><a name="INDEX-2134" />Returns a list of messages with
the label <em class="replaceable"><tt>label</tt></em>. If called in scalar
context, returns the number of messages that have the label.
</p></div>

<a name="INDEX-2135" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>set_option</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">folder</em>-&gt;set_option(<em class="replaceable">option</em>, <em class="replaceable">value</em>)
</pre><p><a name="INDEX-2135" />Sets the specified option to
<em class="replaceable"><tt>value</tt></em>.
</p></div>

<a name="INDEX-2136" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>set_readonly</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">folder</em>-&gt;set_readonly
</pre><p><a name="INDEX-2136" />Sets the
<tt class="literal">readonly</tt> attribute for the folder. Once
<tt class="literal">readonly</tt> has been set, <tt class="literal">sync</tt>
won't perform any updates to the actual folder.
</p></div>

<a name="INDEX-2137" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>sort</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">folder</em>-&gt;sort(\$<em class="replaceable">func_ref</em>)
</pre><p><a name="INDEX-2137" />Returns a sorted list of messages.
<tt class="literal">\$</tt><em class="replaceable"><tt>func_ref</tt></em> is a
reference to a function that is passed two Mail::Header message
references and returns an integer less than, equal to, or greater
than 0 to indicate the sort order.
</p></div>

<a name="INDEX-2138" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>sync</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">folder</em>-&gt;sync
</pre><p><a name="INDEX-2138" />Synchronizes the folder
with internal data structures and reads in any new messages since the
last <tt class="literal">open</tt> or <tt class="literal">sync</tt>. Does not
perform any updates if the <tt class="literal">readonly</tt> attribute has
been set.
</p></div>

<a name="INDEX-2139" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>undelete_message</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">folder</em>-&gt;undelete_message(<em class="replaceable">msgs</em>)
</pre><p><a name="INDEX-2139" />Unmarks a list of messages,
<em class="replaceable"><tt>msgs</tt></em>, that have been marked for deletion.
</p></div>

<a name="INDEX-2140" /><a name="INDEX-2141" /><a name="INDEX-2142" /><a name="INDEX-2143" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>update_message</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">folder</em>-&gt;update_message(<em class="replaceable">msg_num</em>, \$<em class="replaceable">mref</em>)
</pre><p><a name="INDEX-2140" />Replaces the message specified
by <em class="replaceable"><tt>msg_num</tt></em> with the contents of the
message given by
<tt class="literal">\$</tt><em class="replaceable"><tt>mref</tt></em>, which is a
reference to a Mail::Internet object.<a name="INDEX-2141" /><a name="INDEX-2142" /><a name="INDEX-2143" />
</p></div>

</div>
<a name="perlnut2-CHP-16-SECT-2.4" /><div class="sect2">
<h3 class="sect2">16.2.4. Handle Messages with Mail::Internet</h3>

<p><a name="INDEX-2144" /><a name="INDEX-2145" />Mail::Internet implements a number of
helpful functions for manipulating a mail message. These include
<tt class="literal">body</tt>, <tt class="literal">print_header</tt>, and
<tt class="literal">head</tt>. Mail::Internet is built on top of
Mail::Header, which parses the header of an email message, and it
inherits the Mail::Header constructor style that requires that a file
descriptor or reference to an array be used. For example:
</p>

<blockquote><pre class="code">@lines = &lt;STDIN&gt;;
$mi_obj = new Mail::Internet([@lines]);</pre></blockquote>

<p>reads a mail message from STDIN (using a reference to an array). The
following example reads a mail message from a filehandle, FILE:
</p>

<blockquote><pre class="code">open(FILE, "/home/nvp/Mail/nvp");
$mi_obj = new Mail::Internet(\*FILE);
close(FILE);</pre></blockquote>

<p>The <tt class="literal">print_header</tt> function outputs the header of a
message to a file descriptor; the default is STDOUT:
</p>

<blockquote><pre class="code">open(FILE, "/home/nvp/Mail/nvp");
$mi_obj = new Mail::Internet(\*FILE);
close(FILE);
$mi_obj-&gt;print_header(\*STDOUT);</pre></blockquote>

<p>The above example might output: </p>

<blockquote><pre class="code">From nvp Mon Jun  9 00:11:10 1997
Received: (from nvp@localhost) by mail.somename.com (8.8/8.8) id
    AAA03248 for nvp; Mon, 9 Jun 1997 00:11:09 -0500 (EST)
Date: Mon, 9 Jun 1997 00:11:09 -0500 (EST)
From: "Nathan V. Patwardhan" &lt;nvp&gt;
Message-Id: &lt;[e-mail]&gt;
To: nvp
Subject: pop test
X-Status:
X-Uid: 1
Status: RO</pre></blockquote>

<p>in which <tt class="literal">print_body</tt> also takes a file descriptor
as an argument, but outputs only the body of the message, whereas the
<tt class="literal">print</tt> function outputs an entire message.
</p>

</div>
<a name="perlnut2-CHP-16-SECT-2.5" /><div class="sect2">
<h3 class="sect2">16.2.5. Mail::Internet Reference</h3>


<a name="INDEX-2146" /><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">mail</em> = new Mail::Internet ([<em class="replaceable">arg</em>], [<em class="replaceable">options</em>])
</pre><p><a name="INDEX-2146" />Creates a new Mail::Internet object.
<em class="replaceable"><tt>arg</tt></em> is optional and may be either a file
descriptor (a reference to a glob) or a reference to an array. If
present, the new object is initialized with headers either from the
array or read from the file descriptor.
<em class="replaceable"><tt>options</tt></em> is a list of options in the form
of key/value pairs. Possible options are:
</p><dl>
<dt><b><tt class="literal">Header</tt></b></dt>
<dd>
Mail::Internet should not attempt to read a mail header from
<em class="replaceable"><tt>arg</tt></em>, if it was specified. Value is a
Mail::Header object.
</p>
</dd>


<dt><b><tt class="literal">Body</tt></b></dt>
<dd>
Mail::Internet should attempt to read the body from
<em class="replaceable"><tt>arg</tt></em>, if it was specified. Value is a
reference to an array that contains the lines of the message body.
</p>
</dd>


<dt><b><tt class="literal">Modify</tt></b></dt>
<dd>
Reformats the headers if true. Mail::Header option.</p>
</dd>


<dt><b><tt class="literal">MailFrom</tt></b></dt>
<dd>
Specifies behavior for headers in the form <tt class="literal">"From</tt>
". Mail::Header option. Possible values are:
</p>

<dl>
<dt><b><tt class="literal">IGNORE</tt></b></dt>
<dd>
Ignores and discards the headers</p>
</dd>


<dt><b><tt class="literal">ERROR</tt></b></dt>
<dd>