Class TMail::Address
In: lib/tmail/address.rb
Parent: Object

Class Address

Provides a complete handling library for email addresses. Can parse a string of an address directly or take in preformatted addresses themseleves. Allows you to add and remove phrases from the front of the address and provides a compare function for email addresses.

Parsing and Handling a Valid Address:

Just pass the email address in as a string to Address.parse:

 email = TMail::Address.parse('Mikel Lindsaar <mikel@lindsaar.net>)
 #=> #<TMail::Address mikel@lindsaar.net>
 email.address
 #=> "mikel@lindsaar.net"
 email.local
 #=> "mikel"
 email.domain
 #=> "lindsaar.net"
 email.name             # Aliased as phrase as well
 #=> "Mikel Lindsaar"

Detecting an Invalid Address

If you want to check the syntactical validity of an email address, just pass it to Address.parse and catch any SyntaxError:

 begin
   TMail::Mail.parse("mikel   2@@@@@ me .com")
 rescue TMail::SyntaxError
   puts("Invalid Email Address Detected")
 else
   puts("Address is valid")
 end
 #=> "Invalid Email Address Detected"

Methods

==   address   domain   dup   eql?   hash   local   name   name=   new   parse   routes   spec  

Included Modules

TextUtils StrategyInterface

Public Class methods

Address.new(local, domain)

Accepts:

For example:

 Address.new("mikel", ["lindsaar", "net"])
 #=> "#<TMail::Address mikel@lindsaar.net>"

[Source]

# File lib/tmail/address.rb, line 137
    def initialize( local, domain )
      if domain
        domain.each do |s|
          raise SyntaxError, 'empty word in domain' if s.empty?
        end
      end
      
      # This is to catch an unquoted "@" symbol in the local part of the
      # address.  Handles addresses like <"@"@me.com> and makes sure they
      # stay like <"@"@me.com> (previously were becomming <@@me.com>)
      if local && (local.join == '@' || local.join =~ /\A[^"].*?@.*?[^"]\Z/)
        @local = "\"#{local.join}\""
      else
        @local = local
      end

      @domain = domain
      @name   = nil
      @routes = []
    end

Sometimes you need to parse an address, TMail can do it for you and provide you with a fairly robust method of detecting a valid address.

Takes in a string, returns a TMail::Address object.

Raises a TMail::SyntaxError on invalid email format

[Source]

# File lib/tmail/address.rb, line 83
    def Address.parse( str )
      Parser.parse :ADDRESS, special_quote_address(str)
    end

Public Instance methods

Provides == function to the email. Only checks the actual address and ignores the name/phrase component

For Example

 addr1 = TMail::Address.parse("My Address <mikel@lindsaar.net>")
 #=> "#<TMail::Address mikel@lindsaar.net>"
 addr2 = TMail::Address.parse("Another <mikel@lindsaar.net>")
 #=> "#<TMail::Address mikel@lindsaar.net>"
 addr1 == addr2
 #=> true

[Source]

# File lib/tmail/address.rb, line 272
    def ==( other )
      other.respond_to? :spec and self.spec == other.spec
    end
address()

Alias for spec

Returns the domain part of the email address

For Example:

 email = TMail::Address.parse("mikel@lindsaar.net")
 email.local
 #=> "lindsaar.net"

[Source]

# File lib/tmail/address.rb, line 237
    def domain
      return nil unless @domain
      join_domain(@domain)
    end

Duplicates a TMail::Address object returning the duplicate

 addr1 = TMail::Address.parse("mikel@lindsaar.net")
 addr2 = addr1.dup
 addr1.id == addr2.id
 #=> false

[Source]

# File lib/tmail/address.rb, line 294
    def dup
      obj = self.class.new(@local.dup, @domain.dup)
      obj.name = @name.dup if @name
      obj.routes.replace @routes
      obj
    end
eql?( other )

Alias for #==

Provides a unique hash value for this record against the local and domain parts, ignores the name/phrase value

 email = TMail::Address.parse("mikel@lindsaar.net")
 email.hash
 #=> 18767598

[Source]

# File lib/tmail/address.rb, line 284
    def hash
      @local.hash ^ @domain.hash
    end

Returns the local part of the email address

For Example:

 email = TMail::Address.parse("mikel@lindsaar.net")
 email.local
 #=> "mikel"

[Source]

# File lib/tmail/address.rb, line 219
    def local
      return nil unless @local
      return '""' if @local.size == 1 and @local[0].empty?
      # Check to see if it is an array before trying to map it
      if @local.respond_to?(:map)
        @local.map {|i| quote_atom(i) }.join('.')
      else
        quote_atom(@local)
      end
    end

Provides the name or ‘phrase’ of the email address.

For Example:

 email = TMail::Address.parse("Mikel Lindsaar <mikel@lindsaar.net>")
 email.name
 #=> "Mikel Lindsaar"

[Source]

# File lib/tmail/address.rb, line 165
    def name
      @name
    end

Setter method for the name or phrase of the email

For Example:

 email = TMail::Address.parse("mikel@lindsaar.net")
 email.name
 #=> nil
 email.name = "Mikel Lindsaar"
 email.to_s
 #=> "Mikel Lindsaar <mikel@me.com>"

[Source]

# File lib/tmail/address.rb, line 179
    def name=( str )
      @name = str
      @name = nil if str and str.empty?
    end

This is still here from RFC 822, and is now obsolete per RFC2822 Section 4.

"When interpreting addresses, the route portion SHOULD be ignored."

It is still here, so you can access it.

Routes return the route portion at the front of the email address, if any.

For Example:

 email = TMail::Address.parse( "<@sa,@another:Mikel@me.com>")
 => #<TMail::Address Mikel@me.com>
 email.to_s
 => "<@sa,@another:Mikel@me.com>"
 email.routes
 => ["sa", "another"]

[Source]

# File lib/tmail/address.rb, line 204
    def routes
      @routes
    end

Returns the full specific address itself

For Example:

 email = TMail::Address.parse("mikel@lindsaar.net")
 email.address
 #=> "mikel@lindsaar.net"

[Source]

# File lib/tmail/address.rb, line 249
    def spec
      s = self.local
      d = self.domain
      if s and d
        s + '@' + d
      else
        s
      end
    end

[Validate]