Class: TMail::Address

Inherits:
Object show all
Includes:
StrategyInterface, TextUtils
Defined in:
lib/gems/tmail-1.2.3.1/lib/tmail/address.rb,
lib/gems/tmail-1.2.3.1/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 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 <[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::Mail.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, #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]>"



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/gems/tmail-1.2.3.1/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

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/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 83

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

.special_quote_address(str) ⇒ Object

:nodoc:



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 87

def Address.special_quote_address(str) #:nodoc:
  # Takes a string which is an address and adds quotation marks to special
  # edge case methods that the RACC parser can not handle.
  #
  # Right now just handles two edge cases:
  #
  # Full stop as the last character of the display name:
  #   Mikel L. <[email protected]>
  # Returns:
  #   "Mikel L." <[email protected]>
  #
  # Unquoted @ symbol in the display name:
  #   [email protected] <[email protected]>
  # Returns:
  #   "[email protected]" <[email protected]>
  #
  # Any other address not matching these patterns just gets returned as is. 
  case
  # This handles the missing "" in an older version of Apple Mail.app
  # around the display name when the display name contains a '@'
  # like '[email protected] <[email protected]>'
  # Just quotes it to: '"[email protected]" <[email protected]>'
  when str =~ /\A([^"].+@.+[^"])\s(<.*?>)\Z/
    return "\"#{$1}\" #{$2}"
  # This handles cases where 'Mikel A. <[email protected]>' which is a trailing
  # full stop before the address section.  Just quotes it to
  # '"Mikel A. <[email protected]>"
  when str =~ /\A(.*?\.)\s(<.*?>)\Z/
    return "\"#{$1}\" #{$2}"
  else
    str
  end
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



272
273
274
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 272

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

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

:nodoc:



303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 303

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) 


121
122
123
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 121

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"



237
238
239
240
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 237

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



294
295
296
297
298
299
 
# File 'lib/gems/tmail-1.2.3.1/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

#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



284
285
286
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 284

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

#inspect ⇒ Object

:nodoc:



208
209
210
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 208

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"



219
220
221
222
223
224
225
226
227
228
 
# File 'lib/gems/tmail-1.2.3.1/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

#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"



165
166
167
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 165

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]>"



179
180
181
182
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 179

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"]



204
205
206
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 204

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]"



249
250
251
252
253
254
255
256
257
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/address.rb', line 249

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/gems/tmail-1.2.3.1/lib/tmail/obsolete.rb', line 90

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