ch16_02.htm

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

<dd>
Not acted on.</p>
</dd>


<dt><b><tt class="literal">seen</tt></b></dt>
<dd>
Message has been viewed by the user. Set by
<tt class="literal">get_message</tt> for any message it has
<tt class="literal">retrieve</tt> d.
</p>
</dd>

</dl></div>

<a name="INDEX-2097" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>append_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;append_message(\$<em class="replaceable">mi_ref</em>)
</pre><p><a name="INDEX-2097" />Adds
message to a folder. Argument is a reference to a Mail::Internet
object.
</p></div>

<a name="INDEX-2098" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>clear_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;clear_label(<em class="replaceable">label</em>)
</pre><p><a name="INDEX-2098" />Deletes the association with
<em class="replaceable"><tt>label</tt></em> for all messages in the folder.
Returns the number of messages for which there was an association.
</p></div>

<a name="INDEX-2099" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>close</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;close
</pre><p><a name="INDEX-2099" />Does any necessary housekeeping and
closes the folder.
</p></div>

<a name="INDEX-2100" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>current_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;current_message([<em class="replaceable">msg_num</em>])
</pre><p><a name="INDEX-2100" />With
no argument, returns the message number of the current message in the
folder. With an argument, sets the current message number for the
folder to <em class="replaceable"><tt>msg_num</tt></em>.
</p></div>

<a name="INDEX-2101" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>debug</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;debug([<em class="replaceable">value</em>])
</pre><p><a name="INDEX-2101" />Sets the level of debugging information
for the object to <em class="replaceable"><tt>value</tt></em>. With no argument,
returns the current debugging level.
</p></div>

<a name="INDEX-2102" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>debug_print</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;debug_print(<em class="replaceable">text</em>)
</pre><p><a name="INDEX-2102" />Prints
<em class="replaceable"><tt>text</tt></em>, plus some additional information, to
STDERR.
</p></div>

<a name="INDEX-2103" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>delete_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;delete_label(<em class="replaceable">msg_num</em>, <em class="replaceable">label</em>)
</pre><p><a name="INDEX-2103" />Deletes the association of
<em class="replaceable"><tt>label</tt></em> with
<em class="replaceable"><tt>msg_num</tt></em>. Returns <tt class="literal">1</tt> on
success and <tt class="literal">0</tt> if there was no association.
</p></div>

<a name="INDEX-2104" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>delete_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;delete_message(<em class="replaceable">msgs</em>)
</pre><p><a name="INDEX-2104" />Takes
a list of messages, <em class="replaceable"><tt>msgs</tt></em>, to be marked for
deletion. The messages aren't actually deleted until
<tt class="literal">sync</tt> is called.
</p></div>

<a name="INDEX-2105" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>dup</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;dup(<em class="replaceable">msg_num</em>, \$<em class="replaceable">folder_ref</em>)
</pre><p><a name="INDEX-2105" />Copies the message specified by
<em class="replaceable"><tt>msg_num</tt></em> to the folder referenced by
<tt class="literal">\$</tt><em class="replaceable"><tt>folder_ref</tt></em>. Like
<tt class="literal">refile</tt>, but doesn't delete the
original message. Generates a fatal error if no folder is currently
open or if the folder doesn't contain message
<em class="replaceable"><tt>msg_num</tt></em>.
</p></div>

<a name="INDEX-2106" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>first_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;first_labeled_message(<em class="replaceable">label</em>)
</pre><p><a name="INDEX-2106" />Returns the message number of
the first message in the folder that has
<em class="replaceable"><tt>label</tt></em> associated with it, or
<tt class="literal">0</tt> if there are none.
</p></div>

<a name="INDEX-2107" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>first_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;first_message
</pre><p><a name="INDEX-2107" />Returns
the message number of the first message in the folder.
</p></div>

<a name="INDEX-2108" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>foldername</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;foldername
</pre><p><a name="INDEX-2108" />Returns the name of the folder
that the object has opened.
</p></div>

<a name="INDEX-2109" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_fields</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;get_fields(<em class="replaceable">msg_num</em>, <em class="replaceable">fields</em>)
</pre><p><a name="INDEX-2109" />Retrieves the fields specified
in the list <em class="replaceable"><tt>fields</tt></em> for message
<em class="replaceable"><tt>msg_num</tt></em>. If called in list context,
returns a list; in scalar context, returns a reference to a list of
the fields. Returns the fields in the same order as they were
specified.
</p></div>

<a name="INDEX-2110" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_header</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;get_header(<em class="replaceable">msg_num</em>)
</pre><p><a name="INDEX-2110" />Extracts a message header;
takes one argument: the message number. Returns a reference to a
Mail::Header object.
</p></div>

<a name="INDEX-2111" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_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;get_message(<em class="replaceable">msg_num</em>)
</pre><p><a name="INDEX-2111" />Takes a message number as
argument and returns a Mail::Internet object reference to that
message, or <tt class="literal">0</tt> on failure.
</p></div>

<a name="INDEX-2112" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_message_file</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;get_message_file(<em class="replaceable">msg_num</em>)
</pre><p><a name="INDEX-2112" />Like
<tt class="literal">get_message</tt>, but returns a filename instead of a
Mail::Internet object reference.
</p></div>

<a name="INDEX-2113" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_mime_header</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;get_mime_header(<em class="replaceable">msg_num</em>)
</pre><p><a name="INDEX-2113" />Works
much like <tt class="literal">get_header</tt>, but returns a reference to a
MIME::Head object instead. Takes one argument, the message number.
</p></div>

<a name="INDEX-2114" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_mime_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;get_mime_message (<em class="replaceable">msg_num</em>[, <em class="replaceable">parserobject</em>][, <em class="replaceable">options</em>])
</pre><p><a name="INDEX-2114" />Returns a MIME::Entity object
for the specified message. Calls <tt class="literal">get_message_file</tt>
to get a message to parse, creates a MIME::Parser object, and uses
that to create the MIME::Entity object. The arguments are:
</p><dl>
<dt><i><em class="replaceable"><tt>msg_num</tt></em></i></dt>
<dd>
The number of the message.</p>
</dd>


<dt><i><em class="replaceable"><tt>parserobject</tt></em></i></dt>
<dd>
If specified, used instead of internally creating a parser object.</p>
</dd>


<dt><i><em class="replaceable"><tt>options</tt></em></i></dt>
<dd>
Maps onto the equivalent MIME::Parser methods. Specified as key/value
pairs, with possible values of: <tt class="literal">output_dir</tt>,
<tt class="literal">output_prefix</tt>, <tt class="literal">output_to_core</tt>.
See the MIME::Parser documentation for details.
</p>
</dd>

</dl></div>

<a name="INDEX-2115" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_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;get_option(<em class="replaceable">option</em>)
</pre><p><a name="INDEX-2115" />Returns the setting for the
specified option, or <tt class="literal">undef</tt> if the option
doesn't exist.
</p></div>

<a name="INDEX-2116" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>inverse_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;inverse_select(\$<em class="replaceable">func_ref</em>)
</pre><p><a name="INDEX-2116" />Returns a list, in no specific
order, of message numbers that do not match 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.
</p></div>

<a name="INDEX-2117" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_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;is_readonly
</pre><p><a name="INDEX-2117" />Returns <tt class="literal">1</tt> if
the folder has the <tt class="literal">readonly</tt> attribute set;
otherwise, returns <tt class="literal">0</tt>.
</p></div>

<a name="INDEX-2118" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>label_exists</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;label_exists(<em class="replaceable">msg_num</em>, <em class="replaceable">label</em>)
</pre><p><a name="INDEX-2118" />Returns <tt class="literal">1</tt> if
<em class="replaceable"><tt>label</tt></em> is associated with message
<em class="replaceable"><tt>msg_num</tt></em>; otherwise, returns
<tt class="literal">0</tt>. 
</p></div>

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

<a name="INDEX-2120" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>last_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;last_message
</pre><p><a name="INDEX-2120" />Returns the message number of
the last message in the folder.
</p></div>

<a name="INDEX-2121" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>list_all_labels</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;list_all_labels
</pre><p><a name="INDEX-2121" />Returns a list, in no specific
order, of all labels associated with messages in the folder. If
called in scalar context, returns the number of labels associated
with the messages.
</p></div>

<a name="INDEX-2122" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>list_labels</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;list_labels(<em class="replaceable">msg_num</em>)
</pre><p><a name="INDEX-2122" />Returns a list, in no specific
order, of all labels associated with
<em class="replaceable"><tt>msg_num</tt></em>. If called in scalar context,
returns the number of labels associated with the message.
</p></div>

<a name="INDEX-2123" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>message_exists</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_exists(<em class="replaceable">msg_num</em>)
</pre><p><a name="INDEX-2123" />Returns <tt class="literal">1</tt> if
a message with the number <em class="replaceable"><tt>msg_num</tt></em> exists
in the folder; otherwise, returns <tt class="literal">0</tt>.
</p></div>