https://github.com/willnet/gimei
random Japanese name and address generator
https://github.com/willnet/gimei
ruby
Last synced: about 1 month ago
JSON representation
random Japanese name and address generator
- Host: GitHub
- URL: https://github.com/willnet/gimei
- Owner: willnet
- License: mit
- Created: 2012-12-03T11:31:18.000Z (about 13 years ago)
- Default Branch: main
- Last Pushed: 2025-05-02T01:22:16.000Z (10 months ago)
- Last Synced: 2025-05-13T13:10:50.016Z (9 months ago)
- Topics: ruby
- Language: Ruby
- Homepage: https://willnet.github.io/gimei
- Size: 662 KB
- Stars: 417
- Watchers: 11
- Forks: 32
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Gimei
[](https://coveralls.io/r/willnet/gimei)
[](https://codeclimate.com/github/willnet/gimei)
[](https://rubygems.org/gems/gimei)
[日本語のドキュメントはこちら(Japanese README)](README.ja.md)
gimei is a library that generates random Japanese names and addresses. It is useful for testing purposes. A similar library is [faker](https://github.com/stympy/faker). [faker](https://github.com/stympy/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:
```ruby
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`.
```ruby
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.
```ruby
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:
```ruby
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.
```ruby
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.
```ruby
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.
```ruby
Gimei.unique.last
Gimei.unique.first
```
Even in this case, there may be duplicates in terms of furigana.
```ruby
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:
```ruby
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.
```ruby
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.
```ruby
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.
```ruby
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.
```ruby
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.
```ruby
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:
```ruby
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.
```ruby
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](https://github.com/matarillo/dot-gimei)
- Elixir [ma2gedev/gimei_ex](https://github.com/ma2gedev/gimei_ex)
- Emacs Lisp [gongo/emacs-gimei](https://github.com/gongo/emacs-gimei)
- Go [mattn/go-gimei](https://github.com/mattn/go-gimei)
- Java [moznion/gimei-java](https://github.com/moznion/gimei-java)
- Node.js [sabakan404/node-gimei](https://github.com/sabakan404/node-gimei)
- Perl [youpong/Data-Gimei](https://github.com/youpong/Data-Gimei)
- Python [nabetama/gimei](https://github.com/nabetama/gimei)
- TypeScript [abcb2/type-gimei](https://github.com/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