Gimei

日本語のドキュメントはこちら(Japanese README)

gimei is a library that generates random Japanese names and addresses. It is useful for testing purposes. A similar library is faker. faker is an excellent library with multilingual support, but naturally does not support furigana (reading of Japanese characters). gimei supports furigana.

Usage

Generate random names

You can use it as follows:

gimei = Gimei.name
gimei.kanji          #=> "斎藤 陽菜" (Saitou Haruna)
gimei.hiragana       #=> "さいとう はるな"
gimei.katakana       #=> "サイトウ ハルナ"
gimei.romaji         #=> "Haruna Saitou"
gimei.gender         #=> :female
gimei.male?          #=> false
gimei.female?        #=> true
gimei.last.kanji     #=> "斎藤" (Saitou)
gimei.last.hiragana  #=> "さいとう"
gimei.last.katakana  #=> "サイトウ"
gimei.last.romaji    #=> "Saitou"
gimei.first.kanji    #=> "陽菜" (Haruna)
gimei.first.hiragana #=> "はるな"
gimei.first.katakana #=> "ハルナ"
gimei.first.romaji   #=> "Haruna"

You can also use gimei.family and gimei.given instead of gimei.last and gimei.first.

gimei.family.kanji     #=> "斎藤"
gimei.family.hiragana  #=> "さいとう"
gimei.family.katakana  #=> "サイトウ"
gimei.family.romaji    #=> "Saitou"

gimei.given.kanji    #=> "陽菜"
gimei.given.hiragana #=> "はるな"
gimei.given.katakana #=> "ハルナ"
gimei.given.romaji   #=> "Haruna"

You can explicitly specify whether to return a male or female name as shown below. Gimei.name returns male and female names with equal probability.

gimei = Gimei.male
gimei.male?   #=> true
gimei.female? #=> false
gimei.gender  #=> :male
gimei.kanji   #=> "小林 顕士" (Kobayashi Kenji)

gimei = Gimei.female
gimei.male?   #=> false
gimei.female? #=> true
gimei.gender  #=> :female
gimei.kanji   #=> "根本 彩世" (Nemoto Ayase)

If you only need one type of script (Kanji, Hiragana, Katakana, or Romaji), you can write it in a shortened form as follows:

Gimei.kanji          #=> "伊藤 結衣"
Gimei.hiragana       #=> "いとう みさき"
Gimei.katakana       #=> "タカハシ ユイナ"
Gimei.romaji         #=> "Miki Obara"
Gimei.last.kanji     #=> "清水"
Gimei.last.hiragana  #=> "いとう"
Gimei.last.katakana  #=> "コバヤシ"
Gimei.last.romaji    #=> "Wakabayashi"
Gimei.first.kanji    #=> "結菜"
Gimei.first.hiragana #=> "ここあ"
Gimei.first.katakana #=> "ヤマト"
Gimei.first.romaji   #=> "Noriyuki"

Gimei.family.kanji     #=> "黒沢"
Gimei.family.hiragana  #=> "いずみ"
Gimei.family.katakana  #=> "エノモト"
Gimei.family.romaji    #=> "Okada"

Gimei.given.kanji    #=> "航"
Gimei.given.hiragana #=> "まさみつ"
Gimei.given.katakana #=> "ユカ"
Gimei.given.romaji   #=> "Haruto"

If you do not want to retrieve the same name twice, you can use unique. By doing so, Gimei will keep track of the names used and ensure that a unique name is returned.

Gimei.unique.name

In the above case, the full name in Kanji is guaranteed to be unique. That is, there may be duplicates in terms of surname or given name, as shown below.

Gimei.unique.name.kanji #=> "前島 真一"
Gimei.unique.name.kanji #=> "神谷 真一"
Gimei.unique.name.kanji #=> "前島 太郎"

If you want to avoid this, use last or first as follows. This returns a unique name for the surname or given name.

Gimei.unique.last
Gimei.unique.first

Even in this case, there may be duplicates in terms of furigana.

Gimei.unique.first.hiragana #=> "しんいち"
Gimei.unique.first.hiragana #=> "しんいち"

If unique names cannot be returned (e.g., if the list of candidates is exhausted), an error will be raised.

If you want to clear the list of names used so far, do the following:

Gimei.unique.clear # Clear all
Gimei.unique.clear(:name) # Clear results of Gimei.unique.name
Gimei.unique.clear(:first) # Clear results of Gimei.unique.first

Names generated by the following methods are cleared with Gimei.unique.clear(:name).

• Gimei.unique.male
• Gimei.unique.female
• Gimei.unique.kanji

The candidate data for names is located in lib/data/names.yml. Modify the file if necessary.

Generate random addresses

From version 0.2.0, you can also retrieve address information. You can get address information combining prefecture, city/ward, and town in Kanji, Hiragana, and Katakana.

address = Gimei.address
address.kanji                 # => 岡山県大島郡大和村稲木町
address.to_s                  # => 岡山県大島郡大和村稲木町
address.hiragana              # => おかやまけんおおしまぐんやまとそんいなぎちょう
address.katakana              # => オカヤマケンオオシマグンヤマトソンイナギチョウ
address.romaji                # => Okayamaken Ooshimagunyamatoson Inagicho

address.prefecture.kanji      # => 岡山県
address.prefecture.to_s       # => 岡山県
address.prefecture.hiragana   # => おかやまけん
address.prefecture.katakana   # => オカヤマケン
address.prefecture.romaji     # => Okayamaken

address.city.kanji            # => 大島郡大和村
address.city.to_s             # => 大島郡大和村
address.city.hiragana         # => おおしまぐんやまとそん
address.city.katakana         # => オオシマグンヤマトソン
address.city.romaji           # => Ooshimagunyamatoson

address.town.kanji            # => 稲木町
address.town.to_s             # => 稲木町
address.town.hiragana         # => いなぎちょう
address.town.katakana         # => イナギチョウ
address.town.romaji           # => Inagicho

Abbreviations are also available.

Gimei.prefecture.kanji        # => 青森県
Gimei.prefecture.to_s         # => 滋賀県
Gimei.prefecture.hiragana     # => やまがたけん
Gimei.prefecture.katakana     # => チバケン
Gimei.prefecture.romaji       # => Wakayamaken

Gimei.city.kanji              # => 利根郡昭和村
Gimei.city.hiragana           # => うべし
Gimei.city.katakana           # => カモグンヤオツチョウ
Gimei.city.romaji             # => Itanogunaizumichou

Gimei.town.kanji              # => 竹野
Gimei.town.to_s               # => 富久山町南小泉
Gimei.town.hiragana           # => じょうしんでん
Gimei.town.katakana           # => イケナイ
Gimei.town.romaji             # => Heisei

If you do not want to retrieve the same address twice, use unique as follows. By doing so, Gimei will keep track of the addresses used and ensure that a unique address is returned.

address = Gimei.unique.address

In the above case, the entire address is guaranteed to be unique. That is, duplicates may occur at the prefecture or municipality level as shown below.

Gimei.unique.address.prefecture.kanji #=> 東京都
Gimei.unique.address.prefecture.kanji #=> 東京都

If you want to ensure uniqueness at the prefecture or municipality level, use the abbreviated forms as follows.

Gimei.unique.prefecture.kanji #=> 東京都
Gimei.unique.prefecture.kanji #=> 神奈川県

If unique names cannot be returned (e.g., if the list of candidates is exhausted), an error will be raised.

If you want to clear the list of addresses used so far, do the following:

Gimei.unique.clear # Clear all
Gimei.unique.clear(:address) # Clear results of Gimei.unique.address
Gimei.unique.clear(:prefecture) # Clear results of Gimei.unique.prefecture

The candidate data for addresses is located in lib/data/addresses.yml. Modify the file if necessary.

Reproducible random data

You can generate reproducible random data by setting a random number generator as follows.

Gimei.config.rng = Random.new(42)
Gimei.name.kanji    #=> "飯島 誠吾"
Gimei.address.kanji #=> "熊本県日進市東場内"

Gimei.config.rng = Random.new(42)
Gimei.name.kanji    #=> "飯島 誠吾"
Gimei.address.kanji #=> "熊本県日進市東場内"

Supported versions

Ruby 2.3 or higher

Implementations in other languages

• .NET matarillo/dot-gimei
• Elixir ma2gedev/gimei_ex
• Emacs Lisp gongo/emacs-gimei
• Go mattn/go-gimei
• Java moznion/gimei-java
• Node.js sabakan404/node-gimei
• Perl youpong/Data-Gimei
• Python nabetama/gimei
• TypeScript abcb2/type-gimei

Installation

Add this line to your application's Gemfile:

gem 'gimei'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gimei

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request