Class: TMail::Address

Inherits:
Object show all
Includes:
StrategyInterface, TextUtils
Defined in:
lib/tmail/address.rb,
lib/tmail/obsolete.rb

Overview

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 <[email protected]>')
#=> #<TMail::Address [email protected]>
email.address
#=> "[email protected]"
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"

Constant Summary

Constants included from TextUtils

TextUtils::ATOM_UNSAFE, TextUtils::CONTROL_CHAR, TextUtils::MESSAGE_ID, TextUtils::MIME_ENCODED, TextUtils::MONTH, TextUtils::NKF_FLAGS, TextUtils::PHRASE_UNSAFE, TextUtils::RFC2231_ENCODED, TextUtils::TOKEN_UNSAFE, TextUtils::WDAY, TextUtils::ZONESTR_TABLE

Class Method Summary collapse

Instance Method Summary collapse

Methods included from StrategyInterface

#accept_strategy, create_dest, #decoded, #encoded

Methods included from TextUtils

#atom_safe?, #decode_RFC2231, #decode_params, #join_domain, #message_id?, #mime_encoded?, #quote_atom, #quote_boundary, #quote_phrase, #quote_token, #quote_unquoted_bencode, #quote_unquoted_name, #time2str, #timezone_string_to_unixtime, #to_kcode, #token_safe?, #unquote

Constructor Details

#initialize(local, domain) ⇒ Address

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 [email protected]>"



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# 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

Class Method Details

.parse(str) ⇒ Object

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



83
84
85
 
# File 'lib/tmail/address.rb', line 83

def Address.parse( str )
  Parser.parse :ADDRESS, str
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

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

For Example

addr1 = TMail::Address.parse("My Address <[email protected]>")
#=> "#<TMail::Address [email protected]>"
addr2 = TMail::Address.parse("Another <[email protected]>")
#=> "#<TMail::Address [email protected]>"
addr1 == addr2
#=> true



238
239
240
 
# File 'lib/tmail/address.rb', line 238

def ==( other )
  other.respond_to? :spec and self.spec == other.spec
end

#accept(strategy, dummy1 = nil, dummy2 = nil) ⇒ Object

:nodoc:



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/tmail/address.rb', line 269

def accept( strategy, dummy1 = nil, dummy2 = nil ) #:nodoc:
  unless @local
    strategy.meta '<>'   # empty return-path
    return
  end

  spec_p = (not @name and @routes.empty?)
  if @name
    strategy.phrase @name
    strategy.space
  end
  tmp = spec_p ? '' : '<'
  unless @routes.empty?
    tmp << @routes.map {|i| '@' + i }.join(',') << ':'
  end
  tmp << self.spec
  tmp << '>' unless spec_p
  strategy.meta tmp
  strategy.lwsp ''
end

#address_group? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/tmail/address.rb', line 87

def address_group? #:nodoc:
  false
end

#domain ⇒ Object

Returns the domain part of the email address

For Example:

email = TMail::Address.parse("[email protected]")
email.local
#=> "lindsaar.net"



203
204
205
206
 
# File 'lib/tmail/address.rb', line 203

def domain
  return nil unless @domain
  join_domain(@domain)
end

#dup ⇒ Object

Duplicates a TMail::Address object returning the duplicate

addr1 = TMail::Address.parse("[email protected]")
addr2 = addr1.dup
addr1.id == addr2.id
#=> false



260
261
262
263
264
265
 
# 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

#hash ⇒ Object

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

email = TMail::Address.parse("[email protected]")
email.hash
#=> 18767598



250
251
252
 
# File 'lib/tmail/address.rb', line 250

def hash
  @local.hash ^ @domain.hash
end

#inspect ⇒ Object

:nodoc:



174
175
176
 
# File 'lib/tmail/address.rb', line 174

def inspect #:nodoc:
  "#<#{self.class} #{address()}>"
end

#local ⇒ Object

Returns the local part of the email address

For Example:

email = TMail::Address.parse("[email protected]")
email.local
#=> "mikel"



185
186
187
188
189
190
191
192
193
194
 
# 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 ⇒ Object Also known as: phrase

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

For Example:

email = TMail::Address.parse("Mikel Lindsaar <[email protected]>")
email.name
#=> "Mikel Lindsaar"



131
132
133
 
# File 'lib/tmail/address.rb', line 131

def name
  @name
end

#name=(str) ⇒ Object Also known as: phrase=

Setter method for the name or phrase of the email

For Example:

email = TMail::Address.parse("[email protected]")
email.name
#=> nil
email.name = "Mikel Lindsaar"
email.to_s
#=> "Mikel Lindsaar <[email protected]>"



145
146
147
148
 
# File 'lib/tmail/address.rb', line 145

def name=( str )
  @name = str
  @name = nil if str and str.empty?
end

#routes ⇒ Object Also known as: route

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:[email protected]>")
=> #<TMail::Address [email protected]>
email.to_s
=> "<@sa,@another:[email protected]>"
email.routes
=> ["sa", "another"]



170
171
172
 
# File 'lib/tmail/address.rb', line 170

def routes
  @routes
end

#spec ⇒ Object Also known as: address, addr

Returns the full specific address itself

For Example:

email = TMail::Address.parse("[email protected]")
email.address
#=> "[email protected]"



215
216
217
218
219
220
221
222
223
 
# 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

#spec=(str) ⇒ Object Also known as: addr=, address= 



90
91
92
 
# File 'lib/tmail/obsolete.rb', line 90

def spec=( str ) 
  @local, @domain = str.split(/@/,2).map {|s| s.split(/\./) }
end