Unix/Linux Go Back    


CentOS 7.0 - man page for email::address (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Email::Address(3)	       User Contributed Perl Documentation		Email::Address(3)

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

SYNOPSIS
	 use Email::Address;

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

	 print $address->format;

VERSION
       version 1.898

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 emial 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.

	   The specification for an email address allows for infinitley nestable comments. That's
	   nice in theory, but a little over done.  By default this module allows for two (2)
	   levels 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.

SEE ALSO
       Email::Simple, perl.

AUTHOR
       Originally by Casey West, <casey@geeknest.com>.

       Maintained, 2006-2007, Ricardo SIGNES <rjbs@cpan.org>.

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

COPYRIGHT
       Copyright (c) 2004 Casey West.  All rights reserved.  This module is free software; you
       can redistribute it and/or modify it under the same terms as Perl itself.

perl v5.16.3				    2013-02-07				Email::Address(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:05 AM.