home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / Kubuntu 8.10 / kubuntu-8.10-desktop-i386.iso / casper / filesystem.squashfs / usr / share / perl5 / Mail / Address.pod < prev    next >
Encoding:
Text File  |  2008-04-14  |  3.9 KB  |  185 lines
  1. =head1 NAME
  2.  
  3. Mail::Address - Parse mail addresses
  4.  
  5. =head1 INHERITANCE
  6.  
  7. =head1 SYNOPSIS
  8.  
  9.  use Mail::Address;
  10.  my @addrs = Mail::Address->parse($line);
  11.  
  12.  foreach $addr (@addrs) {
  13.      print $addr->format,"\n";
  14.  }
  15.  
  16. =head1 DESCRIPTION
  17.  
  18. C<Mail::Address> extracts and manipulates email addresses from a message
  19. header.  It cannot be used to extract addresses from some random text.
  20. You can use this module to create RFC822 compliant fields.
  21.  
  22. Although C<Mail::Address> is a very popular subject for books, and is
  23. used in many applications, it does a very poor job on the more complex
  24. message fields.  It does only handle simple address formats (which
  25. covers about 95% of what can be found). Problems are with
  26.  
  27. =over 4
  28.  
  29. =item *
  30.  
  31. no support for address groups, even not with the semi-colon as
  32. separator between addresses;
  33.  
  34. =item *
  35.  
  36. limitted support for escapes in phrases and comments.  There are
  37. cases where it can get wrong; and
  38.  
  39. =item *
  40.  
  41. you have to take care of most escaping when you create an address yourself:
  42. C<Mail::Address> does not do that for you.
  43.  
  44. =back
  45.  
  46. Often requests are made to the maintainers of this code improve this
  47. situation, but this is not a good idea, where it will break zillions
  48. of existing applications.  If you wish for a fully RFC2822 compliant
  49. implementation you may take a look at L<Mail::Message::Field::Full>,
  50. part of MailBox.
  51.  
  52. example: 
  53.  
  54.   my $s = Mail::Message::Field::Full->parse($header);
  55.   # ref $s isa Mail::Message::Field::Addresses;
  56.  
  57.   my @g = $s->groups;          # all groups, at least one
  58.   # ref $g[0] isa Mail::Message::Field::AddrGroup;
  59.   my $ga = $g[0]->addresses;   # group addresses
  60.  
  61.   my @a = $s->addresses;       # all addresses
  62.   # ref $a[0] isa Mail::Message::Field::Address;
  63.  
  64. =head1 METHODS
  65.  
  66. =head2 Constructors
  67.  
  68. Mail::Address-E<gt>B<new>(PHRASE, ADDRESS, [ COMMENT ])
  69.  
  70. =over 4
  71.  
  72. Create a new C<Mail::Address> object which represents an address with the
  73. elements given. In a message these 3 elements would be seen like:
  74.  
  75.  PHRASE <ADDRESS> (COMMENT)
  76.  ADDRESS (COMMENT)
  77.  
  78. example: 
  79.  
  80.  Mail::Address->new("Perl5 Porters", "perl5-porters@africa.nicoh.com");
  81.  
  82. =back
  83.  
  84. $obj-E<gt>B<parse>(LINE)
  85.  
  86. =over 4
  87.  
  88. Parse the given line a return a list of extracted C<Mail::Address> objects.
  89. The line would normally be one taken from a To,Cc or Bcc line in a message
  90.  
  91. example: 
  92.  
  93.  my @addr = Mail::Address->parse($line);
  94.  
  95. =back
  96.  
  97. =head2 Accessors
  98.  
  99. $obj-E<gt>B<address>
  100.  
  101. =over 4
  102.  
  103. Return the address part of the object.
  104.  
  105. =back
  106.  
  107. $obj-E<gt>B<comment>
  108.  
  109. =over 4
  110.  
  111. Return the comment part of the object
  112.  
  113. =back
  114.  
  115. $obj-E<gt>B<format>([ADDRESSes])
  116.  
  117. =over 4
  118.  
  119. Return a string representing the address in a suitable form to be placed
  120. on a C<To>, C<Cc>, or C<Bcc> line of a message.  This method is called on
  121. the first ADDRESS to be used; other specified ADDRESSes will be appended,
  122. separated with commas.
  123.  
  124. =back
  125.  
  126. $obj-E<gt>B<phrase>
  127.  
  128. =over 4
  129.  
  130. Return the phrase part of the object.
  131.  
  132. =back
  133.  
  134. =head2 Smart accessors
  135.  
  136. $obj-E<gt>B<host>
  137.  
  138. =over 4
  139.  
  140. Return the address excluding the user id and '@'
  141.  
  142. =back
  143.  
  144. $obj-E<gt>B<name>
  145.  
  146. =over 4
  147.  
  148. Using the information contained within the object attempt to identify what
  149. the person or groups name is.
  150.  
  151. =back
  152.  
  153. $obj-E<gt>B<user>
  154.  
  155. =over 4
  156.  
  157. Return the address excluding the '@' and the mail domain
  158.  
  159. =back
  160.  
  161. =head1 SEE ALSO
  162.  
  163. This module is part of the MailTools distribution,
  164. F<http://perl.overmeer.net/mailtools/>.
  165.  
  166. =head1 AUTHORS
  167.  
  168. The MailTools bundle was developed by Graham Barr.  Later, Mark
  169. Overmeer took over maintenance without development.
  170.  
  171. Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
  172. Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
  173. Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
  174. For other contributors see ChangeLog.
  175.  
  176. =head1 LICENSE
  177.  
  178. Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
  179. 2001-2007 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
  180.  
  181. This program is free software; you can redistribute it and/or modify it
  182. under the same terms as Perl itself.
  183. See F<http://www.perl.com/perl/misc/Artistic.html>
  184.  
  185.