has_unique_three_letter_code 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NjQzOTJkMmY4ZTdhOThmNjMxN2MwZmIyYjMxMDU1ZDExM2JhMmY4Mw==
+  data.tar.gz: !binary |-
+    YTMwYzRmYzE1ZmFhZjNlYTFmZTdlNmQ1YmNlNTM5YmI3N2FhY2NhNg==
+SHA512:
+  metadata.gz: !binary |-
+    OWViOWRhMzNkYmY5MzJlNGU0OWEwOTlmNDVmMWQ2NmI5YjQ5ZjNiMDZlMjE5
+    NzQ1MTcxZTFlYmRlYTgxMDNhN2RkODNiNWY0ZjY5NDYxY2YzMDFhNDkwNzBl
+    ZjA0NGRjMzgyMDZlYWRkOGMwNTQ0ZTI3NzdhNWM4MWJhNjUzNjE=
+  data.tar.gz: !binary |-
+    MWY4NDEyNGQwNmU3MTg3MDdmZTA1N2NmZTI3NGY4M2NiNDFhZGM5YzBlZjRj
+    Mzg4YzVjZGZiNTM0MDk2NDg5ODU4NjQxYzhjNTg0OTdhMjcwZGVkNWQxZmIz
+    YWMxOGY1NWQwYjE5ZTg0YjlhMThiZDI4YjQ3YTYwN2U5YzJjMjk=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.simplecov

@@ -0,0 +1,4 @@
+if ENV['COVERAGE']
+  SimpleCov.start 'test_frameworks' do
+  end
+end

data/.travis.yml

@@ -0,0 +1,10 @@
+before_script:
+  - bundle install
+  - mysql -e 'create database myapp_test;'
+  - |
+    echo "test:
+      adapter: mysql2
+      database: myapp_test
+      username: travis
+      encoding: utf8" > ${HOME}/has_unique_three_letter_code.yml
+script: BCDATABASE_PATH=${HOME} COVERAGE=true rspec

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in has_unique_three_letter_code.gemspec
+gemspec
+gem 'simplecov', :require => false

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Isaac Betesh
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# HasUniqueThreeLetterCode
+
+User requirements: Assign a case-insensitive unique three-letter code to each record in a scope, based loosely on some other attribute of the record.
+
+Example: Within the office, we refer to each client by a TLA (three-letter acronym).  We want to store the TLA's in our database automatically when we create a client, and we want the TLA to be loosely based on the client's name.  The National Rifle Association is the NRA.  The Office of Management and Budget is the OMB.  The National Restaurant Association--well, NRA is already taken, so how about NRX?
+
+Solution: HasUniqueThreeLetterCode
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'has_unique_three_letter_code'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install has_unique_three_letter_code
+
+## Usage
+
+    class Client < ActiveRecord::Base
+      attr_accessible :tla, :name, :tla_group
+
+      include HasUniqueThreeLetterCode
+      def needs_tla?
+        # Maybe clients that went out of business can have their TLA retired.
+        # Or maybe you don't need a TLA for a client with a monosyllabic name
+      end
+      has_unique_three_letter_code :tla,
+        :source => :name, # The field we use to generate the TLA.  This can be another column in this table, or any other method an instance of the class responds_to?, so if it's in another table, just `delegate :name, :to => :the_associated_record`
+        :uniqueness => { :scope => :tla_group }, # uniqueness constraints are passed directly to validates_uniqueness_of
+        :leave_blank => { :unless => :needs_tla? } # :leave_blank supports keys :if and :unless.  Values can be Procs or symbolized instance method names.
+    end
+
+
+## Testing
+
+Create a file at /etc/nubic/db/has_unique_three_letter_code.yml with your database configuration nested under 'test':
+
+Example:
+
+    test:
+      adapter: mysql2
+      encoding: utf8
+      host: ...
+      port: ...
+      database: ...
+      pool: 5
+      username: ...
+      password: ...
+
+Then run:
+
+    $ COVERAGE=true rspec
+(The environment variable 'COVERAGE' is optional and runs it with simplecov)
+
+## Future development possibilities
+
+1. Support options for lowercase and case-sensitive.
+2. Support N-letter codes.
+3. Before resorting to a random letter, search for an available combination using the first two letters of a word.
+4. When choosing a random letter, run through them randomly without repetition, instead of alphabetically.
+5. Add support for Rails 4
+
+## Contributing
+
+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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/has_unique_three_letter_code.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'has_unique_three_letter_code/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "has_unique_three_letter_code"
+  spec.version       = HasUniqueThreeLetterCode::VERSION
+  spec.authors       = ["Isaac Betesh"]
+  spec.email         = ["iybetesh@gmail.com"]
+  spec.description   = "Assigns a case-insensitive unique three-letter code to each record in a scope, based loosely on some other attribute of the record"
+  spec.summary       = `cat README.md`
+  spec.homepage      = "https://github.com/betesh/has_unique_three_letter_code/"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "bcdatabase"
+  spec.add_development_dependency "mysql2"
+
+  spec.add_runtime_dependency "activerecord", "~> 3.2.0"
+end

data/lib/has_unique_three_letter_code.rb

@@ -0,0 +1,7 @@
+require "has_unique_three_letter_code/configuration"
+require "has_unique_three_letter_code/class_methods"
+require "has_unique_three_letter_code/instance_methods"
+require "has_unique_three_letter_code/version"
+
+module HasUniqueThreeLetterCode
+end

data/lib/has_unique_three_letter_code/class_methods.rb

@@ -0,0 +1,32 @@
+require "active_record/validations"
+
+module HasUniqueThreeLetterCode
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    attr_reader :code_sources
+    def has_unique_three_letter_code(*columns)
+      options = columns.last.is_a?(Hash) ? columns.pop : {}
+      columns.each do |column|
+        validates column,
+            :uniqueness => (options[:uniqueness] || true),
+            :length => {:is => 3, :allow_nil => true}.merge(options[:length] || {}),
+            :exclusion => { :in => Proc.new { HasUniqueThreeLetterCode.config.forbidden_codes }, :message => "'%{value}' is not an appropriate word" }
+        (@code_sources ||= {})[column] = options[:source] || :name
+        before_validation do
+          if options[:leave_blank]
+            leave_blank = options[:leave_blank][:if]
+            if (leave_blank.blank? || (leave_blank.is_a?(Proc) && !leave_blank.call(self)) || (leave_blank.is_a?(Symbol) && !self.__send__(leave_blank)))
+              dont_leave_blank = options[:leave_blank][:unless]
+              if (dont_leave_blank.blank? || (dont_leave_blank.is_a?(Proc) && dont_leave_blank.call(self)) || (dont_leave_blank.is_a?(Symbol) && self.__send__(dont_leave_blank)))
+                set_three_letter_column column if self.__send__(column).blank?
+              end
+            end
+          else
+            set_three_letter_column column if self.__send__(column).blank?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/has_unique_three_letter_code/configuration.rb

@@ -0,0 +1,48 @@
+module HasUniqueThreeLetterCode
+  DEFAULT_FORBIDDEN_CODES = ['AID', 'AIL', 'ALL', 'ANA', 'AND', 'APP', 'ASA', 'ASK', 'ASS', 'BAD', 'BED', 'BOA', 'BOB', 'BOY', 'BRA', 'BRO', 'BUG', 'BUM', 'BUN', 'BUY', 'CRA', 'CRP', 'CUM', 'CUN', 'DID', 'DIE', 'DIK', 'DOA', 'DOG', 'EEL', 'FAG', 'FAT', 'FEE', 'FLU', 'FOO', 'FUC', 'FUK', 'FUN', 'GAG', 'GAY', 'GET', 'GOD', 'GOO', 'GOT', 'GOY', 'GUN', 'GUY', 'HAD', 'HAM', 'HEY', 'HIT', 'HOE', 'HOG', 'HOT', 'ICK', 'ILL', 'JEW', 'JIZ', 'LAW', 'LOO', 'MAX', 'MEX', 'MIN', 'MOB', 'MOM', 'MOO', 'NAG', 'NEG', 'NIG', 'NIP', 'ODD', 'OXY', 'PAY', 'PEE', 'PIE', 'PIG', 'POT', 'PUB', 'PUG', 'PUS', 'PUS', 'RAG', 'RED', 'REP', 'RET', 'RIM', 'SAD', 'SAG', 'SEX', 'SHI', 'SHT', 'SOB', 'SOL', 'SUB', 'SUE', 'SUK', 'TAX', 'TOI', 'TOY', 'URN', 'USA', 'WAD', 'WAP', 'WAY', 'WET', 'WIN', 'WOE', 'WOP', 'WOW', 'YEH', 'ZIT', 'ZOO']
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+    def configure
+      yield @config
+    end
+  end
+
+  class Configuration
+    THREE_LETTERS = /[A-Z]{3}/
+
+    attr_reader :forbidden_codes
+
+    def initialize
+      reset
+    end
+
+    def reset
+      self.forbidden_codes = DEFAULT_FORBIDDEN_CODES.dup
+    end
+
+    def forbidden_codes=(_)
+      raise ::ArgumentError, "config.forbidden_codes must be an array of 3-character strings.  For example: `config.forbidden_codes = ['ABC', 'DEF', 'GHI']`" unless _.is_a?(Array)
+
+      _.reject { |code| 3 == code.size }.tap do |wrong_size|
+        if 1 == wrong_size.size
+          raise ::ArgumentError, "config.forbidden_codes contains an element that is the wrong length: #{wrong_size.first}"
+        elsif 1 < wrong_size.size
+          raise ::ArgumentError, "config.forbidden_codes contains elements that are the wrong length: #{wrong_size.join(', ')}"
+        end
+      end
+
+      _.reject { |code| THREE_LETTERS.match(code) }.tap do |non_alpha|
+        if 1 == non_alpha.size
+          raise ::ArgumentError, "config.forbidden_codes contains an element with characters other than capital letters: #{non_alpha.first}"
+        elsif 1 < non_alpha.size
+          raise ::ArgumentError, "config.forbidden_codes contains elements with characters other than capital letters: #{non_alpha.join(', ')}"
+        end
+      end
+
+      @forbidden_codes = _
+    end
+  end
+end

data/lib/has_unique_three_letter_code/instance_methods.rb

@@ -0,0 +1,91 @@
+module HasUniqueThreeLetterCode
+  ALPHABET_ARRAY = ('A'..'Z').to_a
+  private
+    def set_three_letter_column(_)
+      return unless self.__send__(_).blank?
+      deterministic_three_letter_column(_)
+      random_three_letter_column(_) until unique_three_letter_column(_)
+    end
+
+    def deterministic_three_letter_column(_)
+      value = source_value(_)
+      return random_three_letter_column(_) if value.blank?
+      acronym = value.gsub(/\s+/m, ' ').gsub(/^\s+|\s+$/m, '').split(' ').collect(&:first).join.gsub(/[^A-Za-z]/, '').upcase
+      if acronym.size >= 3 then
+        acronym.size.times do |i|
+          (i+1..acronym.size-1).each do |j|
+            (j+1..acronym.size-1).each do |k|
+              self.__send__("#{_}=", "#{acronym[i]}#{acronym[j]}#{acronym[k]}")
+              return if unique_three_letter_column(_)
+            end
+          end
+          (i+1..acronym.size-1).each do |j|
+            ALPHABET_ARRAY.each do |k|
+              self.__send__("#{_}=", "#{acronym[i]}#{acronym[j]}#{k}")
+              return if unique_three_letter_column(_)
+            end
+          end
+          (i+1..acronym.size-1).each do |j|
+            three_letter_column_with_two_fixed_adjacent_letters(_, "#{acronym[i]}#{acronym[j]}")
+            return if unique_three_letter_column(_)
+          end
+          (i+1..acronym.size-1).each do |j|
+            three_letter_column_with_two_fixed_split_letters(_, acronym[i], acronym[j])
+            return if unique_three_letter_column(_)
+          end
+          three_letter_column_with_one_fixed_letter(_, acronym[i])
+          return if unique_three_letter_column(_)
+        end
+      elsif 2 == acronym.size
+        three_letter_column_with_two_fixed_adjacent_letters(_, acronym)
+        return if unique_three_letter_column(_)
+        three_letter_column_with_one_fixed_letter(_, acronym[0])
+        return if unique_three_letter_column(_)
+        three_letter_column_with_one_fixed_letter(_, acronym[1])
+      elsif 1 == acronym.size
+         three_letter_column_with_one_fixed_letter(_, acronym)
+      end
+    end
+
+    def random_char
+      ALPHABET_ARRAY[Random.rand(0..25)]
+    end
+
+    def unique_three_letter_column(_)
+      begin
+      valid? || self.errors[_].empty?
+      rescue => e
+        puts e.backtrace.join("\n")
+        raise e
+      end
+    end
+
+    def random_three_letter_column(_)
+      self.__send__("#{_}=", "#{random_char}#{random_char}#{random_char}")
+    end
+
+    def three_letter_column_with_one_fixed_letter(col, _)
+      ALPHABET_ARRAY.each do |i|
+        three_letter_column_with_two_fixed_adjacent_letters(col, "#{_}#{i}")
+        return if unique_three_letter_column(col)
+      end
+    end
+
+    def three_letter_column_with_two_fixed_adjacent_letters(col, _)
+      ALPHABET_ARRAY.each do |i|
+        self.__send__("#{col}=", "#{_}#{i}")
+        return if unique_three_letter_column(col)
+      end
+    end
+
+    def three_letter_column_with_two_fixed_split_letters(col, i, k)
+      ALPHABET_ARRAY.each do |j|
+        self.__send__("#{col}=", "#{i}#{j}#{k}")
+        return if unique_three_letter_column(col)
+      end
+    end
+
+    def source_value(_)
+      __send__(self.class.code_sources[_])
+    end
+end

data/lib/has_unique_three_letter_code/version.rb

@@ -0,0 +1,3 @@
+module HasUniqueThreeLetterCode
+  VERSION = "0.0.1"
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,32 @@
+require_relative 'spec_helper'
+
+describe HasUniqueThreeLetterCode do
+  describe "forbidden_codes" do
+    def set(_)
+      described_class.config.forbidden_codes=_
+    end
+    it "cannot be nil" do
+      expect{set(nil)}.to raise_error(ArgumentError, "config.forbidden_codes must be an array of 3-character strings.  For example: `config.forbidden_codes = ['ABC', 'DEF', 'GHI']`")
+    end
+    it "cannot have a 4-character string" do
+      expect{set(['ABCD'])}.to raise_error(ArgumentError, "config.forbidden_codes contains an element that is the wrong length: ABCD")
+    end
+    it "cannot have a 2-character string" do
+      expect{set(['AB'])}.to raise_error(ArgumentError, "config.forbidden_codes contains an element that is the wrong length: AB")
+    end
+    it "cannot have 2 elements with the wrong number of characters" do
+      expect{set(['ABCD', 'EF'])}.to raise_error(ArgumentError, "config.forbidden_codes contains elements that are the wrong length: ABCD, EF")
+    end
+    it "cannot have an element with a non-alpha character" do
+      expect{set(['AB1'])}.to raise_error(ArgumentError, "config.forbidden_codes contains an element with characters other than capital letters: AB1")
+    end
+    it "cannot have an element with a non-alpha character" do
+      expect{set(['AB1', '2CD'])}.to raise_error(ArgumentError, "config.forbidden_codes contains elements with characters other than capital letters: AB1, 2CD")
+    end
+    it "can be an empty array" do
+      expect{set([])}.to_not raise_error
+    end
+  end
+
+  after(:all) { described_class.config.reset }
+end

data/spec/has_unique_three_letter_column_spec.rb

@@ -0,0 +1,212 @@
+require_relative 'spec_helper'
+
+def tla_of(_)
+  _.tap(&:valid?).tla
+end
+
+RSpec::Matchers.define :be_assigned_tla do |expected|
+  match do |actual|
+    tla_of(actual) == expected
+  end
+end
+
+RSpec::Matchers.define :be_assigned_any_3_letter_tla do
+  match do |actual|
+    /\A[A-Z]{3}\z/.match(tla_of(actual))
+  end
+end
+
+RSpec::Matchers.define :be_3_letters_beginning_with do |expected|
+  match do |actual|
+    /\A#{expected}[A-Z]{#{3 - expected.size}}\z/.match(tla_of(actual))
+  end
+end
+
+
+describe Client do
+  describe "tla" do
+    def given_tla_is_unavailable(_)
+      HasUniqueThreeLetterCode.config.forbidden_codes << _
+    end
+
+    def given_all_codes_are_taken_that_begin_with(_)
+      if 1 == _.size
+        Client::ALPHABET_ARRAY.each do |a|
+          Client::ALPHABET_ARRAY.each do |b|
+            given_tla_is_unavailable("#{_}#{a}#{b}")
+          end
+        end
+      elsif 2 == _.size
+        Client::ALPHABET_ARRAY.each do |a|
+          given_tla_is_unavailable("#{_}#{a}")
+        end
+      end
+    end
+
+    describe '> 3 letters in initials' do
+      let(:target) { Client.new(:name => "John Deere Tractors & Farm Equipment, Ltd.") }
+
+      it "should be all caps" do
+        Client.new(:name => 'lower case letters').should be_assigned_tla('LCL')
+      end
+
+      it "should be the 1st 3 initials of business name" do
+        target.should be_assigned_tla('JDT')
+      end
+
+      it "should be the 1st, 2nd and 4th initials in business name when 1st 3 are non-unique" do
+        given_tla_is_unavailable('JDT')
+        target.should be_assigned_tla('JDF')
+      end
+
+      it "should be the 1st, 3rd and 4th initials in business name when 1st 2 and any later ones are non-unique" do
+        ['JDT', 'JDF', 'JDE', 'JDL'].each do |_|
+          given_tla_is_unavailable(_)
+        end
+        target.should be_assigned_tla('JTF')
+      end
+
+      it "should be the 1st, 3rd and 5th initials in business name when 1st 2 and any later ones are non-unique and 1st, 3rd and 4th are non-unique" do
+        ['JDT', 'JDF', 'JDE', 'JDL', 'JTF'].each do |_|
+          given_tla_is_unavailable(_)
+        end
+        target.should be_assigned_tla('JTE')
+      end
+
+      it "should begin with the 1st 2 initials in business name when 1st 2 with any later one is non-unique" do
+        ['JDT', 'JDF', 'JDE', 'JDL', 'JTF', 'JTE', 'JTL', 'JFE', 'JFL', 'JEL'].each do |_|
+          given_tla_is_unavailable(_)
+        end
+        target.should be_assigned_tla('JDA')
+      end
+
+      it "should begin with the 1st and 3rd initial in business name when 1st 2 with any letter and 1st and 3rd with any later initial is non-unique" do
+        Client::ALPHABET_ARRAY.each do |_|
+          given_tla_is_unavailable("JD#{_}")
+        end
+        ['JTF', 'JTE', 'JTL', 'JFE', 'JFL', 'JEL'].each do |_|
+          given_tla_is_unavailable(_)
+        end
+        target.should be_assigned_tla('JTA')
+      end
+
+      it "should be the 1st and last initial in business name with another letter after them when no other ordered combination of 2 initials from the business_name is unique with any 3rd letter" do
+        Client::ALPHABET_ARRAY.each do |_|
+          given_tla_is_unavailable("JD#{_}")
+          given_tla_is_unavailable("JT#{_}")
+          given_tla_is_unavailable("JF#{_}")
+          given_tla_is_unavailable("JE#{_}")
+        end
+        target.should be_assigned_tla('JLA')
+      end
+
+      it "should be the 1st and 2nd initial in business name with another letter between them when no ordered combination of 2 initials from the business_name is unique with any 3rd letter" do
+        Client::ALPHABET_ARRAY.each do |_|
+          given_tla_is_unavailable("JD#{_}")
+          given_tla_is_unavailable("JT#{_}")
+          given_tla_is_unavailable("JF#{_}")
+          given_tla_is_unavailable("JE#{_}")
+          given_tla_is_unavailable("JL#{_}")
+        end
+        target.should be_assigned_tla('JAD')
+      end
+
+      it "should begin with the 1st initial in business name when any ordered combination of initials is non-unique" do
+        given_all_codes_are_taken_that_begin_with('JD')
+        ['JTF', 'JTE', 'JTL', 'JFE', 'JFL', 'JEL'].each do |_|
+          given_tla_is_unavailable(_)
+        end
+        target.should be_assigned_tla('JTA')
+      end
+
+      it "should be the 2nd, 3rd and 4th initial in business name when any 3-letter combination beginning with the first letter is non-unique" do
+        given_all_codes_are_taken_that_begin_with('J')
+        target.should be_assigned_tla('DTF')
+      end
+
+      it "should be the 2nd, 3rd and 5th initial in business name when any 3-letter combination beginning with the first letter, and the 2nd, 3rd and 4th, are non-unique" do
+        given_all_codes_are_taken_that_begin_with('J')
+        given_tla_is_unavailable('DTF')
+        target.should be_assigned_tla('DTE')
+      end
+
+      it "should begin with the last initial when all codes beginning with any other initials in business name are taken" do
+        'JDTFE'.each_char do |_|
+          given_all_codes_are_taken_that_begin_with(_)
+        end
+        target.should be_assigned_tla('LAA')
+      end
+
+      it "should be random when all codes beginning with any initials in business name are taken" do
+        'JDTFEL'.each_char do |_|
+          given_all_codes_are_taken_that_begin_with(_)
+        end
+        target.should be_assigned_any_3_letter_tla
+      end
+    end
+
+    describe '2 letters in initials' do
+      let(:target) { Client.new(:name => 'Teddy Bears') }
+
+      it "should be the 1st 2 initials of business name plus a random letter" do
+        target.should be_3_letters_beginning_with('TB')
+      end
+
+      it "should be the 1st initial of business name plus two random letters if all ordered combinations of the 1st 2 initials plus a 3rd letter are taken" do
+        given_all_codes_are_taken_that_begin_with('TB')
+        target.should be_3_letters_beginning_with('T')
+      end
+
+      it "should be random if all ordered combinations beginning with the first letter are taken" do
+        given_all_codes_are_taken_that_begin_with('T')
+        target.should be_assigned_any_3_letter_tla
+      end
+    end
+
+
+    describe '1 letter initials' do
+      let (:target) { Client.new(:name => 'Switzerland') }
+
+      it "should be the initial of business name plus 2 random letters" do
+        target.should be_3_letters_beginning_with('S')
+      end
+
+      it "should be random if all ordered combinations beginning with the first letter are taken" do
+        given_all_codes_are_taken_that_begin_with('S')
+        target.should be_assigned_any_3_letter_tla
+      end
+    end
+
+    it "should be random if business_name is blank" do
+      Client.new.should be_assigned_any_3_letter_tla
+    end
+  end
+
+  describe "scoping uniqueness" do
+    it "should not allow two clients in the same tla_group to share a TLA" do
+      Client.create!(:name => 'A B C D', :tla_group => 1).should be_assigned_tla('ABC')
+      Client.create!(:name => 'A B C D', :tla_group => 1).should be_assigned_tla('ABD')
+    end
+
+    it "should allow two clients in different tla_groups to share a TLA" do
+      Client.create!(:name => 'A B C D', :tla_group => 1).should be_assigned_tla('ABC')
+      Client.create!(:name => 'A B C D', :tla_group => 2).should be_assigned_tla('ABC')
+    end
+  end
+
+  describe "leaving blank" do
+    it "should leave the TLA blank if configured with leave_blank" do
+      Client.create!(:name => 'A B C D', :needs_tla => false).should be_assigned_tla(nil)
+    end
+  end
+
+  describe "forbidden_codes" do
+    it "should not allow a TLA that is a forbidden code" do
+      Client.new(:name => 'A B C D').should be_assigned_tla('ABC')
+      HasUniqueThreeLetterCode.config.forbidden_codes = ['ABC']
+      Client.new(:name => 'A B C D').should be_assigned_tla('ABD')
+    end
+  end
+
+  after(:each) { HasUniqueThreeLetterCode.config.reset }
+end

data/spec/spec_helper.rb

@@ -0,0 +1,25 @@
+require "simplecov"
+
+require "active_record"
+require "bcdatabase"
+ActiveRecord::Base.establish_connection(Bcdatabase.load[:has_unique_three_letter_code, "test"])
+
+require "has_unique_three_letter_code"
+
+Dir[File.expand_path("#{__FILE__}/../support/*.rb")].each { |f| require f }
+
+RSpec.configure do |config|
+  config.order = "random"
+  config.before(:suite) do
+    CreateClients.up
+  end
+  config.after(:suite) do
+    CreateClients.down
+  end
+  config.around(:each) do |test|
+    Client.transaction do
+      test.run
+      raise ActiveRecord::Rollback
+    end
+  end
+end

data/spec/support/migration.rb

@@ -0,0 +1,14 @@
+class CreateClients < ActiveRecord::Migration
+  def self.up
+    create_table :clients do |t|
+      t.string :tla
+      t.string :name
+      t.integer :tla_group, :default => 0
+      t.boolean :needs_tla, :default => true
+      t.timestamps
+    end
+  end
+  def self.down
+    drop_table :clients
+  end
+end

data/spec/support/model.rb

@@ -0,0 +1,9 @@
+class Client < ActiveRecord::Base
+  attr_accessible :tla, :name, :needs_tla, :tla_group
+
+  include HasUniqueThreeLetterCode
+
+  has_unique_three_letter_code :tla, :source => :name,
+    :uniqueness => { :scope => :tla_group },
+    :leave_blank => { :unless => :needs_tla }
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: has_unique_three_letter_code
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Isaac Betesh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bcdatabase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+description: Assigns a case-insensitive unique three-letter code to each record in
+  a scope, based loosely on some other attribute of the record
+email:
+- iybetesh@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .simplecov
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- has_unique_three_letter_code.gemspec
+- lib/has_unique_three_letter_code.rb
+- lib/has_unique_three_letter_code/class_methods.rb
+- lib/has_unique_three_letter_code/configuration.rb
+- lib/has_unique_three_letter_code/instance_methods.rb
+- lib/has_unique_three_letter_code/version.rb
+- spec/configuration_spec.rb
+- spec/has_unique_three_letter_column_spec.rb
+- spec/spec_helper.rb
+- spec/support/migration.rb
+- spec/support/model.rb
+homepage: https://github.com/betesh/has_unique_three_letter_code/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.5
+signing_key: 
+specification_version: 4
+summary: ! '# HasUniqueThreeLetterCode  User requirements: Assign a case-insensitive
+  unique three-letter code to each record in a scope, based loosely on some other
+  attribute of the record.  Example: Within the office, we refer to each client by
+  a TLA (three-letter acronym).  We want to store the TLA''s in our database automatically
+  when we create a client, and we want the TLA to be loosely based on the client''s
+  name.  The National Rifle Association is the NRA.  The Office of Management and
+  Budget is the OMB.  The National Restaurant Association--well, NRA is already taken,
+  so how about NRX?  Solution: HasUniqueThreeLetterCode  ## Installation  Add this
+  line to your application''s Gemfile:  gem ''has_unique_three_letter_code''  And
+  then execute:  $ bundle  Or install it yourself as:  $ gem install has_unique_three_letter_code  ##
+  Usage  class Client < ActiveRecord::Base attr_accessible :tla, :name, :tla_group  include
+  HasUniqueThreeLetterCode def needs_tla? # Maybe clients that went out of business
+  can have their TLA retired. # Or maybe you don''t need a TLA for a client with a
+  monosyllabic name end has_unique_three_letter_code :tla, :source => :name, # The
+  field we use to generate the TLA.  This can be another column in this table, or
+  any other method an instance of the class responds_to?, so if it''s in another table,
+  just `delegate :name, :to => :the_associated_record` :uniqueness => { :scope =>
+  :tla_group }, # uniqueness constraints are passed directly to validates_uniqueness_of
+  :leave_blank => { :unless => :needs_tla? } # :leave_blank supports keys :if and
+  :unless.  Values can be Procs or symbolized instance method names. end   ## Testing  Create
+  a file at /etc/nubic/db/has_unique_three_letter_code.yml with your database configuration
+  nested under ''test'':  Example:  test: adapter: mysql2 encoding: utf8 host: ...
+  port: ... database: ... pool: 5 username: ... password: ...  Then run:  $ COVERAGE=true
+  rspec (The environment variable ''COVERAGE'' is optional and runs it with simplecov)  ##
+  Future development possibilities  1. Support options for lowercase and case-sensitive.
+  2. Support N-letter codes. 3. Before resorting to a random letter, search for an
+  available combination using the first two letters of a word. 4. When choosing a
+  random letter, run through them randomly without repetition, instead of alphabetically.
+  5. Add support for Rails 4  ## Contributing  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'
+test_files:
+- spec/configuration_spec.rb
+- spec/has_unique_three_letter_column_spec.rb
+- spec/spec_helper.rb
+- spec/support/migration.rb
+- spec/support/model.rb