namae 0.1.0

data/lib/namae/parser.y

@@ -0,0 +1,175 @@
+# -*- racc -*-
+
+class Namae::Parser
+
+token COMMA UWORD LWORD PWORD NICK AND APPELLATION TITLE
+
+expect 0
+
+rule
+
+  names :                { result = [] }
+        | name           { result = [val[0]] }
+        | names AND name { result = val[0] << val[2] }
+
+  name : word            { result = Name.new(:given => val[0]) }
+       | display_order
+       | honorific word          { result = val[0].merge(:family => val[1]) }
+       | honorific display_order { result = val[1].merge(val[0]) }
+       | sort_order
+  
+  honorific : APPELLATION { result = Name.new(:appellation => val[0]) }
+            | TITLE       { result = Name.new(:title => val[0]) }
+            
+  display_order : u_words word
+       {
+         result = Name.new(:given => val[0], :family => val[1])
+       }
+       | u_words NICK last
+       {
+         result = Name.new(:given => val[0], :nick => val[1], :family => val[2])
+       }
+       | u_words NICK von last
+       {
+         result = Name.new(:given => val[0], :nick => val[1],
+           :particle => val[2], :family => val[3])
+       }
+       | u_words von last
+       {
+         result = Name.new(:given => val[0], :particle => val[1],
+          :family => val[2])
+       }
+       | von last
+       {
+         result = Name.new(:particle => val[0], :family => val[1])
+       }
+       
+  sort_order : last COMMA first
+       {
+         result = Name.new(:family => val[0], :suffix => val[2][0],
+           :given => val[2][1])
+       }
+       | von last COMMA first
+       {
+         result = Name.new(:particle => val[0], :family => val[1],
+           :suffix => val[3][0], :given => val[3][1])
+       }
+       | u_words von last COMMA first
+       {
+         result = Name.new(:particle => val[0,2].join(' '), :family => val[2],
+           :suffix => val[4][0], :given => val[4][1])
+       }
+       ;
+
+  von : LWORD
+      | von LWORD         { result = val.join(' ') }
+      | von u_words LWORD { result = val.join(' ') }
+
+  last : LWORD | u_words
+
+  first : opt_words                 { result = [nil,val[0]] }
+        | opt_words COMMA opt_words { result = [val[0],val[2]] }
+
+  u_words : u_word
+          | u_words u_word { result = val.join(' ') }
+
+  u_word : UWORD | PWORD
+
+  words : word
+        | words word { result = val.join(' ') }
+  
+  opt_words : /* empty */ | words
+
+  word : LWORD | UWORD | PWORD
+
+---- header
+require 'singleton'
+require 'strscan'
+
+---- inner
+
+  include Singleton
+    
+  attr_reader :options
+  
+  def initialize
+    @input, @options = StringScanner.new(''), {
+      :debug => false,
+      :comma => ',',
+      :separator => /\s*(\band\b|\&)\s*/i,
+      :title => /\s*\b(sir|lord|(prof|dr|md|ph\.?d)\.?)(\s+|$)/i,
+      :appellation => /\s*\b((mrs?|ms|fr|hr)\.?|miss|herr|frau)(\s+|$)/i
+    }
+  end
+  
+  def debug?
+    options[:debug] || ENV['DEBUG']
+  end
+  
+  def separator
+    options[:separator]
+  end
+  
+  def comma
+    options[:comma]
+  end
+
+  def title
+    options[:title]
+  end
+
+  def appellation
+    options[:appellation]
+  end
+  
+  def parse(input)
+    parse!(input)
+  rescue => e
+    warn e.message if debug?
+    []
+  end
+  
+  def parse!(string)
+    @yydebug = debug?
+    input.string = string.strip
+    do_parse
+  end
+    
+  private
+  
+  def next_token
+    case
+    when input.nil?, input.eos?
+      nil
+    when input.scan(separator)
+      [:AND, nil]
+    when input.scan(/\s*,\s*/)
+      [:COMMA, nil]
+    when input.scan(/\s+/)
+      next_token
+    when input.scan(title)
+      [:TITLE, input.matched.strip]
+    when input.scan(appellation)
+      [:APPELLATION, input.matched.strip]
+    when input.scan(/((\\\w+)?\{[^\}]*\})*[[:upper:]][^\s#{comma}]*/)
+      [:UWORD, input.matched]
+    when input.scan(/((\\\w+)?\{[^\}]*\})*[[:lower:]][^\s#{comma}]*/)
+      [:LWORD, input.matched]
+    when input.scan(/(\\\w+)?\{[^\}]*\}[^\s#{comma}]*/)
+      [:PWORD, input.matched]
+    when input.scan(/('[^'\n]+')|("[^"\n]+")/)
+      [:NICK, input.matched[1...-1]]
+    else
+      raise ArgumentError,
+        "Failed to parse name #{input.string.inspect}: unmatched data at offset #{input.pos}"
+    end
+  end
+    
+  def on_error(tid, value, stack)
+    raise ArgumentError,
+      "Failed to parse name: unexpected '#{value}' at #{stack.inspect}"
+  end
+    
+  attr_reader :input
+
+# -*- racc -*-

data/lib/namae/utility.rb

@@ -0,0 +1,47 @@
+
+# Namae is a parser for human names. It recognizes personal names of
+# various cultural backgrounds and tries to split them into their
+# component parts (e.g., given and family names, honorifics etc.).
+#
+# The main use case of Namae is to use the {Namae.parse .parse} or
+# {Namae.parse! .parse!} method to parse a string of names and return
+# a list of {Namae::Name Name} objects.
+#
+# @example Name parsing
+#   Namae.parse('Yukihiro "Matz" Matsumoto')
+#   #=> [#<Name family="Matsumoto" given="Yukihiro" nick="Matz">]
+#
+#   Namae.parse('Torvalds, Linus and Cox, Alan')
+#   #=> [#<Name family="Torvalds" given="Linus">, #<Name family="Cox" given="Alan">]
+#
+module Namae
+
+  module_function
+  
+  # Parses the passed-in string and returns a list of names. Behaves like
+  # parse but returns an empty list for bad input without raising an error.
+  #
+  # @see parse!
+  #
+  # @param names [String] the name or names to be parsed
+  # @return [Array] the list of parsed names
+  def parse(names)
+    Parser.instance.parse(names)
+  end
+
+  # Parses the passed-in string and returns a list of names.
+  #
+  # @param names [String] the name or names to be parsed
+  # @return [Array] the list of parsed names
+  #
+  # @raise [ArgumentError] if the string cannot be parsed.
+  def parse!(names)
+    Parser.instance.parse!(names)
+  end
+  
+  # @return [Hash] the parser's current configuration.
+  def options
+    Parser.instance.options
+  end
+  
+end

data/lib/namae/version.rb

@@ -0,0 +1,10 @@
+module Namae
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    BUILD = nil
+
+    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.').freeze
+  end
+end

data/namae.gemspec

@@ -0,0 +1,80 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "namae"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Sylvester Keil", "Dan Collis-Puro"]
+  s.date = "2012-06-04"
+  s.description = " Namae is a parser for human names. It recognizes personal names of various cultural backgrounds and tries to split them into their component parts (e.g., given and family names, honorifics etc.). "
+  s.email = ["sylvester@keil.or.at", "dan@collispuro.com"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md"
+  ]
+  s.files = [
+    ".autotest",
+    ".document",
+    ".rspec",
+    ".simplecov",
+    ".travis.yml",
+    ".yardopts",
+    "Gemfile",
+    "LICENSE",
+    "README.md",
+    "Rakefile",
+    "cucumber.yml",
+    "features/bibtex.feature",
+    "features/examples.feature",
+    "features/step_definitions/namae_steps.rb",
+    "features/support/env.rb",
+    "lib/namae.rb",
+    "lib/namae/name.rb",
+    "lib/namae/parser.rb",
+    "lib/namae/parser.y",
+    "lib/namae/utility.rb",
+    "lib/namae/version.rb",
+    "namae.gemspec",
+    "spec/namae/name_spec.rb",
+    "spec/namae/parser_spec.rb",
+    "spec/namae/utility_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "https://github.com/berkmancenter/namae"
+  s.licenses = ["AGPL"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "Namae parses personal names and splits them into their component parts."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<racc>, ["~> 1.4.8"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.1"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<ZenTest>, ["~> 4.8.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
+    else
+      s.add_dependency(%q<racc>, ["~> 1.4.8"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<bundler>, ["~> 1.1"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<ZenTest>, ["~> 4.8.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+    end
+  else
+    s.add_dependency(%q<racc>, ["~> 1.4.8"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<bundler>, ["~> 1.1"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<ZenTest>, ["~> 4.8.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+  end
+end
+

data/spec/namae/name_spec.rb

@@ -0,0 +1,65 @@
+module Namae
+  describe 'Name' do
+    
+    describe '.new' do
+      
+      it 'returns an empty name by default' do
+        Name.new.should be_empty
+      end
+      
+      it 'sets all passed-in attributes' do
+        Name.new(:given => 'Foo').given.should == 'Foo'
+      end
+
+      it 'ignores unknown attributes' do
+        Name.new(:foo => 'bar').should be_empty
+      end
+      
+    end
+    
+    describe '#values_at' do
+      it 'returns an array with the given values' do
+        Name.new(:family => 'foo').values_at(:family).should == ['foo']
+      end
+
+      it 'returns an array with the given values' do
+        Name.new(:family => 'foo').values_at(:family).should == ['foo']
+      end
+    end
+    
+    describe '#initials' do
+      it "returns the name's initials" do
+        Name.new(:family => 'Poe', :given => 'Edgar A.').initials.should == 'E.A.P.'
+      end
+
+      it "returns the name's initials but leaves the family name expanded" do
+        Name.new(:family => 'Poe', :given => 'Edgar A.').initials(:expand => true).should == 'E.A. Poe'
+      end
+    end
+    
+    describe '#merge' do
+      it 'merges the attributes in the given hash into the name' do
+        Name.new.merge(:family => 'foo').family.should == 'foo'
+      end
+
+      it 'merges the attributes in the given name into the name' do
+        Name.new.merge(Name.new(:family => 'foo')).family.should == 'foo'
+      end
+      
+      it 'ignores unknown attributes' do
+        Name.new.merge(:foo => 'bar').should be_empty
+      end
+      
+      it 'ignores nil values' do
+        Name.new(:family => 'foo').merge(:family => nil).family.should == 'foo'
+      end
+    end
+    
+    describe '#inspect' do
+      it 'returns the name as a string' do
+        Name.new(:given => 'Ichiro').inspect.should == '#<Name given="Ichiro">'
+      end
+    end
+    
+  end
+end

data/spec/namae/parser_spec.rb

@@ -0,0 +1,107 @@
+module Namae
+  describe 'Parser' do
+    
+    it 'does not respond to .new' do
+      Parser.should_not respond_to(:new)
+    end
+    
+    describe '.instance' do
+      let(:parser) { Parser.instance }
+      
+      it 'returns the parser' do
+        parser.should be_a(Parser)
+      end
+      
+      describe '#next_token' do
+        describe 'when the input is empty' do
+          it 'returns nil' do
+            parser.send(:next_token).should be_nil
+          end
+        end
+        
+        describe 'when the next input is " and "' do
+          before { parser.send(:input).string = ' and ' }
+          it 'returns an AND token' do
+            parser.send(:next_token).should == [:AND, nil]
+          end
+        end
+
+        describe 'when the next input is " & "' do
+          before { parser.send(:input).string = ' & ' }
+          it 'returns an AND token' do
+            parser.send(:next_token).should == [:AND, nil]
+          end
+        end
+
+        describe 'when the next input is " , "' do
+          before { parser.send(:input).string = ' , ' }
+          it 'returns a COMMA token' do
+            parser.send(:next_token).should == [:COMMA, nil]
+          end
+        end
+        
+        describe 'when the next input is " \'foo bar\' "' do
+          before { parser.send(:input).string = " 'foo bar' " }
+          it 'returns a NICK token' do
+            parser.send(:next_token).should == [:NICK, 'foo bar']
+          end
+        end
+        
+        %w{Mr. Mr Mrs. Ms Herr Frau Miss}.each do |appellation|
+          describe "the next token is #{appellation.inspect}" do
+            before { parser.send(:input).string = appellation }
+            it 'returns an APPELLATION token' do
+              parser.send(:next_token).should == [:APPELLATION, appellation]
+            end
+          end
+        end
+        
+      end
+      
+      describe '#parse!' do
+        it 'returns an empty list by default' do
+          parser.parse!('').should be_empty
+        end
+        
+        it 'returns a list of names' do
+          parser.parse!('foo')[0].should be_a(Name)
+        end
+        
+        describe 'when parsing a single name' do
+          
+          it 'treats "Ichiro" as a given name' do
+            parser.parse!('Ichiro')[0].given.should == 'Ichiro'
+          end
+
+          it 'treats "Lord Byron" as a title and family name' do
+            parser.parse!('Lord Byron')[0].values_at(:family, :title).should == ['Byron', 'Lord']
+          end
+          
+          it 'parses given and family part name in "Ichiro Suzuki"' do
+            parser.parse!('Ichiro Suzuki')[0].values_at(:given, :family).should == %w{Ichiro Suzuki}
+          end
+          
+          it 'parses given, nick and family part name in "Yukihiro \'Matz\' Matsumoto"' do
+            parser.parse!("Yukihiro 'Matz' Matsumoto")[0].values_at(:given, :family, :nick).should == %w{Yukihiro Matsumoto Matz}
+          end
+
+          it 'parses given, nick and family part name in \'Yukihiro "Matz" Matsumoto\'' do
+            parser.parse!('Yukihiro "Matz" Matsumoto')[0].values_at(:given, :family, :nick).should == %w{Yukihiro Matsumoto Matz}
+          end
+          
+          it 'parses given and family name in "Poe, Edgar A."' do
+            parser.parse!('Poe, Edgar A.')[0].values_at(:given, :family).should == ['Edgar A.', 'Poe']
+          end
+          
+          %w{Mr. Mr Mrs. Ms Herr Frau Miss}.each do |appellation|
+            it "recognizes #{appellation.inspect} as an appellation" do
+              parser.parse!([appellation, 'Edgar A. Poe'].join(' '))[0].appellation.should == appellation
+            end
+          end
+          
+        end
+      end
+      
+    end  
+  end
+end