README.md
# Nomener
[](http://badge.fury.io/rb/nomener)
[](https://travis-ci.org/dan-ding/nomener)
[](https://codeclimate.com/github/dan-ding/nomener)
[](https://github.com/dan-ding/nomener/blob/master/LICENSE.txt)
Nomener assists with parsing peoples names that they give themselves (or other people). Nomener ~~is~~ was a fork of [People](https://github.com/dan-ding/people) as it uses some code contributed there. It's currently geared towards western style name formatting, however other cultural name formatting is (or would like to be supported). Currently it attempts to parse names through pattern matching without using large(r) dictionary/library/data files (except for name decorations and suffixes, see usage). It may not be possible to do without such in all languages.
If you didn't know, parsing names can be much more difficult than it seems it should be.
Two of the main goals are to support (a) UX in a similar manner as described by [not splitting form fields](http://www.w3.org/International/questions/qa-personal-names#singlefield) and (b) an easy manner to handle parsing of strings which contain a name.
## Requirements
Requires Ruby 1.9.3 or higher (or equivalent).
If using Ruby 1.9.3 or 2.0.0, it depends on [string-scrub](https://github.com/hsbt/string-scrub)
## Installation
Add this line to your application's Gemfile:
gem 'nomener'
And then execute:
$ bundle
Or install it yourself as:
$ gem install nomener
## Basic Usage
Use Nomener directly:
```ruby
name = Nomener.parse "Joe Smith" # <Nomener::Name first="Joe" last="Smith">
```
Create a new instance:
```ruby
name = Nomener::Name.new "Duke Joe (Henry) Smith Jr."
#<Nomener::Name title="Duke" first="Joe" nick="Henry" last="Smith" suffix="Jr">
```
returns the same as:
```ruby
name = Nomener.parse "Duke Joe (Henry) Smith Jr."
name.first # "Joe"
name.name # "Joe Smith"
"Hi #{name}!" # "Hi Joe Smith!""
name.last # "Smith"
name.title # "Duke"
name.suffix # "Jr"
name.nick # "Henry"
```
## Formatting
The .name method accepts a string to format the name however you may like.
It defaults to "%f %l", which is the first and last name.
Other options are:
- %f # first name
- %l # last/surname/family name
- %m # middle name
- %n # nick name
- %m # middle name
- %s # suffix
- %t # title/prefix
```ruby
name = Nomener::Name.new "Duke Joe (Henry) Smith Jr."
name.name "%l, %f" # "Smith, Joe"
name.name "%t %l" # "Duke Smith"
```
## TODO
* optionally use web service api data to assist (and create the web service!)
* fantasy prefixes/suffixes
* multiple names from one string
* specifying formats to parse by
* many other things
* better non-english support
* translations
* NLP?
## References
* [http://en.wikipedia.org/wiki/Personal_name](http://en.wikipedia.org/wiki/Personal_name)
* [http://en.wikipedia.org/wiki/Surname](http://en.wikipedia.org/wiki/Surname)
* [http://en.wikipedia.org/wiki/Title](http://en.wikipedia.org/wiki/Title)
* [http://www.w3.org/International/questions/qa-personal-names](http://www.w3.org/International/questions/qa-personal-names)
* [http://heraldry.sca.org/titles.html](http://heraldry.sca.org/titles.html)
## Contributing
1. Fork it ( http://github.com/<my-github-username>/nomener/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Ensure adequate tests (rspec) on your branch
4. Commit your changes (`git commit -am 'Add some feature'`)
5. Push to the branch (`git push origin my-new-feature`)
6. Create new Pull Request
## Other similar projects (and inspiration)
* [People](https://github.com/dan-ding/people) [Original](https://github.com/mericson/people)
* [Namae](https://github.com/berkmancenter/namae) (Racc based token)
* [Nameable](https://github.com/chorn/nameable)
* [Person-name](https://github.com/matthijsgroen/person-name)