Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mail::Message::Head(3)User Contributed Perl DocumentatioMail::Message::Head(3)

NAME
       Mail::Message::Head - the header	of one message

INHERITANCE
	Mail::Message::Head
	  is a Mail::Reporter

	Mail::Message::Head is extended	by
	  Mail::Message::Head::Complete
	  Mail::Message::Head::Delayed
	  Mail::Message::Head::Subset

SYNOPSIS
	my $head = Mail::Message::Head->new;
	$head->add('From: me@localhost');
	$head->add(From	=> 'me@localhost');
	$head->add(Mail::Message::Field->new(From => 'me'));
	my $subject = $head->get('subject');
	my @rec	= $head->get('received');
	$head->delete('From');

DESCRIPTION
       "Mail::Message::Head" MIME headers are part of Mail::Message messages,
       which are grouped in Mail::Box folders.

       ATTENTION!!! most functionality about e-mail headers is described in
       Mail::Message::Head::Complete, which is a matured header	object.	 Other
       kinds of	headers	will be	translated to that type	when time comes.

       On this page, the general methods which are available on	any header are
       described.  Read	about differences in the sub-class specific pages.

       Extends "DESCRIPTION" in	Mail::Reporter.

OVERLOADED
       overload: ""
	   (stringifaction) The	header,	when used as string, will format as if
	   Mail::Message::Head::Complete::string() was called, so return a
	   nicely folder full header.  An exception is made for	Carp, which
	   will	get a simplified string	to avoid unreadible messages from
	   "croak" and "confess".

	   example: using a header object as string

	    print $head;     # implicit	stringification	by print
	    $head->print;    # the same

	    print "$head";   # explicit	stringication

       overload: bool
	   When	the header does	not contain any	lines (which is	illegal,
	   according to	the RFCs), false is returned.  In all other cases, a
	   true	value is produced.

METHODS
       Extends "METHODS" in Mail::Reporter.

   Constructors
       Extends "Constructors" in Mail::Reporter.

       Mail::Message::Head->build( [PAIR|$field]-LIST )
	   A fast way to construct a header with many lines.  The PAIRs	are
	   "(name, content)" pairs of the header, but it is also possible to
	   pass	Mail::Message::Field objects.	A
	   Mail::Message::Head::Complete header	is created by simply calling
	   Mail::Message::Head::Complete::build(), and then each field is
	   added.  Double field	names are permitted.

	   example:

	    my $subject	= Mail::Message::Field->new(Subject => 'xyz');

	    my $head = Mail::Message::Head->build
	     ( From	=> 'me@example.com'
	     , To	=> 'you@anywhere.aq'
	     , $subject
	     , Received	=> 'one'
	     , Received	=> 'two'
	     );

	    print ref $head;
	     # -->  Mail::Message::Head::Complete

       Mail::Message::Head->new(%options)
	   Create a new	message	header object.	The object will	store all the
	   fields of a header.	When you get information from the header, it
	   will	be returned to you as Mail::Message::Field objects, although
	   the fields may be stored differently	internally.

	   If you try to instantiate a Mail::Message::Head, you	will
	   automatically be upgraded to	a Mail::Message::Head::Complete	--a
	   full	head.

	    -Option    --Defined in	--Default
	     field_type			  Mail::Message::Field::Fast
	     log	 Mail::Reporter	  'WARNINGS'
	     message			  undef
	     modified			  <false>
	     trace	 Mail::Reporter	  'WARNINGS'

	   field_type => CLASS
	     The type of objects that all the fields will have.	 This must be
	     an	extension of Mail::Message::Field.

	   log => LEVEL
	   message => MESSAGE
	     The MESSAGE where this header belongs to.	Usually, this is not
	     known at creation of the header, but sometimes it is.  If not,
	     call the message()	method later to	set it.

	   modified => BOOLEAN
	   trace => LEVEL

   The header
       $obj->isDelayed()
	   Headers may only be partially read, in which	case they are called
	   delayed.  This method returns true if some header information still
	   needs to be read. Returns false if all header data has been read.
	   Will	never trigger completion.

       $obj->isEmpty()
	   Are there any fields	defined	in the current header?	Be warned that
	   the header will not be loaded for this: delayed headers will	return
	   true	in any case.

       $obj->isModified()
	   Returns whether the header has been modified	after being read.

	   example:

	    if($head->isModified) { ...	}

       $obj->knownNames()
	   Like	Mail::Message::Head::Complete::names(),	but only returns the
	   known header	fields,	which may be less than "names" for header
	   types which are partial.  "names()" will trigger completion,	where
	   "knownNames()" does not.

       $obj->message( [$message] )
	   Get (after setting) the message where this header belongs to.  This
	   does	not trigger completion.

       $obj->modified( [BOOLEAN] )
	   Sets	the modified flag to BOOLEAN.  Without value, the current
	   setting is returned,	but in that case you can better	use
	   isModified().  Changing this	flag will not trigger header
	   completion.

	   example:

	    $head->modified(1);
	    if($head->modified)	{ ... }
	    if($head->isModified) { ...	}

       $obj->orderedFields()
	   Returns the fields ordered the way they were	read or	added.

   Access to the header
       $obj->get( $name, [$index] )
	   Get the data	which is related to the	field with the $name.  The
	   case	of the characters in $name does	not matter.

	   If there is only one	data element defined for the $name, or if
	   there is an $index specified	as the second argument,	only the
	   specified element will be returned. If the field $name matches more
	   than	one header the return value depends on the context. In LIST
	   context, all	values will be returned	in the order they are read. In
	   SCALAR context, only	the last value will be returned.

	   example:

	    my $head = Mail::Message::Head->new;
	    $head->add('Received: abc');
	    $head->add('Received: xyz');
	    $head->add('Subject: greetings');

	    my @rec_list   = $head->get('Received');
	    my $rec_scalar = $head->get('Received');
	    print ",@rec_list,$rec_scalar,"	# ,abc xyz, xyz,
	    print $head->get('Received', 0);	# abc
	    my @sub_list   = $head->get('Subject');
	    my $sub_scalar = $head->get('Subject');
	    print ",@sub_list,$sub_scalar,"	# ,greetings, greetings,

       $obj->study( $name, [$index] )
	   Like	get(), but puts	more effort in understanding the contents of
	   the field.  Mail::Message::Field::study() will be called for	the
	   field with the specified FIELDNAME, which returns
	   Mail::Message::Field::Full objects. In scalar context only the last
	   field with that name	is returned.  When an $index is	specified,
	   that	element	is returned.

   About the body
       $obj->guessBodySize()
	   Try to estimate the size of the body	of this	message, but without
	   parsing the header or body.	The result might be "undef" or a few
	   percent of the real size.  It may even be very far of the real
	   value, that's why this is a guess.

       $obj->isMultipart()
	   Returns whether the body of the related message is a	multipart
	   body.  May trigger completion, when the "Content-Type" field	is not
	   defined.

   Internals
       $obj->addNoRealize($field)
	   Add a field,	like Mail::Message::Head::Complete::add() does,	but
	   avoid the loading of	a possibly partial header.  This method	does
	   not test the	validity of the	argument, nor flag the header as
	   changed.  This does not trigger completion.

       $obj->addOrderedFields($fields)
       $obj->fileLocation()
	   Returns the location	of the header in the file, as a	pair begin and
	   end.	 The begin is the first	byte of	the header.  The end is	the
	   first byte after the	header.

       $obj->load()
	   Be sure that	the header is loaded.  This returns the	loaded header
	   object.

       $obj->moveLocation($distance)
	   Move	the registration of the	header in the file.

       $obj->read($parser)
	   Read	the header information of one message into this	header
	   structure.  This method is called by	the folder object (some
	   Mail::Box sub-class), which passes the $parser as an	argument.

       $obj->setNoRealize($field)
	   Set a field,	but avoid the loading of a possibly partial header as
	   set() does.	This method does not test the validity of the
	   argument, nor flag the header as changed.  This does	not trigger
	   completion.

   Error handling
       Extends "Error handling"	in Mail::Reporter.

       $obj->AUTOLOAD()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->addReport($object)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->defaultTrace( [$level]|[$loglevel,	$tracelevel]|[$level,
       $callback] )
       Mail::Message::Head->defaultTrace( [$level]|[$loglevel,
       $tracelevel]|[$level, $callback]	)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->errors()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->log( [$level, [$strings]] )
       Mail::Message::Head->log( [$level, [$strings]] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->logPriority($level)
       Mail::Message::Head->logPriority($level)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->logSettings()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->notImplemented()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->report( [$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->reportAll(	[$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->trace( [$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->warnings()
	   Inherited, see "Error handling" in Mail::Reporter

   Cleanup
       Extends "Cleanup" in Mail::Reporter.

       $obj->DESTROY()
	   Inherited, see "Cleanup" in Mail::Reporter

DETAILS
   Ordered header fields
       Many Perl implementations make a	big mistake by disturbing the order of
       header fields.  For some	fields (especially the resent groups, see
       Mail::Message::Head::ResentGroup) the order shall be maintained.

       MailBox will keep the order of the fields as they were found in the
       source.	When your add a	new field, it will be added at the end.	 If
       your replace a field with a new value, it will stay in the original
       order.

   Head	class implementation
       The header of a MIME message object contains a set of lines, which are
       called fields (by default represented by	Mail::Message::Field objects).
       Dependent on the	situation, the knowledge about the fields can be in
       one of three situations,	each represented by a sub-class	of this
       module:

       o   Mail::Message::Head::Complete

	   In this case, it is sure that all knowledge about the header	is
	   available.  When you	get() information from the header and it is
	   not there, it will never be there.

       o   Mail::Message::Head::Subset

	   There is no certainty whether all header lines are known (probably
	   not).  This may be caused as	result of reading a fast index file,
	   as described	in Mail::Box::MH::Index.  The object is	automatically
	   transformed into a Mail::Message::Head::Complete when all header
	   lines must be known.

       o   Mail::Message::Head::Partial

	   A partial header is like a subset header: probably the header is
	   incomplete.	The means that you are not sure	whether	a get()	for a
	   field fails because the field is not	a part of the message or that
	   it fails because it is not yet known	to the program.	 Where the
	   subset header knows where to	get the	other fields, the partial
	   header does not know	it.  It	cannot hide its	imperfection.

       o   Mail::Message::Head::Delayed

	   In this case, there is no single field known.  Access to this
	   header will always trigger the loading of the full header.

   Subsets of header fields
       Message headers can be quite large, and therefore MailBox provides
       simplified access to some subsets of information.  You can grab these
       sets of fields together,	create and delete them as group.

       On the moment, the following sets are defined:

       o   Mail::Message::Head::ResentGroup

	   A resent group is a set of fields which is used to log one step in
	   the transmission of the message from	the original sender to the
	   destination.

	   Each	step adds a set	of headers to indicate when the	message	was
	   received and	how it was forwarded (without modification).  These
	   fields are best created using Mail::Message::bounce().

       o   Mail::Message::Head::ListGroup

	   Fields which	are used to administer and log mailing list activity.
	   Mailing list	software has to	play trics with	the original message
	   to be able to get the reply on that message back to the mailing
	   list.  Usually a large number of lines are added.

       o   Mail::Message::Head::SpamGroup

	   A set of fields which contains header fields	which are produced by
	   spam	detection software.  You may want to remove these fields when
	   you store a message for a longer period of time.

DIAGNOSTICS
       Error: Package $package does not	implement $method.
	   Fatal error:	the specific package (or one of	its superclasses) does
	   not implement this method where it should. This message means that
	   some	other related classes do implement this	method however the
	   class at hand does not.  Probably you should	investigate this and
	   probably inform the author of the package.

SEE ALSO
       This module is part of Mail-Message distribution	version	3.009, built
       on February 07, 2020. Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2001-2020 by [Mark Overmeer <markov@cpan.org>]. For other
       contributors see	ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See http://dev.perl.org/licenses/

perl v5.32.0			  2020-02-07		Mail::Message::Head(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | OVERLOADED | METHODS | DETAILS | DIAGNOSTICS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Message::Head&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help