Skip to content

Latest commit

 

History

History
230 lines (156 loc) · 6.27 KB

README.md

File metadata and controls

230 lines (156 loc) · 6.27 KB
Raw

JpPrefecture

English

Gem Version GitHub Actions Coveralls

https://rubygems.org/gems/jp_prefecture

jp_prefecture とは

都道府県コードと都道府県名を変換するライブラリです。

JIS X 0402 で定義されている都道府県コードをベースに、 ゼロから始まるものはゼロを削除して使用しています。

北海道: 01 -> 1
東京都: 13 -> 13

参考: Wikipedia: 全国地方公共団体コード

都道府県コードと都道府県名のマッピングは変更することもできます。 詳しくは「都道府県のマッピング情報を変更する」の項目を参照してください。

また、Rails のプラグインとして使用することもできます。

使い方

ライブラリの読み込み

require 'jp_prefecture'

都道府県コードから都道府県を検索

都道府県コードを渡すと、都道府県コードから都道府県を検索します:

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
# => "都"

以下のように書くことも可能です:

JpPrefecture::Prefecture.find(code: 13)

都道府県を検索

前方一致で都道府県を検索します:

# 漢字表記
JpPrefecture::Prefecture.find(name: "東京都")
JpPrefecture::Prefecture.find(name: "東京")

# 英語表記
JpPrefecture::Prefecture.find(name_e: "Tokyo")
JpPrefecture::Prefecture.find(name_e: "tokyo")

# ローマ字表記
JpPrefecture::Prefecture.find(name_r: "Tōkyō")
JpPrefecture::Prefecture.find(name_r: "tōkyō")

# ひらがな表記
JpPrefecture::Prefecture.find(name_h: "とうきょうと")

# カタカナ表記
JpPrefecture::Prefecture.find(name_k: "トウキョウト")

マッピングのすべての項目を検索します (推奨しません):

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

都道府県の一覧を取得

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]>, ...]

Rails (ActiveRecord) で使用する

ActiveRecord::Base を継承した Model で、都道府県コードを扱うことができます。

app/models/place.rb:

class Place < ActiveRecord::Base
  # prefecture_code:integer

  include JpPrefecture
  jp_prefecture :prefecture_code
end

prefecture というメソッドが生成され、都道府県コード、都道府県名が参照できるようになります:

place = Place.new
place.prefecture_code = 13
place.prefecture.name
# => "東京都"

生成されるメソッド名は method_name というオプションで指定することができます:

# model
jp_prefecture :prefecture_code, method_name: :pref

place = Place.new
place.prefecture_code = 13
place.pref.name
# => "東京都"

テンプレートで使用する

collection_select を使用して、都道府県のセレクトボックスを生成することができます。:

f.collection_select :prefecture_code, JpPrefecture::Prefecture.all, :code, :name

# 英語表記で出力
f.collection_select :prefecture_code, JpPrefecture::Prefecture.all, :code, :name_e

マイグレーション

カラムのタイプは integer か string で作成してください。

マイグレーションのサンプル:

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

都道府県のマッピング情報を変更する

デフォルトのマッピング情報以外のものを使用したい場合、以下のようにカスタマイズされた マッピングデータを指定することができます:

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

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

マッピングデータのフォーマットについては prefecture.yml を参考にしてください。

郵便番号の情報を変更する

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

データのフォーマットについては zip.yml を参考にしてください。

インストール

以下の行を Gemfile に記述してから:

gem 'jp_prefecture'

bundle を実行してください。

または、手動でインストールしてください:

$ gem install jp_prefecture

ドキュメント

https://rubydoc.info/gems/jp_prefecture

サポートしているバージョン

  • Ruby: 2.4 - 3.3
  • Rails: 5.0 - 7.2

これより古い Ruby/Rails バージョンを使用する場合は、v0.11.0 を利用してください。

Contributing

CONTRIBUTING.md を確認してください。

GitHub

https://github.com/chocoby/jp_prefecture