Class: EmailAddress::Address

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/email_address/address.rb

Overview

Implements the Email Address container, which hold the Local (EmailAddress::Local) and Host (Email::AddressHost) parts.

Constant Summary collapse

CONVENTIONAL_REGEX = 
/\A#{::EmailAddress::Local::CONVENTIONAL_MAILBOX_WITHIN}
@#{::EmailAddress::Host::DNS_HOST_REGEX}\z/x
STANDARD_REGEX = 
/\A#{::EmailAddress::Local::STANDARD_LOCAL_WITHIN}
@#{::EmailAddress::Host::DNS_HOST_REGEX}\z/x

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(email_address, config = {}) ⇒ Address

Given an email address of the form “local@hostname”, this sets up the instance, and initializes the address to the “normalized” format of the address. The original string is available in the #original method.



19
20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/email_address/address.rb', line 19

def initialize(email_address, config={})
  email_address.strip! if email_address
  @original      = email_address
  email_address||= ""
  if lh = email_address.match(/(.+)@(.+)/)
    (_, local, host) = lh.to_a
  else
    (local, host)    = [email_address, '']
  end
  @host         = EmailAddress::Host.new(host, config)
  @config       = @host.config
  @local        = EmailAddress::Local.new(local, @config)
end

Instance Attribute Details

#config ⇒ Object

Returns the value of attribute config.



9
10
11
 
# File 'lib/email_address/address.rb', line 9

def config
  @config
end

#error ⇒ Object

Returns the value of attribute error.



9
10
11
 
# File 'lib/email_address/address.rb', line 9

def error
  @error
end

#host ⇒ Object

Returns the value of attribute host.



9
10
11
 
# File 'lib/email_address/address.rb', line 9

def host
  @host
end

#local ⇒ Object

Returns the value of attribute local.



9
10
11
 
# File 'lib/email_address/address.rb', line 9

def local
  @local
end

#original ⇒ Object

Returns the value of attribute original.



9
10
11
 
# File 'lib/email_address/address.rb', line 9

def original
  @original
end

Instance Method Details

#<=>(other_email) ⇒ Object

Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison of this addres with another, using the normalized form.



180
181
182
 
# File 'lib/email_address/address.rb', line 180

def <=>(other_email)
  self.to_s <=> other_email.to_s
end

#==(other_email) ⇒ Object Also known as: eql?, equal?

Equal matches the normalized version of each address. Use the Threequal to check for match on canonical or redacted versions of addresses



159
160
161
 
# File 'lib/email_address/address.rb', line 159

def ==(other_email)
  self.to_s == other_email.to_s
end

#canonical ⇒ Object

Returns the canonical email address according to the provider uniqueness rules. Usually, this downcases the address, removes spaves and comments and tags, and any extraneous part of the address not considered a unique account by the provider.



111
112
113
 
# File 'lib/email_address/address.rb', line 111

def canonical
  [self.local.canonical, @host.canonical].join('@')
end

#canonical? ⇒ Boolean

True if the given address is already in it’s canonical form.

Returns:

  • (Boolean) 


116
117
118
 
# File 'lib/email_address/address.rb', line 116

def canonical?
  self.canonical == self.to_s
end

#comment ⇒ Object

Retuns any comments parsed from the local part of the email address. This is retained for inspection after construction, even if it is removed from the normalized email address.



61
62
63
 
# File 'lib/email_address/address.rb', line 61

def comment
  self.local.comment
end

#host_name ⇒ Object Also known as: right, hostname

Returns the host name, the part to the right of the @ sign.



73
74
75
 
# File 'lib/email_address/address.rb', line 73

def host_name
  @host.host_name
end

#inspect ⇒ Object 



103
104
105
 
# File 'lib/email_address/address.rb', line 103

def inspect
  "#<EmailAddress::Address:0x#{self.object_id.to_s(16)} address=\"#{self.to_s}\">"
end

#left ⇒ Object

Everything to the left of the @ in the address, called the local part.



42
43
44
 
# File 'lib/email_address/address.rb', line 42

def left
  self.local.to_s
end

#mailbox ⇒ Object

Returns the mailbox portion of the local port, with no tags. Usually, this can be considered the user account or role account names. Some systems employ dynamic email addresses which don’t have the same meaning.



49
50
51
 
# File 'lib/email_address/address.rb', line 49

def mailbox
  self.local.mailbox
end

#matches?(*rules) ⇒ Boolean

Address matches one of these Matcher rule patterns

Returns:

  • (Boolean) 


185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/email_address/address.rb', line 185

def matches?(*rules)
  rules.flatten!
  match   = self.local.matches?(rules)
  match ||= self.host.matches?(rules)
  return match if match

  # Does "root@*.com" match "[email protected]" domain name
  rules.each do |r|
    if r =~ /.+@.+/
      return r if File.fnmatch?(r, self.to_s)
    end
  end
  false
end

#munge ⇒ Object

Returns the munged form of the address, by default “[email protected]” returns “ma*****@do*****”.



134
135
136
 
# File 'lib/email_address/address.rb', line 134

def munge
  [self.local.munge, self.host.munge].join("@")
end

#normal ⇒ Object Also known as: to_s

Returns the string representation of the normalized email address.



90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/email_address/address.rb', line 90

def normal
  if !@original
    @original
  elsif self.local.to_s.size == 0
    ""
  elsif self.host.to_s.size == 0
    self.local.to_s
  else
    "#{self.local.to_s}@#{self.host.to_s}"
  end
end

#provider ⇒ Object

Returns the ESP (Email Service Provider) or ISP name derived using the provider configuration rules.



81
82
83
 
# File 'lib/email_address/address.rb', line 81

def provider
  @host.provider
end

#redact ⇒ Object

Returns the redacted form of the address This format is defined by this libaray, and may change as usage increases.



122
123
124
125
 
# File 'lib/email_address/address.rb', line 122

def redact
  return self.to_s if self.local.redacted?
  %Q({#{self.sha1}}@#{self.host.to_s})
end

#redacted? ⇒ Boolean

True if the address is already in the redacted state.

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/email_address/address.rb', line 128

def redacted?
  self.local.redacted?
end

#reference ⇒ Object Also known as: md5

Returns and MD5 of the canonical address form. Some cross-system systems use the email address MD5 instead of the actual address to refer to the same shared user identity without exposing the actual address when it is not known in common.



142
143
144
 
# File 'lib/email_address/address.rb', line 142

def reference
  Digest::MD5.hexdigest(self.canonical)
end

#same_as?(other_email) ⇒ Boolean Also known as: include?

Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison of this addres with another, using the canonical or redacted forms.

Returns:

  • (Boolean) 


167
168
169
170
171
172
173
174
175
 
# File 'lib/email_address/address.rb', line 167

def same_as?(other_email)
  if other_email.is_a?(String)
    other_email = EmailAddress::Address.new(other_email)
  end

  self.canonical   == other_email.canonical ||
    self.redact    == other_email.canonical ||
    self.canonical == other_email.redact
end

#sha1 ⇒ Object

This returns the SHA1 digest (in a hex string) of the canonical email address. See #md5 for more background.



149
150
151
 
# File 'lib/email_address/address.rb', line 149

def sha1
  Digest::SHA1.hexdigest(canonical + @config[:sha1_secret])
end

#tag ⇒ Object

Returns the tag part of the local address, or nil if not given.



54
55
56
 
# File 'lib/email_address/address.rb', line 54

def tag
  self.local.tag
end

#valid?(options = {}) ⇒ Boolean

Returns true if this address is considered valid according to the format configured for its provider, It test the normalized form.

Returns:

  • (Boolean) 


206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/email_address/address.rb', line 206

def valid?(options={})
  self.error = nil
  unless self.local.valid?
    self.error = "Invalid Mailbox"
    return false
  end
  unless self.host.valid?
    self.error = "Invalid Host"
    return false
  end
  if @config[:address_size] && !@config[:address_size].include?(self.to_s.size)
    self.error = "Exceeds size"
    return false
  end
  if @config[:address_validation].is_a?(Proc)
    unless @config[:address_validation].call(self.to_s)
      self.error = "Not allowed"
      return false
    end
  else
    return false unless self.local.valid?
    return false unless self.host.valid?
  end
  if !@config[:address_local] && !self.hostname.include?(".")
    self.error = "Incomplete Domain"
    return false
  end
  true
end