diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..e1766a8 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,272 @@ +# Gimei + +[![Coveralls](https://coveralls.io/repos/willnet/gimei/badge.svg)](https://coveralls.io/r/willnet/gimei) +[![Code Climate](https://codeclimate.com/github/willnet/gimei/badges/gpa.svg)](https://codeclimate.com/github/willnet/gimei) +[![Gem](https://img.shields.io/gem/v/gimei.svg)](https://rubygems.org/gems/gimei) + +gimei は、日本人の名前や、日本の住所をランダムに返すライブラリです。テストの時などに使います。似たようなライブラリに[faker](https://github.com/stympy/faker)があります。[faker](https://github.com/stympy/faker)はとても優れたライブラリで、多言語対応もしていますが、ふりがな(フリガナ)は流石に対応していません。gimei はふりがな(及びフリガナ)に対応しています。 + + +## 使い方 + +### 名前をランダムで返す + +下記のように使います。 + +```ruby +gimei = Gimei.name +gimei.kanji #=> "斎藤 陽菜" +gimei.hiragana #=> "さいとう はるな" +gimei.katakana #=> "サイトウ ハルナ" +gimei.romaji #=> "Haruna Saitou" +gimei.gender #=> :female +gimei.male? #=> false +gimei.female? #=> true +gimei.last.kanji #=> "斎藤" +gimei.last.hiragana #=> "さいとう" +gimei.last.katakana #=> "サイトウ" +gimei.last.romaji #=> "Saitou" +gimei.first.kanji #=> "陽菜" +gimei.first.hiragana #=> "はるな" +gimei.first.katakana #=> "ハルナ" +gimei.first.romaji #=> "Haruna" +``` + +`gimei.last`, `gimei.first` の代わりに、`gimei.family`, `gimei.given` を用いることもできます。 + +```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" +``` + +下記のように男性/女性の名前を返すことを明示的に指定できます。`Gimei.name` の場合は男女の名前を等確率で返します。 + +```ruby +gimei = Gimei.male +gimei.male? #=> true +gimei.female? #=> false +gimei.gender #=> :male +gimei.kanji #=> "小林 顕士" + +gimei = Gimei.female +gimei.male? #=> false +gimei.female? #=> true +gimei.gender #=> :female +gimei.kanji #=> "根本 彩世" +``` + +漢字、ひらがな、カタカナ、ローマ字どれか一種類だけ取得できればよい場合には、下記のように短縮して書くことも出来ます。 + +```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" +``` + +同じ名前を二度取得したくない場合には、以下のように`unique`を挟みます。次のようにすると、利用した名前をGimei内で保持することで必ず一意な名前を返すようにできます。 + +```ruby +Gimei.unique.name +``` + +上記の場合は、フルネームの漢字が一意であることを保証します。つまり、次のように姓や名の単位では重複することもありえます。 + +```ruby +Gimei.unique.name.kanji #=> "前島 真一" +Gimei.unique.name.kanji #=> "神谷 真一" +Gimei.unique.name.kanji #=> "前島 太郎" +``` + +これを避けたいときは次のように`last`や`first`を利用してください。これは姓や名の単位で一意な名前を返します。 + +```ruby +Gimei.unique.last +Gimei.unique.first +``` + +この場合でも、ふりがな(フリガナ)の単位では重複することがあります。 + +```ruby +Gimei.unique.first.hiragana #=> "しんいち" +Gimei.unique.first.hiragana #=> "しんいち" +``` + +もし名前の候補が枯渇するなど、一意な名前を返せない場合はエラーになります。 + +これまで利用した名前のリストを消去したい場合は、次のようにします。 + +```ruby +Gimei.unique.clear # 全体を消去 +Gimei.unique.clear(:name) # Gimei.unique.name の結果を消去 +Gimei.unique.clear(:first) # Gimei.unique.first の結果を消去 +``` + +次のメソッドで生成された名前は`Gimei.unique.clear(:name)`で消去します。 + +- `Gimei.unique.male` +- `Gimei.unique.female` +- `Gimei.unique.kanji` + +出力される名前の候補となるデータは `lib/data/names.yml` にあるので、必要であればファイルを修正してください。 + +### 住所をランダムで返す + +バージョン0.2.0からは、住所情報も取得できるようになりました。都道府県、区、市、町を組み合わせた住所情報を漢字、ひらがな、カタカナで取得することができます。 + +```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 +``` + +省略形も用意しています。 + +```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 +``` + +同じ住所を二度取得したくない場合には、以下のように`unique`を挟みます。次のようにすると、利用した住所をGimei内で保持することで必ず一意な名前を返すようにできます。 + +```ruby +address = Gimei.unique.address +``` + +上記の場合は、住所全体が一意であることを保証します。つまり、次のように県や市町村の単位では重複することもありえます。 + +```ruby +Gimei.unique.address.prefecture.kanji #=> 東京都 +Gimei.unique.address.prefecture.kanji #=> 東京都 +``` + +もし県や市町村の単位で一意であることを保証したいのであれば、次のように短縮形を使います。 + +```ruby +Gimei.unique.prefecture.kanji #=> 東京都 +Gimei.unique.prefecture.kanji #=> 神奈川県 +``` + +もし住所の候補が枯渇するなど、一意な名前を返せない場合はエラーになります。 + +これまで利用した住所のリストを消去したい場合は、次のようにします。 + +```ruby +Gimei.unique.clear # 全体を消去 +Gimei.unique.clear(:address) # Gimei.unique.address の結果を消去 +Gimei.unique.clear(:prefecture) # Gimei.unique.prefecture の結果を消去 +``` + +出力される住所の候補となるデータは `lib/data/addresses.yml` にあるので、必要であればファイルを修正してください。 + +### 再現可能なランダムデータ + +下記のように乱数生成器を設定することで、再現性のあるランダムデータを生成できます。 + +```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以上 + +## 他言語による実装 + +- .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 diff --git a/README.md b/README.md index e1766a8..858240b 100644 --- a/README.md +++ b/README.md @@ -4,35 +4,36 @@ [![Code Climate](https://codeclimate.com/github/willnet/gimei/badges/gpa.svg)](https://codeclimate.com/github/willnet/gimei) [![Gem](https://img.shields.io/gem/v/gimei.svg)](https://rubygems.org/gems/gimei) -gimei は、日本人の名前や、日本の住所をランダムに返すライブラリです。テストの時などに使います。似たようなライブラリに[faker](https://github.com/stympy/faker)があります。[faker](https://github.com/stympy/faker)はとても優れたライブラリで、多言語対応もしていますが、ふりがな(フリガナ)は流石に対応していません。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 #=> "斎藤 陽菜" +gimei.kanji #=> "斎藤 陽菜" (Saitou Haruna) gimei.hiragana #=> "さいとう はるな" gimei.katakana #=> "サイトウ ハルナ" gimei.romaji #=> "Haruna Saitou" gimei.gender #=> :female gimei.male? #=> false gimei.female? #=> true -gimei.last.kanji #=> "斎藤" +gimei.last.kanji #=> "斎藤" (Saitou) gimei.last.hiragana #=> "さいとう" gimei.last.katakana #=> "サイトウ" gimei.last.romaji #=> "Saitou" -gimei.first.kanji #=> "陽菜" +gimei.first.kanji #=> "陽菜" (Haruna) gimei.first.hiragana #=> "はるな" gimei.first.katakana #=> "ハルナ" gimei.first.romaji #=> "Haruna" ``` -`gimei.last`, `gimei.first` の代わりに、`gimei.family`, `gimei.given` を用いることもできます。 +You can also use `gimei.family` and `gimei.given` instead of `gimei.last` and `gimei.first`. ```ruby gimei.family.kanji #=> "斎藤" @@ -46,23 +47,23 @@ gimei.given.katakana #=> "ハルナ" gimei.given.romaji #=> "Haruna" ``` -下記のように男性/女性の名前を返すことを明示的に指定できます。`Gimei.name` の場合は男女の名前を等確率で返します。 +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 #=> "小林 顕士" +gimei.kanji #=> "小林 顕士" (Kobayashi Kenji) gimei = Gimei.female gimei.male? #=> false gimei.female? #=> true gimei.gender #=> :female -gimei.kanji #=> "根本 彩世" +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 #=> "伊藤 結衣" @@ -89,13 +90,13 @@ Gimei.given.katakana #=> "ユカ" Gimei.given.romaji #=> "Haruto" ``` -同じ名前を二度取得したくない場合には、以下のように`unique`を挟みます。次のようにすると、利用した名前をGimei内で保持することで必ず一意な名前を返すようにできます。 +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 #=> "前島 真一" @@ -103,41 +104,41 @@ Gimei.unique.name.kanji #=> "神谷 真一" Gimei.unique.name.kanji #=> "前島 太郎" ``` -これを避けたいときは次のように`last`や`first`を利用してください。これは姓や名の単位で一意な名前を返します。 +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 # 全体を消去 -Gimei.unique.clear(:name) # Gimei.unique.name の結果を消去 -Gimei.unique.clear(:first) # Gimei.unique.first の結果を消去 +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 ``` -次のメソッドで生成された名前は`Gimei.unique.clear(:name)`で消去します。 +Names generated by the following methods are cleared with `Gimei.unique.clear(:name)`. - `Gimei.unique.male` - `Gimei.unique.female` - `Gimei.unique.kanji` -出力される名前の候補となるデータは `lib/data/names.yml` にあるので、必要であればファイルを修正してください。 +The candidate data for names is located in `lib/data/names.yml`. Modify the file if necessary. -### 住所をランダムで返す +### Generate random addresses -バージョン0.2.0からは、住所情報も取得できるようになりました。都道府県、区、市、町を組み合わせた住所情報を漢字、ひらがな、カタカナで取得することができます。 +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 @@ -166,7 +167,7 @@ address.town.katakana # => イナギチョウ address.town.romaji # => Inagicho ``` -省略形も用意しています。 +Abbreviations are also available. ```ruby Gimei.prefecture.kanji # => 青森県 @@ -187,41 +188,41 @@ Gimei.town.katakana # => イケナイ Gimei.town.romaji # => Heisei ``` -同じ住所を二度取得したくない場合には、以下のように`unique`を挟みます。次のようにすると、利用した住所をGimei内で保持することで必ず一意な名前を返すようにできます。 +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 # 全体を消去 -Gimei.unique.clear(:address) # Gimei.unique.address の結果を消去 -Gimei.unique.clear(:prefecture) # Gimei.unique.prefecture の結果を消去 +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 ``` -出力される住所の候補となるデータは `lib/data/addresses.yml` にあるので、必要であればファイルを修正してください。 +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) @@ -235,9 +236,9 @@ Gimei.address.kanji #=> "熊本県日進市東場内" ## Supported versions -Ruby 2.3以上 +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) @@ -269,4 +270,4 @@ Or install it yourself as: 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 +5. Create new Pull Request \ No newline at end of file