municipitaly2 2.0.0

data/lib/municipitaly2/municipality.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # Define data structure for a Municipality
+  class Municipality
+    extend Forwardable
+    include DataCaller
+    include RegionDelegator
+    include ZoneDelegator
+
+    def initialize(province_istat:, name:, name_alt:, partial_istat:,
+                   cadastrial_code:, postal_codes:, population:,
+                   area:, latitude:, longitude:) # :nodoc:
+      @province_istat = province_istat
+      @name = name
+      @name_alt = name_alt
+      @partial_istat = partial_istat
+      @cadastrial_code = cadastrial_code
+      @postal_codes = postal_codes.split
+      @population = population.to_i
+      @area = area.to_f
+      @latitude = latitude.to_f
+      @longitude = longitude.to_f
+    end
+
+    # <b>istat code</b> relative to parent province (String)
+    attr_reader :province_istat
+
+    # <b>name</b> of municipality (String)
+    attr_reader :name
+
+    # <b>alternative name</b> of municipality (String)
+    attr_reader :name_alt
+
+    attr_reader :partial_istat # :nodoc:
+
+    # <b>cadastrial code</b> of municipality (String)
+    attr_reader :cadastrial_code
+
+    # an Array of one or more postal code (as String)
+    attr_reader :postal_codes
+
+    # total <b>population</b> of municipality (Integer)
+    attr_reader :population
+
+    # total <b>area</b> of municipality (Float)
+    attr_reader :area
+
+    # total <b>population</b> of municipality (Float)
+    attr_reader :latitude
+
+    # total <b>population</b> of municipality (Float)
+    attr_reader :longitude
+
+    def_delegator :province, :acronym, :province_acronym
+    def_delegator :province, :name, :province_name
+    def_delegator :province, :region_istat, :region_istat
+
+    # returns an array of all +Municipitaly2::Municipality+ objects.
+    def self.all
+      data.municipalities
+    end
+
+    # returns <b>istat code</b> for current municipality.
+    def istat
+      province_istat + partial_istat
+    end
+
+    def name_full
+      name_alt.nil? ? name : "#{name}/#{name_alt}"
+    end
+
+    # returns +Municipitaly2::Province+ object for current municipality.
+    def province
+      @province ||= Search.province_from_istat(province_istat)
+    end
+  end
+end

data/lib/municipitaly2/province.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # Define data structure for a Province
+  class Province
+    extend Forwardable
+    include DataCaller
+    include RegionDelegator
+    include ZoneDelegator
+
+    def initialize(region_istat:, name:, istat:, acronym:)
+      @region_istat = region_istat
+      @name = name
+      @istat = istat
+      @acronym = acronym
+    end
+
+    attr_reader :region_istat, :name, :istat, :acronym
+
+    # returns an array of all +Municipitaly2::Province+ objects.
+    def self.all
+      data.provinces
+    end
+
+    # returns an array of all +Municipitaly2::Municipality+ objects belongs
+    # to current province.
+    def municipalities
+      @municipalities ||= Search.municipalities_from_province_istat(istat)
+    end
+
+    # returns ISO 3166-2 code for current province.
+    def iso3166_2
+      "IT-#{acronym}"
+    end
+
+    alias iso3166 iso3166_2
+  end
+end

data/lib/municipitaly2/region.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # Define data structure for a Region
+  class Region
+    include DataCaller
+    include ZoneDelegator
+
+    def initialize(zone_code:, name:, istat:, partial_iso3166:)
+      @zone_code = zone_code
+      @name = name
+      @istat = istat
+      @partial_iso3166 = partial_iso3166
+    end
+
+    attr_reader :zone_code, :name, :istat, :partial_iso3166
+
+    # returns an array of all +Municipitaly2::Region+ objects.
+    def self.all
+      data.regions
+    end
+
+    # returns an array of all +Municipitaly2::Province+ objects belongs
+    # to current region.
+    def provinces
+      @provinces ||= Search.provinces_from_region_istat(istat)
+    end
+
+    # returns an array of all +Municipitaly2::Municipality+ objects belongs
+    # to current region.
+    def municipalities
+      @municipalities ||= Search.municipalities_from_region_istat(istat)
+    end
+
+    # returns ISO 3166-2 code for current province.
+    def iso3166_2
+      "IT-#{partial_iso3166}"
+    end
+
+    alias iso3166 iso3166_2
+  end
+end

data/lib/municipitaly2/region_delegator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # shared module to delegate Region istance and its methods
+  module RegionDelegator
+    extend Forwardable
+
+    def_delegator :region, :name, :region_name
+    def_delegator :region, :zone_code, :zone_code
+
+    def region
+      @region ||= Search.region_from_istat(region_istat)
+    end
+  end
+end

data/lib/municipitaly2/search.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # +Municipitaly2::Search+ class implement different search methods.
+  #
+  # You <b>must use</b> shortcut <b>class methods</b> that invoke private
+  # instance methods having same method name, for example:
+  #
+  #   Search.municipalities_from_postal_code('36040')
+  #
+  # invoke to:
+  #
+  #   Search.new('36040').municipalities_from_postal_code
+  #
+  class Search
+    include DataCaller
+
+    CLASS_METHODS = %i[zone_from_code region_from_istat regions_from_zone_code
+                       province_from_name province_from_istat
+                       province_from_acronym provinces_from_region_istat
+                       provinces_from_zone_code municipalities_from_name
+                       municipality_from_cadastrial municipality_from_istat
+                       municipalities_from_postal_code
+                       municipalities_from_province_istat
+                       municipalities_from_region_istat
+                       municipalities_from_zone_code].freeze # :nodoc:
+
+    CLASS_METHODS.each do |method|
+      define_singleton_method method do |message, opts = {}|
+        Search.new(message, opts).send(method)
+      end
+    end # :nodoc:
+
+    attr_accessor :term, :opts # :nodoc:
+
+    def initialize(term, opts = {}) # :nodoc:
+      @term = term.to_s.strip
+      @opts = opts
+    end
+
+    protected
+
+    # returns a +Municipitaly2::Zone+ object from a <b>zone code</b> term
+    #
+    # example usage:
+    #   zone = Search.zone_from_code('4')
+    def zone_from_code # :doc:
+      data.zones.find do |z|
+        z.code == term
+      end
+    end
+
+    # returns a +Municipitaly2::Region+ object from a <b>region istat</b> term
+    #
+    # example usage:
+    #   region = Search.region_from_istat('15')
+    def region_from_istat # :doc:
+      data.regions.find do |r|
+        r.istat == term
+      end
+    end
+
+    # returns an array of +Municipitaly2::Region+ objects from a <b>zone
+    # code</b> term
+    #
+    # example usage:
+    #   regions = Search.regions_from_zone_code('3')
+    def regions_from_zone_code # :doc:
+      data.regions.select do |r|
+        r.zone_code == term
+      end
+    end
+
+    # returns a +Municipitaly2::Province+ object from a <b>province name</b>
+    # term
+    #
+    # example usage:
+    #   province = Search.province_from_name('Paler')
+    def province_from_name # :doc:
+      term_set = Municipitaly2.sanitize_term(term)
+      return nil if term_set.size < 3
+
+      data.provinces.find do |p|
+        name_set = Municipitaly2.sanitize_term(p.name)
+        name_set =~ Regexp.new(term_set)
+      end
+    end
+
+    # returns a +Municipitaly2::Province+ object from a <b>province istat</b>
+    # term
+    #
+    # example usage:
+    #   province = Search.province_from_istat('061')
+    def province_from_istat # :doc:
+      data.provinces.find do |p|
+        p.istat == term
+      end
+    end
+
+    # returns a +Municipitaly2::Province+ object from a <b>province acronym</b>
+    # term
+    #
+    # example usage:
+    #   province = Search.province_from_acronym('MI')
+    def province_from_acronym # :doc:
+      data.provinces.find do |p|
+        p.acronym == term
+      end
+    end
+
+    # returns an array of +Municipitaly2::Province+ objects from a <b>region
+    # istat</b> term
+    #
+    # example usage:
+    #   provinces = Search.provinces_from_region_istat('05')
+    def provinces_from_region_istat # :doc:
+      data.provinces.select do |p|
+        p.region_istat == term
+      end
+    end
+
+    # returns an array of +Municipitaly2::Province+ objects from a <b>zone
+    # code</b> term
+    #
+    # example usage:
+    #   provinces = Search.provinces_from_zone_code('5')
+    def provinces_from_zone_code # :doc:
+      region_istats = regions_from_zone_code.map(&:istat)
+      data.provinces.select do |p|
+        region_istats.include? p.region_istat
+      end
+    end
+
+    # returns an array of +Municipitaly2::Municipality+ objects from a
+    # <b>municipality name</b> term.
+    # Term can be a partial string and is case insensitive.
+    # The optional parameter +greedy+ [boolean] permit to serch exact term
+    # name (if false) or partial word (true by default).
+    #
+    # example usage:
+    #   municipalities = Search.municipalities_from_name('monte')
+    #   municipalities = Search.municipalities_from_name('monte', greedy: false)
+    def municipalities_from_name # :doc:
+      greedy = opts.fetch(:greedy, true)
+      term_set = Municipitaly2.sanitize_term(term)
+
+      return [] if term_set.size < 3
+
+      regexp = if greedy
+                 Regexp.new(term_set, true)
+               else
+                 Regexp.new("^#{term_set}$", true)
+               end
+      data.municipalities.select do |m|
+        Municipitaly2.sanitize_term(m.name) =~ regexp || (m.name_alt && Municipitaly2.sanitize_term(m.name_alt) =~ regexp)
+      end
+    end
+
+    # returns a +Municipitaly2::Municipality+ object from a <b>cadastrial
+    # code</b> term
+    #
+    # example usage:
+    #   municipality = Search.municipality_from_cadastrial('D791')
+    def municipality_from_cadastrial # :doc:
+      data.municipalities.find do |m|
+        m.cadastrial_code == term.upcase
+      end
+    end
+
+    # returns a +Municipitaly2::Municipality+ object from a <b>municipality
+    # istat</b> term
+    #
+    # example usage:
+    #   municipality = Search.municipality_from_istat('066032')
+    def municipality_from_istat # :doc:
+      province_istat = term.slice!(0...3)
+      partial_istat = term
+      data.municipalities.find do |m|
+        m.province_istat == province_istat && m.partial_istat == partial_istat
+      end
+    end
+
+    # returns an array of +Municipitaly2::Municipality+ objects from a
+    # <b>postal code</b> term.
+    #
+    # example usage:
+    #   municipalities = Search.municipalities_from_postal_code('00163')
+    def municipalities_from_postal_code # :doc:
+      data.municipalities.select do |m|
+        m.postal_codes.include? term
+      end
+    end
+
+    # returns an array of +Municipitaly2::Municipality+ objects from a
+    # <b>province istat</b> term.
+    #
+    # example usage:
+    #   municipalities = Search.municipalities_from_province_istat('090')
+    def municipalities_from_province_istat # :doc:
+      data.municipalities.select do |m|
+        m.province_istat == term
+      end
+    end
+
+    # returns an array of +Municipitaly2::Municipality+ objects from a
+    # <b>region istat</b> term.
+    #
+    # example usage:
+    #   municipalities = Search.municipalities_from_region_istat('13')
+    def municipalities_from_region_istat # :doc:
+      province_istats = provinces_from_region_istat.map(&:istat)
+      municipalities_from_province_istats(province_istats)
+    end
+
+    # returns an array of +Municipitaly2::Municipality+ objects from a
+    # <b>zone code</b> term.
+    #
+    # example usage:
+    #   municipalities = Search.municipalities_from_zone_code('3')
+    def municipalities_from_zone_code # :doc:
+      province_istats = provinces_from_zone_code.map(&:istat)
+      municipalities_from_province_istats(province_istats)
+    end
+
+    private
+
+    def municipalities_from_province_istats(istats)
+      data.municipalities.select do |m|
+        istats.include? m.province_istat
+      end
+    end
+  end
+end

data/lib/municipitaly2/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # :nodoc:
+  VERSION = '2.0.0'
+end

data/lib/municipitaly2/zone.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # Define data structure for a Zone
+  class Zone
+    include DataCaller
+
+    def initialize(name:, code:)
+      @name = name
+      @code = code
+    end
+
+    attr_reader :name, :code
+
+    # returns an array of all +Municipitaly2::Zone+ objects.
+    def self.all
+      data.zones
+    end
+
+    # returns an array of all +Municipitaly2::Region+ objects belongs to
+    # current zone.
+    def regions
+      Search.regions_from_zone_code(code)
+    end
+
+    # returns an array of all +Municipitaly2::Province+ objects belongs
+    # to current zone.
+    def provinces
+      @provinces ||= Search.provinces_from_zone_code(code)
+    end
+
+    # returns an array of all +Municipitaly2::Municipality+ objects belongs
+    # to current zone.
+    def municipalities
+      @municipalities ||= Search.municipalities_from_zone_code(code)
+    end
+  end
+end

data/lib/municipitaly2/zone_delegator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Municipitaly2
+  # shared module to delegate Zone istance and its methods
+  module ZoneDelegator
+    extend Forwardable
+
+    def_delegator :zone, :name, :zone_name
+
+    def zone
+      @zone ||= Search.zone_from_code(zone_code)
+    end
+  end
+end

data/lib/municipitaly2.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'forwardable'
+
+require_relative 'municipitaly2/version'
+require_relative 'municipitaly2/data'
+require_relative 'municipitaly2/zone_delegator'
+require_relative 'municipitaly2/region_delegator'
+require_relative 'municipitaly2/data_caller'
+require_relative 'municipitaly2/zone'
+require_relative 'municipitaly2/region'
+require_relative 'municipitaly2/province'
+require_relative 'municipitaly2/municipality'
+require_relative 'municipitaly2/search'
+
+# top level namespace
+module Municipitaly2
+  # :nodoc:
+
+  # returns a sanitized term removing everything except letters to make
+  # matches less prone to errors (case insensitive and accent insensitive)
+  #
+  # example usage:
+  #   sanitized_term = Search.sanitize_term('Forlì Cesena')
+  def self.sanitize_term(term) # :doc:
+    term.strip.downcase.tr('àâçèéêìòôù', 'aaceeeioou').gsub(/[^a-z]/, '')
+  end
+end

data/municipitaly2.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'municipitaly2/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'municipitaly2'
+  spec.version       = Municipitaly2::VERSION
+  spec.authors       = %w[yupswing NatyDev]
+  spec.email         = ['me@simonecingano.it', 'natydev@aol.com']
+
+  spec.summary       = 'Municipitaly2'
+  spec.description   = 'Codes (postal, istat, cadastrian, ...) about Italian ' \
+                       'subdivisions and municipalities in Italy [city, cities]'
+  spec.homepage      = 'https://github.com/yupswing/municipitaly2'
+  spec.license       = 'MIT'
+  spec.metadata = {
+    # 'documentation_uri' => 'https://www.rubydoc.info/github/natydev/municipitaly/master',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0")
+                     .reject { |f| f.match(%r{^(test|spec|features|tools)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.add_development_dependency 'bundler', '~> 2.5.11'
+  spec.add_development_dependency 'rake', '~> 13.2.1'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.64.1'
+  spec.add_development_dependency 'simplecov', '~> 0.22.0'
+end