Class: Snail

Inherits:
Object
  • Object
show all
Includes:
Initializable
Defined in:
lib/snail.rb,
lib/snail/helpers.rb,
lib/snail/version.rb,
lib/snail/constants.rb,
lib/snail/initializable.rb

Defined Under Namespace

Modules: Helpers, Initializable, Iso3166 Classes: UnknownAttribute, UnknownCountryError

Constant Summary collapse

REGIONS = 
{
    # see http://en.wikipedia.org/wiki/Postcodes_in_Australia#Australia_States_and_territories
    :au => {
        'Australian Capital Territory' => 'ACT',
        'New South Wales' => 'NSW',
        'Victoria' => 'VIC',
        'Queensland' => 'QLD',
        'South Australia' => 'SA',
        'Western Australia' => 'WA',
        'Tasmania' => 'TAS',
        'Northern Territory' => 'NT'
    },
    # see http://en.wikipedia.org/wiki/Canadian_subnational_postal_abbreviations
    :ca => {
        'Alberta' => 'AB',
        'British Columbia' => 'BC',
        'Manitoba' => 'MB',
        'New Brunswick' => 'NB',
        'Newfoundland and Labrador' => 'NL',
        'Nova Scotia' => 'NS',
        'Northwest Territories' => 'NT',
        'Nunavut' => 'NU',
        'Ontario' => 'ON',
        'Prince Edward Island' => 'PE',
        'Quebec' => 'QC',
        'Saskatchewan' => 'SK',
        'Yukon' => 'YT'
    },
    # see http://www.columbia.edu/kermit/postal.html#usa
    # and http://www.usps.com/ncsc/lookups/usps_abbreviations.html
    :us => {
        'Alabama' => 'AL',
        'Alaska' => 'AK',
        'Arizona' => 'AZ',
        'Arkansas' => 'AR',
        'California' => 'CA',
        'Colorado' => 'CO',
        'Connecticut' => 'CT',
        'Delaware' => 'DE',
        'District Of Columbia' => 'DC',
        'Florida' => 'FL',
        'Georgia' => 'GA',
        'Hawaii' => 'HI',
        'Idaho' => 'ID',
        'Illinois' => 'IL',
        'Indiana' => 'IN',
        'Iowa' => 'IA',
        'Kansas' => 'KS',
        'Kentucky' => 'KY',
        'Louisiana' => 'LA',
        'Maine' => 'ME',
        'Maryland' => 'MD',
        'Massachusetts' => 'MA',
        'Michigan' => 'MI',
        'Minnesota' => 'MN',
        'Mississippi' => 'MS',
        'Missouri' => 'MO',
        'Montana' => 'MT',
        'Nebraska' => 'NE',
        'Nevada' => 'NV',
        'New Hampshire' => 'NH',
        'New Jersey' => 'NJ',
        'New Mexico' => 'NM',
        'New York' => 'NY',
        'North Carolina' => 'NC',
        'North Dakota' => 'ND',
        'Ohio' => 'OH',
        'Oklahoma' => 'OK',
        'Oregon' => 'OR',
        'Pennsylvania' => 'PA',
        'Rhode Island' => 'RI',
        'South Carolina' => 'SC',
        'South Dakota' => 'SD',
        'Tennessee' => 'TN',
        'Texas' => 'TX',
        'Utah' => 'UT',
        'Vermont' => 'VT',
        'Virginia' => 'VA',
        'Washington' => 'WA',
        'West Virginia' => 'WV',
        'Wisconsin' => 'WI',
        'Wyoming' => 'WY',

        # These are not states exactly, but they are addressed as states through USA
        'American Samoa' => 'AS',
        'Federated States Of Micronesia' => 'FM',
        'Guam' => 'GU',
        'Marshall Islands' => 'MH',
        'Northern Mariana Islands' => 'MP',
        'Palau' => 'PW',
        'Puerto Rico' => 'PR',
        'Virgin Islands' => 'VI',
        'Armed Forces Africa' => 'AE',
        'Armed Forces Americas (Except Canada)' => 'AA',
        'Armed Forces Canada' => 'AE',
        'Armed Forces Europe' => 'AE',
        'Armed Forces Middle East' => 'AE',
        'Armed Forces Pacific' => 'AP',
    },
    # http://en.wikipedia.org/wiki/Counties_of_Ireland
    # NB: only includes Replublic of Ireland, also no abbreviations
    :ie => {
        'Carlow' => 'Carlow',
        "Cavan" => 'Cavan',
        'Clare' => 'Clare',
        'Cork' => 'Cork',
        'Donegal' => 'Donegal',
        'Dublin' => 'Dublin',
        'Dún Laoghaire–Rathdown' => 'Dún Laoghaire–Rathdown',
        'Fingal' => 'Fingal',
        'Galway' => 'Galway',
        'Kerry' => 'Kerry',
        'Kildare' => 'Kildare',
        'Kilkenny' => 'Kilkenny',
        'Laois' => 'Laois',
        'Leitrim' => 'Leitrim',
        'Limerick' => 'Limerick',
        'Longford' => 'Longford',
        'Louth' => 'Louth',
        'Mayo' => 'Mayo',
        'Meath' => 'Meath',
        'Monaghan' => 'Monaghan',
        'Offaly' => 'Offaly',
        'Roscommon' => 'Roscommon',
        'Sligo' => 'Sligo',
        'South Dublin' => 'South Dublin',
        'Tipperary' => 'Tipperary',
        'Waterford' => 'Waterford',
        'Westmeath' => 'Westmeath',
        'Wexford' => 'Wexford',
        'Wicklow' => 'Wicklow',
    }
}
VERSION = 
'2.3.0'.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Initializable

#initialize

Instance Attribute Details

#city ⇒ Object

Returns the value of attribute city.



57
58
59
 
# File 'lib/snail.rb', line 57

def city
  @city
end

#country ⇒ Object

Returns the value of attribute country.



70
71
72
 
# File 'lib/snail.rb', line 70

def country
  @country
end

#line_1 ⇒ Object

Returns the value of attribute line_1.



48
49
50
 
# File 'lib/snail.rb', line 48

def line_1
  @line_1
end

#line_2 ⇒ Object

Returns the value of attribute line_2.



53
54
55
 
# File 'lib/snail.rb', line 53

def line_2
  @line_2
end

#name ⇒ Object

Snail’s canonical fields



45
46
47
 
# File 'lib/snail.rb', line 45

def name
  @name
end

#postal_code ⇒ Object

Returns the value of attribute postal_code.



65
66
67
 
# File 'lib/snail.rb', line 65

def postal_code
  @postal_code
end

#region ⇒ Object

Returns the value of attribute region.



61
62
63
 
# File 'lib/snail.rb', line 61

def region
  @region
end

Class Method Details

.home_country ⇒ Object 



26
27
28
 
# File 'lib/snail.rb', line 26

def self.home_country
  @home_country ||= 'US'
end

.home_country=(val) ⇒ Object 



30
31
32
 
# File 'lib/snail.rb', line 30

def self.home_country=(val)
  @home_country = lookup_country_iso(val)
end

.load_helpers ⇒ Object

Load the SnailHelpers module into ActionView::Base. Previously this was done automatically, but going forward it must be included explicitly by calling Snail.load_helpers.



20
21
22
23
24
 
# File 'lib/snail.rb', line 20

def self.load_helpers
  return unless defined? ActionView
  warn '[DEPRECATION] Snail::Helpers will be removed in a future release.'
  ActionView::Base.class_eval { include Snail::Helpers }
end

.lookup_country_iso(val) ⇒ Object 



34
35
36
37
38
39
40
41
42
 
# File 'lib/snail.rb', line 34

def self.lookup_country_iso(val)
  return if val.nil? || val.empty?
  val = val.upcase
  if ::Snail::Iso3166::ALPHA2[val]
    val
  else
    ::Snail::Iso3166::ALPHA2_EXCEPTIONS[val] || ::Snail::Iso3166::ALPHA3_TO_ALPHA2[val]
  end
end

Instance Method Details

#city_line ⇒ Object

this method will get much larger. completeness is out of my scope at this time. currently it’s based on the sampling of city line formats from frank’s compulsive guide.



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/snail.rb', line 109

def city_line
  case country
  when 'CN', 'IN'
    "#{city}, #{region}  #{postal_code}"
  when 'BR'
    "#{postal_code} #{city}-#{region}"
  when 'MX', 'SK'
    "#{postal_code} #{city}, #{region}"
  when 'IT'
    "#{postal_code} #{city} #{region}"
  when 'BY'
    "#{postal_code} #{city}-#{region}"
  when 'US', 'CA', 'AU', nil, ''
    "#{city} #{region}  #{postal_code}"
  when 'IL', 'DK', 'FI', 'FR', 'DE', 'GR', 'NO', 'ES', 'SE', 'TR', 'CY', 'PT', 'MK', 'BA'
    "#{postal_code} #{city}"
  when 'KW', 'SY', 'OM', 'EE', 'LU', 'BE', 'IS', 'CH', 'AT', 'MD', 'ME', 'RS', 'BG', 'GE', 'PL', 'AM', 'HR', 'RO', 'AZ'
    "#{postal_code} #{city}"
  when 'NL'
    "#{postal_code}  #{city}"
  when 'IE'
    "#{city}, #{region}#{"\n" unless postal_code.nil? || postal_code.empty?}#{postal_code}"
  when 'GB', 'RU', 'UA', 'JO', 'LB', 'IR', 'SA', 'NZ'
    "#{city}  #{postal_code}" # Locally these may be on separate lines. The USPS prefers the city line above the country line, though.
  when 'EC'
    "#{postal_code} #{city}"
  when 'HK', 'IQ', 'YE', 'QA', 'AL', 'BS'
    "#{city}"
  when 'AE'
    "#{postal_code}\n#{city}"
  when 'JP'
    "#{city}, #{region}\n#{postal_code}"
  when 'EG', 'ZA', 'IM', 'KZ', 'HU'
    "#{city}\n#{postal_code}"
  when 'LV'
    "#{city}, LV-#{postal_code}"
  when 'LT'
    "LT-#{postal_code} #{city}"
  when 'SI'
    "SI-#{postal_code} #{city}"
  when 'CZ'
    "#{postal_code} #{region}\n#{city}"
  when 'SG'
    "#{country_line.titleize} #{postal_code}"
  else
    if Kernel.const_defined?('Rails')
      Rails.logger.error "[Snail] Unknown Country: #{country}"
    end
    "#{city} #{region}  #{postal_code}"
  end
end

#country_line ⇒ Object 



161
162
163
 
# File 'lib/snail.rb', line 161

def country_line
  (translated_country(origin, @country) || translated_country('US', @country))
end

#international? ⇒ Boolean

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/snail.rb', line 85

def international?
  country && origin != country
end

#origin ⇒ Object

Where the mail is coming from. Defaults to the global ‘home_country`.



81
82
83
 
# File 'lib/snail.rb', line 81

def origin
  @origin ||= Snail.home_country
end

#origin=(val) ⇒ Object

Where the mail is coming from.



76
77
78
 
# File 'lib/snail.rb', line 76

def origin=(val)
  @origin = Snail.lookup_country_iso(val)
end

#to_html(with_country: nil) ⇒ Object 



103
104
105
 
# File 'lib/snail.rb', line 103

def to_html(with_country: nil)
  CGI.escapeHTML(to_s(with_country: with_country)).gsub("\n", '<br />').html_safe
end

#to_s(with_country: nil) ⇒ Object 



89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/snail.rb', line 89

def to_s(with_country: nil)
  with_country = true if with_country.nil? && international?

  [
    name,
    line_1,
    line_2,
    city_line,
    (country_line if with_country)
  ]
    .reject { |line| line.nil? || line.empty? }
    .join("\n")
end

#translated_country(origin, country) ⇒ Object 



165
166
167
168
 
# File 'lib/snail.rb', line 165

def translated_country(origin, country)
  path = File.join(File.dirname(File.expand_path(__FILE__)), "../assets/#{origin}.yml")
  File.read(path).match(/^#{country}: (.*)$/)[1]
end