SimpleX(3pm)						User Contributed Perl Documentation					      SimpleX(3pm)

NAME

       Net::IMAP::SimpleX - Addons for Net::IMAP::Simple

SYNOPSIS

	   use strict;
	   use warnings;
	   use Net::IMAP::SimpleX;

       Net::IMAP::SimpleX uses Net::IMAP::Simple as a base so the object creation is the same as it is for the ancestor:

	   my $imap = Net::IMAP::SimpleX->new('imap.example.com') ||
	      die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr
";

	   $imap->select("INBOX");

       Net::IMAP::SimpleX is a collection of handy methods that are not simple, require Parse::RecDescent, or are experimental.

DESCRIPTION

       This module adds some useful, yet not so simple, extensions on top of Net::IMAP::Simple.

METHODS

       new For details on the invocation, read Net::IMAP::Simple.

       body_summary
	   Typical invocations will take this overall shape.

	       # get an object representation of the message body
	       my $summary = $imap->body_summary($message_number);

	       # multipart message
	       if ($summary->has_parts) {
		   for my $subpart ($summary->parts) {
		       if ($subpart->has_parts) { ... }
		       # examine the message part
		       my @attr = map { $subpart->$_ } qw/content_type encoding encoded_size/;
		       # fetch the raw message part
		       my $subpart_body = $imap->get($message_number, $subpart->part_number);
		   }
	       } else {
		   my $body = $summary->body;
		   my @attr = map { $body->$_ } qw/content_type encoding encoded_size/
	       }

	   This method returns a simple object that contains a representation of the body of a message.  The object is built by a
	   Parse::RecDescent parser using the output of an IMAP fetch body command.  The parser uses the formal syntax as defined by RFC3501
	   http://tools.ietf.org/html/rfc3501#section-9 <http://tools.ietf.org/html/rfc3501#section-9>.

	       my $body = $summary->body;
	       my @attr = map { $body->$_ } qw/
		   content_description
		   encoded_size
		   charset
		   content_type
		   part_number
		   format
		   id
		   encoding
	       /;

	   For multipart messages, the object contains sub-objects for each message part, accessible via the parts() method and inspected via the
	   has_parts() method.	The type method describes the type of multipart (such as mixed or alternative).  The parts method returns a list
	   of sub parts, which themselves may have subparts, and so on.

	   An example of a multipart, alternative message with a text body and an html version of the body would looke something like:

	       if ($summary->has_parts) {
		   if ($summary->type eq 'alternative') {
		       my ($html) = grep { $_->content_type eq 'text/html' } $summary->parts;
		   }
	       }

	   A really complex, multipart message could look something like this:

	       if ($summary->has_parts && $summary->type eq 'mixed') {

		   for my $part ($summary->parts) {
		       if ($part->has_parts && $part->type eq 'mixed') { ... }
		       ...
		   }

	       }

       fetch
	   The fetch command returns the various parts of messages that users request.	It is fairly complicated (following RFC3501 using a
	   grammar/parser), but there are some basic patterns that it follows.

	       my $res	=$imap->fetch('30:32' => 'UID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS')
	       # $res = {
	       #   30 => {
	       #	   "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 -0400

",
	       #	   "FLAGS" => ["\Flagged", "\Seen"],
	       #	   "UID" => 58890,
	       #	 },
	       #   31 => {
	       #	   "BODY[HEADER.FIELDS (DATE)]" => "Date: Wed, 21 Jul 2010 09:09:04 -0400

",
	       #	   "FLAGS" => ["\Seen"],
	       #	   "UID" => 58891,
	       #	 },
	       #   32 => {
	       #	   "BODY[HEADER.FIELDS (DATE)]" => "Date: Sat, 24 Jul 2010 05:12:06 -0700

",
	       #	   "FLAGS" => ["\Seen"],
	       #	   "UID" => 58892,
	       #	 },
	       # }

	   So-called "parenthized" lists will be returned as an array (see "FLAGS") but nearly everything else will come back as strings.  This
	   includes parenthized queries.  Take "BODY.PEAK[HEADER.FIELDS (DATE FROM SUBJECT)]"), for example.  The result would come back as the
	   RFC822 header lines (as the above "Date: Sun, ..." has done).

	   For more information about the different types of queries, see RFC3501.  There's a surprising number of things that can be queried.

       uidfetch
	   This is roughly the same thing as the "fetch()" method above, but the query runs on UIDs instead of sequence numbers.  The keys of the
	   $res are still the sequence numbers though.

	       my $res	=$imap->fetch('58890' => 'UID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS')
	       # $res = {
	       #   30 => {
	       #	   "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 -0400

",
	       #	   "FLAGS" => ["\Flagged", "\Seen"],
	       #	   "UID" => 58890,
	       #	 },
	       #   ...

AUTHOR

       INITIAL AUTHOR
	   Jason Woodward "<woodwardj@jaos.org>"

       ADDITIONAL CONTRIBUTIONS
	   Paul Miller "<jettero@cpan.org>"  [fetch()]

COPYRIGHT

       Copyright (c) 2010 Jason Woodward

       All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

LICENSE

       This module is free software.  You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

       This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of
       merchantability or fitness for a particular purpose.

BUGS

       https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple <https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple>

SEE ALSO

       perl, Net::IMAP::Simple, Parse::RecDescent

perl v5.14.2							    2012-02-11							      SimpleX(3pm)