has_addresses 0.0.1

data/CHANGELOG

@@ -0,0 +1,19 @@
+*SVN*
+
+*0.0.1* (August 21st, 2007)
+
+* Add documentation
+
+* Add descriptive output for rake tasks
+
+* Remove dependency on has_association_helper
+
+* Remove default bootstrap files in favor of creating new ones through the bootstrap tasks
+
+* Add tests for rake tests
+
+* Fix not allowing single character abbreviations for regions
+
+* Add countries:create_fixtures, countries:bootstrap, regions:create_fixtures, and regions:bootstrap files
+
+* Refactor Rake code into Country/Region classes

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2007 Aaron Pfeifer & Neil Abraham
+
+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/README

@@ -0,0 +1,111 @@
+= has_addresses
+
+has_addresses adds a base skeleton for handling countries, regions, and
+addresses.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/has_addresses
+
+Wiki
+
+* http://wiki.pluginaweek.org/Has_addresses
+
+Announcement
+
+* http://www.pluginaweek.org/
+
+Source
+
+* http://svn.pluginaweek.org/trunk/plugins/active_record/has/has_addresses
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/plugins/active_record/has/has_addresses
+
+== Description
+
+Countries, regions, and addresses are all simple models whose data and
+functionality should be able to be standardized across multiple applications.
+has_addresses adds support for countries and regions based on the ISO 3166 and
+ISO 3166-2 standard.  The data for these standards is obtained through the
+open-source Debian package, iso-codes.
+
+Along with the simple Country and Region models, addresses can be defined and
+integrated based on the data in these models.  Addresses are minimalistic in
+terms of the type of data required and follows the standard U.S. format.
+
+=== Running migrations
+
+To migrate the tables required for has_addresses, you can either run the
+migration from the command line like so:
+
+  rake db:migrate:plugins PLUGIN=has_addresses
+
+or (more ideally) generate a migration file that will integrate into your main
+application's migration path:
+
+  ruby script/generate plugin_migration MigrateHasAddressesToVersion3
+
+=== Bootstrapping the database
+
+has_addresses comes bundled with tasks for bootstrapping the countries and
+regions table based on the ISO 3166 and ISO 3166-2 standard.  You can bootstrap
+the database using built-in rake tasks or by creating fixtures which contain the
+bootstrap data.
+
+To bootstrap country/region data into the current database schema:
+
+  $ rake countries:bootstrap
+  (in /my/project)
+  Downloading ISO 3166 data...
+  Parsing countries...
+  Loading countries into database...
+  Done!
+  
+  $ rake regions:bootstrap
+  Downloading ISO 3166 data...
+  Parsing countries...
+  Downloading ISO 3166-2 data...
+  Parsing regions...
+  Loading regions into database...
+  Done!
+
+To create fixtures for the country/region bootstrap data:
+
+  $ rake countries:create_fixtures
+  (in /my/project)
+  Downloading ISO 3166 data...
+  Parsing countries...
+  Saving countries to /my/project/config/../db/bootstrap/countries.yml...
+  Done!
+  
+  $ rake regions:create_fixtures
+  (in /my/project)
+  Downloading ISO 3166 data...
+  Parsing countries...
+  Downloading ISO 3166-2 data...
+  Parsing regions...
+  Saving regions to /my/project/config/../db/bootstrap/regions.yml...
+  Done!
+
+== Testing
+
+Since the rake tasks for installing TinyMCE and updating the configuration
+options are part of the unit tests, already-downloaded files are included with
+the plugin.  If you want to perform a "live" test which actually downloads the
+files off the Internet (rather than using the local versions), you must set
+the LIVE environment variable to true.  For example,
+
+  rake test LIVE=true
+
+The following plugins/gems must be installed before any tests can be run:
+* plugin_dependencies - http://wiki.pluginaweekk.org/Plugin_dependencies
+* loaded_plugins - http://wiki.pluginaweek.org/Loaded_plugins
+* appable_plugins - http://wiki.pluginaweek.org/Appable_plugins
+
+== Dependencies
+
+This plugin does not depend on the presence of any other plugin.

data/Rakefile

@@ -0,0 +1,82 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+# Load custom rakefile extensions
+Dir["#{File.dirname(__FILE__)}/tasks/**/*.rake"].sort.each {|ext| load ext}
+
+PKG_NAME           = 'has_addresses'
+PKG_VERSION        = '0.0.1'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the has_addresses plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/unit/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the has_addresses plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HasAddresses'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds a base skeleton for handling countries, regions, and addresses.'
+  
+  s.files           = FileList['{app,db,lib,tasks,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'has_addresses'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/unit/**/*_test.rb']
+  
+  s.author          = 'Aaron Pfeifer, Neil Abraham'
+  s.email           = 'info@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('pluginaweek@pluginaweek.org', '/home/pluginaweek/gems.pluginaweek.org/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/app/models/address.rb

@@ -0,0 +1,84 @@
+# Represents a mailing address
+class Address < ActiveRecord::Base
+  belongs_to            :addressable,
+                          :polymorphic => true
+  belongs_to            :region
+  belongs_to            :country
+  
+  validates_presence_of :addressable_id,
+                        :addressable_type,
+                        :street_1,
+                        :city,
+                        :postal_code
+  validates_presence_of :region_id,
+                          :if => :known_region_required?
+  validates_presence_of :custom_region,
+                          :if => :custom_region_required?
+  validates_format_of   :postal_code,
+                          :with => /^[0-9]{5}$/,
+                          :allow_nil => true
+  
+  before_save           :ensure_exclusive_references
+  
+  # Returns the region's country if the region is specified
+  def country_with_region_check
+    region ? region.country : country_without_region_check
+  end
+  alias_method_chain :country, :region_check
+  
+  # Gets the name of the region that this address is for (whether it is a custom or
+  # stored region in the database)
+  def region_name
+    custom_region || (region ? region.name : nil)
+  end
+  
+  # Gets the value of the address on a single line
+  def single_line
+    multi_line.join(', ')
+  end
+  
+  # Gets the value of the address on multiple lines
+  def multi_line
+    lines = []
+    lines << street_1 if street_1?
+    lines << street_2 if street_2?
+    
+    line = ''
+    line << city if city?
+    if region_name
+      line << ', ' if !line.blank?
+      line << region_name
+    end
+    if postal_code?
+      line << '  ' if !line.blank?
+      line << postal_code
+    end
+    lines << line if !line.blank?
+    
+    lines << country.name if country
+    lines
+  end
+  
+  private
+  def known_region_required?
+    country.nil? || country.regions.count != 0
+  end
+  
+  # A custom region name is required if a known region was not specified and
+  # the country in which this address resides has no known regions in the
+  # database
+  def custom_region_required?
+    region_id.nil? && country && country.regions.count == 0
+  end
+  
+  # Ensures that the country id/user region combo is not set at the same time as
+  # the region id
+  def ensure_exclusive_references
+    if known_region_required?
+      self.country_id = nil
+      self.custom_region = nil
+    end
+    
+    true
+  end
+end

data/app/models/country.rb

@@ -0,0 +1,114 @@
+require 'open-uri'
+require 'cgi'
+require 'rexml/document'
+
+# Defined by the ISO 3166 standard.  The ISO 3166 standard includes a
+# "Country Subdivision Code", giving a code for the names of the principal
+# administrative subdivisions of the countries coded in ISO 3166.
+class Country < ActiveRecord::Base
+  # The url of the open source version of the ISO 3166 standard
+  ISO_3166_URL = 'http://svn.debian.org/wsvn/pkg-isocodes/trunk/iso-codes/iso_3166/iso_3166.xml?op=file'
+  
+  class << self
+    # Creates a fixtures file containing all possible countries
+    def create_fixtures(output_file_path = nil)
+      output_file_path ||= 'db/bootstrap/countries.yml'
+      output_file_path = File.join(RAILS_ROOT, output_file_path)
+      
+      FileUtils.mkdir_p(File.dirname(output_file_path))
+      output_file = File.new(output_file_path, File::CREAT|File::TRUNC|File::RDWR)
+      output = ''
+      
+      countries = download_all
+      puts "Saving countries to #{output_file_path}..." if PluginAWeek::Has::Addresses.verbose
+      countries.each do |country|
+        record_name = country.name.gsub(' ', '_').gsub(/[^A-Za-z_]/, '').downcase
+        
+        output << "#{record_name}:\n"
+        country.attributes.each do |attr, value|
+          output << "  #{attr}: #{value}\n" if value
+        end
+      end
+      
+      output_file << output.slice(0..output.length-2)
+      output_file.close
+      
+      puts 'Done!' if PluginAWeek::Has::Addresses.verbose
+      true
+    end
+    
+    # Bootstraps the table by downloading the latest ISO 3166 standard and
+    # saving each country to the database
+    def bootstrap
+      countries = download_all
+      
+      puts 'Loading countries into database...' if PluginAWeek::Has::Addresses.verbose
+      delete_all
+      countries.each {|country| country.save!}
+      
+      puts 'Done!' if PluginAWeek::Has::Addresses.verbose
+      true
+    end
+    
+    # Downloads the latest ISO 3166 standard and returns the data as a list of
+    # countries
+    def download_all
+      # Download the standard
+      puts 'Downloading ISO 3166 data...' if PluginAWeek::Has::Addresses.verbose
+      iso_3166 = open(ISO_3166_URL).readlines * "\n"
+      iso_3166 = CGI::unescapeHTML(/<pre>(.+)<\/pre>/im.match(iso_3166)[1].gsub('&nbsp;', ''))
+      
+      # Parse and load the countries
+      puts 'Parsing countries...' if PluginAWeek::Has::Addresses.verbose
+      countries = []
+      REXML::Document.new(iso_3166).elements.each('*/iso_3166_entry') do |country|
+        name = country.attributes['name'].to_s.gsub("'","\\'")
+        official_name = country.attributes['official_name']
+        official_name = official_name.to_s.gsub!("'", "\\'") if official_name
+        alpha_2_code = country.attributes['alpha_2_code'].to_s.upcase
+        alpha_3_code = country.attributes['alpha_3_code'].to_s.upcase
+        country_id = country.attributes['numeric_code'].to_s.to_i
+        record_name = name.gsub(' ', '_').gsub(/[^A-Za-z_]/, '').downcase
+        
+        country = new(
+          :name => name,
+          :official_name => official_name,
+          :alpha_2_code => alpha_2_code,
+          :alpha_3_code => alpha_3_code
+        )
+        country.id = country_id
+        countries << country
+      end
+      
+      countries
+    end
+  end
+  
+  has_many  :regions
+  
+  validates_presence_of   :name,
+                          :alpha_2_code,
+                          :alpha_3_code
+  validates_uniqueness_of :name,
+                          :alpha_2_code,
+                          :alpha_3_code
+  validates_length_of     :name,
+                            :within => 2..80
+  validates_length_of     :alpha_2_code,
+                            :is => 2
+  validates_length_of     :alpha_3_code,
+                            :is => 3
+  
+  alias_attribute :abbreviation_2, :alpha_2_code
+  alias_attribute :abbreviation_3, :alpha_3_code
+  
+  # The official name of the country
+  def official_name
+    read_attribute(:official_name) || name
+  end
+  
+  # Returns the name of the country
+  def to_s #:nodoc
+    name
+  end
+end

data/app/models/region.rb

@@ -0,0 +1,112 @@
+require 'open-uri'
+require 'cgi'
+require 'rexml/document'
+
+# Defined by the ISO 3166-2 standard.  This is a standard that gives short codes
+# for provinces, etc. within a country.
+class Region < ActiveRecord::Base
+  # The url of the open source version of the ISO 3166-2 standard
+  ISO_3166_2_URL = 'http://svn.debian.org/wsvn/pkg-isocodes/trunk/iso-codes/iso_3166/iso_3166_2/iso_3166_2.xml?op=file'
+  
+  class << self
+    # Creates a fixtures containing all possible regions
+    def create_fixtures(output_file_path = nil)
+      output_file_path ||= 'db/bootstrap/regions.yml'
+      output_file_path = File.join(RAILS_ROOT, output_file_path)
+      
+      FileUtils.mkdir_p(File.dirname(output_file_path))
+      output_file = File.new(output_file_path, File::CREAT|File::TRUNC|File::RDWR)
+      output = ''
+      
+      regions = download_all
+      puts "Saving regions to #{output_file_path}..." if PluginAWeek::Has::Addresses.verbose
+      regions.each do |region|
+        record_name = region.name.gsub(' ', '_').gsub(/[^A-Za-z_]/, '').downcase
+        
+        output << "#{record_name}:\n"
+        region.attributes.each do |attr, value|
+          output << "  #{attr}: #{value}\n" if value
+        end
+      end
+      
+      output_file << output.slice(0..output.length-2)
+      output_file.close
+      
+      puts 'Done!' if PluginAWeek::Has::Addresses.verbose
+      true
+    end
+    
+    # Bootstraps the table by downloading the latest ISO 3166-2 standard and
+    # saving each region to the database
+    def bootstrap
+      regions = download_all
+      
+      puts 'Loading regions into database...' if PluginAWeek::Has::Addresses.verbose
+      delete_all
+      regions.each {|region| region.save!}
+      
+      puts 'Done!' if PluginAWeek::Has::Addresses.verbose
+      true
+    end
+    
+    # Downloads the latest ISO 3166-2 standard and returns the data as a list of
+    # regions
+    def download_all
+      countries = Country.download_all
+      alpha_2_code_to_country = Hash[*countries.collect {|c| [c.alpha_2_code, c]}.flatten]
+      
+      # Download the standard
+      puts 'Downloading ISO 3166-2 data...' if PluginAWeek::Has::Addresses.verbose
+      iso_3166_2 = open(ISO_3166_2_URL).readlines * "\n"
+      iso_3166_2 = CGI::unescapeHTML(/<pre>(.+)<\/pre>/im.match(iso_3166_2)[1].gsub('&nbsp;', ''))
+      
+      # Parse and load the regions
+      puts 'Parsing regions...' if PluginAWeek::Has::Addresses.verbose
+      region_id = 1
+      regions = []
+      REXML::Document.new(iso_3166_2).elements.each('*/iso_3166_country') do |country|
+        code = country.attributes['code'][0..1] # Belarius is more than 2 characters for some reason, so just get the first 2
+        country_record = alpha_2_code_to_country[code.upcase]
+        
+        country.elements.each('iso_3166_2_entry') do |region|
+          name = region.attributes['name'].to_s.gsub("'","\\'").strip
+          abbreviation = region.attributes['code'].upcase.sub("#{code}-", '')
+          
+          region = new(
+            :country_id => country_record.id,
+            :name => name,
+            :abbreviation => abbreviation
+          )
+          region.id = region_id
+          
+          if !country_record.regions.any? {|known_region| known_region.name == region.name}
+            regions << region
+            country_record.regions << region 
+            region_id += 1
+          end
+        end
+      end
+      
+      regions
+    end
+  end
+  
+  belongs_to  :country
+  has_many    :addresses
+  
+  validates_presence_of   :name,
+                          :country_id,
+                          :abbreviation
+  validates_length_of     :name,
+                            :within => 2..80
+  validates_length_of     :abbreviation,
+                            :within => 1..5
+  validates_uniqueness_of :name,
+                            :scope => :country_id
+  validates_uniqueness_of :abbreviation,
+                            :scope => :country_id
+  
+  def to_s #:nodoc
+    name
+  end
+end

data/db/migrate/001_create_countries.rb

@@ -0,0 +1,17 @@
+class CreateCountries < ActiveRecord::Migration
+  def self.up
+    create_table :countries do |t|
+      t.column :name, :string, :null => false, :limit => 80
+      t.column :official_name, :string, :limit => 80
+      t.column :alpha_2_code, :string, :null => false, :limit => 2
+      t.column :alpha_3_code, :string, :null => false, :limit => 3
+    end
+    add_index :countries, :name, :unique => true
+    add_index :countries, :alpha_2_code, :unique => true
+    add_index :countries, :alpha_3_code, :unique => true
+  end
+  
+  def self.down
+    drop_table :countries
+  end
+end

data/db/migrate/002_create_regions.rb

@@ -0,0 +1,15 @@
+class CreateRegions < ActiveRecord::Migration
+  def self.up
+    create_table :regions do |t|
+      t.column :country_id, :integer, :null => false
+      t.column :name, :string, :null => false, :limit => 50
+      t.column :abbreviation, :string, :null => false, :limit => 5
+    end
+    add_index :regions, [:name, :country_id], :unique => true
+    add_index :regions, [:abbreviation, :country_id], :unique => true
+  end
+  
+  def self.down
+    drop_table :regions
+  end
+end

data/db/migrate/003_create_addresses.rb

@@ -0,0 +1,21 @@
+class CreateAddresses < ActiveRecord::Migration
+  def self.up
+    create_table :addresses do |t|
+      t.column :addressable_id, :integer, :null => false, :references => nil
+      t.column :addressable_type, :string, :null => false
+      t.column :street_1, :string, :null => false, :limit => 100
+      t.column :street_2, :string, :limit => 100
+      t.column :city, :string, :null => false, :limit => 255
+      t.column :region_id, :integer
+      t.column :custom_region, :string, :limit => 50
+      t.column :postal_code, :string, :null => false, :limit => 5
+      t.column :country_id, :integer, :default => 223
+      t.column :created_at, :timestamp, :null => false
+      t.column :updated_at, :datetime, :null => false
+    end
+  end
+  
+  def self.down
+    drop_table :addresses
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'has_addresses'

data/lib/has_addresses.rb

@@ -0,0 +1,74 @@
+module PluginAWeek #:nodoc:
+  module Has #:nodoc:
+    # Adds base models for interacting with addresses, including Country,
+    # Region, and Address.  These have the minimal attribute definitions needed
+    # to store addresses.
+    module Addresses
+      # Whether or not to use verbose output
+      mattr_accessor :verbose
+      @@verbose = true
+      
+      def self.included(base) #:nodoc:
+        base.extend(MacroMethods)
+      end
+      
+      module MacroMethods
+        # Creates a new association for having a single address.  This takes
+        # the same parameters as ActiveRecord::Associations::ClassMethods#has_one.
+        # By default, the following associations are the same:
+        # 
+        #   class Person < ActiveRecord::Base
+        #     has_address
+        #   end
+        # 
+        # and
+        # 
+        #   class Person < ActiveRecord::Base
+        #     has_one :address,
+        #               :class_name => 'Address',
+        #               :as => :addressable,
+        #               :dependent => :destroy
+        #   end
+        def has_address(*args, &extension)
+          create_address_association(:one, :address, *args, &extension)
+        end
+        
+        # Creates a new association for having a multiple addresses.  This takes
+        # the same parameters as ActiveRecord::Associations::ClassMethods#has_many.
+        # By default, the following associations are the same:
+        # 
+        #   class Person < ActiveRecord::Base
+        #     has_addresses
+        #   end
+        # 
+        # and
+        # 
+        #   class Person < ActiveRecord::Base
+        #     has_many  :addresses,
+        #                 :class_name => 'Address',
+        #                 :as => :addressable,
+        #                 :dependent => :destroy
+        #   end
+        def has_addresses(*args, &extension)
+          create_address_association(:many, :addresses, *args, &extension)
+        end
+        
+        private
+        def create_address_association(cardinality, association_id, *args, &extension)
+          options = extract_options_from_args!(args)
+          options.symbolize_keys!.reverse_merge!(
+            :class_name => 'Address',
+            :as => :addressable,
+            :dependent => :destroy
+          )
+          
+          send("has_#{cardinality}", args.first || association_id, options, &extension)
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include PluginAWeek::Has::Addresses
+end