has_addresses 0.0.2 → 0.5.0

data/CHANGELOG.rdoc

@@ -0,0 +1,50 @@
+== master
+
+== 0.5.0 / 2009-04-30
+
+* Replace acts_as_enumeration with enumerate_by
+* Add dependency on Rails 2.3
+
+== 0.4.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+
+== 0.3.0 / 2008-10-26
+
+* Add mass-assignment protection in the Address model
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.2.1 / 2008-06-22
+
+* Remove log files from gems
+
+== 0.2.0 / 2008-06-22
+
+* Fix incorrect regions being listed for most countries
+* Use an id scheme for regions based on the id of the country to prevent id clashing in future updates
+* Improve performance by not requiring that the country be looked up for every new region created
+* Index region enumerations by their ISO code
+* Use common display names for countries, rather than the default specified in the standard; use the official name if needed
+* Organize country enumerations by id
+* Index country enumerations by their alpha 2 code
+
+== 0.1.0 / 2008-05-05
+
+* Convert Country/Region to enumerations
+* Add dependency on acts_as_enumeration
+* Update documentation to reflect plugins_plus changes
+
+== 0.0.2 / 2007-09-26
+
+* Move test fixtures out of the test application root directory
+
+== 0.0.1 / 2007-08-21
+
+* 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 → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2007 Aaron Pfeifer & Neil Abraham
+Copyright (c) 2006-2009 Aaron Pfeifer
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,63 @@
+= has_addresses
+
++has_addresses+ demonstrates a reference implementation for handling countries,
+regions, and addresses.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/has_addresses
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13271-has_addresses
+
+Development
+
+* http://github.com/pluginaweek/has_addresses
+
+Source
+
+* git://github.com/pluginaweek/has_addresses.git
+
+== 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.
+
+== Usage
+
+Note that this is a reference implementation and, most likely, should be
+modified for your own usage.
+
+=== Example
+
+  address = Address.new(
+    :street_1 => '1600 Amphitheatre Parkway',
+    :city => 'Mountain View',
+    :region => 'US-CA',
+    :postal_code => '94043'
+  )
+  address.single_line # => "1600 Amphitheatre Parkway, Mountain View, California  94043, United States"
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.3 or later
+* enumerate_by[http://github.com/pluginaweek/enumerate_by]

data/Rakefile

@@ -3,48 +3,55 @@ 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.2'
-PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
-RUBY_FORGE_PROJECT = 'pluginaweek'
-
-desc 'Default: run unit tests.'
+spec = Gem::Specification.new do |s|
+  s.name              = 'has_addresses'
+  s.version           = '0.5.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Demonstrates a reference implementation for handling countries, regions, and addresses.'
+  
+  s.files             = FileList['{app,db,lib,test}/**/*']  + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  s.add_dependency    'enumerate_by', '>= 0.4.0'
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
 task :default => :test
 
-desc 'Test the has_addresses plugin.'
+desc "Test the #{spec.name} plugin."
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
-  t.pattern = 'test/unit/**/*_test.rb'
+  t.test_files = spec.test_files
   t.verbose = true
 end
 
-desc 'Generate documentation for the has_addresses plugin.'
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/|app/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'HasAddresses'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
   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'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb', 'app/**/*.rb')
 end
   
 Rake::GemPackageTask.new(spec) do |p|
@@ -53,30 +60,30 @@ Rake::GemPackageTask.new(spec) do |p|
   p.need_zip = true
 end
 
-desc 'Publish the beta gem'
+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
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
 end
 
-desc 'Publish the API documentation'
+desc 'Publish the API documentation.'
 task :pdoc => [:rdoc] do
-  Rake::SshDirPublisher.new('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
 end
 
 desc 'Publish the API docs and gem'
-task :publish => [:pdoc, :release]
+task :publish => [:pgem, :pdoc, :release]
 
 desc 'Publish the release files to RubyForge.'
 task :release => [:gem, :package] do
   require 'rubyforge'
   
-  ruby_forge = RubyForge.new
+  ruby_forge = RubyForge.new.configure
   ruby_forge.login
   
-  %w( gem tgz zip ).each do |ext|
-    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
     puts "Releasing #{File.basename(file)}..."
     
-    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
   end
 end

data/app/models/address.rb

@@ -1,43 +1,84 @@
-# Represents a mailing address
+# Represents a generic mailing address. Addresses are expected to consist of
+# the following fields:
+# * +addressable+ - The record that owns the address
+# * +street_1+ - The first line of the street address
+# * +city+ - The name of the city
+# * +postal_code+ - A value uniquely identifying the area in the city
+# * +region+ - Either a known region or a custom value for countries that have no list of regions available
+# * +country+ - The country, which may be implied by the region
+# 
+# The following fields are optional:
+# * +street_2+ - The second line of the street address
+# 
+# There is no attempt to validate open-ended fields since the context in which
+# the addresses will be used is unknown
 class Address < ActiveRecord::Base
-  belongs_to  :addressable,
-                :polymorphic => true
-  belongs_to  :region
-  belongs_to  :country
+  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
+  validates_presence_of :addressable_id, :addressable_type, :street_1, :city,
+                        :postal_code, :country_id
+  validates_presence_of :region_id, :if => :known_region_required?
+  validates_presence_of :custom_region, :if => :custom_region_required?
   
-  before_save :ensure_exclusive_references
+  attr_accessible :street_1, :street_2, :city, :postal_code, :region,
+                  :custom_region, :country
   
-  # 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
+  before_validation :ensure_exclusive_references, :set_region_attributes
   
-  # Gets the name of the region that this address is for (whether it is a custom or
-  # stored region in the database)
+  # Gets the name of the region that this address is for (whether it is a
+  # custom or known region in the database)
   def region_name
-    custom_region || (region ? region.name : nil)
+    custom_region || region && region.name
   end
   
-  # Gets the value of the address on a single line
+  # Gets a representation of the address on a single line.
+  # 
+  # For example,
+  # 
+  #   address = Address.new
+  #   address.single_line     # => ""
+  #   
+  #   address.street_1 = "1600 Amphitheatre Parkey"
+  #   address.single_line     # => "1600 Amphitheatre Parkway"
+  #   
+  #   address.street_2 = "Suite 100"
+  #   address.single_line     # => "1600 Amphitheatre Parkway, Suite 100"
+  #   
+  #   address.city = "Mountain View"
+  #   address.single_line     # => "1600 Amphitheatre Parkway, Suite 100, Mountain View"
+  #   
+  #   address.region = Region['US-CA']
+  #   address.single_line     # => "1600 Amphitheatre Parkway, Suite 100, Mountain View, California, United States"
+  #   
+  #   address.postal_code = '94043'
+  #   address.single_line     # => "1600 Amphitheatre Parkway, Suite 100, Mountain View, California  94043, United States"
   def single_line
     multi_line.join(', ')
   end
   
-  # Gets the value of the address on multiple lines
+  # Gets a representation of the address on multiple lines.
+  # 
+  # For example,
+  # 
+  #   address = Address.new
+  #   address.multi_line      # => []
+  #   
+  #   address.street_1 = "1600 Amphitheatre Parkey"
+  #   address.multi_line      # => ["1600 Amphitheatre Parkey"]
+  #   
+  #   address.street_2 = "Suite 100"
+  #   address.multi_line      # => ["1600 Amphitheatre Parkey", "Suite 100"]
+  #   
+  #   address.city = "Mountain View"
+  #   address.multi_line      # => ["1600 Amphitheatre Parkey", "Suit 100", "Mountain View"]
+  #   
+  #   address.region = Region['US-CA']
+  #   address.multi_line      # => ["1600 Amphitheatre Parkey", "Suit 100", "Mountain View, California", "United States"]
+  #   
+  #   address.postal_code = '94043'
+  #   address.multi_line      # => ["1600 Amphitheatre Parkey", "Suit 100", "Mountain View, California  94043", "United States"]
   def multi_line
     lines = []
     lines << street_1 if street_1?
@@ -46,39 +87,40 @@ class Address < ActiveRecord::Base
     line = ''
     line << city if city?
     if region_name
-      line << ', ' if !line.blank?
+      line << ', ' unless line.blank?
       line << region_name
     end
     if postal_code?
-      line << '  ' if !line.blank?
+      line << '  ' unless line.blank?
       line << postal_code
     end
-    lines << line if !line.blank?
+    lines << line unless 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
+    # Does the current country have a list of regions to choose from?
+    def known_region_required?
+      !country || country.regions.any?
     end
     
-    true
-  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 && country && country.regions.empty?
+    end
+    
+    # Ensures that the custom region is not set at the same time as the known
+    # region
+    def ensure_exclusive_references
+      self.custom_region = nil if known_region_required?
+    end
+    
+    # Sets the attributes on the address based on the region (if available)
+    def set_region_attributes
+      self.country = region.country if region
+    end
 end