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

NAME

       Mail::Field::Received -- mostly RFC822-compliant parser of Received headers

SYNOPSIS

	 use Mail::Field;

	 my $received = Mail::Field->new('Received', $header);
	 my $results = $received->parse_tree();
	 my $parsed_ok = $received->parsed_ok();
	 my $diagnostics = $received->diagnostics();

DESCRIPTION

       Don't use this class directly!  Instead ask Mail::Field for new instances based on the field name!

       Mail::Field::Received provides subroutines for parsing Received headers from e-mails.  It mostly complies with RFC822, but deviates to
       accommodate a number of broken MTAs which are in common use.  It also attempts to extract useful information which MTAs often embed within
       the "(comments)".

       It is a subclass derived from the Mail::Field and Mail::Field::Generic classes.

ROUTINES

       o   debug

	   Returns current debugging level obtained via the "diagnostics" method.  If a parameter is given, the debugging level is changed.  The
	   default level is 3.

       o   diagnose

	     $received->diagnose("foo", "
");

	   Appends stuff to the parser's diagnostics buffer.

       o   diagnostics

	     my $diagnostics = $received->diagnostics();

	   Returns the contents of the parser's diagnostics buffer.

       o   parse

	   The actual parser.  Returns the object (Mail::Field barfs otherwise).

       o   parsed_ok

	     if ($received->parsed_ok()) {
	       ...
	     }

	   Returns true if the parse succeed, or if it failed, but was permitted to fail for some reason, such as encountering evidence of a known
	   broken (non-RFC822-compliant) format mid-parse.

       o   parse_tree

	     my $parse_tree = $received->parse_tree();

	   Returns the actual parse tree, which is where you get all the useful information.  It is returned as a hashref whose keys are strings
	   like `from', `by', `with', `id', `via' etc., corresponding to the components of Received headers as defined by RFC822:

	     received	 =  "Received"	  ":"		 ; one per relay
			       ["from" domain]		 ; sending host
			       ["by"   domain]		 ; receiving host
			       ["via"  atom]		 ; physical path
			      *("with" atom)		 ; link/mail protocol
			       ["id"   msg-id]		 ; receiver msg id
			       ["for"  addr-spec]	 ; initial form
				";"    date-time	 ; time received

	   The corresponding values are more hashrefs which are mini-parse-trees for these individual components.  A typical parse tree looks
	   something like:

	     {
	      'by' => {
		       'domain' => 'host5.hostingcheck.com',
		       'whole' => 'by host5.hostingcheck.com',
		       'comments' => [
				      '(8.9.3/8.9.3)'
				     ],
		      },
	      'date_time' => {
			      'year' => 2000,
			      'week_day' => 'Tue',
			      'minute' => 57,
			      'day_of_year' => '1 Feb',
			      'month_day' => ' 1',
			      'zone' => '-0500',
			      'second' => 18,
			      'hms' => '21:57:18',
			      'date_time' => 'Tue, 1 Feb 2000 21:57:18 -0500',
			      'hour' => 21,
			      'month' => 'Feb',
			      'rest' => '2000 21:57:18 -0500',
			      'whole' => 'Tue, 1 Feb 2000 21:57:18 -0500'
			     },
	      'with' => {
			 'with' => 'ESMTP',
			 'whole' => 'with ESMTP'
			},
	      'from' => {
			 'domain' => 'mediacons.tecc.co.uk',
			 'HELO' => 'tr909.mediaconsult.com',
			 'from' => 'tr909.mediaconsult.com',
			 'address' => '193.128.6.132',
			 'comments' => [
					'(mediacons.tecc.co.uk [193.128.6.132])',
				       ],
			 'whole' => 'from tr909.mediaconsult.com (mediacons.tecc.co.uk [193.128.6.132])
	   '
			},
	      'id' => {
		       'id' => 'VAA24164',
		       'whole' => 'id VAA24164'
		      },
	      'comments' => [
			     '(mediacons.tecc.co.uk [193.128.6.132])',
			     '(8.9.3/8.9.3)'
			    ],
	      'for' => {
			'for' => '<adam@spiers.net>',
			'whole' => 'for <adam@spiers.net>'
		       },
	      'whole' => 'from tr909.mediaconsult.com (mediacons.tecc.co.uk [193.128.6.132]) by host5.hostingcheck.com (8.9.3/8.9.3) with ESMTP id VAA24164 for <adam@spiers.net>; Tue, 1 Feb 2000 21:57:18 -0500'
	     }

BUGS

       Doesn't use Parse::RecDescent, which it maybe should.

       Doesn't offer a `strict RFC822' parsing mode.  To implement that would be a royal pain in the arse, unless we move to Parse::RecDescent.

SEE ALSO

       Mail::Field, Mail::Header

AUTHOR

       Adam Spiers <adam@spiers.net>

LICENSE

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

perl v5.10.1							    2011-02-05							     Received(3pm)