japanese_names 0.0.2 → 0.0.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Y2RiZjRlZTEzMDQ4NjJhZmQyMTg4YmI5ZjE0M2IyNGU5MGRlNGU1YQ==
+    YTZhOWUxMzRlNTE5ZmVmZTJkMWJmMzlhZTYzMzBjNzAxZjEzMzQ2MA==
   data.tar.gz: !binary |-
-    OWVlN2EzY2NmYWNiMzA1ZThjZGQxYjUxY2MwZTE2YzRhZGZiNDU5ZA==
+    MDdhYjQ3NTA3NTgxZjMyY2Q4ZmQxZTk2MzgwMmRjYzMwMzAxNmQ4Mg==
 SHA512:
   metadata.gz: !binary |-
-    YmViZDBkNzFhNjU5OGE0NGNlZDAzMzUzMTAwZjBmOWI3OWE3ZjdhZjYwYTI4
-    MDZlODJkNTA2ZjQ5ZTU2M2E2YjEwNzY1Mjk2MDVlOWMyNWU4NzA4ZTlkNmFl
-    MTlkZjdhNjhhY2NiZDQ3MTU3MjQ3MTMzMmVjMTE2YTg5NmM4YzM=
+    ZGQxNjI5ODEyYjUwZTYzY2JlZDZmOWQwYzI4ZjRkNzc3ZTljMTc0YzdlNWNj
+    NjFiOTQ3MGJkYjg1Y2NiNTI5YWI1NTJmNWIwNWNkYTkyODU3ODU3Yjc4MDY3
+    N2Q2NmJlMGUzZWY2N2MzZjA1N2VjYTUwYTc2MDVjMTE3YWM0YWE=
   data.tar.gz: !binary |-
-    ZTVmZWI4ZGUxNDQ5ZDA5ZTZhYjRkZjcxMzU3ZDQxNmQ2YTYwMmQyZTk3Njgz
-    NzUxYzdlOThkNTgwM2I4NGQxODY5OWMxNGM3OGIwODViYmU1ZjZjYmIzZWNi
-    YjhhOWIzMDM2ZjFhNDhlMjZlM2I3MjFjYjdlNGYxYmU0NzM0NGE=
+    YjRiNTMzNzQzMDc1OGQ2NWY3YmExM2VjOWMyOWE4ODBiZTFmNGQzMmI3MTJi
+    NzU0NmJiNzdhY2YwMjY5OGRiYWUzYTM4NmM2MDUwMjA3NTE0MTljY2Y2ODgx
+    ZGM2MTc1ZmVhN2ZjMTk0ZGFmZGVhOTljNTY1ZWQ1NTZiZDhlODE=

data/README.md

@@ -1,10 +1,58 @@
 # JapaneseNames
 
-Japanese name parser based on ENAMDIC
+JapaneseNames provides an interface to the [ENAMDIC file](http://www.csse.monash.edu.au/~jwb/enamdict_doc.html).
 
-## Overview
 
-JapaneseNames provides an interface to the [ENAMDIC file](http://www.csse.monash.edu.au/~jwb/enamdict_doc.html).
+## JapaneseNames::Enamdict
+
+This library comes packaged with a compacted version of the [ENAMDIC file](http://www.csse.monash.edu.au/~jwb/enamdict_doc.html)
+at `bin/enamdict.min`. Refer to *Rake Tasks* below for how this file is constructed.
+
+`JapaneseNames::Enamdict` is a module; all methods are called on the module `self` class.
+
+
+### Enamdict.find
+
+Provides a structured query interface to access ENAMDICT data.
+
+   ```ruby
+   JapaneseNames::Enamdict.find(kanji: '外世子')  #=> [["外世子", "とよこ", "f"]]
+
+   JapaneseNames::Enamdict.find(kana: 'ならしま', flags: 's')  #=> [["奈良島", "ならしま", "s"],
+                                                                      ["楢島", "ならしま", "s"],
+                                                                      ["楢嶋", "ならしま", "s"]]
+
+   JapaneseNames::Enamdict.find(kanji: '楢二郎', kana: 'ならじろう')  #=> [["楢二郎", "ならじろう", "m"]]
+   ```
+
+where options are:
+
+* `kanji`: The kanji name string to match. Regex syntax suppported. Either `:kanji` or `:kana` must be specified.
+* `kana`:  The kana name string to match. Regex syntax suppported.
+* `flags`: The flag char or array of flag chars to match. Refer to [ENAMDIC documentation](http://www.csse.monash.edu.au/~jwb/enamdict_doc.html).
+Additionally constants JapaneseNames::Enamdict::NAME_FAM and JapaneseNames::Enamdict::NAME_GIV may be used.
+
+Note that romaji data has been removed from our `enamdict.min` file in the compression step. We recommend to use a gem such as `mojinizer` to convert romaji to kana before doing a query.
+
+
+### Enamdict.match
+
+Provides a raw interface to match ENAMDICT entries via a block, which would typically contain a `Regexp` expression:
+
+   ```ruby
+   JapaneseNames::Enamdict.match{|entry| entry =~ /^堺|/}  #=> [["堺", "さかい", "p,s"], ["堺", "さかえ", "p"]]
+   ```
+
+where each dictionary entry is in the format below (different from raw ENAMDICT file):
+
+   ```
+   kanji|kana|flag1(,flag2,...)
+   ```
+
+
+## JapaneseNames::Parser
+
+### Parser#split
 
 Currently the main method is `split` which, given a kanji and kana representation of a name splits
 into to family/given names.
@@ -14,13 +62,77 @@ into to family/given names.
   parser.split('堺雅美', 'さかいマサミ')  #=> [['堺', '雅美'], ['さかい', 'マサミ']]
 ```
 
+The logic is as follows:
 
-## ENAMDICT
+* Step 1: Split kanji name into possible surname sub-strings
 
-This library comes packaged with a compacted version of the [ENAMDIC file](http://www.csse.monash.edu.au/~jwb/enamdict_doc.html)
-at `bin/enamdict.min`.
+   ```
+   上原亜沙子 => 
+
+   上原亜沙子
+   上原亜沙
+   上原亜
+   上原
+   上
+   ```
+
+* Step 2: Lookup possible kana matches in dictionary (done in a single pass)
+
+   ```
+   上原亜沙子 => X
+   上原亜沙　 => X
+   上原亜　　 => X
+   上原　　　 => かみはら　かみばら　うえはら うえばら...
+   上　　　　 => かみ　うえ ...
+   ```
+
+* Step 3: Compare kana lookups versus kana name and detect first match (starting from longest candidate string)
+
+   ```
+   うえはらあさこ contains かみはら ? => X
+   うえはらあさこ contains かみばら ? => X
+   うえはらあさこ contains うえはら ? => YES! [うえはら]あさこ
+   ```
+
+* Step 4: If match found, split names accordingly
+
+   ```
+   [上原]亜沙子  => 上原 亜沙子
+   [うえはら]あさこ => うえはら あさこ
+   ```
+
+* Step 5: If match not found, repeat steps 1-4 in reverse for given name:
+
+   ```
+   上原亜沙子 => 
 
-This file can be regenerated by `rake enamdict:refresh`, which downloads, extracts, and compiles the ENAMDICT file.
+   上原亜沙子 => X
+   　原亜沙子 => X
+   　　亜沙子 => あさこ
+   　　　沙子 => さこ
+   　　　　子 => こ
+
+   上原[亜沙子]  => 上原 亜沙子
+   うえはら[あさこ] => うえはら あさこ
+   ```
+
+* Step 6: If match still not found, return `nil`
+
+
+## Rake Tasks
+
+The following tasks are used for development purposes of this gem only. They will not be accessible
+in projects which use this gem.
+
+* `rake enamdict:refresh`: Runs `enamdict:download` and `enamdict:minify` (see below)
+
+* `rake enamdict:download`: Downloads and extract the ENAMDICT file to `/tmp/enamdict`
+
+* `rake enamdict:minify`: Compiles `/bin/enamdict.min` file from `/tmp/enamdict`. Performs several processing steps including:
+   * Converts to UTF-8
+   * Compacts format (pipe-delimited)
+   * Removes non-human name entries
+   * Removes romaji strings (redundant with kana)
 
 
 ## TODO
@@ -38,6 +150,12 @@ implementation of the dictionary would be nice.
 Fork -> Commit -> Spec -> Push -> Pull Request
 
 
+## Similar Projects
+
+* Marco Bresciani's [wwwwjdic](https://rubygems.org/gems/wwwjdic) gem which is **NOT** used by this lib
+* [@jeresig](https://github.com/jeresig)'s [node-enamdict](https://github.com/jeresig/node-enamdict) an ENAMDIC reader for Node.js
+
+
 ## Authors
 
 * [@johnnyshields](https://github.com/johnnyshields)

data/lib/japanese_names/enamdict.rb

@@ -18,7 +18,8 @@ module JapaneseNames
 
     class << self
 
-      # Public: Matches kanji and/or kana regex strings in the dictionary.
+      # Public: Finds kanji and/or kana regex strings in the dictionary via
+      # a structured query interface.
       #
       # opts - The Hash options used to match the dictionary (default: {}):
       #        kanji: Regex to match kanji name (optional)
@@ -26,7 +27,7 @@ module JapaneseNames
       #        flags: Flag or Array of flags to filter the match (optional)
       #
       # Returns the dict entries as an Array of Arrays [[kanji, kana, flags], ...]
-      def match(opts={})
+      def find(opts={})
         return [] unless opts[:kanji] || opts[:kana]
 
         kanji = name_regex opts.delete(:kanji)
@@ -34,14 +35,14 @@ module JapaneseNames
         flags = flags_regex opts.delete(:flags)
         regex = /^#{kanji}\|#{kana}\|#{flags}$/
 
-        search{|line| line[regex]}
+        match{|line| line[regex]}
       end
 
-      # Public: Selects entries in the enamdict based on a block which should
+      # Public: Matches entries in the enamdict based on a block which should
       # evaluate true or false (typically a regex).
       #
       # Returns the dict entries as an Array of Arrays [[kanji, kana, flags], ...]
-      def search(&block)
+      def match(&block)
         sel = []
         each_line do |line|
           if block.call(line)

data/lib/japanese_names/parser.rb

@@ -20,7 +20,7 @@ module JapaneseNames
     def split_giv(kanji, kana)
       return nil unless kanji && kana
       kanji, kana = kanji.strip, kana.strip
-      dict = Enamdict.match(kanji: window_right(kanji))
+      dict = Enamdict.find(kanji: window_right(kanji))
       dict.sort!{|x,y| y[0].size <=> x[0].size}
       kana_match = nil
       if match = dict.detect{|m| kana_match = kana[/#{hk m[1]}$/]}
@@ -31,7 +31,7 @@ module JapaneseNames
     def split_fam(kanji, kana)
       return nil unless kanji && kana
       kanji, kana = kanji.strip, kana.strip
-      dict = Enamdict.match(kanji: window_left(kanji))
+      dict = Enamdict.find(kanji: window_left(kanji))
       dict.sort!{|x,y| y[0].size <=> x[0].size}
       kana_match = nil
       if match = dict.detect{|m| kana_match = kana[/^#{hk m[1]}/]}

data/lib/japanese_names/version.rb

@@ -2,5 +2,5 @@
 # encoding: utf-8
 
 module JapaneseNames
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/spec/unit/enamdict_spec.rb

@@ -7,15 +7,15 @@ describe JapaneseNames::Enamdict do
 
   subject { JapaneseNames::Enamdict }
 
-  describe '#search' do
+  describe '#match' do
 
     it 'should select only lines which match criteria' do
-      result = subject.search{|line| line =~ /^.+?\|あわのはら\|.+?$/}
+      result = subject.match{|line| line =~ /^.+?\|あわのはら\|.+?$/}
       result.should eq [["粟野原", "あわのはら", "s"]]
     end
 
     it 'should select multiple lines' do
-      result = subject.search{|line| line =~ /^.+?\|はしの\|.+?$/}
+      result = subject.match{|line| line =~ /^.+?\|はしの\|.+?$/}
       result.should eq [["橋之", "はしの", "p"],
                         ["橋埜", "はしの", "s"],
                         ["橋野", "はしの", "s"],
@@ -24,15 +24,15 @@ describe JapaneseNames::Enamdict do
     end
   end
 
-  describe '#lookup' do
+  describe '#find' do
 
     it 'should match kanji only' do
-      result = subject.match(kanji: '外世子')
+      result = subject.find(kanji: '外世子')
       result.should eq [["外世子", "とよこ", "f"]]
     end
 
     it 'should match kana only' do
-      result = subject.match(kana: 'ならしま')
+      result = subject.find(kana: 'ならしま')
       result.should eq [["樽島", "ならしま", "u"],
                         ["奈良島", "ならしま", "s"],
                         ["楢島", "ならしま", "s"],
@@ -40,19 +40,19 @@ describe JapaneseNames::Enamdict do
     end
 
     it 'should match both kanji and kana only' do
-      result = subject.match(kanji: '楢二郎', kana: 'ならじろう')
+      result = subject.find(kanji: '楢二郎', kana: 'ならじろう')
       result.should eq [["楢二郎", "ならじろう", "m"]]
     end
 
     it 'should match flags as String' do
-      result = subject.match(kana: 'ならしま', flags: 's')
+      result = subject.find(kana: 'ならしま', flags: 's')
       result.should eq [["奈良島", "ならしま", "s"],
                         ["楢島", "ならしま", "s"],
                         ["楢嶋", "ならしま", "s"]]
     end
 
     it 'should match flags as Array' do
-      result = subject.match(kana: 'ならしま', flags: ['u','g'])
+      result = subject.find(kana: 'ならしま', flags: ['u','g'])
       result.should eq [["樽島", "ならしま", "u"]]
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: japanese_names
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Johnny Shields
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-07 00:00:00.000000000 Z
+date: 2014-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: moji