Subversion Repositories sysadmin_scripts

package Mail::IMAPClient::BodyStructure;

#$Id: BodyStructure.pm,v 1.3 2003/06/12 21:41:37 dkernen Exp $

#use Parse::RecDescent;

use Mail::IMAPClient;

use Mail::IMAPClient::BodyStructure::Parse;

use vars qw/$parser/;

use Exporter;

push @ISA, "Exporter";

push @EXPORT_OK , '$parser';

$Mail::IMAPClient::BodyStructure::VERSION = '0.0.2';

# Do it once more to show we mean it!

$Mail::IMAPClient::BodyStructure::VERSION = '0.0.2'; 

$parser = Mail::IMAPClient::BodyStructure::Parse->new()

	or 	die 	"Cannot parse rules: $@\n"	.

			"Try remaking Mail::IMAPClient::BodyStructure::Parse.\n" 

	and 	return undef;

sub new {

	my $class = shift;

	my $bodystructure = shift;

	my $self 		= $parser->start($bodystructure) or return undef;

	$self->{_prefix}	= "";

	if ( exists $self->{bodystructure} ) {

		$self->{_id}	= 'HEAD' ;

	} else {

		$self->{_id}	= 1;

	}

	$self->{_top}		= 1;

	return bless($self ,ref($class)||$class);

}

sub _get_thingy {

	my $thingy = shift;

	my $object = shift||(ref($thingy)?$thingy:undef);

	unless ( defined($object) and ref($object) ) {

		$@ = "No argument passed to $thingy method." 	;

		$^W and print STDERR "$@\n" ;

		return undef;

	}

	unless ( 	"$object" =~ /HASH/ 

		and 	exists($object->{$thingy}) 

	) {

		$@ = 	ref($object) 					.

			" $object does not have " 			. 

			( $thingy =~ /^[aeiou]/i ? "an " : "a " ) 	.

			"${thingy}. " 					.

			( ref($object) =~ /HASH/ ? "It has " . join(", ",keys(%$object)) : "") ; 

		$^W and print STDERR "$@\n" ;

		return undef;

	}

	return Unwrapped($object->{$thingy});

}

BEGIN {

 foreach my $datum (qw/	bodytype bodysubtype 	bodyparms 	bodydisp bodyid

			bodydesc bodyenc 	bodysize 	bodylang 

			envelopestruct  	textlines

		   /

 ) {

        no strict 'refs';

        *$datum = sub { _get_thingy($datum, @_); };

 }

}

sub parts {

	my $self = shift;

	if ( exists $self->{PartsList} )  {

		return wantarray ? @{$self->{PartsList}} : $self->{PartsList} ;

	}

	my @parts = ();

	$self->{PartsList} = \@parts;

	unless ( exists($self->{bodystructure}) ) {

		$self->{PartsIndex}{1} = $self ;

		@parts = ("HEAD",1);

		return wantarray ? @parts : \@parts;

	}

	#@parts = ( 1 );

	#} else {

	foreach my $p ($self->bodystructure()) {

		push @parts, $p->id();

		$self->{PartsIndex}{$p->id()} = $p ;

		if ( uc($p->bodytype()||"") eq "MESSAGE" ) {

			#print "Part $parts[-1] is a ",$p->bodytype,"\n";

			push @parts,$parts[-1] . ".HEAD";

		#} else {

		#	print "Part $parts[-1] is a ",$p->bodytype,"\n";

		}

	}

	#}

	return wantarray ? @parts : \@parts;

}

sub oldbodystructure {

	my $self = shift;

	if ( exists $self->{_bodyparts} ) { 

		return wantarray ? @{$self->{_bodyparts}} : $self->{_bodyparts} ;

	}

	my @bodyparts = ( $self );

	$self->{_id} ||= "HEAD";	# aka "0"

	my $count = 0;

	#print STDERR "Analyzing a ",$self->bodytype, " part which I think is part number ",

	#	$self->{_id},"\n";

	my $dump = Data::Dumper->new( [ $self ] , [ 'bodystructure' ] );

	$dump->Indent(1);

	foreach my $struct (@{$self->{bodystructure}}) {

		$struct->{_prefix} ||= $self->{_prefix} . +$count . "." unless $struct->{_top};	

		$struct->{_id} ||= $self->{_prefix} . $count unless $struct->{_top};

		#if (

		#	uc($struct->bodytype) eq 'MULTIPART' or 	

		#	uc($struct->bodytype) eq 'MESSAGE'

		#) {

		#} else 	{

		#}

		push @bodyparts, $struct, 

			ref($struct->{bodystructure}) ? $struct->bodystructure : () ;

	}

	$self->{_bodyparts} = \@bodyparts ;

	return wantarray ? @bodyparts : $self->bodyparts ;

}

sub bodystructure {

	my $self = shift;

	my @parts = ();

	my $partno = 0;

        my $prefix = $self->{_prefix} || "";

	#print STDERR 	"Analyzing a ",($self->bodytype||"unknown ") , 

		#	" part which I think is part number ",

		#	$self->{_id},"\n";

	my $bs = $self;

        $prefix = "$prefix." if ( $prefix and $prefix !~ /\.$/);

	if ( $self->{_top} ) {

		$self->{_id} ||= "HEAD";

		$self->{_prefix} ||= "HEAD";

		$partno = 0;

		for (my $x = 0; $x < scalar(@{$self->{bodystructure}}) ; $x++) {

			$self->{bodystructure}[$x]{_id} = ++$partno ;

			$self->{bodystructure}[$x]{_prefix} = $partno ;

			push @parts, $self->{bodystructure}[$x] , 

				$self->{bodystructure}[$x]->bodystructure;

		}

	} else {

	  $partno = 0;

	  foreach my $p ( @{$self->{bodystructure}}  ) {

		$partno++;

		if (

			! exists $p->{_prefix}  

		) {

			$p->{_prefix} = "$prefix$partno";

		}

		$p->{_prefix} = "$prefix$partno";

		$p->{_id} ||= "$prefix$partno";

		#my $bt = $p->bodytype;

		#if ($bt eq 'MESSAGE') {

			#$p->{_id} = $prefix . 

			#$partno = 0;

		#} 

		push @parts, $p, $p->{bodystructure} ? $p->bodystructure : ();

	  }

	}

	return wantarray ? @parts : \@parts;

}

sub id {

	my $self = shift;

	return $self->{_id} if exists $self->{_id};

	return "HEAD" if $self->{_top};

	#if ($self->bodytype eq 'MESSAGE') {

	#	return 

	#}

	if ($self->{bodytype} eq 'MULTIPART') {

		my $p = $self->{_id}||$self->{_prefix} ;

		$p =~ s/\.$//;

		return $p;

	} else {

		return $self->{_id} ||= 1;

	}

}

sub Unwrapped {

	my $unescape = Mail::IMAPClient::Unescape(@_);

	$unescape =~ s/^"(.*)"$/$1/ if defined($unescape);

	return $unescape;

}

package Mail::IMAPClient::BodyStructure::Part;

@ISA = qw/Mail::IMAPClient::BodyStructure/;

package Mail::IMAPClient::BodyStructure::Envelope;

@ISA = qw/Mail::IMAPClient::BodyStructure/;

sub new {

	my $class = shift;

	my $envelope = shift;

	my $self 		= $Mail::IMAPClient::BodyStructure::parser->envelope($envelope);

	return $self;

}

sub _do_accessor {

  my $datum = shift;

  if (scalar(@_) > 1) {

    return $_[0]->{$datum} = $_[1] ;

  } else {

    return $_[0]->{$datum};

  }

}

# the following for loop sets up accessor methods for 

# the object's address attributes:

sub _mk_address_method {

	my $datum = shift;

	my $method1 = $datum . "_addresses" ;

        no strict 'refs';

        *$method1 = sub { 

		my $self = shift;

		return undef unless ref($self->{$datum}) eq 'ARRAY';

		my @list = map {

			my $pn = $_->personalname ; 

			$pn = "" if $pn eq 'NIL' ;

			( $pn ? "$pn " : "" ) 	. 

			"<"			.

			$_->mailboxname		.

			'@'			.

			$_->hostname		.

			">" 

		} 	@{$self->{$datum}} 	;

		if ( $senderFields{$datum} ) {

			return wantarray ? @list : $list[0] ;

		} else {

			return wantarray ? @list : \@list ;

		}

	};

}

BEGIN {

 for my $datum ( 

	qw( subject inreplyto from messageid bcc date replyto to sender cc )

 ) {

        no strict 'refs';

        *$datum = sub { _do_accessor($datum, @_); };

 }

 my %senderFields = map { ($_ => 1) } qw/from sender replyto/ ;

 for my $datum ( 

	qw( from bcc replyto to sender cc )

 ) {

	_mk_address_method($datum);

 }

}

package Mail::IMAPClient::BodyStructure::Address;

@ISA = qw/Mail::IMAPClient::BodyStructure/;

for my $datum ( 

	qw( personalname mailboxname hostname sourcename )

 ) {

	no strict 'refs';

	*$datum = sub { return $_[0]->{$datum}; };

}

1;

__END__

=head1 NAME

Mail::IMAPClient::BodyStructure - Perl extension to Mail::IMAPClient to facilitate 

the parsing of server responses to the FETCH BODYSTRUCTURE and FETCH ENVELOPE

IMAP client commands.

=head1 SYNOPSIS

  use Mail::IMAPClient::BodyStructure;

  use Mail::IMAPClient;

  my $imap = Mail::IMAPClient->new(Server=>$serv,User=>$usr,Password=>$pwd);

  $imap->select("INBOX") or die "cannot select the inbox for $usr: $@\n";

  my @recent = $imap->search("recent");

  foreach my $new (@recent) {

	my $struct = Mail::IMAPClient::BodyStructure->new(

			$imap->fetch($new,"bodystructure")

	);

	print	"Msg $new (Content-type: ",$struct->bodytype,"/",$struct->bodysubtype,

        	") contains these parts:\n\t",join("\n\t",$struct->parts),"\n\n";

  }

=head1 DESCRIPTION

This extension will parse the result of an IMAP FETCH BODYSTRUCTURE command into a perl 

data structure. It also provides helper methods that will help you pull information out 

of the data structure.

Use of this extension requires Parse::RecDescent. If you don't have Parse::RecDescent 

then you must either get it or refrain from using this module.

=head2 EXPORT

Nothing is exported by default. C<$parser> is exported upon request. C<$parser> 

is the BodyStucture object's Parse::RecDescent object, which you'll probably 

only need for debugging purposes. 

=head1 Class Methods

The following class method is available:

=head2 new

This class method is the constructor method for instantiating new 

Mail::IMAPClient::BodyStructure objects. The B<new> method accepts one argument, 

a string containing a server response to a FETCH BODYSTRUCTURE directive.  

Only one message's body structure should be described in this 

string, although that message may contain an arbitrary number of parts.

If you know the messages sequence number or unique ID (UID) but haven't got its 

body structure, and you want to get the body structure and parse it into a 

B<Mail::IMAPClient::BodyStructure> object, then you might as well save yourself 

some work and use B<Mail::IMAPClient>'s B<get_bodystructure> method, which 

accepts a message sequence number (or UID if I<Uid> is true) and returns a 

B<Mail::IMAPClient::BodyStructure> object. It's functionally equivalent to issuing the 

FETCH BODYSTRUCTURE IMAP client command and then passing the results to 

B<Mail::IMAPClient::BodyStructure>'s B<new> method but it does those things in one 

simple method call.

=head1 Object Methods

The following object methods are available:

=head2 bodytype

The B<bodytype> object method requires no arguments.  

It returns the bodytype for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodysubtype

The B<bodysubtype> object method requires no arguments.  

It returns the bodysubtype for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodyparms

The B<bodyparms> object method requires no arguments.  

It returns the bodyparms for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodydisp

The B<bodydisp> object method requires no arguments.  

It returns the bodydisp for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodyid

The B<bodyid> object method requires no arguments.  

It returns the bodyid for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodydesc

The B<bodydesc> object method requires no arguments.  

It returns the bodydesc for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodyenc

The B<bodyenc> object method requires no arguments.  

It returns the bodyenc for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodysize

The B<bodysize> object method requires no arguments.  

It returns the bodysize for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodylang

The B<bodylang> object method requires no arguments.  

It returns the bodylang for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 bodystructure

The B<bodystructure> object method requires no arguments.  

It returns the bodystructure for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head2 envelopestruct

The B<envelopestruct> object method requires no arguments.  

It returns the envelopestruct for the message whose structure is described by the 

calling B<Mail::IMAPClient::Bodystructure> object. This envelope structure is blessed

into the B<Mail::IMAPClient::BodyStructure::Envelope> subclass, which is explained more

fully below.

=cut

=head2 textlines

The B<textlines> object method requires no arguments.  

It returns the textlines for the message whose structure is described by the calling 

B<Mail::IMAPClient::Bodystructure> object.

=cut

=head1 Envelopes and the Mail::IMAPClient::BodyStructure::Envelope Subclass

The IMAP standard specifies that output from the IMAP B<FETCH ENVELOPE> command 

will be an RFC2060 envelope structure. It further specifies that output from the 

B<FETCH BODYSTRUCTURE> command may also contain embedded envelope structures (if, 

for example, a message's subparts contain one or more included messages). Objects

belonging to B<Mail::IMAPClient::BodyStructure::Envelope> are Perl representations

of these envelope structures, which is to say the nested parenthetical lists of 

RFC2060 translated into a Perl datastructure.

Note that all of the fields relate to the specific part to which they belong. In other

words, output from a FETCH nnnn ENVELOPE command (or, in B<Mail::IMAPClient>,

C<$imap->fetch($msgid,"ENVELOPE")> or C<my $env = $imap->get_envelope($msgid)>) are for

the message, but fields from within a bodystructure relate to the message subpart and 

not the parent message.

An envelope structure's B<Mail::IMAPClient::BodyStructure::Envelope> representation 

is a hash of thingies that looks like this:

{

                     subject => 	"subject",

                     inreplyto =>	"reference_message_id",

                     from => 		[ addressStruct1 ],

                     messageid => 	"message_id",

                     bcc => 		[ addressStruct1, addressStruct2 ],

                     date => 		"Tue, 09 Jul 2002 14:15:53 -0400",

                     replyto => 	[ adressStruct1, addressStruct2 ],

                     to => 		[ adressStruct1, addressStruct2 ],

                     sender => 		[ adressStruct1 ],

                     cc => 		[ adressStruct1, addressStruct2 ],

}

The B<...::Envelope> object also has methods for accessing data in the structure. They

are:

=over 4

=item date

Returns the date of the message.

=item inreplyto

Returns the message id of the message to which this message is a reply.

=item subject

Returns the subject of the message. 

=item messageid

Returns the message id of the message.

=back

You can also use the following methods to get addressing information. Each of these methods

returns an array of B<Mail::IMAPClient::BodyStructure::Address> objects, which are perl 

data structures representing RFC2060 address structures. Some of these arrays would naturally  

contain one element (such as B<from>, which normally contains a single "From:" address); others

will often contain more than one address. However, because RFC2060 defines all of these as "lists

of address structures", they are all translated into arrays of B<...::Address> objects. 

See the section on B<Mail::IMAPClient::BodyStructure::Address>", below, for alternate (and 

preferred) ways of accessing these data.

The methods available are:

=over 4

=item bcc

Returns an array of blind cc'ed recipients' address structures. (Don't expect much in here

unless the message was sent from the mailbox you're poking around in, by the way.)

=item cc

Returns an array of cc'ed recipients' address structures.

=item from

Returns an array of "From:" address structures--usually just one.

=item replyto

Returns an array of "Reply-to:" address structures. Once again there is usually

just one address in the list.

=item sender

Returns an array of senders' address structures--usually just one and usually the same

as B<from>.

=item to

Returns an array of recipients' address structures.

=back

Each of the methods that returns a list of address structures (i.e. a list of 

B<Mail::IMAPClient::BodyStructure::Address> arrays) also has an analagous method

that will return a list of E-Mail addresses instead. The addresses are in the  

format C<personalname E<lt>mailboxname@hostnameE<gt>> (see the section on 

B<Mail::IMAPClient::BodyStructure::Address>, below) However, if the personal name 

is 'NIL' then it is omitted from the address. 

These methods are:

=over 4

=item bcc_addresses

Returns a list (or an array reference if called in scalar context) of blind cc'ed 

recipients' email addresses. (Don't expect much in here unless the message was sent 

from the mailbox you're poking around in, by the way.)

=item cc_addresses

Returns a list of cc'ed recipients' email addresses. If called in a scalar 

context it returns a reference to an array of email addresses.

=item from_addresses

Returns a list of "From:" email addresses.  If called in a scalar context

it returns the first email address in the list. (It's usually a list of just

one anyway.)

=item replyto_addresses

Returns a list of "Reply-to:" email addresses.  If called in a scalar context

it returns the first email address in the list.

=item sender_addresses

Returns a list of senders' email addresses.  If called in a scalar context

it returns the first email address in the list.

=item to_addresses

Returns a list of recipients' email addresses.  If called in a scalar context

it returns a reference to an array of email addresses.

=back

Note that context affects the behavior of all of the above methods. 

Those fields that will commonly contain multiple entries (i.e. they are 

recipients) will return an array reference when called in scalar context. 

You can use this behavior to optimize performance.

Those fields that will commonly contain just one address (the sender's) will 

return the first (and usually only) address. You can use this behavior to 

optimize your development time.

=head1 Addresses and the Mail::IMAPClient::BodyStructure::Address

Several components of an envelope structure are address structures. They are each 

parsed into their own object, B<Mail::IMAPClient::BodyStructure::Address>, which 

looks like this:

	  {

            mailboxname 	=> 'somebody.special',

            hostname 		=> 'somplace.weird.com',

            personalname 	=> 'Somebody Special

            sourceroute 	=> 'NIL'

          } 

RFC2060 specifies that each address component of a bodystructure is a list of 

address structures, so B<Mail::IMAPClient::BodyStructure> parses each of these into

an array of B<Mail::IMAPClient::BodyStructure::Address> objects.

Each of these objects has the following methods available to it:

=over 4

=item mailboxname

Returns the "mailboxname" portion of the address, which is the part to the left 

of the '@' sign.

=item hostname

Returns the "hostname" portion of the address, which is the part to the right of the

'@' sign. 

=item personalname

Returns the "personalname" portion of the address, which is the part of 

the address that's treated like a comment.

=item sourceroute

Returns the "sourceroute" portion of the address, which is typically "NIL".

=back

Taken together, the parts of an address structure form an address that will 

look something like this:

C<personalname E<lt>mailboxname@hostnameE<gt>>

Note that because the B<Mail::IMAPClient::BodyStructure::Address> objects come in 

arrays, it's generally easier to use the methods available to 

B<Mail::IMAPClient::BodyStructure::Envelope> to obtain all of the addresses in a 

particular array in one operation. These methods are provided, however, in case 

you'd rather do things the hard way. (And also because the aforementioned methods

from B<Mail::IMAPClient::BodyStructure::Envelope> need them anyway.)

=cut

=head1 AUTHOR

David J. Kernen

=head1 SEE ALSO

perl(1), Mail::IMAPClient, and RFC2060. See also Parse::RecDescent if you want

to understand the internals of this module.

=cut

# History: 

# $Log: BodyStructure.pm,v $

# Revision 1.3  2003/06/12 21:41:37  dkernen

# Cleaning up cvs repository

#

# Revision 1.1  2003/06/12 21:37:03  dkernen

#

# Preparing 2.2.8

# Added Files: COPYRIGHT

# Modified Files: Parse.grammar

# Added Files: Makefile.old

# 	Makefile.PL Todo sample.perldb

# 	BodyStructure.pm

#

# Revision 1.2  2002/09/26 17:56:14  dkernen

#

# Modified Files:

# BUG_REPORTS Changes IMAPClient.pm INSTALL_perl5.80 MANIFEST

# Makefile.PL for version 2.2.3. See the Changes file for details.

# Modified Files: BodyStructure.pm -- cosmetic changes to pod doc

#

# Revision 1.1  2002/08/30 20:58:51  dkernen

#

# In Mail::IMAPClient/IMAPClient, added files: BUG_REPORTS getGrammer runtest sample.perldb

# In Mail::IMAPClient/IMAPClient/BodyStructure, added files: BodyStructure.pm Makefile.PL debug.ksh runtest

#