chilean_cities 1.0.0

data/README.md

@@ -0,0 +1,133 @@
+Comunas de Chile
+================
+
+[![Gem Version](https://badge.fury.io/rb/chilean_cities.svg)](http://badge.fury.io/rb/chilean_cities)
+[![Build Status](https://api.travis-ci.org/gonzalo-bulnes/chilean_cities.png?branch=master)](https://travis-ci.org/gonzalo-bulnes/chilean_cities)
+[![Code Climate](https://codeclimate.com/github/gonzalo-bulnes/chilean_cities.png)](https://codeclimate.com/github/gonzalo-bulnes/chilean_cities)
+[![Inline docs](http://inch-ci.org/github/gonzalo-bulnes/chilean_cities.svg?branch=master)](http://inch-ci.org/github/gonzalo-bulnes/chilean_cities)
+
+A Ruby representation of the Chilean _administrative areas_ as described by the [SUBDERE][subdere].
+
+  [subdere]: http://www.subdere.gov.cl
+
+Disclaimer
+----------
+
+This library is not developed, supported nor endorsed in any way by the Chilean [Subsecretaría de Desarrollo Regional y Administrativo (SUBDERE)][subdere], nor any related institution.
+
+Data Sources
+------------
+
+This library is based on the publicly available information from the SUBDERE related to the [Codificación Única Territorial][source]. The sources quoted by [the document on which this library is based][ref] are:
+
+- Decreto Supremo No 1439, del Ministerio del Interior, publicado en el Diario Oficial del 8 de Mayo de 2000
+- Decreto Supremo No 1352, del Ministerio del Interior, publicado en el Diario Oficial del 23 de Agosto de 2008
+- Decreto Exento No 910, del Ministerio del Interior, publicado en el Diario Oficial del 14 de Junio de 2007
+- Decreto Exento No 817, del Ministerio del Interior, publicado en el Diario Oficial del 26 de Marzo de 2010
+
+  [source]: http://www.subdere.gov.cl/documentacion/regiones-provincias-y-comunas-de-chile
+  [ref]: http://www.subdere.gov.cl/sites/default/files/documentos/articles-73111_recurso_2.pdf
+
+Usage
+-----
+
+Add the gem to your Gemfile:
+
+```ruby
+# Gemfile
+
+gem 'chilean_cities', '~> 1.0' # see semver.org
+```
+
+Then generate the chilean administrative areas:
+
+```ruby
+require 'chilean_cities'
+
+chile = ChileanCities::Factory.instance
+
+chile.generate!
+
+# and use them as you want : )
+
+chile.regiones.select{ |region| region.iso_3166_2 == 'CL-LL' }.first.name
+# => "Región de los Lagos"
+
+chile.provincias.select{ |provincia| provincia.name =~ /Magallanes/ }.first.comunas.map{ |comuna| comuna.name }
+# => ["Punta Arenas", "Laguna Blanca", "Río Verde", "San Gregorio"]
+ ```
+
+### Schema.org
+
+ The generated administrative areas representations do _partially_ enforce the **Place schema** (see [schema.org][schema] and [the schemas specs][schema-specs] for details):
+
+```ruby
+# comunas, provincias and regiones do implement the `contained_in` method:
+
+chile.comunas.select{ |comuna| comuna.name == 'Quellón' }.first.contained_in.name
+# => "Chiloé"
+```
+
+  [schema]: http://schema.org
+  [schema-specs]: spec/support/schemas
+
+**Note about the previous version** (`v0.1.0`)
+
+If you were using this gem in the past and are looking for its ancient behaviour, please modify your `Gemfile` to checkout the `v0.1.0` tag (it's been a few years, so this is not recommended):
+
+```ruby
+# Gemfile
+
+gem 'chilean_cities', git: 'https://github.com/gonzalo-bulnes/chilean_cities.git', tag: 'v0.1.0'
+```
+The same tag does also [point to the corresponding documentation][deprecated-doc].
+
+  [deprecated-doc]: https://github.com/gonzalo-bulnes/chilean_cities/blob/v0.1.0/README.md
+
+Code of Conduct
+---------------
+
+Please note that by participating in this project, you agree to abide by its [code of conduct]. That is true for pull requests, and also when participating in issues.
+
+[code of conduct]: ./CODE_OF_CONDUCT.md
+
+See Also
+--------
+
+- The Wikipedia article about the [ISO 3166-2][iso] standard
+- Comunas de Chile ([gist][json]) (a Ruby on Rails seed and a JSON document)
+- The Schema.org [AdministrativeArea schema][schema]
+- An interesting overview of [how the administrative areas can be categorized for mapping][administrative_mapping]
+- The [OpenStreetMap relations][osm_boundaries] corresponding to the described administrative areas
+
+  [iso]: https://en.wikipedia.org/wiki/ISO_3166-2:CL
+  [json]: https://gist.github.com/gonzalo-bulnes/337ea1e916e3890fdefa
+  [schema]: http://schema.org/AdministrativeArea
+  [administrative_mapping]: http://wiki.openstreetmap.org/wiki/Tag:admin%20level=8?uselang=en-US
+  [osm_boundaries]: http://www.openstreetmap.org/relation/164609
+
+Credits
+-------
+
+Part of this gem was crafted during my 10% _free focus_ work time at [Acid Labs][acidlabs]. Thanks @acidlabs!
+
+  [acidlabs]: https://github.com/acidlabs
+
+License
+-------
+
+    ChileanCities provides a Ruby representation of the Chilean _administrative areas_.
+    Copyright (C) 2013, 2020 Gonzalo Bulnes Guilpain
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rspec/core/rake_task'
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc 'Provide private interfaces documentation'
+  RSpec::Core::RakeTask.new(:spec)
+
+  namespace :spec do
+    desc 'Provide public interfaces documentation'
+      RSpec::Core::RakeTask.new(:public) do |t|
+      t.rspec_opts = "--tag public"
+    end
+  end
+
+  namespace :spec do
+    desc 'Provide private interfaces documentation for development purpose'
+      RSpec::Core::RakeTask.new(:development) do |t|
+      t.rspec_opts = "--tag protected --tag private"
+    end
+  end
+rescue LoadError
+  desc 'RSpec rake task not available'
+  task :spec do
+    abort 'RSpec rake task is not available. Be sure to install rspec-core as a gem or plugin'
+  end
+end
+
+begin
+  require 'inch/rake'
+
+  Inch::Rake::Suggest.new(:inch) do |suggest|
+    suggest.args << "--private"
+    suggest.args << "--pedantic"
+  end
+rescue LoadError
+   desc 'Inch rake task not available'
+  task :inch do
+    abort 'Inch rake task is not available. Be sure to install inch as a gem or plugin'
+  end
+end
+
+task :default => ['spec:public', 'spec:development', :inch]

data/lib/chilean_cities.rb

@@ -0,0 +1,7 @@
+require 'chilean_cities/version'
+require 'chilean_cities/comuna'
+require 'chilean_cities/provincia'
+require 'chilean_cities/region'
+require 'chilean_cities/factory'
+
+module ChileanCities; end

data/lib/chilean_cities/comuna.rb

@@ -0,0 +1,27 @@
+require 'active_model'
+
+require 'chilean_cities/provincia_part'
+require 'chilean_cities/region_part'
+require 'schemas/place'
+
+module ChileanCities
+
+  class Comuna
+    include ActiveModel::Model
+
+    include ProvinciaPart
+    include RegionPart
+    include Schemas::Place
+
+    attr_accessor :code
+
+    def initialize(*args)
+      @name = args.shift
+      @code = args.shift
+      @provincia = args.shift
+      @region = args.shift
+    end
+
+    validates_presence_of :code, :name
+  end
+end

data/lib/chilean_cities/comunas_list.rb

@@ -0,0 +1,14 @@
+module ChileanCities
+  module ComunasList
+
+    def initialize
+      raise NotImplementedError, 'ComunasList must implement initialize()'
+    end
+
+    attr_reader :comunas
+
+    def append_comuna(comuna)
+      @comunas << comuna unless @comunas.include? comuna
+    end
+  end
+end

data/lib/chilean_cities/factory.rb

@@ -0,0 +1,46 @@
+require 'multi_json'
+
+module ChileanCities
+
+  class Factory
+    include Singleton
+
+    attr_reader :regiones
+    attr_reader :provincias
+    attr_reader :comunas
+
+    def generate!
+
+      @regiones = []
+      @provincias = []
+      @comunas = []
+
+      data_file = File.read('data/comunas.json')
+
+      data = MultiJson.load(data_file, symbolize_keys: true)
+
+      data.each do |datum|
+        comuna = Comuna.new(datum[:name], datum[:code])
+
+        provincia = @provincias.select { |provincia| provincia.name == datum[:provincia] }.first ||
+                    Provincia.new(datum[:provincia])
+
+        region = @regiones.select { |region| region.name == datum[:region] }.first ||
+                 Region.new(datum[:region], datum[:region_iso_3166_2])
+
+        comuna.region = region
+        comuna.provincia = comuna.contained_in = provincia
+        @comunas << comuna unless @comunas.include? comuna
+
+        provincia.region = provincia.contained_in = region
+        provincia.append_comuna(comuna)
+        @provincias << provincia unless @provincias.include? provincia
+
+        region.append_comuna(comuna)
+        region.append_provincia(provincia)
+        @regiones << region unless @regiones.include? region
+      end
+      { comunas_count: @comunas.count, provincias_count: @provincias.count, regiones_count: @regiones.count }
+    end
+  end
+end

data/lib/chilean_cities/provincia.rb

@@ -0,0 +1,23 @@
+require 'active_model'
+
+require 'chilean_cities/comunas_list'
+require 'chilean_cities/region_part'
+
+module ChileanCities
+
+  class Provincia
+    include ActiveModel::Model
+
+    include ComunasList
+    include RegionPart
+    include Schemas::Place
+
+    def initialize(*args)
+      @name = args.shift
+      @comunas = []
+      @region = nil
+    end
+
+    validates_presence_of :name
+  end
+end

data/lib/chilean_cities/provincia_part.rb

@@ -0,0 +1,11 @@
+module ChileanCities
+  module ProvinciaPart
+
+    def initialize
+      raise NotImplementedError, 'ProvinciaPart must implement initialize()'
+      @provincia = nil
+    end
+
+    attr_accessor :provincia
+  end
+end

data/lib/chilean_cities/provincias_list.rb

@@ -0,0 +1,14 @@
+module ChileanCities
+  module ProvinciasList
+
+    def initialize
+      raise NotImplementedError, 'ProvinciasList must implement initialize()'
+    end
+
+    attr_reader :provincias
+
+    def append_provincia(provincia)
+      @provincias << provincia unless @provincias.include? provincia
+    end
+  end
+end

data/lib/chilean_cities/region.rb

@@ -0,0 +1,27 @@
+require 'active_model'
+
+require 'chilean_cities/comunas_list'
+require 'chilean_cities/provincias_list'
+
+module ChileanCities
+
+  class Region
+    include ActiveModel::Model
+
+    include ComunasList
+    include ProvinciasList
+    include Schemas::Place
+
+    attr_accessor :iso_3166_2
+
+    def initialize(*args)
+      @name = args.shift
+      @iso_3166_2 = args.shift
+      @comunas = []
+      @provincias = []
+    end
+
+    validates_presence_of :iso_3166_2, :name
+    validates_format_of :iso_3166_2, with: /\ACL-[A-Z][A-Z]\z/ # ISO 3166-2:CL
+  end
+end

data/lib/chilean_cities/region_part.rb

@@ -0,0 +1,6 @@
+module ChileanCities
+  module RegionPart
+
+    attr_accessor :region
+  end
+end

data/lib/chilean_cities/version.rb

@@ -0,0 +1,3 @@
+module ChileanCities
+  VERSION = "1.0.0"
+end

data/lib/schemas/place.rb

@@ -0,0 +1,10 @@
+require 'schemas/thing'
+
+module Schemas
+  module Place
+    include Schemas::Thing
+
+    attr_accessor :contained_in
+    attr_accessor :has_map
+  end
+end

data/lib/schemas/thing.rb

@@ -0,0 +1,6 @@
+module Schemas
+  module Thing
+
+    attr_accessor :name
+  end
+end

data/spec/factories/comunas.rb

@@ -0,0 +1,10 @@
+FactoryGirl.define do
+  factory :comuna, class: ChileanCities::Comuna do
+    code 15102
+    name 'Camarones'
+  end
+
+  factory :invalid_comuna, class: ChileanCities::Comuna do
+    # nop
+  end
+end

data/spec/factories/provincias.rb

@@ -0,0 +1,9 @@
+FactoryGirl.define do
+  factory :provincia, class: ChileanCities::Provincia do
+    name 'Arica'
+  end
+
+  factory :invalid_provincia, class: ChileanCities::Provincia do
+    # nop
+  end
+end

data/spec/factories/regiones.rb

@@ -0,0 +1,10 @@
+FactoryGirl.define do
+  factory :region, class: ChileanCities::Region do
+    name 'Arica y Parinacota'
+    iso_3166_2 'CL-AP'
+  end
+
+  factory :invalid_region, class: ChileanCities::Region do
+    # nop
+  end
+end

data/spec/lib/chilean_cities/comuna_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+describe ChileanCities::Comuna do
+
+  describe 'provides a Schema.org interface', public: true do
+    it_behaves_like 'a City'
+  end
+
+  it_behaves_like 'part of a ChileanCities::Provincia'
+
+  it 'responds to :code', public: true do
+    expect(subject).to respond_to :code
+  end
+
+  # validations
+
+  it 'has a valid factory', private: true do
+    expect(FactoryGirl.build(:comuna)).to be_valid
+  end
+
+  it 'requires a name', private: true do
+    expect(FactoryGirl.build(:comuna, name: nil)).not_to be_valid
+  end
+
+  it 'requires a code', private: true do
+    expect(FactoryGirl.build(:comuna, code: nil)).not_to be_valid
+  end
+
+  describe '#provincia', data: true, private: true do
+
+    it 'returns a ChileanCities::Provincia' do
+      chile = ChileanCities::Factory.instance
+      chile.generate!
+
+      subject = chile.comunas.sample
+
+      expect(subject.provincia).not_to be_nil
+      expect(subject.provincia).to be_instance_of ChileanCities::Provincia
+    end
+  end
+
+  describe '#region', data: true, private: true do
+
+    it 'returns a ChileanCities::Region' do
+      chile = ChileanCities::Factory.instance
+      chile.generate!
+
+      subject = chile.comunas.sample
+
+      expect(subject.region).not_to be_nil
+      expect(subject.region).to be_instance_of ChileanCities::Region
+    end
+  end
+
+  describe '#contained_in', data: true, private: true do
+
+    it 'returns a ChileanCities::Provincia' do
+      chile = ChileanCities::Factory.instance
+      chile.generate!
+
+      subject = chile.comunas.sample
+
+      expect(subject.contained_in).not_to be_nil
+      expect(subject.contained_in).to be_instance_of ChileanCities::Provincia
+    end
+  end
+end