{"id":17122622,"url":"https://github.com/gmac/gemoji-parser","last_synced_at":"2025-06-30T11:37:56.646Z","repository":{"id":29012375,"uuid":"32539528","full_name":"gmac/gemoji-parser","owner":"gmac","description":"The missing helper methods for GitHub's gemoji gem.","archived":false,"fork":false,"pushed_at":"2018-02-20T12:55:32.000Z","size":288,"stargazers_count":72,"open_issues_count":6,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-03T02:11:41.053Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-19T18:35:45.000Z","updated_at":"2024-09-08T04:36:02.000Z","dependencies_parsed_at":"2022-08-20T22:01:10.710Z","dependency_job_id":null,"html_url":"https://github.com/gmac/gemoji-parser","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/gmac/gemoji-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmac%2Fgemoji-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmac%2Fgemoji-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmac%2Fgemoji-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmac%2Fgemoji-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmac","download_url":"https://codeload.github.com/gmac/gemoji-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmac%2Fgemoji-parser/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262766420,"owners_count":23361101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T18:23:23.538Z","updated_at":"2025-06-30T11:37:56.597Z","avatar_url":"https://github.com/gmac.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gemoji-parser\n\nThe 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*). Parser performs the transformation of emoji symbols between unicode characters (😃), token strings (`:smile:`), and emoticons (`:-D`); and may perform arbitrary replacement of emoji symbols into custom display formats (such as image tags). Internally, [highly-optimized regular expressions](http://product.voxmedia.com/2015/3/25/8292199/optimizing-regex-for-emoji) are generated and cached for efficient parsing.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'gemoji-parser'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install gemoji-parser\n\nTo run tests:\n\n    $ bundle exec rake spec\n\n## Usage\n\n### Tokenizing\n\nThe tokenizer methods perform basic conversions of unicode symbols into token symbols, and vice versa.\n\n```ruby\nEmojiParser.tokenize(\"Test 🙈 🙊 🙉\")\n# \"Test :see_no_evil: :speak_no_evil: :hear_no_evil:\"\n\nEmojiParser.detokenize(\"Test :see_no_evil: :speak_no_evil: :hear_no_evil:\")\n# \"Test 🙈 🙊 🙉\"\n```\n\n### Symbol Parsing\n\nUse 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.\n\n**Unicode symbols**\n\n```ruby\nEmojiParser.parse_unicode(\"Test 🐠\") do |emoji|\n  %Q(\u003cimg src=\"#{emoji.image_filename}\" alt=\":#{emoji.name}:\"\u003e).html_safe\nend\n\n# 'Test \u003cimg src=\"unicode/1f420.png\" alt=\":tropical_fish:\"\u003e'\n```\n\n**Token symbols**\n\n```ruby\nEmojiParser.parse_tokens(\"Test :tropical_fish:\") do |emoji|\n  %Q(\u003cimg src=\"#{emoji.image_filename}\" alt=\":#{emoji.name}:\"\u003e).html_safe\nend\n\n# 'Test \u003cimg src=\"unicode/1f420.png\" alt=\":tropical_fish:\"\u003e'\n```\n\n**Emoticon symbols**\n\n```ruby\nEmojiParser.parse_emoticons(\"Test ;-)\") do |emoji|\n  %Q(\u003cimg src=\"#{emoji.image_filename}\" alt=\":#{emoji.name}:\"\u003e).html_safe\nend\n\n# 'Test \u003cimg src=\"unicode/1f609.png\" alt=\":wink:\"\u003e'\n```\n\nSee [emoticons output](https://github.com/gmac/gemoji-parser/blob/master/output/emoticons.txt) for the default emoticon set.\n\n**All symbol types**\n\nUse the `parse` method to target all symbol types with a single parsing pass. Specific symbol types may be excluded using options:\n\n```ruby\nEmojiParser.parse(\"Test 🐠 :scream: ;-)\") { |emoji| \"[#{emoji.name}]\" }\n# 'Test [tropical_fish] [scream] [wink]'\n\nEmojiParser.parse(\"Test 🐠 :scream: ;-)\", emoticons: false) do |emoji|\n  \"[#{emoji.name}]\"\nend\n# 'Test [tropical_fish] [scream] ;-)'\n```\n\nWhile 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:\n\n```ruby\nEmojiParser.parse(\"Test 🐠 ;-)\") do |emoji|\n  %Q(\u003cimg src=\"#{emoji.image_filename}\" alt=\":#{emoji.name}:\"\u003e).html_safe\nend\n\n# 'Test \u003cimg src=\"unicode/1f420.png\" alt=\":tropical_fish:\"\u003e \u003cimg src=\"unicode/1f609.png\" alt=\":wink:\"\u003e'\n```\n\n### Lookups \u0026 File Paths\n\nUse 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):\n\n```ruby\nemoji = EmojiParser.find(🐠)\nemoji = EmojiParser.find('see_no_evil')\nemoji = EmojiParser.find(';-)')\n```\n\nUse 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):\n\n```ruby\nEmojiParser.image_path('tropical_fish')\n# \"unicode/1f420.png\"\n\nEmojiParser.image_path('tropical_fish', '//cdn.fu/emoji/')\n# \"//cdn.fu/emoji/1f420.png\"\n```\n\n## Custom Symbols\n\n**Emoji**\n\nThe parser plays nicely with [custom emoji](https://github.com/github/gemoji#adding-new-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:\n\n```ruby\nEmoji.create('boxing_kangaroo') # \u003c\u003c WHY IS THIS NOT STANDARD?!\nEmojiParser.rehash!\n```\n\n**Emoticons**\n\nEmoticon [patterns](https://github.com/gmac/gemoji-parser/blob/master/output/emoticons.txt) 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 name, or a [custom name](https://github.com/github/gemoji#adding-new-emoji) that you have added). To add custom emoticon symbols:\n\n```ruby\n# Alias a standard emoji name:\nEmojiParser.emoticons[':@'] = :angry\n\n# Create a custom emoji name, and alias it:\nEmoji.create('bill_clinton')\nEmojiParser.emoticons['=:o]'] = :bill_clinton\n\n# IMPORTANT:\n# Rehash once after adding any new symbols:\nEmojiParser.rehash!\n```\n\n**Emoticon Lookarounds**\n\nEmoticons are matched using [lookaround patterns](http://www.regular-expressions.info/lookaround.html) that separate the icon from its surrounding text. By default, an emoticon pattern must start a string, end it, and/or be surrounded by whitespace. To adjust these rules, you may modify the `emoticon_lookaround` settings. The following would allow emoticons to be wrapped in HTML tags:\n\n```ruby\n# Allow HTML tags to surround emoticons, ex: \"\u003cp\u003e:-)\u003c/p\u003e\"\nEmojiParser.emoticon_lookaround[:behind] += '|\u003e'\nEmojiParser.emoticon_lookaround[:ahead] += '|\u003c'\nEmojiParser.rehash!\n```\n\n## Shoutout\n\nThanks to the GitHub team for the [gemoji](https://github.com/github/gemoji) gem, Matthew Rothenberg for [emojitracker](http://www.emojitracker.com/), and my esteemed colleague Michael Lovitt for the fantastic [Rubular](http://rubular.com/) regex tool (it has been invaluable on this project).\n\n🙈 🙊 🙉\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmac%2Fgemoji-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmac%2Fgemoji-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmac%2Fgemoji-parser/lists"}