A token phrase generator
Switch branches/tags
Nothing to show
Latest commit 18c305d Jul 21, 2013 @genericsteele genericsteele version bump


TokenPhrase (v1.0.6)

Build Status

TokenPhrase is a simple gem that generates unique phrases for you to use in your app as tokens.

"Why?" you may be asking. Why not? Token phrases give your app a little personality and make support a lot easier.


Add this line to your application's Gemfile:

gem 'token_phrase'

And then execute:

$ bundle

Or install it yourself as:

$ gem install token_phrase

TokenPhrase.generate(separator = nil, dictionaries = {})


By default, TokenPhrase uses the included dictionaries, separates everything with a hyphen (-), and appends a random number between 1 and 1,000,000 :

=> "groovy-red-fractal-fork-101589"

5.times { p TokenPhrase.generate }

With the current dictionaries and numbers, there are 4,199,040,000,000 (four trillion!) unique possibilites.


If you would like a different separator, just pass a string as an argument:

=> "groovy$salmon$paisley$cape$848536"

=> "sugarfilledMARSIPANcrimsonMARSIPANstripedMARSIPANfrogMARSIPAN860203"


TokenPhrase combines words from four different dictionaries:

  • :adjectives
  • :colors
  • :patterns
  • :nouns

If you want to replace the dictionary, just pass a hash with an array as an argument:

TokenPhrase.generate :adjectives => %w(glowing)
=> "glowing-peach-glossy-barracuda-743220"

5.times { p TokenPhrase.generate :nouns => %w(Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune Pluto) }

You can pass multiple dictionaries:

5.times { p TokenPhrase.generate :colors => %w(black white), :nouns => %w(cat dog) }

And you can, of course pass a separator before the dictionaries:

5.times { p TokenPhrase.generate '^^^', :patterns => %w(striped), :adjectives =>%w(great awesome) }


To help with uniqueness, a random number is added to the token by default. This may not be your cup of tea, so if you pass :numbers => false with the dictionaries, you can remove the number:

TokenPhrase.generate(:numbers => false)
=> "energetic-yellow-pinstriped-skunk"

Dictionary Methods

If you like the existing dictionaries, but want to add your own words, you can use get an array of each dictionary:

  • TokenPhrase.adjectives(more_adjectives = nil)
  • TokenPhrase.colors(more_colors = nil)
  • TokenPhrase.patterns(more_patterns = nil)
  • TokenPhrase.nouns(more_nouns = nil)

Each of these dictionary methods accept an array as an argument that will merge the existing dictionary with your array

your_patterns = TokenPhrase.patterns %w(magic-eye)
2.times { p TokenPhrase.generate :patterns => your_patterns }

TokenPhrase.permutations(dictionaries = {})

If you want to see how many unique combinations you can generate, use the permutations method. Just pass it the dictionaries hash the same way you would use TokenPhrase.generate:

=> 4199040000000

TokenPhrase.permutations :nouns => %w(cat dog)
=> 87480000000

TokenPhrase.permutations :nouns => %w(scooter boat car vroom-vroom), :numbers => false
=> 174960

Rails Uniqueness

The simplest way to create a unique token for your models is to add a before_create filter to your model:

#assuming your Thing model has a token property
class Thing < ActiveRecord::Base
  before_create :generate_token
  def generate_token
      self.token = TokenPhrase.generate
    end while self.class.exists?(token: token)


  1. Fork it
  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 new Pull Request


Thanks to benolee for refactoring the generator model!