Merge branch 'add-chilean-administrative-areas'

As a developer
In order to be able to generate any set of data related to
administrative areas
I want them to be represented as a collection of related objects

Gemfile.lock

@@ -2,19 +2,37 @@ PATH
   remote: .
   specs:
     chilean_cities (0.1.0)
+      activemodel (>= 3.2.11, < 5)
+      multi_json (~> 1.0)
       rake (~> 10.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activemodel (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    builder (3.2.2)
     coderay (1.1.0)
     diff-lcs (1.2.5)
+    factory_girl (4.5.0)
+      activesupport (>= 3.0.0)
+    i18n (0.7.0)
     inch (0.4.10)
       pry
       sparkr (>= 0.2.0)
       term-ansicolor
       yard (~> 0.8.7)
+    json (1.8.2)
     method_source (0.8.2)
+    minitest (5.5.1)
+    multi_json (1.11.0)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
@@ -37,13 +55,17 @@ GEM
     sparkr (0.4.1)
     term-ansicolor (1.3.0)
       tins (~> 1.0)
+    thread_safe (0.3.4)
     tins (1.3.4)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
     yard (0.8.7.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   chilean_cities!
+  factory_girl (~> 4.5)
   inch (~> 0.4.6)
   rspec (~> 3.0)

README.md

@@ -1,16 +1,15 @@
 Comunas de Chile
 ================
 
-[![Build Status](https://api.travis-ci.org/gonzalo-bulnes/chilean_cities.png)](https://travis-ci.org/gonzalo-bulnes/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)
 [![Dependency Status](https://gemnasium.com/gonzalo-bulnes/chilean_cities.svg)](https://gemnasium.com/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 _comunas_ as described by the [SUBDERE][subdere].
+A Ruby representation of the Chilean _administrative areas_ as described by the [SUBDERE][subdere].
 
   [subdere]: http://www.subdere.gov.cl
 
-
 Disclaimer
 ----------
 
@@ -19,47 +18,99 @@ This library is not developed, supported nor endorsed in any way by the Chilean
 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][1] are:
+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
-  [1]: http://www.subdere.gov.cl/sites/default/files/documentos/articles-73111_recurso_2.pdf
+  [ref]: http://www.subdere.gov.cl/sites/default/files/documentos/articles-73111_recurso_2.pdf
 
 
 Usage
 -----
 
 Add the gem to your Gemfile:
 
-    gem 'chilean_cities', git: '[email protected]:gonzalo-bulnes/chilean_cities.git'
+```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:
+
+```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].
 
-Then copy the migrations to your application and apply them:
+  [deprecated-doc]: https://github.com/gonzalo-bulnes/chilean_cities/blob/v0.1.0/README.md
 
-    rake chilean_cities:install:migrations
-    rake db:migrate
+See Also
+--------
 
-Add the line `# Load the chilean cities here please` in `db/seeds.rb` if
-your application has one. (If it doesn't, the generator will create one.)
-Finally, generate the seed and run it:
+- 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
 
-    rails generate chilean_cities:seeds
-    bundle exec rake db:seed
+  [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][1]. Thanks for that!
+Part of this gem was crafted during my 10% _free focus_ work time at [Acid Labs][acidlabs]. Thanks @acidlabs!
 
-  [1]: https://github.com/acidlabs
+  [acidlabs]: https://github.com/acidlabs
 
 License
 -------
 
-    ChileanCities provides a Ruby representation of the Chilean _comunas_.
+    ChileanCities provides a Ruby representation of the Chilean _administrative areas_.
     Copyright (C) 2013, 2014, 2015  Gonzalo Bulnes Guilpain
 
     This program is free software: you can redistribute it and/or modify

chilean_cities.gemspec

@@ -19,8 +19,11 @@ Gem::Specification.new do |gem|
   gem.files = Dir["{doc,lib}/**/*", "Gemfile", "LICENSE.txt", "Rakefile", "README.md"]
   gem.test_files = Dir["spec/**/*"]
 
+  gem.add_dependency "activemodel", ">= 3.2.11", "< 5"
   gem.add_dependency "rake", "~> 10.4"
+  gem.add_dependency "multi_json", "~> 1.0"
 
   gem.add_development_dependency "rspec", "~> 3.0"
   gem.add_development_dependency "inch", "~> 0.4.6"
+  gem.add_development_dependency "factory_girl", "~> 4.5"
 end