worldly 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6068b30844d8b8b46ec7d1ba870ae785add189d7
+  data.tar.gz: dcde25b22092ed67cb06b4d5bafe5aefa0294238
+SHA512:
+  metadata.gz: 7b96e40b4b799578925f67867d50833f407ad5bef8f22e099d82ac4b2d3958403a5da963025f387c90d8119e1b1a06d5aca19f0e606713e78c2e4fb0fdceac63
+  data.tar.gz: e8babb37f54b270905a66b2f948fc9a6162bc19d9921370e3eb2a51a0260c49e36a0e79e16e2c9aa7ba4eab4aad46bb3d43cb8cef1daa6e8f30d4b6d7db8c885

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in worldly.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 danlewis
+
+MIT License
+
+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.md

@@ -0,0 +1,113 @@
+# Worldly
+
+Worldly provides information on countries for the purpose of address formatting and local naming
+Additional information on country phone number conventions is available.
+
+The gem aims to be small with no dependencies.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'worldly'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install worldly
+
+## Usage
+
+Worldly has a Country class which can be used to access address and telephone information for countries.
+
+Get all countries:
+```
+  Worldly::Country.all  => [["Afghanistan", "AF"], ["Albania", "AL"], ["Algeria", "DZ"],....]
+```
+Check if a country exists?
+```
+  Worldly::Country.exists?('AU')  => true
+```  
+### Working with a Country
+
+Retrieve a country using it's country code
+```
+  country = Worldly::Country['AU']  => #<Worldly::Country:0x007fa48239ee90 @code="AU", @data={:name=>"Australia", :alpha2=>"AU", :alpha3=>"AUS", :country_code=>"61", :fields=>{:city=>{:label=>"City", :format=>["upcase"]}, :region=>{:label=>"State", :format=>["upcase"]}, :postcode=>{:label=>"Post Code"}}, :address_format=>"{{address1}}\n{{address2}}\n{{city}} {{region}} {{postcode}}\n{{country}}"}>
+```
+```  
+  country.name => Australia
+  country.code   => AU
+  country.alpha2 => AU
+  country.alpha3 => AUS
+  country.country_code => 61
+```  
+Worldly uses the address fields locality, city, region & postcode. Address1, Address2 and Country are implied and hence not added. A call to country.fields will return the fields not implied that the country address uses.
+```
+  country.fields => {:city=>{:label=>"City", :format=>["upcase"], :required=>true}, :region=>{:label=>"State", :format=>["upcase"], :required=>true}, :postcode=>{:label=>"Post Code", :required=>true}}
+```
+Each field notes the following details:
+
+1. Label: The fields name in the specific country. For example a postcode is called "Post Code" in Australia, "PIN code" in India and "Zip Code" in the US
+2. Required: Whether the field is required
+3. Format: format is an array or rules applied when displaying the address. Current address rules include
+  * upcase: Change the field to uppercase
+  * code: Used be regions. By default the regions full name is used when displaying otherwise the region code. For example 'NSW' is used rather than New South Wales for the Australia state.
+
+Field Methods
+```
+  country.has_field?(:city) => true
+  country.has_field?(:locality) => false
+  country.required_fields => {:city=>{:label=>"City", :format=>["upcase"], :required=>true}, :region=>{:label=>"State", :format=>["upcase"], :required=>true}, :postcode=>{:label=>"Post Code", :required=>true}}
+```
+To retrieve all fields including address1, address2 & country use
+```
+  country.all_fields => [:address1, :address2, :country, :city, :region, :postcode]
+```
+### Regions
+
+Regions (State/Province) are provided for some countries in seperate YAML files
+
+Check if a regions exist for country
+```
+  country.regions? => true
+```
+Check if a given field has regions. This can be useful when generating forms based on the country.
+```
+  country.has_regions?(:region) => true
+  country.has_regions?(:city) => false
+```
+```
+  country.region_options => [["Australian Capital Territory", "ACT"], ["New South Wales", "NSW"], ["Northern Territory", "NT"], ["Queensland", "QLD"], ["South Australia", "SA"], ["Tasmania", "TAS"], ["Victoria", "VIC"], ["Western Australia", "WA"]]
+```
+
+### Formatting an address for mailing or display
+
+You can return the address formatting with liquid tags
+```
+  country.address_format  => "{{address1}}\n{{address2}}\n{{city}} {{region}} {{postcode}}\n{{country}}"
+```
+
+To have the address formatted correctly for mailing use to_print(attributes, sending_country=nil)
+* attributes: takes a hash of field values. If a required field is not provided it will simple not display in the address.
+* sending_country: a country code - if provided and the address country matches the sending_country the country field will not be shown. This is useful if generating mailing addresses to be sent by your home country where country field is not required.
+
+```
+  country.to_print({address1: '12 hey St', address2: '', postcode: '2000', city: 'Newtown', state:'NSW'})
+  => "12 hey St\nNEWTOWN 2000\nAustralia"
+  country.to_print({address1: '12 hey St', region:'NSW', postcode: '2000' }, 'AU')
+  => "12 hey St\nNSW 2000"
+```
+## Contributing
+
+If you find a country with mission regions, or a country missing address formatting information you can create a issue ticket with corrections.
+
+Thanks bro!
+
+1. Fork it ( http://github.com/amnwebmaster/worldly/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"