email_address 0.0.3 → 0.1.0

data/Rakefile

@@ -1,8 +1,5 @@
 require "bundler/gem_tasks"
 
-task :default do
-  sh "ruby test/email_address/*"
-end
 require "bundler/gem_tasks"
 require "bundler/setup"
 require 'rake/testtask'
@@ -10,14 +7,12 @@ require 'rake/testtask'
 task :default => :test
 
 desc "Run the Test Suite, toot suite"
-task :test do
-  sh "find test -name 'test*rb' -exec ruby {} \\;"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/test_*.rb"
 end
 
 desc "Open and IRB Console with the gem loaded"
 task :console do
-  sh "bundle exec irb  -Ilib -I . -r email_address"
-  #require 'irb'
-  #ARGV.clear
-  #IRB.start
+  sh "bundle exec irb  -Ilib -I . -r active_record -r email_address"
 end

data/email_address.gemspec

@@ -8,9 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = EmailAddress::VERSION
   spec.authors       = ["Allen Fair"]
   spec.email         = ["allen.fair@gmail.com"]
-  spec.description   = %q{The EmailAddress library is an _opinionated_ email address handler and
-validator.}
-  spec.summary       = %q{EmailAddress checks on validates an acceptable set of email addresses.}
+  spec.description   = %q{The EmailAddress Gem to work with and validate email addresses.}
+  spec.summary       = %q{This gem provides a ruby language library for working with and validating email addresses. By default, it validates against conventional usage, the format preferred for user email addresses. It can be configured to validate against RFC “Standard” formats, common email service provider formats, and perform DNS validation.}
   spec.homepage      = "https://github.com/afair/email_address"
   spec.license       = "MIT"
 
@@ -19,9 +18,14 @@ validator.}
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "activemodel", "~> 4.2"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest",     "~> 5.8.3"
+  spec.add_development_dependency "bundler",      "~> 1.3"
+  spec.add_development_dependency "activerecord", "~> 5.0.0.beta1"   if RUBY_PLATFORM != 'java'
+  spec.add_development_dependency "activerecord", "~> 4.2.5"         if RUBY_PLATFORM == 'java'
+  spec.add_development_dependency "sqlite3"                          if RUBY_PLATFORM != 'java'
+  spec.add_development_dependency "activerecord-jdbcsqlite3-adapter" if RUBY_PLATFORM == 'java'
+  spec.add_development_dependency "codeclimate-test-reporter"
   spec.add_dependency "simpleidn"
   spec.add_dependency "netaddr"
 end

data/lib/email_address.rb

@@ -1,42 +1,73 @@
-require "email_address/address"
-require "email_address/config"
-require "email_address/domain_matcher"
-require "email_address/domain_parser"
-require "email_address/exchanger"
-require "email_address/host"
-require "email_address/local"
-require "email_address/matcher"
-require "email_address/validator"
-require "email_address/version"
-require "email_address/active_record_validator" if defined?(ActiveModel)
 
 module EmailAddress
 
+  require "email_address/config"
+  require "email_address/exchanger"
+  require "email_address/host"
+  require "email_address/local"
+  require "email_address/address"
+  require "email_address/version"
+  require "email_address/active_record_validator" if defined?(ActiveModel)
+  if defined?(ActiveRecord) && ::ActiveRecord::VERSION::MAJOR >= 5
+    require "email_address/email_address_type"
+    require "email_address/canonical_email_address_type"
+  end
+
   # Creates an instance of this email address.
   # This is a short-cut to Email::Address::Address.new
-  def self.new(email_address)
-    EmailAddress::Address.new(email_address)
+  def self.new(email_address, config={})
+    EmailAddress::Address.new(email_address, config)
+  end
+
+  # Given an email address, this returns true if the email validates, false otherwise
+  def self.valid?(email_address, config={})
+    self.new(email_address, config).valid?
+  end
+
+  # Given an email address, this returns nil if the email validates,
+  # or a string with a small error message otherwise
+  def self.error(email_address, config={})
+    self.new(email_address, config).error
   end
 
-  # Given an email address, this return true if the email validates, false otherwise
-  def self.valid?(email_address, options={})
-    self.new(email_address).valid?(options)
+  # Shortcut to normalize the given email address in the given format
+  def self.normal(email_address, config={})
+    EmailAddress::Address.new(email_address, config).to_s
   end
 
   # Shortcut to normalize the given email address
-  def self.normal(email_address)
-    EmailAddress::Address.new(email_address).normalize
+  def self.redact(email_address, config={})
+    EmailAddress::Address.new(email_address, config).redact
+  end
+
+  # Shortcut to munge the given email address for web publishing
+  # returns ma_____@do_____.com
+  def self.munge(email_address, config={})
+    EmailAddress::Address.new(email_address, config).munge
+  end
+
+  def self.new_redacted(email_address, config={})
+    EmailAddress::Address.new(EmailAddress::Address.new(email_address, config).redact)
+  end
+
+  # Returns the Canonical form of the email address. This form is what should
+  # be considered unique for an email account, lower case, and no address tags.
+  def self.canonical(email_address, config={})
+    EmailAddress::Address.new(email_address, config).canonical
   end
 
-  def self.new_normal(email_address)
-    EmailAddress::Address.new(EmailAddress::Address.new(email_address).normalize)
+  def self.new_canonical(email_address, config={})
+    EmailAddress::Address.new(EmailAddress::Address.new(email_address, config).canonical, config)
   end
 
-  def self.canonical(email_address)
-    EmailAddress::Address.new(email_address).normalize
+  # Returns the Reference form of the email address, defined as the MD5
+  # digest of the Canonical form.
+  def self.reference(email_address, config={})
+    EmailAddress::Address.new(email_address, config).reference
   end
 
-  def self.new_canonical(email_address)
-    EmailAddress::Address.new(EmailAddress::Address.new(email_address).canonical)
+  # Does the email address match any of the given rules
+  def self.matches?(email_address, rules, config={})
+    EmailAddress::Address.new(email_address, config).matches?(rules)
   end
 end

data/lib/email_address/active_record_validator.rb

@@ -8,10 +8,10 @@ module EmailAddress
   #    validates_with EmailAddress::ActiveRecordValidator, field: :name
   #
   # Options:
-  #         field: email,
-  #         fields: [:email1, :email2]
-  # Default field:
-  #         :email or :email_address (first found)
+  # * field: email,
+  # * fields: [:email1, :email2]
+  #
+  # Default field: :email or :email_address (first found)
   #
   class ActiveRecordValidator < ActiveModel::Validator
 
@@ -23,7 +23,7 @@ module EmailAddress
       if @opt[:fields]
         @opt[:fields].each {|f| validate_email(r, f) }
       elsif @opt[:field]
-        validate_email(r, opt[:field])
+        validate_email(r, @opt[:field])
       elsif r.respond_to? :email
         validate_email(r, :email)
       elsif r.respond_to? :email_address

data/lib/email_address/address.rb

@@ -2,116 +2,162 @@ require 'digest/sha1'
 require 'digest/md5'
 
 module EmailAddress
+  # Implements the Email Address container, which hold the Local
+  # (EmailAddress::Local) and Host (Email::AddressHost) parts.
   class Address
     include Comparable
+    attr_accessor :original, :local, :host, :config, :error
+
+    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
 
     # 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.
-    def initialize(email_address)
-      @original     = email_address
-      (local, host) = email_address.split('@', 2)
-      @host         = EmailAddress::Host.new(host)
-      @local        = EmailAddress::Local.new(local||@address, @host)
-    end
-
-    # Returns the Email::Address::Host to inspect the host name of the address
-    def host
-      @host
-    end
-
-    # Returns the EmailAddress::local to inspect the data to the left of the @
-    # Use the #left method to access the full string
-    def local
-      @local
-    end
+    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
+
+    ############################################################################
+    # Local Part (left of @) access
+    # * local: Access full local part instance
+    # * left: everything on the left of @
+    # * mailbox: parsed mailbox or email account name
+    # * tag: address tag (mailbox+tag)
+    ############################################################################
 
     # Everything to the left of the @ in the address, called the local part.
     def left
-      local.to_s
+      self.local.to_s
     end
 
     # 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.
     def mailbox
-      @local.mailbox
-    end
-
-    # Returns the host name, the part to the right of the @ sign.
-    def host_name
-      @host.host_name
+      self.local.mailbox
     end
-    alias :right :host_name
 
     # Returns the tag part of the local address, or nil if not given.
     def tag
-      @local.tag
+      self.local.tag
     end
 
     # 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.
     def comment
-      @local.comment
+      self.local.comment
     end
 
+    ############################################################################
+    # Host Part (right of @) access
+    # * host: Access full local part instance (alias: right)
+    # * hostname: everything on the right of @
+    # * provider: determined email service provider
+    ############################################################################
+
+    # Returns the host name, the part to the right of the @ sign.
+    def host_name
+      @host.host_name
+    end
+    alias :right :host_name
+    alias :hostname :host_name
+
     # Returns the ESP (Email Service Provider) or ISP name derived
     # using the provider configuration rules.
     def provider
       @host.provider
     end
 
-    # Returns the string representation of the normalized email address.
-    def to_s
-      normalize
-    end
+    ############################################################################
+    # Address methods
+    ############################################################################
 
-    # The original email address in the request (unmodified).
-    def original
-      @original
+    # Returns the string representation of the normalized email address.
+    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
+    alias :to_s :normal
 
-    # Returns the normailed email address according to the provider
-    # and system normalization rules. Ususally this downcases the address,
-    # removes spaces and comments, but includes any tags.
-    def normal
-      [@local.normalize, @host.normalize].join('@')
+    def inspect
+      "#<EmailAddress::Address:0x#{self.object_id.to_s(16)} address=\"#{self.to_s}\">"
     end
-    alias :normalize :normal
 
     # 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.
     def canonical
-      [@local.canonical, @host.canonical].join('@')
+      [self.local.canonical, @host.canonical].join('@')
+    end
+
+    # True if the given address is already in it's canonical form.
+    def canonical?
+      self.canonical == self.to_s
+    end
+
+    # Returns the redacted form of the address
+    # This format is defined by this libaray, and may change as usage increases.
+    def redact
+      return self.to_s if self.local.redacted?
+      %Q({#{self.sha1}}@#{self.host.to_s})
+    end
+
+    # True if the address is already in the redacted state.
+    def redacted?
+      self.local.redacted?
+    end
+
+    # Returns the munged form of the address, by default "mailbox@domain.tld"
+    # returns "ma*****@do*****".
+    def munge
+      [self.local.munge, self.host.munge].join("@")
     end
-    alias :uniq :canonical
-    alias :canonicalize :canonical
 
     # 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.
-    def md5
-      Digest::MD5.hexdigest(canonical)
-    end
-
-    def canonical_md5
+    def reference
       Digest::MD5.hexdigest(self.canonical)
     end
+    alias :md5 :reference
 
     # This returns the SHA1 digest (in a hex string) of the canonical email
     # address. See #md5 for more background.
     def sha1
-      Digest::SHA1.hexdigest(canonical)
+      Digest::SHA1.hexdigest(canonical + @config[:sha1_secret])
     end
 
+    #---------------------------------------------------------------------------
+    # Comparisons & Matching
+    #---------------------------------------------------------------------------
+
     # Equal matches the normalized version of each address. Use the Threequal to check
     # for match on canonical or redacted versions of addresses
     def ==(other_email)
-      normalize == other_email.normalize
+      self.to_s == other_email.to_s
     end
     alias :eql? :==
     alias :equal? :==
@@ -119,43 +165,77 @@ module EmailAddress
     # Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison
     # of this addres with another, using the canonical or redacted forms.
     def same_as?(other_email)
-      canonical == other_email.canonical ||
-        redact == other_email.canonical || canonical == other_email.redact
+      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
     alias :include? :same_as?
 
     # Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison
     # of this addres with another, using the normalized form.
     def <=>(other_email)
-      normalize <=> other_email.normalize
+      self.to_s <=> other_email.to_s
     end
 
-    # Redact the address for storage. To protect the user's privacy,
-    # use this when you don't want to store a real email, only a fingerprint.
-    # Given the original address, you can match the original with this method.
-    # This returns the SHA1 of the canonical address (no tags, no gmail dots)
-    # at the original host. The host is part of the digest part, but also
-    # retained for verification and domain maintenance.
-    def redact
-      [sha1, @host.canonical].join('@')
-    end
+    # Address matches one of these Matcher rule patterns
+    def matches?(*rules)
+      rules.flatten!
+      match   = self.local.matches?(rules)
+      match ||= self.host.matches?(rules)
+      return match if match
 
-    def redacted?
-      @local.to_s =~ /\A[0-9a-f]{40}\z/ ? true : false
+      # Does "root@*.com" match "root@example.com" domain name
+      rules.each do |r|
+        if r =~ /.+@.+/
+          return r if File.fnmatch?(r, self.to_s)
+        end
+      end
+      false
     end
 
+    #---------------------------------------------------------------------------
+    # Validation
+    #---------------------------------------------------------------------------
+
     # Returns true if this address is considered valid according to the format
     # configured for its provider, It test the normalized form.
     def valid?(options={})
-      EmailAddress::Validator.validate(self, 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
+
+    def error
+      self.valid? ? nil : @error
     end
 
-    # Returns an array of error messages generated from the validation process via
-    # the #valid? method.
-    def errors(options={})
-      v = EmailAddress::Validator.new(self, options)
-      v.valid?
-      v.errors
-    end
   end
 end