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

FreeBSD Manual Pages

  
 
  

home | help
Email::Address(3)     User Contributed Perl Documentation    Email::Address(3)

NAME
       Email::Address -	RFC 2822 Address Parsing and Creation

VERSION
       version 1.908

SYNOPSIS
	 use Email::Address;

	 my @addresses = Email::Address->parse($line);
	 my $address   = Email::Address->new(Casey => 'casey@localhost');

	 print $address->format;

DESCRIPTION
       This class implements a regex-based RFC 2822 parser that	locates	email
       addresses in strings and	returns	a list of "Email::Address" objects
       found.  Alternatively you may construct objects manually. The goal of
       this software is	to be correct, and very	very fast.

   Package Variables
       ACHTUNG!	 Email isn't easy (if even possible) to	parse with a regex, at
       least if	you're on a "perl" prior to 5.10.0.  Providing regular
       expressions for use by other programs isn't a great idea, because it
       makes it	hard to	improve	the parser without breaking the	"it's a	regex"
       feature.	 Using these regular expressions is not	encouraged, and
       methods like "Email::Address->is_addr_spec" should be provided in the
       future.

       Several regular expressions used	in this	package	are useful to others.
       For convenience,	these variables	are declared as	package	variables that
       you may access from your	program.

       These regular expressions conform to the	rules specified	in RFC 2822.

       You can access these variables using the	full namespace.	If you want
       short names, define them	yourself.

	 my $addr_spec = $Email::Address::addr_spec;

       $Email::Address::addr_spec
	   This	regular	expression defined what	an email address is allowed to
	   look	like.

       $Email::Address::angle_addr
	   This	regular	expression defines an $addr_spec wrapped in angle
	   brackets.

       $Email::Address::name_addr
	   This	regular	expression defines what	an email address can look like
	   with	an optional preceding display name, also known as the
	   "phrase".

       $Email::Address::mailbox
	   This	is the complete	regular	expression defining an RFC 2822	email
	   address with	an optional preceding display name and optional
	   following comment.

   Class Methods
       parse
	     my	@addrs = Email::Address->parse(
	       q[me@local, Casey <me@local>, "Casey" <me@local>	(West)]
	     );

	   This	method returns a list of "Email::Address" objects it finds in
	   the input string.  Please note that it returns a list, and expects
	   that	it may find multiple addresses.	 The behavior in scalar
	   context is undefined.

	   The specification for an email address allows for infinitely
	   nestable comments.  That's nice in theory, but a little over	done.
	   By default this module allows for one (1) level of nested comments.
	   If you think	you need more, modify the
	   $Email::Address::COMMENT_NEST_LEVEL package variable	to allow more.

	     $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep

	   The reason for this hardly-limiting limitation is simple:
	   efficiency.

	   Long	strings	of whitespace can be problematic for this module to
	   parse, a bug	which has not yet been adequately addressed.  The
	   default behavior is now to collapse multiple	spaces into a single
	   space, which	avoids this problem.  To prevent this behavior,	set
	   $Email::Address::COLLAPSE_SPACES to zero.  This variable will go
	   away	when the bug is	resolved properly.

	   In accordance with RFC 822 and its descendants, this	module demands
	   that	email addresses	be ASCII only.	Any non-ASCII content in the
	   parsed addresses will cause the parser to return no results.

       new
	     my	$address = Email::Address->new(undef, 'casey@local');
	     my	$address = Email::Address->new('Casey West', 'casey@local');
	     my	$address = Email::Address->new(undef, 'casey@local', '(Casey)');

	   Constructs and returns a new	"Email::Address" object. Takes four
	   positional arguments: phrase, email,	and comment, and original
	   string.

	   The original	string should only really be set using "parse".

       purge_cache
	     Email::Address->purge_cache;

	   One way this	module stays fast is with internal caches. Caches live
	   in memory and there is the remote possibility that you will have a
	   memory problem. On the off chance that you think you're one of
	   those people, this class method will	empty those caches.

	   I've	loaded over 12000 objects and not encountered a	memory
	   problem.

       disable_cache
       enable_cache
	     Email::Address->disable_cache if memory_low();

	   If you'd rather not cache address parses at all, you	can disable
	   (and	re-enable) the Email::Address cache with these methods.	 The
	   cache is enabled by default.

   Instance Methods
       phrase
	     my	$phrase	= $address->phrase;
	     $address->phrase( "Me oh my" );

	   Accessor and	mutator	for the	phrase portion of an address.

       address
	     my	$addr =	$address->address;
	     $addr->address( "me@PROTECTED.com"	);

	   Accessor and	mutator	for the	address	portion	of an address.

       comment
	     my	$comment = $address->comment;
	     $address->comment(	"(Work address)" );

	   Accessor and	mutator	for the	comment	portion	of an address.

       original
	     my	$orig =	$address->original;

	   Accessor for	the original address found when	parsing, or passed to
	   "new".

       host
	     my	$host =	$address->host;

	   Accessor for	the host portion of an address's address.

       user
	     my	$user =	$address->user;

	   Accessor for	the user portion of an address's address.

       format
	     my	$printable = $address->format;

	   Returns a properly formatted	RFC 2822 address representing the
	   object.

       name
	     my	$name =	$address->name;

	   This	method tries very hard to determine the	name belonging to the
	   address.  First the "phrase"	is checked. If that doesn't work out
	   the "comment" is looked into. If that still doesn't work out, the
	   "user" portion of the "address" is returned.

	   This	method does not	try to massage any name	it identifies and
	   instead leaves that up to someone else. Who is it to	decide if
	   someone wants their name capitalized, or if they're Irish?

   Overloaded Operators
       stringify
	     print "I have your	email address, $address.";

	   Objects stringify to	"format" by default. It's possible that	you
	   don't like that idea. Okay, then, you can change it by modifying
	   $Email:Address::STRINGIFY. Please consider modifying	this package
	   variable using "local". You might step on someone else's toes if
	   you don't.

	     {
	       local $Email::Address::STRINGIFY	= 'host';
	       print "I	have your address, $address.";
	       #   geeknest.com
	     }
	     print "I have your	address, $address.";
	     #	 "Casey	West" <casey@geeknest.com>

	   Modifying this package variable is now deprecated. Subclassing is
	   now the recommended approach.

   Did I Mention Fast?
       On his 1.8GHz Apple MacBook, rjbs gets these results:

	 $ perl	-Ilib bench/ea-vs-ma.pl	bench/corpus.txt 5
			  Rate	Mail::Address Email::Address
	 Mail::Address	2.59/s		   --		-44%
	 Email::Address	4.59/s		  77%		  --

	 $ perl	-Ilib bench/ea-vs-ma.pl	bench/corpus.txt 25
			  Rate	Mail::Address Email::Address
	 Mail::Address	2.58/s		   --		-67%
	 Email::Address	7.84/s		 204%		  --

	 $ perl	-Ilib bench/ea-vs-ma.pl	bench/corpus.txt 50
			  Rate	Mail::Address Email::Address
	 Mail::Address	2.57/s		   --		-70%
	 Email::Address	8.53/s		 232%		  --

       ...unfortunately, a known bug causes a loss of speed the	string to
       parse has certain known characteristics,	and disabling cache will also
       degrade performance.

ACKNOWLEDGEMENTS
       Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
       phrase-quoting bugs!

AUTHORS
       o   Casey West

       o   Ricardo SIGNES <rjbs@cpan.org>

CONTRIBUTORS
       o   Alex	Vandiver <alex@chmrr.net>

       o   David Golden	<dagolden@cpan.org>

       o   David Steinbrunner <dsteinbrunner@pobox.com>

       o   Glenn Fowler	<cebjyre@cpan.org>

       o   Ruslan Zakirov <ruz@bestpractical.com>

       o   William Yardley <pep@veggiechinese.net>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2004 by Casey West.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2015-09-20		     Email::Address(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | ACKNOWLEDGEMENTS | AUTHORS | CONTRIBUTORS | COPYRIGHT AND LICENSE

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

home | help