geopolitical 3.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8e48641bb3edaca229ec8ee388684cff45da3612
-  data.tar.gz: 1cf9b43ae4f9080148b6bbd12f0ffaf0602d48d4
+SHA256:
+  metadata.gz: 6eab76b546c1fe68a2b74c24193504f349c650ef97a5982cc87ee5fb74769d4e
+  data.tar.gz: 3301e6d264d6446a0663941819b76b64f956e83f89a16e5bcf70f87644abe616
 SHA512:
-  metadata.gz: 75ec8c8ae0d7e35033e6ce0274f37c0e2b543bdca5d4e100dd97eb0bb758d761de58c24c0f2f823c88e73146e26eedb5df938987a42939276c88d940cf2e7145
-  data.tar.gz: 8fa9fb4416f4a07b42a4c9f17c3a2986d7650727c4dbdab898e60ea4570c1e5261de3aa782296848f441bd94cd55d80dd44ffba6bc654f24daf866b65f3175a2
+  metadata.gz: e4b582dacaf75fe5584450b61ee55d05bab5e15565ee7ee31c0104a852fcd1d28853fef45aa11c5de67bc48d9be8f18997789032fed639dd4deba8a5cd8e45ad
+  data.tar.gz: 1461b8bf452628a21c708f7c884d72301d0ac421079671b554e1aa2d4816064adafde8595c95c988936b52f85b5996c37bd27e08c00ee8e1d31461f88c200e68

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 3.2.0
+
+- Slugs work in every script: `東京` → `東京`, `Санкт-Петербург` → `санкт-петербург`. Non-Latin names were previously invalid (blank slug). Accents are stripped via NFKD (`Hà Nội` → `ha-noi`). Underscores now become hyphens.
+- `Geopolitocracy.slugify(text)` is public; `slug=`, `.search` and `Hood` all use it.
+- `Nation['br']` — find by abbr, any case.
+- City name uniqueness is now scoped by nation **and** region; region-less cities in different nations no longer collide.
+- Removed `==`/`<=>` overrides on City, Region, Hood (Mongoid's `_id` equality already matches the unique indexes) and `Hood#as_json`.
+- Removed empty rake task and RDoc task.
+- Tested on Ruby 3.2 through 4.0 (CI matrix); `required_ruby_version` is now `>= 3.2` (Rails 8 / the test suite floor).
+- Engine request specs cover full CRUD for all four resources.
+- `Geopolitical.parent_controller` lets a host app point the engine's controllers at one of its own, so the admin UI inherits the host's authentication. Defaults to `ActionController::Base` (unauthenticated), and the README now says so.
+- **i18n**: every label, button, table header and flash in the engine now goes through `I18n`; `config/locales/geopolitical.en.yml` and `geopolitical.pt.yml` ship with the gem. Model and attribute names use Mongoid's `mongoid.models` / `mongoid.attributes` scopes, so `f.label :souls` translates for free.
+- The dashboard and layout used `model_name.human.pluralize` for nav headings, which is English-only ("Regiãos"); they now use `model_name.human(count: 2)`.
+
+### Fixes from review
+
+
+- **City slugs are unique planet-wide again.** A city with no region is now suffixed with its nation abbr (`singapore-sg`, `victoria-sc`), mirroring the region suffix (`santos-sp`). Previously two region-less cities in different nations both slugged to the same string.
+- `City`s unique slug index was never created: `Geopolitocracy` declared a plain `index({slug: 1})` that shadowed it. The concern no longer declares one; `Region` (which needs a non-unique one for `.search`) declares its own.
+- `slugify` normalizes to NFC first — decomposed input (macOS filenames, some form posts) slugged as `sa-o-paulo`.
+- Moving a city to another region now refreshes the cached `rbbr` and rebuilds the slug; it used to keep the old abbr forever.
+- Renaming or moving a `Hood` rebuilds its slug instead of stacking prefixes (`rio-rj-santos-sp-gonzaga`).
+- `Nation#lang=` keeps the nations other languages instead of wiping `langs` to a single entry.
+- `Nation[]` returns `nil` for an unknown abbr instead of raising `DocumentNotFound`.
+
+**Upgrading:** stored slugs are not rewritten until a document is saved again, so existing data is untouched � but region-less cities will pick up a nation suffix the next time they are saved, and `City.create_indexes` will now fail on a database that already holds duplicate city slugs. `geonames_local` depends on `geopolitical > 0.8.4` (no upper bound) and will pick this up on its next bundle.

data/README.md

@@ -1,91 +1,170 @@
-Geopolitical
-============
+# Geopolitical
 
 [![Gem Version](https://badge.fury.io/rb/geopolitical.svg)](http://badge.fury.io/rb/geopolitical)
-[![Code Climate](https://codeclimate.com/github/fireho/geopolitical.svg)](https://codeclimate.com/github/fireho/geopolitical)
-[![Coverage Status](https://coveralls.io/repos/fireho/geopolitical/badge.svg?branch=&service=github)](https://coveralls.io/github/fireho/geopolitical?branch=)
-[![Dependency Status](https://gemnasium.com/fireho/geopolitical.svg)](https://gemnasium.com/fireho/geopolitical)
-[![Build Status](https://travis-ci.org/fireho/geopolitical.svg)](https://travis-ci.org/fireho/geopolitical)
+[![CI](https://github.com/fireho/geopolitical/actions/workflows/ci.yml/badge.svg)](https://github.com/fireho/geopolitical/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](MIT-LICENSE)
+
+```
+        _.--""--._            Nation ─┐  "Brasil"  BR  .br  BRL  +55
+      .'   __ o   '.                  │
+     /   .'  \      \         Region ─┤  "São Paulo"  SP  America/Sao_Paulo
+    |   /  o  |  ~   |                │
+    |   \_ o /   ~   |          City ─┤  "São Paulo"  sao-paulo-sp  (-46.63, -23.55)
+     \    `-'     ~ /                 │
+      '.  ~  ~  ~ .'            Hood ─┘  "Vila Madalena"  sao-paulo-sp-vila-madalena
+        `--....--'
+                              place.hood.city.region.nation.planet  # => :earth
+```
+
+**The whole planet as four Mongoid models.** Nation → Region → City → Hood,
+with slugs that never collide, names in every script, geo queries, and a
+fallback chain for phone/postal codes. Bring your own data (Geonames, IBGE,
+a CSV, a hunch) — or let [geonames_local](https://github.com/nofxx/geonames_local)
+fill it for you.
+
+## Why not the other gems?
+
+| gem                                                        | Nation | Region | City | Hood | DB       | Geo | i18n names | Admin UI |
+|------------------------------------------------------------|:------:|:------:|:----:|:----:|----------|:---:|:----------:|:--------:|
+| [countries](https://github.com/countries/countries)         | ✓      | ✓      | –    | –    | in-memory| –   | ✓          | –        |
+| [city-state](https://github.com/loureirorg/city-state)      | ✓      | ✓      | ✓    | –    | in-memory| –   | –          | –        |
+| [geonames-rails](https://github.com/tanguyantoine/geonames-rails) | ✓ | ✓  | ✓    | –    | AR       | ✓   | –          | –        |
+| [geonames_dump](https://github.com/kmmndr/geonames_dump)    | ✓      | ✓      | ✓    | –    | AR       | ✓   | –          | –        |
+| **geopolitical**                                           | ✓      | ✓      | ✓    | ✓    | Mongoid  | ✓   | ✓          | ✓        |
+
+Static lists are great until a user wants *their* city in the dropdown, a
+neighborhood on the address, or a query like "cities within 50km".
+That's when you want documents, not constants.
+
+## Install
+
+```ruby
+gem 'geopolitical'
+```
+
+Rails: it's an engine, models autoload. Optionally mount the admin UI:
+
+```ruby
+# config/routes.rb
+mount Geopolitical::Engine => '/geopolitical'
+```
+
+**The admin UI has no authentication of its own** — it is a mountable engine, so
+guarding it is the host app's job. Either constrain the mount:
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount Geopolitical::Engine => '/geopolitical'
+end
+```
+
+or hand the engine a controller of yours that already authenticates:
+
+```ruby
+# config/initializers/geopolitical.rb
+Geopolitical.parent_controller = 'Admin::BaseController'
+```
+
+Plain Ruby: configure Mongoid, then `require 'geopolitical'`.
+
+### Languages
+
+The engine ships `en` and `pt` (`config/locales/geopolitical.*.yml`) and follows
+`I18n.locale` — model names, attribute labels, buttons and flashes all move together:
+
+```ruby
+I18n.locale = :pt
+City.model_name.human(count: 2)      # => "Cidades"
+Hood.human_attribute_name(:souls)    # => "População"
+```
+
+Override a string by defining the same key in your app, or add a locale by copying
+one of those two files. Note the model *data* is localized separately — `name` and
+`alt` are `localize: true` fields, so a city carries its own name per language.
+
+## Cheat sheet
+
+
+```ruby
+br = Nation.create!(name: 'Brasil', abbr: 'br', tld: '.br', cash: 'BRL', langs: %w[pt], phone: '55')
+sp = Region.create!(name: 'São Paulo', abbr: 'SP', nation: br, timezone: 'America/Sao_Paulo')
+sampa = City.create!(name: 'São Paulo', region: sp, souls: 12_000_000, geom: [-46.63, -23.55])
+vila = Hood.create!(name: 'Vila Madalena', city: sampa)
+
+Nation['br']                    # => #<Nation BR>   abbr is the _id, any case
+Nation.find('BR')               # same thing
+sampa.slug                      # => "sao-paulo-sp"    region suffix, no collisions
+vila.slug                       # => "sao-paulo-sp-vila-madalena"
+sampa.nation                    # => BR   derived from the region, you may omit it
+sampa.to_s                      # => "São Paulo/SP"
+sampa.with_nation('-')          # => "São Paulo-SP-BR"
+sampa.population                # => 12000000   alias of `souls`
+vila.phone                      # => "55"   hood → city → region → nation
+br.currency                     # => "BRL"  alias of `cash`
+
+City.search('sao pa')           # slug prefix, accent/case-insensitive
+City.search('sao-paulo-sp', exact: true)
+City.nearby(sampa.geom)         # 2dsphere $near, needs City.create_indexes
+City.population.first           # biggest city
+Region.ordered                  # by name
+```
+
+Slugs are the API. They're stable, unique, URL-safe and they survive scripts
+you can't transliterate:
 
-Geopolitical models ready to use!
+```
+"São Paulo"        => "sao-paulo"
+"Baden-Württemberg"=> "baden-wurttemberg"
+"Hà Nội"           => "ha-noi"
+"St. Louis"        => "st-louis"
+"東京"              => "東京"
+"Санкт-Петербург"  => "санкт-петербург"
+"دبي"              => "دبي"
+```
 
-With
-----
+Two Springfields? `springfield-il` and `springfield-ma`. Tokyo with a region
+that has no abbr? `tokyo-東京都`. It just works.
 
-    gem "geopolitical"
+## The models
 
+```
+Nation   _id = abbr (ISO 3166-1 α2)   gid  tld  cash  code3  langs  capital
+  └── Region   abbr (ISO 3166-2)  code  timezone  capital        unique per nation
+        └── City   geom (Point)  area  rbbr           slug unique globally
+              └── Hood   rank                        slug unique globally
+```
 
-I have
-------
+Every model shares (via the `Geopolitocracy` concern):
+`name` & `alt` (localized), `abbr`, `nick`, `ascii`, `code`, `slug`,
+`souls`/`population`, `postal`, `phone`, `.search`, `.ordered`, `to_s`, `==`, `<=>`.
 
-[DB Pattern](http://dbpatterns.com/documents/54b5b9529785db781af57b4e)
+Names get titleized only when you shout or mumble: `'new york'` and
+`'NEW YORK'` become `"New York"`; `'McAllen'` stays `"McAllen"`.
 
-Nation > Region > City > Hood all with:
+## Feeding it
 
-* Names (with i18n and sanitized version)
-* ISO codes and abbreviations (Nations & Regions)
-* Hierarchy (Hood.first.city.region.nation.abbr # BR)
-* Languages
-* Geometries
-* Postal codes
-* Phone codes
+[geonames_local](https://github.com/nofxx/geonames_local) downloads
+[Geonames](http://download.geonames.org/export/dump/) dumps and writes
+straight into these models:
 
+```
+geonames BR -c geonames.yml    # all of Brasil: regions, cities, hoods
+```
 
-Geopolitical
-------------
+Or hand-roll from any source — every model is just a Mongoid document.
 
-## ISO 3366-1
+## Development
 
-Two letter code: BR, DE, UK, US...
+```
+bundle install
+bundle exec rspec     # needs a local mongod
 
-## ISO 3366-2
+```
 
-Region/Province state code:
-BR-SP, BR-RJ, BR-MG, US-NY, US-WA, US-CA
+Specs take a world tour (`spec/models/world_spec.rb`): Japan, Russia, Greece,
+Egypt, India, Korea, Germany, the US, Singapore… add your country if it's
+missing, that's the best PR you can send.
 
-## Geometries
+## License
 
-Areas and points.
-
-
-## Phone codes
-
-With the help of phonie, it's now easy to two way
-map entities and phone codes.
-
-## Postal codes
-
-Great for address validation and form pre-population.
-
-
-Outside Rails
--------------
-
-    require 'geopolitical/models'
-
-
-Naming
-------
-
-* Nation ->  Country
-  * Region ->  State/Province
-    * City   ->  District/Microregion
-      * Hood   ->  Zone/Neighbourhood
-
-
-Each must be inside the former.
-
-
-Populate
---------
-
-Use Geonames_local to populate data easily!
-"geonames_local"(https://github.com/fireho/geonames_local)
-
-Links
------
-
-http://download.geonames.org/export/dump/
-http://www.statoids.com/ubr.html
-
-This project rocks and uses MIT-LICENSE.
+MIT. Bug reports and PRs at [fireho/geopolitical](https://github.com/fireho/geopolitical).

data/app/controllers/geopolitical/application_controller.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Geopolitical
+  class ApplicationController < Geopolitical.parent_controller.constantize
+    protect_from_forgery with: :exception
+    layout 'geopolitical'
+  end
+end

data/app/controllers/geopolitical/cities_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Geopolitical
+  class CitiesController < ApplicationController
+    before_action :set_city, only: %i[show edit update destroy]
+    before_action :set_form_options, only: %i[new edit create update]
+
+    def index
+      @cities = City.ordered
+    end
+
+    def show; end
+
+    def new
+      @city = City.new
+    end
+
+    def edit; end
+
+    def create
+      @city = City.new(city_params)
+      if @city.save
+        redirect_to city_path(@city), notice: t('geopolitical.flash.created', model: City.model_name.human)
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @city.update(city_params)
+        redirect_to city_path(@city), notice: t('geopolitical.flash.updated', model: City.model_name.human)
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @city.destroy
+      redirect_to cities_path, notice: t('geopolitical.flash.destroyed', model: City.model_name.human)
+    end
+
+    private
+
+    def set_city
+      @city = City.find(params[:id])
+    end
+
+    def set_form_options
+      @nations = Nation.ordered.map { |nation| [nation.to_s, nation.id] }
+      @regions = Region.ordered.map { |region| [region.to_s, region.id] }
+    end
+
+    def city_params
+      params.require(:city).permit(:name, :slug, :nation_id, :region_id, :souls, :postal, :phone)
+    end
+  end
+end

data/app/controllers/geopolitical/geopolitical_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Geopolitical
+  class GeopoliticalController < ApplicationController
+    def index; end
+
+    def show
+      render :index
+    end
+
+    def new
+      redirect_to root_path
+    end
+
+    def edit
+      redirect_to root_path
+    end
+  end
+end

data/app/controllers/geopolitical/hoods_controller.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Geopolitical
+  class HoodsController < ApplicationController
+    before_action :set_hood, only: %i[show edit update destroy]
+    before_action :set_city_options, only: %i[new edit create update]
+
+    def index
+      @hoods = Hood.ordered
+    end
+
+    def show; end
+
+    def new
+      @hood = Hood.new
+    end
+
+    def edit; end
+
+    def create
+      @hood = Hood.new(hood_params)
+      if @hood.save
+        redirect_to hood_path(@hood), notice: t('geopolitical.flash.created', model: Hood.model_name.human)
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @hood.update(hood_params)
+        redirect_to hood_path(@hood), notice: t('geopolitical.flash.updated', model: Hood.model_name.human)
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @hood.destroy
+      redirect_to hoods_path, notice: t('geopolitical.flash.destroyed', model: Hood.model_name.human)
+    end
+
+    private
+
+    def set_hood
+      @hood = Hood.find(params[:id])
+    end
+
+    def set_city_options
+      @cities = City.ordered.map { |city| [city.to_s, city.id] }
+    end
+
+    def hood_params
+      params.require(:hood).permit(:name, :slug, :city_id, :souls, :rank, :postal, :phone)
+    end
+  end
+end

data/app/controllers/geopolitical/nations_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Geopolitical
+  class NationsController < ApplicationController
+    before_action :set_nation, only: %i[show edit update destroy]
+
+    def index
+      @nations = Nation.ordered
+    end
+
+    def show; end
+
+    def new
+      @nation = Nation.new
+    end
+
+    def edit; end
+
+    def create
+      @nation = Nation.new(nation_params)
+      if @nation.save
+        redirect_to nation_path(@nation), notice: t('geopolitical.flash.created', model: Nation.model_name.human)
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @nation.update(nation_params)
+        redirect_to nation_path(@nation), notice: t('geopolitical.flash.updated', model: Nation.model_name.human)
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @nation.destroy
+      redirect_to nations_path, notice: t('geopolitical.flash.destroyed', model: Nation.model_name.human)
+    end
+
+    private
+
+    def set_nation
+      @nation = Nation.find(params[:id])
+    end
+
+    def nation_params
+      params.require(:nation).permit(:name, :abbr, :slug, :lang, :cash, :code, :code3, :tld, :postal, :phone)
+    end
+  end
+end

data/app/controllers/geopolitical/regions_controller.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Geopolitical
+  class RegionsController < ApplicationController
+    before_action :set_region, only: %i[show edit update destroy]
+    before_action :set_nation_options, only: %i[new edit create update]
+
+    def index
+      @regions = Region.ordered
+    end
+
+    def show; end
+
+    def new
+      @region = Region.new
+    end
+
+    def edit; end
+
+    def create
+      @region = Region.new(region_params)
+      if @region.save
+        redirect_to region_path(@region), notice: t('geopolitical.flash.created', model: Region.model_name.human)
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @region.update(region_params)
+        redirect_to region_path(@region), notice: t('geopolitical.flash.updated', model: Region.model_name.human)
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @region.destroy
+      redirect_to regions_path, notice: t('geopolitical.flash.destroyed', model: Region.model_name.human)
+    end
+
+    private
+
+    def set_region
+      @region = Region.find(params[:id])
+    end
+
+    def set_nation_options
+      @nations = Nation.ordered.map { |nation| [nation.to_s, nation.id] }
+    end
+
+    def region_params
+      params.require(:region).permit(:name, :abbr, :slug, :nation_id, :timezone, :postal, :phone)
+    end
+  end
+end

data/app/helpers/geopolitical/application_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Geopolitical
   # Geopolitical Views Helper
   module ApplicationHelper