canonical-emails 0.1.0 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e8ad63767c830088daf91f1b1b442a4c2bddc209a4ed720a1b6e493c0b038f55
+  data.tar.gz: ac6f3c6327e206c0f7313c87fcb78a9d74176d42c7042e933ad837ed2abd4a82
+SHA512:
+  metadata.gz: 68b08b165db5f62e1aa2e0c227013279047991cb08cfc607219e3029614423e862e2ae4ffd10c541e9f92df37feb8d4b05ee194d6501f143b6d72eb584b00710
+  data.tar.gz: f1c8199c48581cfbfe6b8b79da5d1784ec6cf8afd7918b9e736f07c74c2520fa8c4c72553ec69a294e5e559cd8fd995ee09ce33022a80fc6fdebff36e1ae2c4a

data/CHANGELOG.md

@@ -1,3 +1,19 @@
-### 0.1.0 (6/22/2013)
+### 0.2.0 (2026-10-20)
+
+* [#15](https://github.com/dblock/canonical-emails/pull/15): Cache canonical model accessors by raw field value and remove `address=` from all canonical address types - [@dblock](https://github.com/dblock).
+* [#14](https://github.com/dblock/canonical-emails/pull/14): Add `as:` for custom canonical email accessor names and optional original-reader overrides - [@dblock](https://github.com/dblock).
+* [#13](https://github.com/dblock/canonical-emails/pull/13): Document and test independent canonical accessors for multiple email fields - [@dblock](https://github.com/dblock).
+* [#12](https://github.com/dblock/canonical-emails/pull/12): Add explicit, case-insensitive provider registration, registry clearing, and an unregistered `TaggedGMail` type that retains plus-tags - [@dblock](https://github.com/dblock).
+* [#11](https://github.com/dblock/canonical-emails/pull/11): Introduce breaking provider-aware `.parse` and `type:` APIs, replace nested provider address classes and transform pipelines, and enforce provider restrictions on address reassignment; see UPGRADING.md - [@dblock](https://github.com/dblock).
+* [#10](https://github.com/dblock/canonical-emails/pull/10): Refactor provider transformations into a shared address subclass with opt-in behavior mixins and document migration in UPGRADING.md - [@dblock](https://github.com/dblock).
+* [#6](https://github.com/dblock/canonical-emails/pull/6): Add release and agent guides and prepare version 0.2.0 - [@dblock](https://github.com/dblock).
+* [#8](https://github.com/dblock/canonical-emails/pull/8): Add Danger checks with danger-changelog - [@dblock](https://github.com/dblock).
+* [#7](https://github.com/dblock/canonical-emails/pull/7): Add line and branch coverage reporting with SimpleCov and Coveralls - [@dblock](https://github.com/dblock).
+* [#5](https://github.com/dblock/canonical-emails/pull/5): Canonicalize Gmail plus-address tags and expose the original `username` and `tag` through `CanonicalEmails::GMail::Address`, adapted from [#3](https://github.com/dblock/canonical-emails/pull/3) - [@jdpopkin](https://github.com/jdpopkin).
+* [#4](https://github.com/dblock/canonical-emails/pull/4): Replace Travis CI with GitHub Actions for Ruby 3.1–4.0 and ActiveSupport 6.1–8.1, require Ruby 3.1, and modernize development dependencies and lint configuration - [@dblock](https://github.com/dblock).
+* Implemented RuboCop, Ruby style linter - [@dblock](https://github.com/dblock).
+* Upgraded RSpec to 3.x syntax - [@dblock](https://github.com/dblock).
+
+### 0.1.0 (2013-06-22)
 
 * Initial public release, written on a plane from NYC to SF - [@dblock](https://github.com/dblock).

data/README.md

@@ -1,100 +1,284 @@
 CanonicalEmails
 ==============
 
-[![Build Status](https://travis-ci.org/dblock/canonical-emails.png)](https://travis-ci.org/dblock/canonical-emails)
+[![Gem Version](http://img.shields.io/gem/v/canonical-emails.svg)](http://badge.fury.io/rb/canonical-emails)
+[![CI](https://github.com/dblock/canonical-emails/actions/workflows/ci.yml/badge.svg)](https://github.com/dblock/canonical-emails/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/dblock/canonical-emails/badge.svg?branch=master)](https://coveralls.io/github/dblock/canonical-emails?branch=master)
 
-Combine email validation and transformations to produce canonical email addresses. For example, parse and transform `Donald Duck <donald.duck@gmail.com>` into `donaldduck@gmail.com`, for `@gmail.com` addresses only. Patches instances of `Mail::Address`.
+Parse email addresses into provider-aware canonical forms. Gmail addresses become `CanonicalEmails::GMail` instances; unsupported domains become unchanged `CanonicalEmails::Address` instances. Both inherit from `Mail::Address`.
 
 ### Install
 
-Add `canonical-emails` to your Gemfile.
+Add `canonical-emails` to your Gemfile. Requires Ruby 3.1 or newer and compatible Mail and ActiveSupport versions.
 
-```
+```ruby
 gem 'canonical-emails'
 ```
 
-### Use
+See [UPGRADING.md](UPGRADING.md) for breaking API changes, Gmail plus-tag behavior, and migration considerations for stored canonical addresses.
+
+### Basic Usage
+
+Add a canonical email accessor to your model:
 
-``` ruby
+```ruby
 class User
   include CanonicalEmails::Extensions
 
   attr_accessor :email
-  canonical_email :email, CanonicalEmails::GMail
+  canonical_email :email
+end
+
+user = User.new
+user.email = "Alex Smith <Alex.Smith+Newsletter@gmail.com>"
+user.canonical_email.class # CanonicalEmails::GMail
+user.canonical_email.address # "alexsmith@gmail.com"
+user.canonical_email.tag # "Newsletter"
+```
+
+### Multiple Email Fields
+
+Declare `canonical_email` once for each field. Each declaration creates a separate `canonical_<field>` accessor and can select its own `type:`:
+
+```ruby
+class User
+  include CanonicalEmails::Extensions
+
+  attr_accessor :email, :backup_email
+  canonical_email :email
+  canonical_email :backup_email, type: CanonicalEmails::TaggedGMail
+end
+
+user = User.new
+user.email = "Alex.Smith+Newsletter@gmail.com"
+user.backup_email = "Alex.Smith+Backup@gmail.com"
+user.canonical_email.address # "alexsmith@gmail.com"
+user.canonical_backup_email.address # "alexsmith+backup@gmail.com"
+```
+
+Each accessor reads its own field without changing the original value. A nil field returns nil.
+
+### Custom Accessor Names
+
+Use `as:` to choose the generated accessor's name instead of `canonical_<field>`. String and symbol names are supported, and each field can have its own name and type:
+
+```ruby
+class User
+  include CanonicalEmails::Extensions
+
+  attr_accessor :email, :backup_email
+  canonical_email :email, as: :normalized_email
+  canonical_email :backup_email, as: :normalized_backup, type: CanonicalEmails::TaggedGMail
 end
 
 user = User.new
-user.email = "Donald Duck <Donald.Duck@gmail.com>"
-user.canonical_email.class # Mail::Address
-user.canonical_email.to_s # "Donald Duck <donaldduck@gmail.com>"
-user.canonical_email.address # "donaldduck@gmail.com"
-``` 
+user.email = "Alex.Smith+Newsletter@gmail.com"
+user.backup_email = "Alex.Smith+Backup@gmail.com"
+user.normalized_email.address # "alexsmith@gmail.com"
+user.normalized_backup.address # "alexsmith+backup@gmail.com"
+```
 
-### Transform
+Custom names replace the default generated names. When the name differs from the source field, the original reader and writer remain unchanged.
 
-#### CanonicalEmails::Downcase
+#### Override the Original Reader
 
-Replaces the address and domain portion of the email by its lowercase equivalent.
+Use the source field's name with `as:` to return a parsed address directly from that reader:
 
-``` ruby
-email = CanonicalEmails::Downcase.transform("Donald Duck <DoNaLD.DuCK@eXaMPLe.CoM>")
-email.to_s # "Donald Duck <donald.duck@example.com>"
-email.address # "donald.duck@example.com"
+```ruby
+class User
+  include CanonicalEmails::Extensions
+
+  attr_accessor :email
+  canonical_email :email, as: :email
+end
+
+user = User.new
+user.email = "Alex.Smith+Newsletter@gmail.com"
+user.email.class # CanonicalEmails::GMail
+user.email.address # "alexsmith@gmail.com"
+user.email.tag # "Newsletter"
 ```
 
-#### CanonicalEmails::GMail
+The reader now returns an address object (or `nil`) instead of a string. The original writer still stores the submitted value unchanged. The source reader must exist when accessed; inherited and generated readers are supported. `type:` also works with reader overrides.
 
-Gmail.com e-mail addresses ignore periods and aren't case-sensitive. The canonical version removes them and changes the address portion to lowercase.
+Raw-value access depends on your model: for the `attr_accessor` example, `user.instance_variable_get(:@email)` returns the original string; in ActiveRecord, use `user[:email]`. No additional raw-value accessor is generated.
 
-``` ruby
-email = CanonicalEmails::GMail.transform("Donald Duck <donald.duck@gmail.com>")
-email.to_s # "Donald Duck <donaldduck@gmail.com>"
-email.local # "donaldduck"
-email.address # "donaldduck@gmail.com"
+### Parse
+
+To parse an address directly without a model, use `CanonicalEmails.parse`:
+
+```ruby
+email = CanonicalEmails.parse("Alex Smith <Alex.Smith+Newsletter+Offers@GMAIL.COM>")
+email.class # CanonicalEmails::GMail
+email.to_s # "Alex Smith <alexsmith@gmail.com>"
+email.address # "alexsmith@gmail.com"
+email.local # "alexsmith"
+email.domain # "gmail.com"
+email.username # "Alex.Smith+Newsletter+Offers"
+email.tag # "Newsletter+Offers"
+
+email = CanonicalEmails.parse("Alex.Smith+Newsletter@EXAMPLE.COM")
+email.class # CanonicalEmails::Address
+email.address # "Alex.Smith+Newsletter@EXAMPLE.COM"
 ```
 
-### Multiple Transformations
+Provider detection matches the complete domain case-insensitively. Unregistered domains return generic addresses. See [Available Providers](#available-providers) for built-in behavior and [Register Providers](#register-providers) for adding your own types.
+
+`parse(nil)` returns `nil`. Empty or whitespace-only strings return empty generic addresses. Domainless input remains a generic address. Non-string input raises `TypeError`; malformed input may raise Mail parsing errors.
+
+The read-only `username` property preserves the original local part, including case, periods, and plus-tags. `tag` preserves the removed suffix, including case and additional `+` characters, when tag stripping is enabled. A missing tag returns `nil`; an explicitly empty tag returns `""`. Generic addresses have `tag == nil`.
 
-Combine multiple transformations, executed from left to right.
+### Available Providers
 
+#### Gmail
+
+`CanonicalEmails::GMail` is the default Gmail provider type. It registers `gmail.com` through the same registration API available to applications, matching the complete domain case-insensitively. Outlook, `googlemail.com`, and Google Workspace custom domains remain generic unless your application registers them.
+
+Gmail normalization removes periods and the first `+` and everything after it from the local part, and lowercases the local part and domain. Display names are preserved. [Gmail period equivalence](https://support.google.com/mail/answer/7436150?hl=en) applies to `gmail.com`, not custom domains.
+
+```ruby
+email = CanonicalEmails::GMail.parse("Alex Smith <Alex.Smith+Newsletter+Offers@GMAIL.COM>")
+email.class # CanonicalEmails::GMail
+email.to_s # "Alex Smith <alexsmith@gmail.com>"
+email.address # "alexsmith@gmail.com"
+email.username # "Alex.Smith+Newsletter+Offers"
+email.tag # "Newsletter+Offers"
 ```
-canonical_email :email, CanonicalEmails::GMail, CanonicalEmails::...
+
+#### Tagged Gmail
+
+`CanonicalEmails::TaggedGMail` normalizes Gmail periods and case while retaining the complete plus suffix in the address, lowercased along with the rest of the local part. It is built in but not registered for automatic dispatch; select it explicitly:
+
+```ruby
+email = CanonicalEmails::TaggedGMail.parse("Alex Smith <Alex.Smith+Newsletter+Offers@GMAIL.COM>")
+email.class # CanonicalEmails::TaggedGMail
+email.to_s # "Alex Smith <alexsmith+newsletter+offers@gmail.com>"
+email.address # "alexsmith+newsletter+offers@gmail.com"
+email.username # "Alex.Smith+Newsletter+Offers"
+email.tag # nil
 ```
 
-### Custom Transformations
-
-A transformation is a module that has a single `transform` method that returns a `Mail::Address` instance. This library patches internal methods of the `Mail::Address` class.
-
-``` ruby
-module CanonicalEmails
-  module ReverseName
-    def self.transform(value)
-      Mail::Address.new(value).tap do |email|
-        email.instance_eval do
-          def name
-            super.reverse
-          end
-        end
-      end
-    end
+It enforces the same Gmail domain restrictions as `GMail`. `tag` remains `nil` because the suffix is not stripped.
+
+### Register Providers
+
+Register a custom class during application initialization to enable automatic selection in both `CanonicalEmails.parse` and model accessors. For example, an application can define an Outlook type that lowercases the domain while preserving the local part, periods, and plus-tags:
+
+```ruby
+class Outlook < CanonicalEmails::Address
+  include CanonicalEmails::Behaviors::DowncaseDomain
+
+  def self.accepts?(domain)
+    domain&.casecmp?("outlook.com")
   end
 end
 
-email = CanonicalEmails::ReverseName.transform("Donald Duck <donald@example.org>")
-email.name # "kcuD dlanoD"
+CanonicalEmails.register("outlook.com", type: Outlook)
+email = CanonicalEmails.parse("Alex.Smith+Newsletter@OUTLOOK.COM")
+email.class # Outlook
+email.address # "Alex.Smith+Newsletter@outlook.com"
+email.username # "Alex.Smith+Newsletter"
+email.tag # nil
 ```
 
-### Contribute
+See [Custom Address Types](#custom-address-types) for additional normalization behaviors.
+
+Registrations match complete domains case-insensitively, not subdomains or suffixes. The type must subclass `Address` and accept the registered domain. Repeating the same mapping is harmless; a conflicting mapping raises `ArgumentError` without replacing the existing type. Explicit `type:` and class-level `.parse` bypass the registry.
+
+Call `CanonicalEmails.clear` during application initialization to remove all registrations, including the default Gmail mapping, before configuring your own provider set. For example, to use `TaggedGMail` for automatic Gmail detection:
+
+```ruby
+CanonicalEmails.clear
+CanonicalEmails.register("gmail.com", type: CanonicalEmails::TaggedGMail)
+
+email = CanonicalEmails.parse("Alex.Smith+Newsletter@gmail.com")
+email.class # CanonicalEmails::TaggedGMail
+email.address # "alexsmith+newsletter@gmail.com"
+```
+
+Defaults are not automatically restored: domains remain generic until registered again. Explicit `type:` and class-level `.parse` continue to work. Configure the full provider set before serving requests.
+
+### Explicit Types
+
+Use `canonical_email :email, type: CanonicalEmails::Address` to disable provider detection in a model, or select another class with `type:`.
+
+Specify `type:` to request an exact address class instead of provider detection:
+
+```ruby
+email = CanonicalEmails.parse("Alex.Smith+Newsletter@GMAIL.COM", type: CanonicalEmails::Address)
+email.address # "Alex.Smith+Newsletter@GMAIL.COM" (no normalization)
+
+email = CanonicalEmails.parse("Alex.Smith+Newsletter@GMAIL.COM", type: CanonicalEmails::Downcase)
+email.address # "alex.smith+newsletter@gmail.com" (lowercase both parts only)
+```
+
+`type:` must be `CanonicalEmails::Address` or one of its subclasses. Classes also expose `.parse`, equivalent to specifying `type:`:
+
+```ruby
+CanonicalEmails::GMail.parse("Alex.Smith+Newsletter@GMAIL.COM")
+CanonicalEmails::Address.parse("Alex.Smith+Newsletter@GMAIL.COM")
+CanonicalEmails::Downcase.parse("Alex.Smith+Newsletter@EXAMPLE.COM")
+```
 
-You're encouraged to contribute to this gem.
+An explicit provider class rejects mismatched domains with `ArgumentError`, including empty and domainless input. All `.parse` entry points return `nil` for nil input.
+
+Generic addresses preserve local-part and domain casing. Use `type: CanonicalEmails::Downcase` to lowercase both parts regardless of provider.
+
+### Assignment
+
+#### Model Fields
+
+Both separately named and overridden model readers cache their results per accessor and model instance. Each read compares the current raw input against a saved string copy, detecting writer assignments, changes that bypass the writer, and in-place string edits. Unchanged input returns the same address object (or cached nil); changed input is parsed again. Parsing errors propagate rather than returning a stale result. Configure provider registrations during initialization; registry changes alone do not invalidate existing model caches.
+
+Canonical address objects do not support `address=`. Assign through the model's original writer instead:
+
+```ruby
+user.email = "Alex.Smith+Newsletter@gmail.com"
+user.canonical_email.equal?(user.canonical_email) # true
+user.canonical_email.address = "Alex@example.com" # raises NoMethodError
+user.email = "Alex@example.com"
+user.canonical_email.address # "Alex@example.com"
+```
+
+For `as: :email`, use `user.email = ...` to update the stored value. Removing `address=` does not make other inherited Mail APIs read-only.
+
+#### Directly Parsed Addresses
+
+Parse a new value instead of reassigning a directly parsed address:
+
+```ruby
+email = CanonicalEmails.parse("Alex.Smith@gmail.com")
+email = CanonicalEmails.parse("Alex Smith <Alex.Smith+Newsletter@GMAIL.COM>")
+email.to_s # "Alex Smith <alexsmith@gmail.com>"
+email.username # "Alex.Smith+Newsletter"
+email.tag # "Newsletter"
+```
+
+### Custom Address Types
+
+`CanonicalEmails::Address` performs no normalization by default. Include any combination of these mixins to opt in:
+
+| Mixin under `CanonicalEmails::Behaviors` | Behavior |
+|---|---|
+| `DowncaseLocal` | Lowercase the local part. |
+| `DowncaseDomain` | Lowercase the domain. |
+| `RemovePeriods` | Remove periods from the local part. |
+| `StripTags` | Remove the first `+` and its suffix, storing the original suffix in `tag`. |
+
+`Downcase` includes the two downcasing mixins for all domains. `TaggedGMail` composes both downcasing mixins and `RemovePeriods`; `GMail` adds `StripTags`.
+
+Custom types are not automatically registered for provider detection. Override `.accepts?(domain)` to restrict allowed domains; it receives the original parsed domain. Mixins otherwise apply to all domains. Only remove periods or tags where your application has established equivalence. A custom type works directly in a model: `canonical_email :email, type: CustomAddress`.
+
+### Validation
+
+CanonicalEmails normalizes email addresses; it does not validate them. For Active Model email validations, consider [valid_email](https://github.com/hallelujah/valid_email), configured separately.
+
+### Contribute
 
-* Fork this project.
-* Make changes, write tests.
-* Updated CHANGELOG.
-* Make a pull request, bonus points for topic branches.
+See [CONTRIBUTING](CONTRIBUTING.md).
 
 ### Copyright and License
 
-Copyright Daniel Doubrovkine and Contributors, Artsy Inc., 2013
+Copyright Daniel Doubrovkine and Contributors, [Artsy](https://artsy.net), 2013-2014
 
 [MIT License](LICENSE.md)

data/UPGRADING.md

@@ -0,0 +1,92 @@
+# Upgrading CanonicalEmails
+
+## From 0.1.x to 0.2.0
+
+Requires Ruby 3.1 or newer. Both `require 'canonical-emails'` and `require 'canonical_emails'` remain supported.
+
+### Replace transform with parse
+
+Names below are relative to `CanonicalEmails`.
+
+| Before | After |
+|---|---|
+| `GMail.transform(value)` | `CanonicalEmails.parse(value)` |
+| `Downcase.transform(value)` | `Downcase.parse(value)` |
+| `canonical_email :email, GMail` | `canonical_email :email` |
+| `canonical_email :email, Downcase` | `canonical_email :email, type: Downcase` |
+| `email.class == Mail::Address` | `email.is_a?(Mail::Address)` |
+
+`GMail` and `Downcase` are now subclasses of `CanonicalEmails::Address < Mail::Address`. Automatic parsing selects `GMail` only for `gmail.com`; other domains return an unchanged `Address`. Explicit `GMail.parse` rejects other domains with `ArgumentError`.
+
+### Gmail plus-tags are removed
+
+```ruby
+# Before
+CanonicalEmails::GMail.transform("Alex.Smith+Newsletter@gmail.com").address
+# => "alexsmith+newsletter@gmail.com"
+
+# After
+email = CanonicalEmails.parse("Alex.Smith+Newsletter@gmail.com")
+email.address # => "alexsmith@gmail.com"
+email.username # => "Alex.Smith+Newsletter"
+email.tag # => "Newsletter"
+
+# To retain plus-tags
+CanonicalEmails::TaggedGMail.parse("Alex.Smith+Newsletter@gmail.com").address
+# => "alexsmith+newsletter@gmail.com"
+```
+
+**Check stored canonical addresses and unique indexes for collisions before backfilling.** Previously distinct Gmail values may now canonicalize to the same address.
+
+### Handle nil and reject non-string input
+
+| Before | After |
+|---|---|
+| `GMail.transform(nil)` returns an empty address | `CanonicalEmails.parse(nil)` returns `nil` |
+| Model accessors stringify input before transformation | Input must be a String or nil; other types raise `TypeError` |
+
+```ruby
+# Before
+user.canonical_email.address
+
+# After: the source field may be nil
+user.canonical_email&.address
+```
+
+Empty and domainless strings remain generic addresses with default parsing. Mail parsing errors propagate.
+
+### Replace address assignment
+
+`address=` has been removed and raises `NoMethodError`.
+
+```ruby
+# Before
+email.address = "Alex@example.com"
+
+# After: standalone address
+email = CanonicalEmails.parse("Alex@example.com")
+
+# After: model field
+user.email = "Alex@example.com"
+user.canonical_email.address # => "Alex@example.com"
+```
+
+Model readers now return the same parsed object while the raw field value is unchanged, including nil results. Assignments and in-place string edits refresh the cache; provider registry changes alone do not.
+
+### Replace transformer pipelines with one address type
+
+```ruby
+# Before: custom transformers applied in sequence
+canonical_email :email, RemovePeriods, CanonicalEmails::Downcase
+
+# After: select one class with the required behaviors
+class CustomAddress < CanonicalEmails::Address
+  include CanonicalEmails::Behaviors::RemovePeriods
+  include CanonicalEmails::Behaviors::DowncaseLocal
+  include CanonicalEmails::Behaviors::DowncaseDomain
+end
+
+canonical_email :email, type: CustomAddress
+```
+
+Move custom `.transform` logic into address subclasses or behavior mixins. Restrict provider-specific rules with `.accepts?(domain)` and register types during initialization for automatic dispatch. See [Custom Address Types](README.md#custom-address-types) and [Register Providers](README.md#register-providers).

data/lib/canonical-emails/address.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CanonicalEmails
+  # An unchanged Mail address with original local-part metadata.
+  class Address < Mail::Address
+    attr_reader :username, :tag
+
+    undef_method :address=
+
+    def self.parse(value)
+      CanonicalEmails.parse(value, type: self)
+    end
+
+    def self.accepts?(_domain)
+      true
+    end
+
+    def initialize(value = nil)
+      super
+      raise ArgumentError, "#{self.class} does not support domain #{get_domain.inspect}" unless self.class.accepts?(get_domain)
+
+      update_properties
+    end
+
+    private
+
+    def update_properties
+      @username = get_local
+      @tag = nil
+    end
+  end
+end

data/lib/canonical-emails/behaviors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CanonicalEmails
+  # Opt-in transformations for Address subclasses.
+  module Behaviors
+    # Lowercases the local part.
+    module DowncaseLocal
+      def local(*)
+        super&.downcase
+      end
+    end
+
+    # Lowercases the domain.
+    module DowncaseDomain
+      def domain(*)
+        super&.downcase
+      end
+    end
+
+    # Removes periods from the local part.
+    module RemovePeriods
+      def local(*)
+        super&.delete('.')
+      end
+    end
+
+    # Removes the plus suffix while retaining it in the tag property.
+    module StripTags
+      def local(*)
+        value = super
+        return unless value
+
+        value.split('+', 2).first
+      end
+
+      private
+
+      def update_properties
+        super
+        @tag = username.split('+', 2).at(1) if username
+      end
+    end
+  end
+end

data/lib/canonical-emails/downcase.rb

@@ -1,20 +1,9 @@
-module CanonicalEmails
-  module Downcase
-
-    def self.transform(value)
-      Mail::Address.new(value).tap do |email|
-        email.instance_eval do
-          def get_local
-            value = super
-            value.downcase if value
-          end
-          def domain
-            value = super
-            value.downcase if value
-          end
-        end
-      end if value
-    end
+# frozen_string_literal: true
 
+module CanonicalEmails
+  # Normalizes the local part and domain without changing the display name.
+  class Downcase < Address
+    include Behaviors::DowncaseLocal
+    include Behaviors::DowncaseDomain
   end
-end
+end

data/lib/canonical-emails/extensions.rb

@@ -1,17 +1,39 @@
+# frozen_string_literal: true
+
 module CanonicalEmails
+  # Adds lazily evaluated canonical address accessors to application models.
   module Extensions
     extend ActiveSupport::Concern
 
+    private
+
+    def cached_canonical_email(key, raw, type)
+      @canonical_email_cache ||= {}
+      cached = @canonical_email_cache[key]
+      return cached.last if cached && cached.first == raw
+
+      address = CanonicalEmails.parse(raw, type: type)
+      @canonical_email_cache[key] = [raw&.dup, address]
+      address
+    end
+
+    # Defines provider-aware canonical address accessors.
     module ClassMethods
-      def canonical_email(field, *parsers)
-        define_method "canonical_#{field}" do
-          value = send(field)
-          Array(parsers).each do |parser|
-            value = parser.transform(value.to_s)
+      def canonical_email(field, type: nil, as: :"canonical_#{field}")
+        raise ArgumentError, 'as must be a nonempty String or Symbol' unless (as.is_a?(String) || as.is_a?(Symbol)) && !as.to_s.empty?
+
+        key = Object.new
+        if as.to_s == field.to_s
+          @canonical_email_readers ||= Module.new.tap { |readers| prepend readers }
+          @canonical_email_readers.define_method(as) do
+            cached_canonical_email(key, super(), type)
+          end
+        else
+          define_method as do
+            cached_canonical_email(key, send(field), type)
           end
-          value
         end
       end
     end
   end
-end
+end

data/lib/canonical-emails/gmail.rb

@@ -1,22 +1,8 @@
-module CanonicalEmails
-  module GMail
-
-    def self.transform(value)
-      Mail::Address.new(value).tap do |email|
-        if email.domain && [ "gmail.com" ].include?(email.domain.downcase)
-          email.instance_eval do
-            def get_local
-              value = super
-              value.gsub(".", "").downcase if value
-            end
-            def domain
-              value = super
-              value.downcase if value
-            end
-          end
-        end if value
-      end
-    end
+# frozen_string_literal: true
 
+module CanonicalEmails
+  # Removes periods and plus tags and normalizes case for gmail.com addresses only.
+  class GMail < TaggedGMail
+    include Behaviors::StripTags
   end
-end
+end

data/lib/canonical-emails/tagged_gmail.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CanonicalEmails
+  # Normalizes Gmail periods and case while retaining plus-tags.
+  class TaggedGMail < Address
+    include Behaviors::DowncaseLocal
+    include Behaviors::DowncaseDomain
+    include Behaviors::RemovePeriods
+
+    def self.accepts?(domain)
+      domain&.casecmp?('gmail.com')
+    end
+  end
+end

data/lib/canonical-emails/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CanonicalEmails
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/canonical-emails.rb

@@ -1,7 +1,50 @@
+# frozen_string_literal: true
+
 require 'mail'
-require 'active_support'
+require 'active_support/concern'
 
 require 'canonical-emails/version'
+require 'canonical-emails/address'
+require 'canonical-emails/behaviors'
 require 'canonical-emails/downcase'
+require 'canonical-emails/tagged_gmail'
 require 'canonical-emails/gmail'
 require 'canonical-emails/extensions'
+
+# Parses addresses into provider-aware canonical forms.
+module CanonicalEmails
+  @types = {}
+  @types_mutex = Mutex.new
+
+  def self.clear
+    @types_mutex.synchronize { @types.clear }
+  end
+
+  def self.register(domain, type:)
+    raise ArgumentError, 'domain must be a nonempty domain String without whitespace or @' unless domain.is_a?(String) && !domain.empty? && !domain.match?(/[\s@]/)
+    raise ArgumentError, 'type must be a CanonicalEmails::Address subclass' unless type.is_a?(Class) && type <= Address
+
+    domain = domain.downcase
+    raise ArgumentError, "#{type} does not accept #{domain}" unless type.accepts?(domain)
+
+    @types_mutex.synchronize do
+      existing = @types[domain]
+      raise ArgumentError, "#{domain} is already registered to #{existing}" if existing && existing != type
+
+      @types[domain] = type
+    end
+  end
+
+  def self.parse(value, type: nil)
+    raise ArgumentError, 'type must be a CanonicalEmails::Address subclass' unless type.nil? || (type.is_a?(Class) && type <= Address)
+    return if value.nil?
+
+    raise TypeError, 'address must be a String or nil' unless value.is_a?(String)
+
+    data = Mail::Parsers::AddressListsParser.parse(value).addresses.first unless value.strip.empty?
+    type ||= @types_mutex.synchronize { @types.fetch(data&.domain&.downcase, Address) }
+    type.new(data)
+  end
+
+  register('gmail.com', type: GMail)
+end

data/lib/canonical_emails.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'canonical-emails'

metadata

@@ -1,107 +1,84 @@
 --- !ruby/object:Gem::Specification
 name: canonical-emails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
-  prerelease: 
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Doubrovkine
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-06-22 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: mail
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: mail
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email: dblock@dblock.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
 - CHANGELOG.md
-- Gemfile
 - LICENSE.md
 - README.md
-- Rakefile
-- canonical-emails.gemspec
+- UPGRADING.md
 - lib/canonical-emails.rb
+- lib/canonical-emails/address.rb
+- lib/canonical-emails/behaviors.rb
 - lib/canonical-emails/downcase.rb
 - lib/canonical-emails/extensions.rb
 - lib/canonical-emails/gmail.rb
+- lib/canonical-emails/tagged_gmail.rb
 - lib/canonical-emails/version.rb
 - lib/canonical_emails.rb
-- spec/canonical-emails/downcase_spec.rb
-- spec/canonical-emails/extensions_spec.rb
-- spec/canonical-emails/fixtures/downcase.yml
-- spec/canonical-emails/fixtures/extensions.yml
-- spec/canonical-emails/fixtures/gmail.yml
-- spec/canonical-emails/gmail_spec.rb
-- spec/canonical-emails/version_spec.rb
-- spec/shared/extension_examples.rb
-- spec/shared/transform_examples.rb
-- spec/spec_helper.rb
-- spec/support/reverse.rb
-- spec/support/yml_examples.rb
-homepage: http://github.com/dblock/canonical-emails
+homepage: https://github.com/dblock/canonical-emails
 licenses:
 - MIT
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
-      segments:
-      - 0
-      hash: 247467439
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.24
-signing_key: 
-specification_version: 3
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
 summary: Combine email validation and transformations to produce canonical email addresses.
 test_files: []

data/.gitignore

@@ -1,2 +0,0 @@
-Gemfile.lock
-pkg

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---color

data/.travis.yml

@@ -1,6 +0,0 @@
-rvm:
-  - 1.8.7
-  - 1.9.3
-  - 2.0.0
-  - jruby-19mode
-  - rbx-19mode

data/Gemfile

@@ -1,6 +0,0 @@
-source "http://rubygems.org"
-
-gemspec
-
-gem "rspec"
-gem "rake"

data/Rakefile

@@ -1,13 +0,0 @@
-require 'rubygems'
-require 'bundler/gem_tasks'
-
-Bundler.setup :default, :development
-
-require 'rspec/core'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList["spec/**/*_spec.rb"]
-end
-
-task :default => :spec

data/canonical-emails.gemspec

@@ -1,18 +0,0 @@
-$:.push File.expand_path("../lib", __FILE__)
-require 'canonical-emails/version'
-
-Gem::Specification.new do |s|
-  s.name = "canonical-emails"
-  s.version = CanonicalEmails::VERSION
-  s.authors = [ "Daniel Doubrovkine" ]
-  s.email = "dblock@dblock.org"
-  s.platform = Gem::Platform::RUBY
-  s.required_rubygems_version = '>= 1.3.6'
-  s.files = `git ls-files`.split("\n")
-  s.require_paths = [ "lib" ]
-  s.homepage = "http://github.com/dblock/canonical-emails"
-  s.licenses = [ "MIT" ]
-  s.summary = "Combine email validation and transformations to produce canonical email addresses."
-  s.add_dependency "mail"
-  s.add_dependency "activesupport"
-end

data/spec/canonical-emails/downcase_spec.rb

@@ -1,5 +0,0 @@
-require 'spec_helper'
-
-describe CanonicalEmails::Downcase do
-  it_behaves_like 'transform fixture_examples'
-end

data/spec/canonical-emails/extensions_spec.rb

@@ -1,5 +0,0 @@
-require 'spec_helper'
-
-describe CanonicalEmails::Extensions do
-  it_behaves_like 'extension fixture_examples'
-end

data/spec/canonical-emails/fixtures/downcase.yml

@@ -1,30 +0,0 @@
--
-  source: Donald <donald@example.org>
-  name: Donald
-  local: donald
-  domain: example.org
--
-  source: Donald   <   donald@example.org     >
-  name: Donald
-  local: donald
-  domain: example.org
--
-  source: donald@example.org
-  local: donald
-  domain: example.org
--
-  source: ! ' donald@example.org'
-  local: donald
-  domain: example.org
--
-  source: donald@eXaMPLe.org
-  local: donald
-  domain: example.org
--
-  source: DONALD@eXaMPLe.org
-  local: donald
-  domain: example.org
--
-  source: DoNaLD@example.org
-  local: donald
-  domain: example.org

data/spec/canonical-emails/fixtures/extensions.yml

@@ -1,16 +0,0 @@
--
-  email: Donald Duck <DoNaLD.DuCK@GMaiL.CoM>
-  transforms:
-    - CanonicalEmails::Downcase
-  canonical_email: Donald Duck <donald.duck@gmail.com>
--
-  email: Donald Duck <DoNaLD.DuCK@GMaiL.CoM>
-  transforms:
-    - CanonicalEmails::GMail
-  canonical_email: Donald Duck <donaldduck@gmail.com>
--
-  email: Donald Duck <DoNaLD.DuCK@GMaiL.CoM>
-  transforms:
-    - CanonicalEmails::GMail
-    - CanonicalEmails::Reverse
-  canonical_email: Donald Duck <kcuddlanod@moc.liamg>

data/spec/canonical-emails/fixtures/gmail.yml

@@ -1,29 +0,0 @@
--
-  source: Donald Duck <example@example.org>
-  name: Donald Duck
-  local: example
-  domain: example.org
--
-  source: donald@example.org
-  local: donald
-  domain: example.org
--
-  source: donald@eXaMPLe.org
-  local: donald
-  domain: eXaMPLe.org
--
-  source: donald.duck@gmail.com
-  local: donaldduck
-  domain: gmail.com
--
-  source: donaldduck@gmail.com
-  local: donaldduck
-  domain: gmail.com
--
-  source: donald.duck@gMaiL.com
-  local: donaldduck
-  domain: gmail.com
--
-  source: donald.duck@google.com
-  local: donald.duck
-  domain: google.com

data/spec/canonical-emails/gmail_spec.rb

@@ -1,5 +0,0 @@
-require 'spec_helper'
-
-describe CanonicalEmails::GMail do
-  it_behaves_like 'transform fixture_examples'
-end

data/spec/canonical-emails/version_spec.rb

@@ -1,7 +0,0 @@
-require 'spec_helper'
-
-describe CanonicalEmails do
-  it "has a version" do
-    CanonicalEmails::VERSION.should_not be_nil
-  end
-end

data/spec/shared/extension_examples.rb

@@ -1,14 +0,0 @@
-shared_examples 'extension fixture_examples' do
-  yml_examples.each do |example|
-    it "#{example['transforms'].join(', ')}" do
-      klass = Class.new do
-        include CanonicalEmails::Extensions
-        attr_accessor :email
-        canonical_email :email, * example['transforms'].map(&:constantize)
-      end
-      user = klass.new
-      user.email = example['email']
-      user.canonical_email.to_s.should == example['canonical_email']
-    end
-  end
-end

data/spec/shared/transform_examples.rb

@@ -1,11 +0,0 @@
-shared_examples 'transform fixture_examples' do
-  yml_examples.each do |example|
-    it "transforms '#{example['source']}'" do
-      subject.transform(example['source']).tap do |email|
-        email.local.should == example['local']
-        email.domain.should == example['domain']
-        email.name.should == example['name']
-      end
-    end
-  end
-end

data/spec/spec_helper.rb

@@ -1,12 +0,0 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-
-require 'rubygems'
-require 'rspec'
-require 'canonical-emails'
-require 'yaml'
-
-[ "support", "shared" ].each do |path|
-  Dir["#{File.dirname(__FILE__)}/#{path}/**/*.rb"].each do |f|
-    require f
-  end
-end

data/spec/support/reverse.rb

@@ -1,18 +0,0 @@
-module CanonicalEmails
-  module Reverse
-
-    def self.transform(value)
-      Mail::Address.new(value).tap do |email|
-        email.instance_eval do
-          def get_local
-            super.reverse
-          end
-          def domain
-            super.reverse
-          end
-        end
-      end
-    end
-
-  end
-end

data/spec/support/yml_examples.rb

@@ -1,10 +0,0 @@
-def yml_examples
-  caller.each do |c|
-    c =~ /(.*):(\d+)/
-    dir_name = File.dirname($1)
-    file_name = File.basename($1)
-    next unless file_name.end_with?("_spec.rb")
-    fixture_file = "#{file_name.split('_spec').first}.yml"
-    return YAML::load(File.open([ dir_name, 'fixtures', fixture_file ].join('/')))
-  end  
-end