gemoji-parser 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1f5c233d77c332dabf52ca117a87ac008e0df2c2
-  data.tar.gz: 79876f028d01361d173c93de9ca527ee6ec71c7b
+  metadata.gz: 3621544eb0c0dfe923ad4639f4ec51fefbf42cdc
+  data.tar.gz: 412e5b97b12b82fd2fcb1ae4a95546bb0eac8bff
 SHA512:
-  metadata.gz: 20e96eb56067495de4b03295e5484853bf86162d0773203f8b67c7eff47bf1ffda05d8753c67c575fe4dd502e68ffbee231a40f75f2db94eb2908b95db1d52e6
-  data.tar.gz: d24710b9c58651f74749ff7fcf2efb00440b04102ffe511e8eaa1b54b066ed5169c9074d8b37eacfb3a6a33fce06117919fc50f77798a08203b2144272eab365
+  metadata.gz: dec9825da6d1d409f98c5afb6cce0363bc00c0ee34b5fa5f6b0ed3c8faca12a1228b7d20b10e75174ed36621756075ba6cb145b766acecd2bb0756fc12d57d5f
+  data.tar.gz: 67e7e574e303eda0b25f2fb1dca6227802afc86210827df428d9d5423b1cf98a92e0abba5788cc156a0f89a9d12281cb634d459832f3e3401af0b7cff555273d

data/README.md

@@ -1,6 +1,6 @@
 # gemoji-parser
 
-The missing helper methods for [GitHub's Gemoji](https://github.com/github/gemoji) gem. This utility provides a parsing API for the `Emoji` corelib (provided by Gemoji). The parser includes quick tokenizers for transforming unicode symbols (🐠) into token symbols (`:tropical_fish:`), and arbitrary block replacement methods for custom formatting of symbols.
+The missing helper methods for [GitHub's gemoji](https://github.com/github/gemoji) gem. This utility provides a parsing API for the `Emoji` corelib (provided by *gemoji*). The parser handles transformations of emoji symbols between unicode (😃), token (`:smile:`), and emoticon (`:-D`) formats; and may perform arbitrary replacement of emoji symbols into custom display formats (such as image tags). Internally, highly-optimized regular expressions are generated and cached to maximize parsing efficiency.
 
 ## Installation
 
@@ -12,7 +12,7 @@ gem 'gemoji-parser'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 
@@ -20,14 +20,13 @@ Or install it yourself as:
 
 To run tests:
 
-	$ be rake spec
+    $ bundle exec rake spec
 
 ## Usage
 
-
 ### Tokenizing
 
-These methods perform basic conversions of unicode symbols to token symbols, and vice versa.
+The tokenizer methods perform basic conversions of unicode symbols into token symbols, and vice versa.
 
 ```ruby
 EmojiParser.tokenize("Test 🙈 🙊 🙉")
@@ -37,56 +36,114 @@ EmojiParser.detokenize("Test :see_no_evil: :speak_no_evil: :hear_no_evil:")
 # "Test 🙈 🙊 🙉"
 ```
 
-### Block Parsing
+### Symbol Parsing
 
-For custom symbol transformations, use the block parser methods. All parsers yeild Gemoji `Emoji::Character` instances into the parsing block for custom formatting.
+Use the symbol parser methods for custom transformations. All symbol parsers yield [Emoji::Character](https://github.com/github/gemoji/blob/master/lib/emoji/character.rb) instances into the parsing block for custom formatting.
 
 **Unicode symbols**
 
 ```ruby
-EmojiParser.parse_unicode('Test 🐠') do |emoji|
+EmojiParser.parse_unicode("Test 🐠") do |emoji|
   %Q(<img src="#{emoji.image_filename}" alt=":#{emoji.name}:">).html_safe
 end
 
-# 'Test <img src="unicode/1F420.png" alt=":tropical_fish:">'
+# 'Test <img src="unicode/1f420.png" alt=":tropical_fish:">'
 ```
 
 **Token symbols**
 
 ```ruby
-EmojiParser.parse_tokens('Test :tropical_fish:') do |emoji|
+EmojiParser.parse_tokens("Test :tropical_fish:") do |emoji|
   %Q(<img src="#{emoji.image_filename}" alt=":#{emoji.name}:">).html_safe
 end
 
-# 'Test <img src="unicode/1F420.png" alt=":tropical_fish:">'
+# 'Test <img src="unicode/1f420.png" alt=":tropical_fish:">'
 ```
 
-**All symbols**
+**Emoticon symbols**
 
 ```ruby
-EmojiParser.parse_all('Test 🐠 :tropical_fish:') { |emoji| emoji.hex_inspect }
+EmojiParser.parse_emoticons("Test ;-)") do |emoji|
+  %Q(<img src="#{emoji.image_filename}" alt=":#{emoji.name}:">).html_safe
+end
 
-# 'Test 1f420 1f420'
+# 'Test <img src="unicode/1f609.png" alt=":wink:">'
 ```
 
-### File Paths
+**All symbol types**
 
-A helper is provided for formatting custom filepaths beyond the Gemoji default. This may be useful if you'd like to upload your images to a CDN, and simply reference them from there:
+Use the `parse` method to target all symbol types with a single parsing pass. Specific symbol types may be excluded using options:
 
 ```ruby
-fish = Emoji.find_by_alias('tropical_fish')
-EmojiParser.filepath(fish, '//cdn.fu/emoji/')
-# "//cdn.fu/emoji/1F420.png"
+EmojiParser.parse("Test 🐠 :scream: ;-)") { |emoji| "[#{emoji.name}]" }
+# 'Test [tropical_fish] [scream] [wink]'
+
+EmojiParser.parse("Test 🐠 :scream: ;-)", emoticons: false) do |emoji|
+  "[#{emoji.name}]"
+end
+# 'Test [tropical_fish] [scream] ;-)'
 ```
 
-## Shoutout
+While the `parse` method is heavier to run than the discrete parsing methods for each symbol type (`parse_unicode`, `parse_tokens`, etc...), it has the advantage of avoiding multiple parsing passes. This is handy if you want parsed symbols to output new symbols in a different format, such as generating image tags that include a symbol in their alt text:
+
+```ruby
+EmojiParser.parse("Test 🐠 ;-)") do |emoji|
+  %Q(<img src="#{emoji.image_filename}" alt=":#{emoji.name}:">).html_safe
+end
+
+# 'Test <img src="unicode/1f420.png" alt=":tropical_fish:"> <img src="unicode/1f609.png" alt=":wink:">'
+```
+
+### Lookups & File Paths
+
+Use the `find` method to derive [Emoji::Character](https://github.com/github/gemoji/blob/master/lib/emoji/character.rb) instances from any symbol format (unicode, token, emoticon):
+
+```ruby
+emoji = EmojiParser.find(🐠)
+emoji = EmojiParser.find('see_no_evil')
+emoji = EmojiParser.find(';-)')
+```
+
+Use the `image_path` helper to derive an image filepath from any symbol format (unicode, token, emoticon). You may optionally provide a custom path that overrides the *gemoji* default location (this is useful if you'd like to reference your images from a CDN):
 
-Thanks to the GitHub team for the [Gemoji](https://github.com/github/gemoji) gem. They're handling all the heavy lifting.
+```ruby
+EmojiParser.image_path('tropical_fish')
+# "unicode/1f420.png"
+
+EmojiParser.image_path('tropical_fish', '//cdn.fu/emoji/')
+# "//cdn.fu/emoji/1f420.png"
+```
+
+## Custom Symbols
+
+**Emoji**
+
+The parser plays nicely with custom emoji defined through the *gemoji* core. You just need to call `rehash!` once after adding new emoji symbols to regenerate the parser's regex cache:
+
+```ruby
+Emoji.create('boxing_kangaroo') # << WHY IS THIS NOT STANDARD?!
+EmojiParser.rehash!
+```
+
+**Emoticons**
+
+Emoticon patterns are defined through the parser, and are simply mapped to an emoji name that exists within the *gemoji* core (this can be a standard emoji, or a custom emoji that you have added). To see default emoticons, inspect the `EmojiParser.emoticons` hash. For custom emoticons:
+
+```ruby
+# Alias a standard emoji:
+EmojiParser.emoticons[':@'] = :angry
+
+# Create a custom emoji, and alias it:
+Emoji.create('bill_clinton')
+EmojiParser.emoticons['=:o]'] = :bill_clinton
+
+# IMPORTANT:
+# Rehash once after adding new symbols to Emoji core, or to the EmojiParser:
+EmojiParser.rehash!
+```
+
+## Shoutout
 
-## Contributing
+Thanks to the GitHub team for the [gemoji](https://github.com/github/gemoji) gem, and my esteemed colleague Michael Lovitt for the fantastic [Rubular](http://rubular.com/) regex tool (it has been invaluable for this project).
 
-1. Fork it ( https://github.com/gmac/gemoji-parser/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+🙈 🙊 🙉

data/gemoji-parser.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.authors       = ["Greg MacWilliam"]
   s.email         = ["greg.macwilliam@voxmedia.com"]
   s.summary       = %q{The missing helper methods for GitHub's Gemoji gem.}
-  s.description   = %q{Parses emoji unicode symbols and string tokens, allowing for customizable transformations.}
+  s.description   = %q{Expands GitHub Gemoji to parse unicode and token emoji symbols into custom formats.}
   s.homepage      = "https://github.com/gmac/gemoji-parser"
   s.license       = "MIT"
 
@@ -19,7 +19,6 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.required_ruby_version = '> 1.9'
-  
   s.add_dependency "gemoji", ">= 2.1.0"
   s.add_development_dependency "bundler", "~> 1.6"
   s.add_development_dependency "rake", "~> 10.0"

data/lib/gemoji-parser.rb

@@ -4,46 +4,215 @@ require 'gemoji'
 module EmojiParser
   extend self
 
-  # Generates a regular expression for matching emoji unicodes.
-  # Call with "rehash: true" to regenerate the cached regex.
-  def emoji_regexp(opts = {})
-    return @emoji_regexp if defined?(@emoji_regexp) && !opts[:rehash]
-    patterns = []
+  # Emoticons
+  # ---------
+  # The base emoticons set (below) is generated with "noseless" variants, ie:  :-) and :)
+  # The generated `EmojiParser.emoticons` hash is formatted as:
+  # ---
+  # > {
+  # >   ":-)" => :blush,
+  # >   ":)" => :blush,
+  # >   ":-D" => :smile,
+  # >   ":D" => :smile,
+  # > }
+  # 
+  # This base set is selected for commonality and high degrees of author intention.
+  # If you want more/different emoticons:
+  # - Please DO customize the `EmojiParser.emoticons` hash in your app runtime.
+  # - Please DO NOT customize this source code and issue a pull request.
+  #
+  # To add an emoticon:
+  # ---
+  # > EmojiParser.emoticons[':-$'] = :grimacing
+  # > EmojiParser.rehash!
+  # 
+  # To remove an emoticon:
+  # ---
+  # > EmojiParser.emoticons.delete(':-$')
+  # > EmojiParser.rehash!
+  # 
+  # NOTE: call `rehash!` after making changes to Emoji/emoticon sets.
+  # Rehashing updates the parser's regex cache with the latest icons.
+  #
+  def emoticons
+    return @emoticons if defined? @emoticons
+    @emoticons = {}
+    emoticons = {
+      angry: ">:-(",
+      blush: ":-)",
+      cry: ":'(",
+      confused: [":-\\", ":-/"],
+      disappointed: ":-(",
+      kiss: ":-*",
+      neutral_face: ":-|",
+      monkey_face: ":o)",
+      open_mouth: ":-o",
+      smiley: "=-)",
+      smile: ":-D",
+      stuck_out_tongue: [":-p", ":-P", ":-b"],
+      stuck_out_tongue_winking_eye: [";-p", ";-P", ";-b"],
+      wink: ";-)"
+    }
+
+    # Parse all named patterns into a flat hash table,
+    # where pattern is the key and its token is the value.
+    # all patterns are duplicated with the "noseless" variants, ie:  :-) and :)
+    emoticons.each_pair do |name, patterns|
+      patterns = [patterns] unless patterns.is_a?(Array)
+      patterns.each do |pattern| 
+        @emoticons[pattern] = name
+        @emoticons[pattern.sub(/(?<=:|;|=)-/, '')] = name
+      end
+    end
+
+    @emoticons
+  end
+
+  attr_writer :emoticons
+
+  # Rehashes all cached regular expressions.
+  # IMPORTANT: call this once after changing emoji characters or emoticon patterns.
+  def rehash!
+    unicode_regex(rehash: true)
+    token_regex(rehash: true)
+    emoticon_regex(rehash: true)
+  end
+
+  # Creates an optimized regular expression for matching unicode symbols.
+  # - Options: rehash:boolean
+  def unicode_regex(opts={})
+    return @unicode_regex if defined?(@unicode_regex) && !opts[:rehash]
+    pattern = []
 
     Emoji.all.each do |emoji|
       u = emoji.unicode_aliases.map do |str|
         str.codepoints.map { |c| '\u{%s}' % c.to_s(16).rjust(4, '0') }.join('')
       end
-      # Append unicode patterns longest first for broader match:
-      patterns.concat u.sort! { |a, b| b.length - a.length }
+      # Simple method: x10 slower!
+      # pattern.concat u.sort! { |a, b| b.length - a.length }
+      pattern << unicode_matcher(u) if u.any?
+    end
+
+    @unicode_pattern = pattern.join('|')
+    @unicode_regex = Regexp.new("(#{@unicode_pattern})")
+  end
+
+  # Creates a regular expression for matching token symbols.
+  # - Options: rehash:boolean (currently unused)
+  def token_regex(opts={})
+    return @token_regex if defined?(@token_regex)
+    @token_pattern = ':([\w+-]+):'
+    @token_regex = Regexp.new(@token_pattern)
+  end
+
+  # Creates an optimized regular expression for matching emoticon symbols.
+  # - Options: rehash:boolean
+  def emoticon_regex(opts={})
+    return @emoticon_regex if defined?(@emoticon_regex) && !opts[:rehash]
+    pattern = {}
+
+    emoticons.keys.each do |icon|
+      compact_icon = icon.gsub('-', '')
+
+      # Check to see if this icon has a compact version, ex:  :-)  versus  :)
+      # One expression will match as many nose/noseless variants as possible.
+      if compact_icon != icon && emoticons[compact_icon]
+        compact_regex = Regexp.escape(icon).gsub('-', '-?')
+
+        # Keep this expression if it hasn't been defined yet,
+        # or if it's longer than a previously defined pattern.
+        if !pattern[compact_icon] || pattern[compact_icon].length < compact_regex.length
+          pattern[compact_icon] = compact_regex
+        end
+      elsif !pattern[icon]
+        pattern[icon] = Regexp.escape(icon)
+      end
+    end
+
+    @emoticon_pattern = "(?<=^|\\s)(?:#{ pattern.values.join('|') })(?=\\s|$)"
+    @emoticon_regex = Regexp.new("(#{@emoticon_pattern})")
+  end
+
+  # Generates a macro regex for matching one or more symbol sets.
+  # Regex uses various formats, based on symbol sets. Yields match as $1 OR $2
+  # T/EU:        (token-$1)|(emoticon-unicode-$2)
+  # T/E or T/U:  (token-$1)|(emoticon/unicode-$2)
+  # EU:          (emoticon/unicode-$1)
+  # - Options: unicode:boolean, tokens:boolean, emoticons:boolean
+  def macro_regex(opts={})
+    unicode_regex if opts[:unicode]
+    token_regex if opts[:tokens]
+    emoticon_regex if opts[:emoticons]
+    pattern = []
+
+    if opts[:emoticons] && opts[:unicode]
+      pattern << "(?:#{ @emoticon_pattern })"
+      pattern << @unicode_pattern
+    else
+      pattern << @emoticon_pattern if opts[:emoticons]
+      pattern << @unicode_pattern if opts[:unicode]
+    end
+
+    pattern = pattern.any? ? "(#{ pattern.join('|') })" : ""
+
+    if opts[:tokens]
+      if pattern.empty?
+        pattern = @token_pattern
+      else
+        pattern = "(?:#{ @token_pattern })|#{ pattern }"
+      end
     end
 
-    @emoji_regexp = Regexp.new("(#{patterns.join('|')})")
+    Regexp.new(pattern)
   end
 
-  # Parses all unicode emoji characters within a string.
-  # Provide a block that performs the character transformation.
+  # Parses all unicode symbols within a string.
+  # - Block: performs all symbol transformations.
   def parse_unicode(text)
-    text.gsub(emoji_regexp) do |match|
+    text.gsub(unicode_regex) do |match|
       emoji = Emoji.find_by_unicode($1)
       block_given? && emoji ? yield(emoji) : match
     end
   end
 
-  # Parses all emoji tokens within a string.
-  # Provide a block that performs the token transformation.
+  # Parses all token symbols within a string.
+  # - Block: performs all symbol transformations.
   def parse_tokens(text)
-    text.gsub(/:([\w+-]+):/) do |match|
-      emoji = Emoji.find_by_alias($1.to_s)
+    text.gsub(token_regex) do |match|
+      emoji = Emoji.find_by_alias($1)
       block_given? && emoji ? yield(emoji) : match
     end
   end
 
-  # Parses all emoji unicodes and tokens within a string.
-  # Provide a block that performs all transformations.
-  def parse_all(text)
-    text = parse_unicode(text) { |emoji| yield(emoji) }
-    parse_tokens(text) { |emoji| yield(emoji) }
+  # Parses all emoticon symbols within a string.
+  # - Block: performs all symbol transformations.
+  def parse_emoticons(text)
+    text.gsub(emoticon_regex) do |match|
+      if emoticons.has_key?($1)
+        emoji = Emoji.find_by_alias(emoticons[$1].to_s)
+        block_given? && emoji ? yield(emoji) : match
+      else
+        match
+      end
+    end
+  end
+
+  # Parses all emoji unicode, tokens, and emoticons within a string.
+  # - Block: performs all symbol transformations.
+  # - Options: unicode:boolean, tokens:boolean, emoticons:boolean
+  def parse(text, opts={})
+    opts = { unicode: true, tokens: true, emoticons: true }.merge(opts)
+    if opts.one?
+      return parse_unicode(text)   { |e| yield e } if opts[:unicode]
+      return parse_tokens(text)    { |e| yield e } if opts[:tokens]
+      return parse_emoticons(text) { |e| yield e } if opts[:emoticons]
+    end
+    text.gsub(macro_regex(opts)) do |match|
+      a = defined?($1) ? $1 : nil
+      b = defined?($2) ? $2 : nil
+      emoji = find(a || b)
+      block_given? && emoji ? yield(emoji) : match
+    end
   end
 
   # Transforms all unicode emoji into token strings.
@@ -56,8 +225,67 @@ module EmojiParser
     parse_tokens(text) { |emoji| emoji.raw }
   end
 
-  # Generates a custom emoji file path.
-  def filepath(emoji, path='/')
-    [path.sub(/\/$/, ''), emoji.image_filename.split('/').pop].join('/')
+  # Finds an Emoji::Character instance for an unknown symbol type.
+  # - symbol: an <Emoji::Character>, or a unicode/token/emoticon string.
+  def find(symbol)
+    return symbol if (symbol.is_a?(Emoji::Character))
+    symbol = emoticons[symbol].to_s if emoticons.has_key?(symbol)
+    Emoji.find_by_alias(symbol) || Emoji.find_by_unicode(symbol) || nil
+  end
+
+  # Gets the image file reference for a symbol; optionally with a custom path.
+  # - symbol: an <Emoji::Character>, or a unicode/token/emoticon string.
+  # - path: a file path to sub into symbol's filename.
+  def image_path(symbol, path=nil)
+    emoji = find(symbol)
+    return nil unless emoji
+    return emoji.image_filename unless path
+    "#{ path.sub(/\/$/, '') }/#{ emoji.image_filename.split('/').pop }"
+  end
+
+  private
+
+  # Compiles an optimized unicode pattern for fast matching.
+  # Matchers use as small a base as possible, with added options. Ex:
+  # 1-char base \w option:  \u{1f6a9}\u{fe0f}?
+  # 2-char base \w option:  \u{1f1ef}\u{1f1f5}\u{fe0f}?
+  # 1-char base \w options: \u{0031}(?:\u{fe0f}\u{20e3}|\u{20e3}\u{fe0f})?
+  def unicode_matcher(patterns)
+    return patterns.first if patterns.length == 1
+
+    # Sort patterns, longest to shortest:
+    patterns.sort! { |a, b| b.length - a.length }
+
+    # Select a base pattern:
+    # this is the shortest prefix contained by all patterns.
+    base = patterns.last
+
+    if patterns.all? { |p| p.start_with?(base) }
+      base = patterns.pop
+    else
+      base = base.match(/\\u\{.+?\}/).to_s
+      base = nil unless patterns.all? { |p| p.start_with?(base) }
+    end
+
+    # Collect base options and/or alternate patterns:
+    opts = []
+    alts = []
+    patterns.each do |pattern|
+      if base && pattern.start_with?(base)
+        opts << pattern.sub(base, '')
+      else
+        alts << pattern
+      end
+    end
+
+    # Format base options:
+    if opts.length == 1
+      base += "#{ opts.first }?"
+    elsif opts.length > 1
+      base += "(?:#{ opts.join('|') })?"
+    end
+
+    alts << base if base
+    alts.join('|')
   end
 end

data/lib/gemoji-parser/version.rb

@@ -1,3 +1,3 @@
 module EmojiParser
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/spec/emoji_parser_spec.rb

@@ -0,0 +1,222 @@
+# coding: utf-8
+require 'gemoji-parser'
+
+describe EmojiParser do
+  let(:test_unicode) { 'Test 🙈 🙊 🙉 😰 :invalid: 🐠. :o)' }
+  let(:test_mixed) { 'Test 🙈 🙊 🙉 :cold_sweat: :invalid: :tropical_fish:. :o)' }
+  let(:test_tokens) { 'Test :see_no_evil: :speak_no_evil: :hear_no_evil: :cold_sweat: :invalid: :tropical_fish:. :o)' }
+  let(:test_emoticons) { ';-) Test (:cold_sweat:) :) :-D' }
+  let(:test_custom) { Emoji.create('custom') }
+
+  describe '#emoticons' do
+    it 'should provide a hash with emoticons and their tokens as key/value pairs.' do
+      expect(EmojiParser.emoticons[':o)']).to eq :monkey_face
+    end
+  end
+
+  describe '#unicode_regex' do
+    it 'generates once and remains cached.' do
+      first = EmojiParser.unicode_regex
+      second = EmojiParser.unicode_regex
+      expect(first).to be second
+    end
+
+    it 'regenerates when called with a :rehash option.' do
+      first = EmojiParser.unicode_regex
+      second = EmojiParser.unicode_regex(rehash: true)
+      expect(first).not_to be second
+    end
+  end
+
+  describe '#token_regex' do
+    it 'generates once and remains cached.' do
+      first = EmojiParser.token_regex
+      second = EmojiParser.token_regex
+      expect(first).to be second
+    end
+  end
+
+  describe '#emoticon_regex' do
+    it 'generates once and remains cached.' do
+      first = EmojiParser.emoticon_regex
+      second = EmojiParser.emoticon_regex
+      expect(first).to be second
+    end
+
+    it 'regenerates when called with a :rehash option.' do
+      first = EmojiParser.emoticon_regex
+      second = EmojiParser.emoticon_regex(rehash: true)
+      expect(first).not_to be second
+    end
+  end
+
+  describe '#parse_unicode' do
+    it 'successfully parses full Gemoji unicode set.' do
+      Emoji.all.each do |emoji|
+        emoji.unicode_aliases.each do |u|
+          parsed = EmojiParser.parse_unicode("Test #{u}") { |e| 'X' }
+          expect(parsed).to eq "Test X"
+        end
+      end
+    end
+
+    it 'replaces all valid unicode symbols via block transformation.' do
+      parsed = EmojiParser.parse_unicode(test_mixed) { |e| 'X' }
+      expect(parsed).to eq 'Test X X X :cold_sweat: :invalid: :tropical_fish:. :o)'
+    end
+  end
+
+  describe '#parse_tokens' do
+    it 'successfully parses full Gemoji name set.' do
+      Emoji.all.each do |emoji|
+        parsed = EmojiParser.parse_tokens("Test :#{emoji.name}:") { |e| 'X' }
+        expect(parsed).to eq "Test X"
+      end
+    end
+
+    it 'replaces all valid token symbols via block transformation.' do
+      parsed = EmojiParser.parse_tokens(test_tokens) { |e| 'X' }
+      expect(parsed).to eq 'Test X X X X :invalid: X. :o)'
+    end
+  end
+
+  describe '#parse_emoticons' do
+    it 'successfully parses full default emoticon set.' do
+      EmojiParser.emoticons.each_key do |emoticon|
+        parsed = EmojiParser.parse_emoticons("Test #{emoticon}") { |e| 'X' }
+        expect(parsed).to eq "Test X"
+      end
+    end
+
+    it 'replaces all valid emoticon symbols via block transformation.' do
+      parsed = EmojiParser.parse_emoticons(test_emoticons) { |e| 'X' }
+      expect(parsed).to eq 'X Test (:cold_sweat:) X X'
+    end
+  end
+
+  describe '#parse' do
+    it 'replaces valid symbols of all types via block transformation.' do
+      parsed = EmojiParser.parse(test_mixed) { |e| 'X' }
+      expect(parsed).to eq 'Test X X X X :invalid: X. X'
+    end
+
+    it 'replaces valid symbols of specified types (unicode, tokens).' do
+      parsed = EmojiParser.parse(test_mixed, emoticons: false) { |e| 'X' }
+      expect(parsed).to eq 'Test X X X X :invalid: X. :o)'
+    end
+
+    it 'replaces valid symbols of specified types (unicode, emoticons).' do
+      parsed = EmojiParser.parse(test_mixed, tokens: false) { |e| 'X' }
+      expect(parsed).to eq 'Test X X X :cold_sweat: :invalid: :tropical_fish:. X'
+    end
+
+    it 'replaces valid symbols of specified types (tokens, emoticons).' do
+      parsed = EmojiParser.parse(test_mixed, unicode: false) { |e| 'X' }
+      expect(parsed).to eq 'Test 🙈 🙊 🙉 X :invalid: X. X'
+    end
+
+    it 'allows symbols to safely insert other symbol types without getting re-parsed.' do
+      parsed = EmojiParser.parse('🙈 🙊 :hear_no_evil:') { |e| ":#{e.name}:" }
+      expect(parsed).to eq ':see_no_evil: :speak_no_evil: :hear_no_evil:'
+    end
+  end
+
+  describe '#tokenize' do
+    it 'successfully tokenizes full Gemoji unicode set.' do
+      Emoji.all.each do |emoji|
+        emoji.unicode_aliases.each do |u|
+          tokenized = EmojiParser.tokenize("Test #{u}")
+          expect(tokenized).to eq "Test :#{emoji.name}:"
+        end
+      end
+    end
+
+    it 'replaces all valid emoji unicode with their token equivalent.' do
+      tokenized = EmojiParser.tokenize(test_mixed)
+      expect(tokenized).to eq test_tokens
+    end
+  end
+
+  describe '#detokenize' do
+    it 'replaces all valid emoji tokens with their raw unicode equivalent.' do
+      tokenized = EmojiParser.detokenize(test_mixed)
+      expect(tokenized).to eq test_unicode
+    end
+  end
+
+  describe '#find' do
+    let (:the_unicode) { '🐵' }
+    let (:the_token) { 'monkey_face' }
+    let (:the_emoticon) { ':o)' }
+    let (:the_emoji) { Emoji.find_by_alias(the_token) }
+    
+    it 'returns valid emoji characters.' do
+      expect(EmojiParser.find(the_emoji)).to eq the_emoji
+    end
+
+    it 'finds the proper emoji character for a unicode symbol.' do
+      expect(EmojiParser.find(the_unicode)).to eq the_emoji
+    end
+
+    it 'finds the proper emoji character for a token symbol.' do
+      expect(EmojiParser.find(the_token)).to eq the_emoji
+    end
+
+    it 'finds the proper emoji character for a unicode symbol.' do
+      expect(EmojiParser.find(the_emoticon)).to eq the_emoji
+    end
+  end
+
+  describe '#image_path' do
+    let (:the_emoji) { Emoji.find_by_alias('smiley') }
+    let (:the_image) { '1f603.png' }
+
+    it 'gets the image filename by emoji character.' do
+      path = EmojiParser.image_path(the_emoji)
+      expect(path).to eq the_emoji.image_filename
+    end
+
+    it 'gets the image filename by unicode symbol.' do
+      path = EmojiParser.image_path(the_emoji.raw)
+      expect(path).to eq the_emoji.image_filename
+    end
+
+    it 'gets the image filename by token symbol.' do
+      path = EmojiParser.image_path(the_emoji.name)
+      expect(path).to eq the_emoji.image_filename
+    end
+
+    it 'gets the image filename by emoticon symbol.' do
+      path = EmojiParser.image_path('=)')
+      expect(path).to eq the_emoji.image_filename
+    end
+
+    it 'formats a Gemoji image path as a custom location (with trailing slash).' do
+      custom_path = '//fonts.test.com/emoji/'
+      path = EmojiParser.image_path(the_emoji, custom_path)
+      expect(path).to eq "#{ custom_path }#{ the_image }"
+    end
+
+    it 'formats a Gemoji image path to a custom location (no trailing slash).' do
+      custom_path = '//fonts.test.com/emoji'
+      path = EmojiParser.image_path(the_emoji, custom_path)
+      expect(path).to eq "#{ custom_path }/#{ the_image }"
+    end
+  end
+
+  describe 'custom emoji' do
+    it 'replaces tokens for custom Emoji.' do
+      Emoji.create('boxing_kangaroo')
+      parsed = EmojiParser.parse_tokens('Test :boxing_kangaroo:') { |e| 'X' }
+      expect(parsed).to eq 'Test X'
+    end
+
+    it 'replaces custom emoticons (requires rehashing the regex).' do
+      EmojiParser.emoticons['¯\\(°_o)/¯'] = :confused
+      EmojiParser.emoticon_regex(rehash: true)
+
+      parsed = EmojiParser.parse_emoticons('Test ¯\\(°_o)/¯') { |e| e.name }
+      expect(parsed).to eq 'Test confused'
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gemoji-parser
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-19 00:00:00.000000000 Z
+date: 2015-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gemoji
@@ -66,8 +66,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Parses emoji unicode symbols and string tokens, allowing for customizable
-  transformations.
+description: Expands GitHub Gemoji to parse unicode and token emoji symbols into custom
+  formats.
 email:
 - greg.macwilliam@voxmedia.com
 executables: []
@@ -82,7 +82,7 @@ files:
 - gemoji-parser.gemspec
 - lib/gemoji-parser.rb
 - lib/gemoji-parser/version.rb
-- spec/emoji_helper_spec.rb
+- spec/emoji_parser_spec.rb
 homepage: https://github.com/gmac/gemoji-parser
 licenses:
 - MIT
@@ -108,4 +108,4 @@ signing_key:
 specification_version: 4
 summary: The missing helper methods for GitHub's Gemoji gem.
 test_files:
-- spec/emoji_helper_spec.rb
+- spec/emoji_parser_spec.rb

data/spec/emoji_helper_spec.rb

@@ -1,88 +0,0 @@
-# coding: utf-8
-require 'gemoji-parser'
-
-describe EmojiParser do
-  let(:test_unicode) { 'Test 🙈 🙊 🙉 😰 :invalid: 🐠.' }
-  let(:test_mixed) { 'Test 🙈 🙊 🙉 :cold_sweat: :invalid: :tropical_fish:.' }
-  let(:test_tokens) { 'Test :see_no_evil: :speak_no_evil: :hear_no_evil: :cold_sweat: :invalid: :tropical_fish:.' }
-
-  describe '#emoji_regexp' do
-    it 'generates once and remains cached.' do
-      first = EmojiParser.emoji_regexp
-      second = EmojiParser.emoji_regexp
-      expect(first).to be second
-    end
-
-    it 'regenerates when called with a :rehash option.' do
-      first = EmojiParser.emoji_regexp
-      second = EmojiParser.emoji_regexp(rehash: true)
-      expect(first).not_to be second
-    end
-  end
-
-  describe '#parse_unicode' do
-    it 'replaces all valid emoji unicode via block transformation.' do
-      parsed = EmojiParser.parse_unicode(test_mixed) { |emoji| 'X' }
-      expect(parsed).to eq "Test X X X :cold_sweat: :invalid: :tropical_fish:."
-    end
-  end
-
-  describe '#parse_tokens' do
-    it 'replaces all valid emoji tokens via block transformation.' do
-      parsed = EmojiParser.parse_tokens(test_tokens) { |emoji| 'X' }
-      expect(parsed).to eq "Test X X X X :invalid: X."
-    end
-  end
-
-  describe '#parse_all' do
-    it 'replaces all valid emoji unicode and tokens via block transformation.' do
-      parsed = EmojiParser.parse_all(test_mixed) { |emoji| 'X' }
-      expect(parsed).to eq "Test X X X X :invalid: X."
-    end
-  end
-
-  describe '#tokenize' do
-    it 'successfully tokenizes all Gemoji unicode aliases.' do
-      Emoji.all.each do |emoji|
-        emoji.unicode_aliases.each do |u|
-          tokenized = EmojiParser.tokenize("Test #{u}")
-          expect(tokenized).to eq "Test :#{emoji.name}:"
-        end
-      end
-    end
-
-    it 'replaces all valid emoji unicodes with their token equivalent.' do
-      tokenized = EmojiParser.tokenize(test_mixed)
-      expect(tokenized).to eq test_tokens
-    end
-  end
-
-  describe '#detokenize' do
-    it 'replaces all valid emoji tokens with their raw unicode equivalent.' do
-      tokenized = EmojiParser.detokenize(test_mixed)
-      expect(tokenized).to eq test_unicode
-    end
-  end
-
-  describe '#filepath' do
-    let (:test_emoji) { Emoji.find_by_alias('de') }
-    let (:test_file) { '1f1e9-1f1ea.png' }
-
-    it 'formats a Gemoji image path as a root location by default.' do
-      path = EmojiParser.filepath(test_emoji)
-      expect(path).to eq "/#{test_file}"
-    end
-
-    it 'formats a Gemoji image path as a custom location (with trailing slash).' do
-      images_path = '//fonts.test.com/emoji/'
-      path = EmojiParser.filepath(test_emoji, images_path)
-      expect(path).to eq "#{images_path}#{test_file}"
-    end
-
-    it 'formats a Gemoji image path to a custom location (no trailing slash).' do
-      images_path = '//fonts.test.com/emoji'
-      path = EmojiParser.filepath(test_emoji, images_path)
-      expect(path).to eq "#{images_path}/#{test_file}"
-    end
-  end
-end