yolk-biggs 0.1.0

data/README.textile

@@ -0,0 +1,139 @@
+biggs is a small ruby gem/rails plugin for formatting postal addresses from over 60 countries.
+
+h3. Install
+
+As a ruby gem:
+   
+   sudo gem install yolk-biggs
+   
+If your rather prefer to install it as a plugin for rails, from your application directory simply run:
+   
+   script/plugin install git://github.com/yolk/biggs.git
+
+h3. Standalone usage
+   
+   f = Biggs::Formatter.new
+   
+   f.format(
+      :recipient  => "Yolk Sebastian Munz & Julia Soergel GbR", 
+      :street     => "Adalbertstr. 11", # <= street + house number
+      :city       => "Berlin",
+      :zip        => 10999,
+      :state      => "Berlin", # <= state/province/region
+      :country    => "de" # <= ISO alpha 2 code
+   )
+
+returns
+   
+   "Yolk Sebastian Munz & Julia Soergel GbR
+   Adalbertstr. 11
+   10999 Berlin
+   Germany"
+   
+At the moment Biggs::Formatter.new accepts only one option:
+
+*blank_county_on* ISO alpha 2 code (single string or array) of countries the formatter should skip the line "country" (for national shipping).
+   
+   f = Biggs::Formatter.new(:blank_county_on => "de")
+   
+With the data from the above example this would return:
+
+   "Yolk Sebastian Munz & Julia Soergel GbR
+   Adalbertstr. 11
+   10999 Berlin"
+
+h3. Usage with Rails and ActiveRecord
+
+   Address < ActiveRecord::Base
+      biggs :postal_address
+   end
+   
+This adds the method postal_address to your Address-model, and assumes the presence of the methods/columns recipient, street, city, zip, state, and country to get the address data. Country should return the ISO-code (e.g. 'us', 'fr', 'de'). 
+
+You can customize the method-names biggs will use by passing in a hash of options:
+   
+   Address < ActiveRecord::Base
+      biggs :postal_address, 
+            :zip => :postal_code,
+            :country => :country_code,
+            :street => Proc.new {|address| "#{address.street} #{address.house_number}" }
+   end
+   
+You can pass in a symbol to let biggs call a different method on your Address-model, or a Proc-object to create your data on the fly.
+
+To access the formatted address string, simply call the provided method on an address instance:
+
+   Address.find(1).postal_address
+   
+If you pass in a ISO alpha 2 code as :country that is not supported by biggs, it will choose the US-format for addresses with an state specified, and the french/german format for addresses without an state.
+   
+h3. Supported countries
+
+biggs knows how to format addresses of over 60 different countries. If you are missing one or find an misstake, feel free to let us know, fork this repository and commit your additions.
+
+* Argentina
+* Australia
+* Austria
+* Bahrain
+* Belgium
+* Bosnia and Herzegovina
+* Brazil
+* Bulgaria
+* Canada
+* China
+* Croatia
+* Czech
+* Denmark
+* Egypt
+* Finland
+* France
+* Germany
+* Greece
+* Greenland
+* Hong Kong
+* Hungary
+* Iceland
+* India
+* Indonesia
+* Ireland
+* Israel
+* Italy
+* Japan
+* Jordan
+* Kuwait
+* Lebanon
+* Luxembourg
+* Macedonia
+* Mexico
+* Netherlands
+* New Zealand
+* Norway
+* Oman
+* Philippines
+* Poland
+* Portugal
+* Qatar
+* Romania
+* Russian Federation
+* Saudi Arabia
+* Serbia and Montenegro
+* Singapore
+* Slovakia
+* Slovenia
+* South Africa
+* South Korea
+* Spain
+* Sweden
+* Switzerland
+* Syrian Arab Republic
+* Taiwan
+* Turkey
+* Ukraine
+* United Arab Emirates
+* United Kingdom
+* United States
+* Yemen
+
+biggs is tested to behave well with Rails 2.2.2.
+
+Copyright (c) 2009 Yolk Sebastian Munz & Julia Soergel GbR

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 1

data/lib/biggs/activerecord.rb

@@ -0,0 +1,64 @@
+module Biggs
+  module ActiveRecordAdapter
+    
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      def biggs_value_methods
+        read_inheritable_attribute(:biggs_value_methods) || write_inheritable_attribute(:biggs_value_methods, {})
+      end
+      
+      def biggs_instance
+        read_inheritable_attribute(:biggs_formatter) || write_inheritable_attribute(:biggs_formatter, Biggs::Formatter.new)
+      end
+      
+      def biggs(method_name=nil, options={})
+        self.send(:include, Biggs::ActiveRecordAdapter::InstanceMethods)
+        alias_method(method_name || :postal_address, :biggs_postal_address)
+        
+        value_methods = {}
+        Biggs::Formatter::FIELDS.each do |field|
+          value_methods[field] = options.delete(field) if options[field]
+        end
+        write_inheritable_attribute(:biggs_value_methods, value_methods)
+        write_inheritable_attribute(:biggs_formatter, Biggs::Formatter.new(options))
+      end
+    end
+    
+    module InstanceMethods
+      
+      def biggs_postal_address
+        self.class.biggs_instance.format(biggs_country, biggs_values)
+      end
+    
+      private
+    
+      def biggs_country
+        biggs_get_value(:country)
+      end
+    
+      def biggs_values
+        values = {}
+        (Biggs::Formatter::FIELDS - [:country]).each do |field|
+          values[field] = biggs_get_value(field)
+        end
+        values
+      end
+      
+      def biggs_get_value(field)
+        key = self.class.biggs_value_methods[field.to_sym] || field.to_sym
+        
+        case key
+        when Symbol, String
+          self.send(key.to_sym)
+        when Proc
+          key.call(self).to_s
+        else
+          raise "Biggs: Can't handle #{field} type #{key.class}"
+        end
+      end
+    end
+  end
+end

data/lib/biggs/formatter.rb

@@ -0,0 +1,42 @@
+module Biggs
+  class Formatter
+    
+    FIELDS = [:recipient, :street, :city, :state, :zip, :country]
+    
+    def initialize(options={})
+      @blank_country_on = [options[:blank_country_on]].compact.flatten.map{|s| s.to_s.downcase}
+    end
+  
+    def format(country_code, values={})
+      values.symbolize_keys! if values.respond_to?(:symbolize_keys!)
+      country_code = country_code.dup.to_s.downcase
+    
+      country_entry = (Biggs.formats[country_code] || default_country_entry(country_code, values))
+      country_name = (country_entry["name"].dup || "").to_s
+      country_format = (country_entry["format"].dup || "").to_s
+    
+      (FIELDS - [:country]).each do |key|
+        country_format.gsub!(/\{\{#{key}\}\}/, (values[key] || "").to_s)
+      end
+    
+      country_name = "" if blank_country_on.include?(country_code)
+      country_format.gsub!(/\{\{country\}\}/, country_name)
+    
+      country_format.gsub(/\n$/,"")
+    end
+  
+    attr_accessor :blank_country_on, :default_country_without_state, :default_country_with_state
+  
+    private
+  
+    def default_country_entry(country_code, values={})
+      {
+        "name" => country_code.to_s,
+        "format" => (values[:state] && values[:state] != "" ?
+                  Biggs.formats[default_country_with_state || "us"] :
+                  Biggs.formats[default_country_without_state || "fr"])["format"]
+      }
+    end
+  end
+  
+end

data/lib/biggs.rb

@@ -0,0 +1,20 @@
+require 'biggs/formatter'
+
+module Biggs
+  class << self
+    def formats
+      @@formats ||= YAML.load_file(File.join(File.dirname(__FILE__), '..', 'formats.yml')) || {}
+    end
+    
+    def enable_activerecord
+      return if ActiveRecord::Base.respond_to? :biggs_formatter
+      require 'biggs/activerecord'
+      ActiveRecord::Base.send :include, Biggs::ActiveRecordAdapter
+    end
+  end
+end
+
+if defined?(ActiveRecord) and defined?(ActiveRecord::Base)
+  Biggs.enable_activerecord
+end
+

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: yolk-biggs
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Sebastian Munz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-03 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: biggs is a small ruby tool to format postal addresses from over 60 countries. Use it as a standalone ruby gem or as a plugin for Rails.
+email: sebastian@yo.lk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.textile
+- VERSION.yml
+- lib/biggs
+- lib/biggs/activerecord.rb
+- lib/biggs/formatter.rb
+- lib/biggs.rb
+has_rdoc: true
+homepage: http://github.com/yolk/biggs
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: biggs is a small ruby tool to format postal addresses from over 60 countries. Use it as a standalone ruby gem or as a plugin for Rails.
+test_files: []
+