README.md in emoji_data-0.1.0 vs README.md in emoji_data-0.2.0.rc1
- old
+ new
@@ -1,25 +1,33 @@
# emoji_data.rb
[](https://rubygems.org/gems/emoji_data)
[](https://travis-ci.org/mroth/emoji_data.rb)
[](https://gemnasium.com/mroth/emoji_data.rb)
-[](https://codeclimate.com/github/mroth/emoji_data.rb)
[](https://coveralls.io/r/mroth/emoji_data.rb)
+Ruby library providing low level operations for dealing with Emoji
+glyphs in the Unicode standard. :cool:
-Provides classes and helpers for dealing with emoji character data as unicode. Wraps a library of all known emoji characters and provides convenience methods.
+EmojiData is like a swiss-army knife for dealing with Emoji encoding issues. If
+all you need to do is translate `:poop:` into :poop:, then there are plenty of
+other libs out there that will probably do what you want. But once you are
+dealing with Emoji as a fundamental part of your application, and you start to
+realize the nightmare of [doublebyte encoding][doublebyte] or
+[variants][variant], then this library may be your new best friend.
+:raised_hands:
-Note, this is mostly useful for low-level operations. If you can avoid having to deal with unicode character data extensively and just want to encode/decode stuff, [rumoji](https://github.com/mwunsch/rumoji) might be a better bet for you. If however, you are doing anything complicated involving emoji encoding/decoding, or you are just obsessed with understanding the details, this library is your new best friend.
+EmojiData is used in production by [Emojitracker.com][emojitracker] to parse
+well over 100M+ emoji glyphs daily. :dizzy:
-This library currently uses `iamcal/emoji-data` as it's dataset, and thus considers it to be the "source of truth" regarding certain things, such as how to represent doublebyte unified codepoint IDs as strings (seperated by a dash).
+[doublebyte]: http://www.quora.com/Why-does-using-emoji-reduce-my-SMS-character-limit-to-70
+[variant]: http://www.unicode.org/L2/L2011/11438-emoji-var.pdf
+[emojitracker]: http://www.emojitracker.com
-This is basically a helper library for my [emojitrack](https://github.com/mroth/emojitrack) and [emojistatic](https://github.com/mroth/emojistatic) projects, but may be useful for other people.
-
## Installation
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`:
gem 'emoji_data'
And then execute:
@@ -27,44 +35,64 @@
Or install it yourself as:
$ gem install emoji_data
-Currently requires `RUBY_VERSION >= 1.9.2`.
+Currently requires `RUBY_VERSION >= 1.9.3`.
-## Library Usage
+## Usage
-Pretty straightforward, read the source. But here are some things you might care about:
+### Documentation
+Full API documentation is available via YARD or here:
+http://rubydoc.info/github/mroth/emoji_data.rb/master/frames
-### EmojiData
+### Examples
+Here are some examples of the type of stuff you can do:
- The `EmojiData` module provides some convenience methods for dealing with the library of known emoji characters. Check out the source to see what's up.
+```irb
+>> require 'emoji_data'
+=> true
-Some notable methods to call out:
+>> EmojiData.from_unified('1f680')
+=> #<EmojiData::EmojiChar:0x007f8fdba33b40 @variations=[], @name="ROCKET",
+@unified="1F680", @docomo=nil, @au="E5C8", @softbank="E10D", @google="FE7ED",
+@image="1f680.png", @sheet_x=25, @sheet_y=4, @short_name="rocket",
+@short_names=["rocket"], @text=nil, @apple_img=true, @hangouts_img=true,
+@twitter_img=true>
- - `EmojiData.find_by_unified(id)` gives you a quick way to grab a specific EmojiChar.
+>> EmojiData.all.count
+=> 845
- >> EmojiData.find_by_unified('1f680')
- => #<EmojiData::EmojiChar:0x007fd455ab2ff8 @name="ROCKET", @unified="1F680", @docomo="", @au="E5C8", @softbank="E10D", @google="FE7ED", @image="1f680.png", @sheet_x=21, @sheet_y=28, @short_name="rocket", @short_names=["rocket"], @text=nil>
+>> EmojiData.all_with_variants.count
+=> 107
- - `EmojiData.find_by_name(name)` and `.find_by_short_name(name)` do pretty much what you'd expect:
+>> EmojiData.find_by_short_name("moon").count
+=> 13
- >> EmojiData.find_by_name('thumb')
- => [#<EmojiData::EmojiChar:0x007f9db214a558 @name="THUMBS UP SIGN", @unified="1F44D", @docomo="E727", @au="E4F9", @softbank="E00E", @google="FEB97", @image="1f44d.png", @sheet_x=10, @sheet_y=17, @short_name="+1", @short_names=["+1", "thumbsup"], @text=nil>, #<EmojiData::EmojiChar:0x007f9db2149720 @name="THUMBS DOWN SIGN", @unified="1F44E", @docomo="E700", @au="EAD5", @softbank="E421", @google="FEBA0", @image="1f44e.png", @sheet_x=10, @sheet_y=18, @short_name="-1", @short_names=["-1", "thumbsdown"], @text=nil>]
+>> EmojiData.all.select(&:doublebyte?).map(&:short_name)
+=> ["hash", "zero", "one", "two", "three", "four", "five", "six", "seven",
+"eight", "nine", "cn", "de", "es", "fr", "gb", "it", "jp", "kr", "ru", "us"]
- - `EmojiData.char_to_unified(char)` takes a string containing a unified unicode representation of an emoji character and gives you the unicode ID.
+>> EmojiData.find_by_name("tree").map { |c| [c.unified, c.name, c.render] }
+=> [["1F332", "EVERGREEN TREE", "🌲"], ["1F333", "DECIDUOUS TREE", "🌳"],
+["1F334", "PALM TREE", "🌴"], ["1F384", "CHRISTMAS TREE", "🎄"], ["1F38B",
+"TANABATA TREE", "🎋"]]
- >> EmojiData.char_to_unified('🚀')
- => "1F680"
+>> EmojiData.scan("I ♥ when marketers talk about the ☁. #blessed").each do |ec|
+?> puts "Found some #{ec.short_name}!"
+>> end
+Found some hearts!
+Found some cloud!
+=> [...]
+```
- - `EmojiData.all` will return an array of all known EmojiChars, so you can map or do whatever funky Enumerable stuff you want to do across the entire character set.
+## Contributing
- #gimmie the shortname of all doublebyte chars
- >> EmojiData.all.select(&:doublebyte?).map(&:short_name)
- => ["hash", "zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "cn", "de", "es", "fr", "gb", "it", "jp", "kr", "ru", "us"]
+Please be sure to run `rake spec` and help keep test coverage at :100:.
+There is a full benchmark suite available via `scripts/benchmark.rb`. Please
+run before and after your changes to ensure you have not caused a performance
+regression.
-### EmojiData::EmojiChar
+## License
- `EmojiData::EmojiChar` is a class representing a single emoji character. All the variables from the `iamcal/emoji-data` dataset have dynamically generated getter methods.
-
-There are some additional convenience methods, such as `#doublebyte?` etc. Most important addition is the `#char` method which will output a properly unicode encoded string containing the character.
+[The MIT License (MIT)](LICENSE)