address_concern 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54db12d5f83e9438e61c47552eba316511be4cbc69200bee3e51568a10c2c41e
+  data.tar.gz: 73a84002eeafb49d0536d2bf5de94391410b3b4d873633ba62f2fd3e42df8ab5
+SHA512:
+  metadata.gz: ac7f541ac00b56b64c9a6e8f6cc7a49ee423cce621c90a13173ddc7e4c852883d5f5a2ad14bca967b2d7c7fcc9678a7b8062bb580c30baa43bb656e681b7fed9
+  data.tar.gz: 305160aabeca32990a9aa74aa2519b6b58b54c7354985ccbb1677fc1ec370b5c0f104319541834c33865f86079f10d4f45b31342be2d2656e90ade6eb42a85fa

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+spec/test.log
+.byebug_history
+Gemfile.lock
+tmp/

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.7.4

data/CHANGELOG

@@ -0,0 +1,3 @@
+Tue, Mar 8, 2011
+- - - - - - - - -
+- Initial Release

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in address_concern.gemspec
+gemspec
+
+gem 'pry'
+gem 'byebug'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2011 Paul Campbell
+Copyright (c) 2011-2018 Tyler Rick
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+
+#---------------------------------------------------------------------------------------------------
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+desc "Start a console with this version of library loaded"
+task :console do
+  require 'bundler/setup'
+  require 'address_concern'
+  require 'irb'
+  ARGV.clear
+  IRB.start
+end
+
+task :default => :spec

data/Readme.md

@@ -0,0 +1,231 @@
+# Address Concern
+
+A reusable polymorphic `Address` model concern for your Rails apps.
+
+# Installation
+
+Add `address_concern` to your `Gemfile`:
+
+    gem 'address_concern'
+
+Then run the generator to create your addresses table:
+
+    rails generate address_concern:install
+    rake db:migrate
+
+You now have an `Address` model that you can use in your app just as if it were in your `app/models` directory.
+
+# Usage
+
+## Base usage
+
+```ruby
+class Address < ApplicationRecord
+  include AddressConcern::Address
+end
+```
+
+## `belongs_to_address`
+
+`AddressConcern::AddressAssociations` is automatically included into `ActiveRecord::Base` and
+provides a few macros for defining associations with your app's Address model.
+
+```ruby
+class Person < ApplicationRecord
+  belongs_to_address
+end
+
+person = Person.new
+person.build_address(address: '...')
+```
+
+## Multiple addresses on same model
+
+```ruby
+class User < ApplicationRecord
+  belongs_to_address :shipping_address
+  belongs_to_address :billing_address
+end
+
+user = User.new
+shipping_address = user.build_shipping_address(address: '...')
+billing_address  = user.build_billing_address( address: '...')
+```
+
+See "Adding an `address` association to your ActiveRecord models" section for more examples of
+configuration your associations.
+
+
+# Adding an `address` association to your ActiveRecord models
+
+You can add an address association (or multiple) to any model that has an address.
+
+You can associate with the address via a `belongs_to`, `has_one`, or `has_many` — whichever makes
+the most sense for your use case.
+
+You can either use standard ActiveRecord association macros, like this:
+
+```ruby
+class Person < ApplicationRecord
+  belongs_to :address
+end
+```
+
+... or use the provided macros:
+
+## `belongs_to_address`
+
+```ruby
+class Person < ApplicationRecord
+  belongs_to_address
+end
+
+person = Person.new
+person.build_address(address: '...')
+```
+
+If needed, you can pass a name as well as options for the `belongs_to` and (optional) inverse `has_one`
+associations.
+
+```ruby
+class Child < ApplicationRecord
+  belongs_to_address inverse: false
+  belongs_to_address :secret_hideout, inverse: {name: :child_for_secret_hideout}
+end
+
+child = Child.new
+child.build_secret_hideout(address: '...')
+```
+
+## `has_address`
+
+`has_address` creates a `has_one :address` association:
+
+```ruby
+class Company < ApplicationRecord
+  has_address
+end
+```
+
+```
+company = company.new
+address = company.build_address(address: '...')
+```
+
+This also adds a polymorphic `addressable` association on the Address model (not available if you're
+using `belongs_to :address` on your addressable models):
+
+```ruby
+belongs_to :addressable, :polymorphic => true
+```
+
+## `has_addresses`
+
+`has_addresses` creates a `has_many :addresses` association:
+
+```ruby
+class User < ApplicationRecord
+  has_addresses
+end
+```
+
+If you want to have several *individually accessible* addresses associated with a single model (such
+as a separate shipping and billing address), you can do something like this:
+
+```ruby
+class User < ApplicationRecord
+  has_addresses :types => [:physical, :shipping, :billing]
+end
+```
+
+Then you can refer to them by name, like this:
+
+```ruby
+shipping_address = user.build_shipping_address(address: 'Some address')
+user.shipping_address # => shipping_address
+```
+
+Note that you aren't *limited* to only the address types you specifically list in your
+`has_addresses` declaration; you can still add and retrieve other addresses using the `has_many
+:addresses` association:
+
+```ruby
+vacation_address = user.addresses.build(address: 'Vacation', :address_type => 'Vacation')
+user.addresses # => [shipping_address, vacation_address]
+```
+
+# Country/state database
+
+Country/state data comes from the [`carmen`](https://github.com/carmen-ruby/carmen) gem.
+
+- You can set the country either by using the `country=` writer (if you want to use a country name
+  as input in your frontend) or the `country_code=` writer (if you want to use a country code as
+  input). It will automatically update the other column for you and keep both of them up-to-date.
+- The country name is stored in the `country` attribute (most common use case).
+- Country codes can be optionally get/set via the `country_code2` (ISO 3166-1 alpha-2 codes)
+  (aliased as `country_code`) or `country_code3` attributes.
+- Be aware that if the country you entered isn't recognized (in Carmen's database), it will be
+  rejected and the country field reset to nil. This should probably be considered a bug and be fixed
+  in a later release (using validations instead).
+
+Other notes regarding country:
+
+- Added some special handling of UK countries, since Carmen doesn't recognize 'England', etc. as
+  countries but we want to allow those country names to be stored since they may be a part of the
+  address you want to preserve.
+
+# View helpers
+
+Because this gem depends on [`carmen`](https://github.com/carmen-ruby/carmen), you have access to
+its `country_select` and `state_select` helpers.
+
+# Related Projects
+
+(Along with some feature/API ideas that we may want to incorporate (pull requests welcome!).)
+
+- https://github.com/ankane/mainstreet — A standard US address model for Rails
+  - Use `alias_attribute` to map existing field names
+  - Add new fields like `original_attributes` and `verification_info`
+  - Uses `SmartyStreets` to verify addresses (`valid?` returns false).
+  - [`acts_as_address` association macro](https://github.com/ankane/mainstreet/blob/master/lib/mainstreet.rb)
+  - [`Address` model generator](https://github.com/ankane/mainstreet/blob/master/lib/generators/mainstreet/address_generator.rb)
+  - `acts_as_address` could potentially be included into our `Address` model and both gems used together
+
+- https://github.com/yrgoldteeth/whereabouts — A simple rails plugin that adds a polymorphic address model
+  - `has_whereabouts :location, {:geocode => true}`
+  - `has_whereabouts :location, {:validate => [:city, :state, :zip]}`
+  - [`has_whereabouts` association macro](https://github.com/yrgoldteeth/whereabouts/blob/master/lib/whereabouts_methods.rb)
+  - [`Address` model generator](https://github.com/yrgoldteeth/whereabouts/blob/master/lib/generators/address/templates/address.rb)
+
+- https://github.com/wilbert/addresses — An Address engine to use Country, State, City and Neighborhood models
+  - Allows you use these models: `Country`, `State` (belongs to country), `City` (belongs to State), `Neighborhood` (belongs to city), `Address` (Belongs to `Neighborhood` and `City`, because neighborhood is not required)
+  - `address.city = Address::City.find(city_id)`
+  - `mount Addresses::Engine => "/addresses"`
+  - [`Address` model](https://github.com/wilbert/addresses/blob/master/app/models/addresses/address.rb)
+
+- https://github.com/huerlisi/has_vcards — Rails plugin providing VCard like contact and address models and helpers
+  - [`Address` model](https://github.com/huerlisi/has_vcards/blob/master/app/models/has_vcards/address.rb)
+
+Not maintained for 3+ years:
+- https://github.com/mobilityhouse/acts_as_addressable — Make your models addressable
+  - `acts_as_addressable :postal, :billing`
+  - [`acts_as_addressable` association macro](https://github.com/mobilityhouse/acts_as_addressable/blob/master/lib/acts_as_addressable/addressable.rb)
+  - [`Address` model generator](https://github.com/mobilityhouse/acts_as_addressable/blob/master/lib/generators/acts_as_addressable/templates/address.rb)
+- https://github.com/mariusz360/postally_addressable — Add postal addresses to your models
+  - [`has_postal_address` association macro](https://github.com/mariusz360/postally_addressable/blob/master/lib/postally_addressable/has_postal_address.rb)
+  - [`PostalAddress` model](https://github.com/mariusz360/postally_addressable/blob/master/app/models/postal_address.rb)
+    - `alias_attribute :state, :province`
+- https://github.com/nybblr/somewhere — Serialized address class for use with Rails models. Like it should be.
+  - `address :billing, :postal_code => :zip, :include_prefix => false`
+  - `address.to_hash :exclude => [:country]`
+  - `address.to_s :country => false`
+  - [`Address` model](https://github.com/nybblr/somewhere/blob/master/lib/address.rb)
+  - [`address` association macro](https://github.com/nybblr/somewhere/blob/master/lib/somewhere.rb)
+- https://github.com/rumblelabs/is_addressable
+
+# License
+
+Licensed under the MIT License.
+
+See LICENSE.txt for further details.
+

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/address_concern.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "address_concern/version"
+
+Gem::Specification.new do |s|
+  s.name        = "address_concern"
+  s.version     = AddressConcern.version
+  s.authors     = ["Paul Campbell", "Tyler Rick"]
+  s.email       = ["paul@rslw.com", "tyler@tylerrick.com"]
+  s.homepage    = %q{http://github.com/TylerRick/address_concern}
+  s.summary     = %q{A reusable Address model for your Rails apps}
+  s.description = s.summary
+  s.licenses = ["MIT"]
+
+  s.add_dependency "rake"
+  s.add_dependency "cucumber"
+  s.add_dependency "rails", ">= 4.0"
+  s.add_dependency "activerecord", ">= 4.0"
+  s.add_dependency "activesupport", ">= 4.0"
+  s.add_dependency "carmen", '>= 1.1.1'
+  s.add_dependency "attribute_normalizer"
+  s.add_dependency "active_record_ignored_attributes"
+  s.add_dependency "facets"
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'sqlite3'
+  #s.add_development_dependency 'mysql2', '~>0.2.11'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  #s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/bin/console

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'address_concern'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require_relative "../spec/spec_helper"
+require "pry"
+Pry.start

data/config/locale/overlay/en/id.yml

@@ -0,0 +1,8 @@
+---
+en:
+  world:
+    id:
+      jw:
+        jk:
+          #name: Jakarta Raya
+          name: DKI Jakarta

data/lib/address_concern/address.rb

@@ -0,0 +1,306 @@
+module AddressConcern::Address
+  extend ActiveSupport::Concern
+  included do
+
+    #validates_presence_of :name
+    #validates_presence_of :address
+    #validates_presence_of :state, :if => :state_required?
+    #validates_presence_of :country
+    #validates_format_of :phone, :with => /^[0-9\-\+ ]*$/
+    #validates_format_of :email, :with => /^[^@]*@.*\.[^\.]*$/, :message => 'is invalid. Please enter an address in the format of you@company.com'
+    #validates_presence_of :phone, :message => ' is required.'
+
+    #-------------------------------------------------------------------------------------------------
+    normalize_attributes :name, :city, :state, :postal_code, :country
+    normalize_attribute  :address, :with => [:cleanlines, :strip]
+
+    #-------------------------------------------------------------------------------------------------
+    # Country code
+
+    def country_alpha2=(code)
+      if code.blank?
+        write_attribute(:country, nil)
+        write_attribute(:country_alpha2, nil)
+        write_attribute(:country_alpha3, nil)
+
+      elsif (country = Carmen::Country.alpha_2_coded(code))
+        # Only set it if it's a recognized country code
+        write_attribute(:country, country.name)
+        write_attribute(:country_alpha2, code)
+      end
+    end
+
+    # Aliases
+    def country_code
+      country_alpha2
+    end
+    def country_code=(code)
+      self.country_alpha2 = code
+    end
+    def state_code
+      state
+    end
+
+    def carmen_country
+      Carmen::Country.alpha_2_coded(country_alpha2)
+    end
+
+    def carmen_state
+      if (country = carmen_country)
+        Address.states_for_country(country).coded(state_code)
+      end
+    end
+
+    #-------------------------------------------------------------------------------------------------
+    # Country name
+
+    def country=(name)
+      if name.blank?
+        write_attribute(:country, nil)
+        write_attribute(:country_alpha2, nil)
+        write_attribute(:country_alpha3, nil)
+      else
+        name = recognize_country_name_alias(name)
+        if (country = Carmen::Country.named(name))
+          write_attribute(:country,        country.name)
+          write_attribute(:country_alpha2, country.alpha_2_code)
+          write_attribute(:country_alpha3, country.alpha_3_code)
+        else
+          write_attribute(:country, nil)
+          write_attribute(:country_alpha2, nil)
+          write_attribute(:country_alpha3, nil)
+        end
+      end
+    end
+
+    def recognize_country_name_alias(name)
+      name = case name
+      when 'USA'
+      when 'The Democratic Republic of the Congo', 'Democratic Republic of the Congo'
+        'Congo, the Democratic Republic of the'
+      when 'Republic of Macedonia', 'Macedonia, Republic of', 'Macedonia'
+        'Macedonia, Republic of'
+      else
+        name
+      end
+    end
+
+    # This should not be different from the value stored in the country attribute, but allows you to
+    # look it up just to make sure they match (or to update country field to match this).
+    def country_name_from_code
+      if (country = Carmen::Country.alpha_2_coded(country_alpha2))
+        country.name
+      end
+    end
+
+    # Aliases
+    def country_name
+      country
+    end
+    def country_name=(name)
+      self.country = name
+    end
+
+    #════════════════════════════════════════════════════════════════════════════════════════════════════
+    # State/province options for country
+
+    # This is useful if want to list the state options allowed for a country in a select box and
+    # restrict entry to only officially listed state options.
+    # It is not required in the postal address for all countries, however. If you only want to show it
+    # if it's required in the postal address, you can make it conditional based on
+    # state_included_in_postal_address?.
+    def self.states_for_country(country)
+      return [] unless country
+      raise ArgumentError.new('expected a Carmen::Country') unless country.is_a? Carmen::Country
+      Carmen::RegionCollection.new(
+        if country.name == 'Kenya'
+          # https://github.com/jim/carmen/issues/227
+          # https://en.wikipedia.org/wiki/Provinces_of_Kenya
+          # Kenya's provinces were replaced by a system of counties in 2013.
+          # https://en.wikipedia.org/wiki/ISO_3166-2:KE confirms that they are "former" provinces.
+          # At the time of this writing, however, it doesn't look like Carmen has been updated to
+          # include the 47 counties listed under https://en.wikipedia.org/wiki/ISO_3166-2:KE.
+          country.subregions.typed('county')
+        elsif country.name == 'France'
+          # https://github.com/jim/carmen/issues/228
+          # https://en.wikipedia.org/wiki/Regions_of_France
+          # In 2016 what had been 27 regions was reduced to 18.
+          # France is divided into 18 administrative regions, including 13 metropolitan regions and 5 overseas regions.
+          # https://en.wikipedia.org/wiki/ISO_3166-2:FR
+          []
+        else # Needed for New Zealand, Philippines, Indonesia, and possibly others
+          country.subregions.map {|_| _.subregions.any? ? _.subregions : _ }.flatten
+        end
+      )
+    end
+    def states_for_country
+      self.class.states_for_country(carmen_country)
+    end
+    alias_method :state_options, :states_for_country
+
+    def country_with_states?
+      states_for_country.any?
+    end
+
+    # Is the state/province required in a postal address?
+    # If no, perhaps you want to collect it for other reasons (like seeing which people/things are in
+    # the same region). Or for countries where it *may* be included in a postal address but is not
+    # required to be included.
+    def state_required_in_postal_address?
+      [
+        'Australia',
+        'Brazil',
+        'Canada',
+        'Mexico',
+        'United States',
+        'Italy',
+        'Venezuela',
+      ].include? country_name
+    end
+    def state_possibly_included_in_postal_address?
+      # https://ux.stackexchange.com/questions/64665/address-form-field-for-region
+      # http://www.bitboost.com/ref/international-address-formats/denmark/
+      # http://www.bitboost.com/ref/international-address-formats/poland/
+      return true if state_required_in_postal_address?
+      return false if [
+        'Algeria',
+        'Argentina',
+        'Austria',
+        'Denmark',
+        'France',
+        'Germany',
+        'Indonesia',
+        'Ireland',
+        'Israel',
+        'Netherlands',
+        'New Zealand',
+        'Poland',
+        'Sweden',
+        'United Kingdom',
+      ].include? country_name
+      # Default:
+      country_with_states?
+    end
+
+    # It's not called a "State" in all countries.
+    # In some countries, it could technically be multiple different types of regions:
+    # - In United States, it could be a state or an outlying region or a district or an APO
+    # - In Canada, it could be a province or a territory.
+    # This attempts to return the most common, expected name for this field.
+    # See also: https://ux.stackexchange.com/questions/64665/address-form-field-for-region
+    #
+    # To see what it should be called in all countries known to Carmen:
+    # Country.countries_with_states.map {|country| [country.name, Address.new(country_name: country.name).state_label] }.to_h
+    # => {"Afghanistan"=>"Province",
+    #     "Armenia"=>"Province",
+    #     "Angola"=>"Province",
+    #     "Argentina"=>"Province",
+    #     "Austria"=>"State",
+    #     "Australia"=>"State",
+    #     ...
+    def state_label
+      # In UK, it looks like they (optionally) include the *county* in their addresses. They don't actually have "states" per se.
+      # Reference: http://bitboost.com/ref/international-address-formats/united-kingdom/
+      # Could also limit to Countries (England, Scotland, Wales) and Provinces (Northern Ireland).
+      # Who knows. The UK's subregions are a mess.
+      # If allowing the full list of subregions from https://en.wikipedia.org/wiki/ISO_3166-2:GB,
+      # perhaps Region is a better, more inclusive term.
+      if country_name.in? ['United Kingdom']
+        'Region'
+      elsif state_options.any?
+        state_options[0].type.capitalize
+      end
+    end
+
+    def state_name
+      carmen_state ? carmen_state.name : state
+    end
+
+    #════════════════════════════════════════════════════════════════════════════════════════════════════
+
+    def empty?
+      [:address, :city, :state, :postal_code, :country].all? {|_|
+        !self[_].present?
+      }
+    end
+
+    def started_filling_out?
+      [:address, :city, :state, :postal_code, :country].any? {|_|
+        self[_].present?
+      }
+    end
+
+    #════════════════════════════════════════════════════════════════════════════════════════════════════
+    # Formatting for humans
+
+    # Lines of a postal address
+    def lines
+      [
+        name,
+        address.to_s.lines.to_a,
+        city_line,
+        country_name,
+      ].flatten.reject(&:blank?)
+    end
+
+    # Used by #lines
+    #
+    # Instead of using `state` method (which is really state_code). That's fine for some countries
+    # like US, Canada, Australia but not other countries (presumably).
+    #
+    # TODO: Put postal code and city in a different order, as that countries conventions dictate.
+    # See http://bitboost.com/ref/international-address-formats/new-zealand/
+    #
+    def city_line
+      [
+        #[city, state].reject(&:blank?).join(', '),
+        [city, state_for_postal_address].reject(&:blank?).join(', '),
+        postal_code,
+      ].reject(&:blank?).join(' ')
+    end
+
+    def city_state_code
+      [city, state].reject(&:blank?).join(', ')
+    end
+
+    def city_state_name
+      [city, state_name].reject(&:blank?).join(', ')
+    end
+
+    def city_state_country
+      [city_state_name, country_name].join(', ')
+    end
+
+    def state_for_postal_address
+      # Possibly others use a code? But seems safer to default to a name until confirmed that they use
+      # a code.
+      if country_name.in? ['United States', 'Canada', 'Australia']
+        state_code
+      elsif state_possibly_included_in_postal_address?
+        state_name
+      else
+        ''
+      end
+    end
+
+    #════════════════════════════════════════════════════════════════════════════════════════════════════
+    # Misc. output
+
+    def parts
+      [
+        name,
+        address.to_s.lines.to_a,
+        city,
+        state_name,
+        postal_code,
+        country_name,
+      ].flatten.reject(&:blank?)
+    end
+
+    def inspect
+      inspect_with([:id, :name, :address, :city, :state, :postal_code, :country], ['{', '}'])
+    end
+
+    #-------------------------------------------------------------------------------------------------
+  end
+end