Module: CityState

Defined in:
lib/city/and/state.rb,
lib/city/and/state/version.rb

Overview

The CityState module exposes framework-agnostic helpers to list countries, states and cities using the underlying ‘city-state` gem (CS module). It provides three public methods: `countries`, `states(country_code)`, and `cities(country_code, state_name=nil)`.

  • countries: returns country names

  • states: expects ISO alpha-2 country code and returns state names

  • cities: returns city names; for a given state name it resolves the state code

    and returns cities within that state; otherwise it tries country-wide
cities or aggregates from all states.

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION = 
"0.1.0"

Class Method Summary collapse

Class Method Details

.blank?(value) ⇒ Boolean

Rails-independent blank? check

Returns:

  • (Boolean) 


51
52
53
 
# File 'lib/city/and/state.rb', line 51

def self.blank?(value)
  value.respond_to?(:empty?) ? !!value.empty? : !value
end

.cities(country, state = nil) ⇒ Object

Public API: return array of city names If state is provided, fetch cities for that state within the country. If state is nil/blank, attempt country-wide cities, else aggregate from all states.



36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/city/and/state.rb', line 36

def self.cities(country, state = nil)
  return [] if blank?(country)

  state = nil if blank?(state)

  if state
    fetch_state_cities(country, state)
  else
    fetch_country_cities(country)
  end
rescue StandardError
  []
end

.countries ⇒ Object

Public API: return array of country codes or names



18
19
20
21
22
 
# File 'lib/city/and/state.rb', line 18

def self.countries
  CS.countries&.values || []
rescue StandardError
  []
end

.fetch_country_cities(country) ⇒ Object 



64
65
66
67
68
69
70
71
72
 
# File 'lib/city/and/state.rb', line 64

def self.fetch_country_cities(country)
  cities = CS.cities(country)
  return cities if cities&.any?

  states_hash = CS.states(country)
  return [] unless states_hash

  states_hash.keys.flat_map { |state_code| CS.cities(state_code, country) || [] }.uniq
end

.fetch_state_cities(country, state) ⇒ Object

— private helpers (module-private) —



56
57
58
59
60
61
62
 
# File 'lib/city/and/state.rb', line 56

def self.fetch_state_cities(country, state)
  states_hash = CS.states(country)
  state_code = states_hash&.key(state)
  return [] unless state_code

  CS.cities(state_code, country) || []
end

.states(country) ⇒ Object

Public API: return array of state names for a given country code



25
26
27
28
29
30
31
 
# File 'lib/city/and/state.rb', line 25

def self.states(country)
  return [] if blank?(country)

  CS.states(country)&.values || []
rescue StandardError
  []
end