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.).
-
Install the namae gem (or add it to your Gemfile):
$ gem install namae -
Start parsing names! Namae expects you to pass in a string and it returns a list of parsed names:
require 'namae' names = Namae.parse 'Yukihiro "Matz" Matsumoto' #-> [#<Name family="Matsumoto" given="Yukihiro" nick="Matz">] -
Use the name objects to access the individual parts:
matz = names[0] matz.nick #-> "Matz" matz.family #-> "Matsumoto" matz.initials #-> "Y.M." matz.initials :expand => true #-> "Y. Matsumoto" matz.initials :dots => false #-> "YM"
It is easy to integrate Namae into your Rails project. There are two typical cases where this might be useful: you want to store individual parts of a person's name in your database, but want to provide your user's with a single input field; or else, you keep personal names in a single database column but your application occasionally requires access to individual parts.
For the latter use case, there is a straightforward way to add Namae to your Rails model:
class Person < ActiveRecord::Base
attr_accessible :name
delegate :family, :initials, :to => :namae
private
def namae
@namae ||= Namae::Name.parse(name)
end
end
In this minimal example, we are using the method Namae::Name.parse which
always returns a single Name instance and delegate all readers for the name's
parts in which we are interested to this instance.
Namae recognizes names in a wide variety of two basic formats, internally referred to as display-order and sort-order. For example, the following names are written in display-order:
Namae.parse 'Charles Babbage'
#-> [#<Name family="Babbage" given="Charles">]]
Namae.parse 'Mr. Alan M. Turing'
#-> [#<Name family="Turing" given="Alan M." appellation="Mr.">]
Namae.parse 'Yukihiro "Matz" Matsumoto'
#-> [#<Name family="Matsumoto" given="Yukihiro" nick="Matz">]
Namae.parse 'Augusta Ada King and Lord Byron'
#-> [#<Name family="King" given="Augusta Ada">, #<Name family="Byron" title="Lord">]
Namae.parse 'Sir Isaac Newton'
#-> [#<Name family="Newton" given="Isaac" title="Sir">]
Namae.parse 'Prof. Donald Ervin Knuth'
#-> [#<Name family="Knuth" given="Donald Ervin" title="Prof.">]
Namae.parse 'Ms. Sofia Kovaleskaya'
#-> [#<Name family="Kovaleskaya" given="Sofia" appellation="Ms.">]
Namae.parse 'Countess Ada Lovelace'
#-> [#<Name family="Lovelace" given="Ada" title="Countess">]
Namae.parse 'Ken Griffey Jr.'
#-> [#<Name family="Griffey" given="Ken" suffix="Jr.">]
Or in sort-order:
Namae.parse 'Turing, Alan M.'
#-> [#<Name family="Turing" given="Alan M.">]
You can also mix sort- and display-order in the same expression:
Namae.parse 'Torvalds, Linus and Alan Cox'
#-> [#<Name family="Torvalds" given="Linus">, #<Name family="Cox" given="Alan">]
Typically, sort-order names are easier to parse, because the syntax is less ambiguous. For example, multiple family names are always possible in sort-order:
Namae.parse 'Carreño Quiñones, María-Jose'
#-> [#<Name family="Carreño Quiñones" given="María-Jose">]
Whilst in display-order, multiple family names are only supported when the name contains a particle or a nickname.
Namae tries to detect common particles using the :uppercase_particle lexer
pattern. If you prefer to always include particles with the family name, you
can set the the :include_particle_in_family parser option.
Namae.parse 'Ludwig von Beethoven'
#-> [#<Name family="Beethoven" given="Ludwig" particle="von">]
Namae.options[:include_particle_in_family] = true
#-> [#<Name family="von Beethoven" given="Ludwig">]
You can tweak some of Namae's parse rules by configuring the parser's
options. Take a look at Namae.options to see your current settings.
If you want to change the default settings for all parsers, you can run
Namae.configure which will yield the default options (make sure to
change the configuration before using the parser).
When using the top-level parse functions, Namae will re-use a thread-local
parser instance (Namae::Parser.instance); the instance is created, using
the current default options (Namae::Parser.defaults). If you need more
control, you are encouraged to create individual parser instances using
Namae::Parser.new.
Parsing human names is at once too easy and too hard. When working in the confines of a single language or culture it is often a trivial task that does not warrant a dedicated software package; when working across different cultures, languages, or scripts, however, it may quickly become unrealistic to devise a satisfying, one-size-fits-all solution. In languages like Japanese or Chinese, for instance, the issue of word segmentation alone is probably more difficult than name parsing itself.
Having said that, Namae is based on the rules used by BibTeX to format names and can therefore be used to parse names of most languages using latin script with the long-time goal to support as many languages and scripts as possible without the need for sophisticated or large dictionary based language-detection or word segmentation features.
For further reading, see the W3C's primer on Personal Names Around the World.
The Namae source code is hosted on GitHub. You can check out a copy of the latest code using Git:
$ git clone https://github.com/berkmancenter/namae.git
To get started, generate the parser and run all tests:
$ cd namae
$ bundle install
$ bundle exec rake features
$ bundle exec rake spec
If you've found a bug or have a question, please open an issue on the issue tracker. Or, for extra credit, clone the Namae repository, write a failing example, fix the bug and submit a pull request.
- Sylvester Keil
- Dan Collis-Puro
Namae was written as a part of a Google Summer of Code project. Thanks Google!
Copyright (c) 2013-2020 Sylvester Keil
Copyright (c) 2012 President and Fellows of Harvard College.
Namae is dual licensed under the AGPL and a BSD-style license.