Skip to content

README_EN.md

Latest commit

 

History

History
233 lines (158 loc) · 5.16 KB

README_EN.md

File metadata and controls

233 lines (158 loc) · 5.16 KB

JpPrefecture

Japanese

Gem Version GitHub Actions Coveralls

https://rubygems.org/gems/jp_prefecture

Description

Convert prefecture code to prefecture name in Japan.

Based on JIS X 0401. Remove 0 when prefecture code start with 0.

Hokkaido: 01 -> 1
Tokyo: 13 -> 13

Reference(Japanese): Wikipedia: 全国地方公共団体コード

You can change prefecture code and prefecture name's mapping data. Please check this Customize mapping data

Also available as a Rails plugin

Usage

Requirement

require 'jp_prefecture'

Search Prefecture by Code

Provide prefecture code to search prefecture's data

pref = JpPrefecture::Prefecture.find(13)
# => #<JpPrefecture::Prefecture:0x00000001126b6558 @area="関東", @code=13, @name="東京都", @name_e="Tokyo", @name_h="とうきょうと", @name_k="トウキョウト", @name_r="Tōkyō", @type="都", @zips=[1000000..2080035]>
pref.code
# => 13
pref.name
# => "東京都"
pref.name_e
# => "Tokyo"
pref.name_r
# => "Tōkyō"
pref.name_h
# => "とうきょうと"
pref.name_k
# => "トウキョウト"
pref.area
# => "関東"
pref.type
# => "都"

or

JpPrefecture::Prefecture.find(code: 13)

Search by Prefecture Name

Search for a prefecture by forward match.

# Kanji
JpPrefecture::Prefecture.find(name: "東京都")
JpPrefecture::Prefecture.find(name: "東京")

# English
JpPrefecture::Prefecture.find(name_e: "Tokyo")
JpPrefecture::Prefecture.find(name_e: "tokyo")

# Romaji
JpPrefecture::Prefecture.find(name_r: "Tōkyō")
JpPrefecture::Prefecture.find(name_r: "tōkyō")

# Hiragana
JpPrefecture::Prefecture.find(name_h: "とうきょうと")

# Katakana
JpPrefecture::Prefecture.find(name_k: "トウキョウト")

Search all items in the mapping (not recommended).

JpPrefecture::Prefecture.find(all_fields: "東京")

All Prefectures

JpPrefecture::Prefecture.all
# => [#<JpPrefecture::Prefecture:0x0000000112555ab0 @area="北海道", @code=1, @name="北海道", @name_e="Hokkaido", @name_h="ほっかいどう", @name_k="ホッカイドウ", @name_r="Hokkaidō", @type="道", @zips=[10000..70895, 400000..996509]>, ...]

Usage on Rails (ActiveRecord)

Include JpPrefecture to Model which ActiveRecord::Base inherited.

app/models/place.rb:

class Place < ActiveRecord::Base
  # prefecture_code:integer

  include JpPrefecture
  jp_prefecture :prefecture_code
end

By JpPrefecture included, prefecture method will be generated:

place = Place.new
place.prefecture_code = 13
place.prefecture.name_e
# => "Tokyo"

Customize prefecture method name with method_name option:

# model
jp_prefecture :prefecture_code, method_name: :pref

place = Place.new
place.prefecture_code = 13
place.pref.name_e
# => "Tokyo"

Template usage

Use collection_select to generate selector in view:

# Selector prefecture name in English
f.collection_select :prefecture_code, JpPrefecture::Prefecture.all, :code, :name_e

# Selector prefecture name in Japanese
f.collection_select :prefecture_code, JpPrefecture::Prefecture.all, :code, :name

Migration

Set prefecture_code column type to integer or string.

Example:

class AddPrefectureCodeToPlaces < ActiveRecord::Migration
  def change
    add_column :places, :prefecture_code, :integer
  end
end

Customize Mapping Data

Customize mapping data with mapping_data.

custom_mapping_path = "/path/to/mapping_data.yml"

JpPrefecture.setup do |config|
  config.mapping_data = YAML.load_file(custom_mapping_path)
end

Check out prefecture.yml for data format.

Customize Zip Code Data

Customize zip code data with zip_mapping_data.

custom_zip_mapping_path = "/path/to/zip_mapping_data.yml"

JpPrefecture.setup do |config|
  config.zip_mapping_data = YAML.load_file(custom_zip_mapping_path)
end

Check out zip.yml for data format.

Installation

Add this line in Gemfile.

gem 'jp_prefecture'

Run

$ bundle

Or install gem with gem install

$ gem install jp_prefecture

Documentation

https://rubydoc.info/gems/jp_prefecture

Supported versions

  • Ruby: 2.4 - 4.0
  • Rails: 5.0 - 8.1

If you are using an older Ruby/Rails version, please use v0.11.0.

Contributing

See CONTRIBUTING.md.

GitHub

https://github.com/chocoby/jp_prefecture