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
RELAXED_REGEX = 
/\A#{::EmailAddress::Local::RELAXED_MAILBOX_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.



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

def initialize(email_address, config={})
  email_address  = 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, @host)
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

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



188
189
190
 
# File 'lib/email_address/address.rb', line 188

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



167
168
169
 
# File 'lib/email_address/address.rb', line 167

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.



113
114
115
116
117
 
# File 'lib/email_address/address.rb', line 113

def canonical
  c = self.local.canonical
  c += "@" + self.host.canonical if self.host.canonical && self.host.canonical > " "
  c
end

#canonical? ⇒ Boolean

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

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/email_address/address.rb', line 120

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.



63
64
65
 
# File 'lib/email_address/address.rb', line 63

def comment
  self.local.comment
end

#error ⇒ Object 



244
245
246
 
# File 'lib/email_address/address.rb', line 244

def error
  self.valid? ? nil : @error
end

#host_name ⇒ Object Also known as: right, hostname

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



75
76
77
 
# File 'lib/email_address/address.rb', line 75

def host_name
  @host.host_name
end

#inspect ⇒ Object 



105
106
107
 
# File 'lib/email_address/address.rb', line 105

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.



44
45
46
 
# File 'lib/email_address/address.rb', line 44

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.



51
52
53
 
# File 'lib/email_address/address.rb', line 51

def mailbox
  self.local.mailbox
end

#matches?(*rules) ⇒ Boolean

Address matches one of these Matcher rule patterns

Returns:

  • (Boolean) 


193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/email_address/address.rb', line 193

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*****”.



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

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.



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

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.



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

def provider
  @host.provider
end

#redact(digest = :sha1) ⇒ Object

Returns the redacted form of the address This format is defined by this libaray, and may change as usage increases. Takes either :sha1 (default) or :md5 as the argument



127
128
129
130
131
132
133
 
# File 'lib/email_address/address.rb', line 127

def redact(digest=:sha1)
  raise "Unknown Digest type: #{digest}" unless %i(sha1 md5).include?(digest)
  return self.to_s if self.local.redacted?
  r = %Q({#{send(digest)}})
  r += "@" + self.host.to_s if self.host.to_s && self.host.to_s > " "
  r
end

#redacted? ⇒ Boolean

True if the address is already in the redacted state.

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/email_address/address.rb', line 136

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.



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

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) 


175
176
177
178
179
180
181
182
183
 
# File 'lib/email_address/address.rb', line 175

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

#set_error(err) ⇒ Object 



239
240
241
242
 
# File 'lib/email_address/address.rb', line 239

def set_error(err)
  @error = EmailAddress::Config.error_messages.fetch(err) { err }
  false
end

#sha1 ⇒ Object

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



157
158
159
 
# File 'lib/email_address/address.rb', line 157

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.



56
57
58
 
# File 'lib/email_address/address.rb', line 56

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) 


214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/email_address/address.rb', line 214

def valid?(options={})
  @error = nil
  unless self.local.valid?
    return set_error :invalid_mailbox
  end
  unless self.host.valid?
    return set_error self.host.error_message
  end
  if @config[:address_size] && !@config[:address_size].include?(self.to_s.size)
    return set_error :exceeds_size
  end
  if @config[:address_validation].is_a?(Proc)
    unless @config[:address_validation].call(self.to_s)
      return set_error :not_allowed
    end
  else
    return false unless self.local.valid?
    return false unless self.host.valid?
  end
  if !@config[:address_local] && !self.hostname.include?(".")
    return set_error :incomplete_domain
  end
  true
end