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 themselves. 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::Address.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

new( local, domain )

Address.new(local, domain)

Accepts:

- local - Left of the at symbol
- domain - Array of the domain split at the periods.

For example:

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

[Source]

    # File lib/tmail/address.rb, line 103
        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 becoming <@@me.com>)
          if local && (local.join == '@' || local.join =~ /\A[^"].*?@.*?[^"]\Z/)
            @local = "\"#{local.join}\""
          else
            @local = local
          end

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

parse( str )

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, str
        end

### Public Instance methods

==( other )

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 238
        def ==( other )
          other.respond_to? :spec and self.spec == other.spec
        end

address()

Alias for spec

domain()

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 203
        def domain
          return nil unless @domain
          join_domain(@domain)
        end

dup()

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 260
        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 #==

hash()

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 250
        def hash
          @local.hash ^ @domain.hash
        end

local()

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 185
        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

name()

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 131
        def name
          @name
        end

name=( str )

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 145
        def name=( str )
          @name = str
          @name = nil if str and str.empty?
        end

routes()

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 170
        def routes
          @routes
        end

spec()

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 215
        def spec
          s = self.local
          d = self.domain
          if s and d
            s + '@' + d
          else
            s
          end
        end

[Validate]