pseudocephalopod 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.bundle
+*.tmproj
+tmtags
+*~
+\#*
+.\#*
+*.swp
+coverage
+rdoc
+pkg
+*.gem
+*.gemspec

data/Gemfile

@@ -0,0 +1,9 @@
+source :gemcutter
+
+# Setup gems
+gem "activerecord", "= 3.0.0.beta2"
+gem "reversible_data"
+gem "uuid"
+gem "shoulda"
+gem "sqlite3-ruby", :require => "sqlite3"
+gem "redgreen", :require => nil if RUBY_VERSION < "1.9"

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Darcy Laycock
+
+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,117 @@
+# Pseudocephalopod #
+
+## About ###
+
+Pseudocephalopod is a simple slug library for ActiveRecord 3.0 plus.
+
+It's main features are:
+
+1. A very simple and tested codebase
+2. Support for slug history (e.g. if a users slug changes, it will record the old slug)
+3. Simple defaulting for slugs to UUID's (to avoid showing ID's.)
+4. Built on ActiveRecord 3.0
+5. If stringex is installed, uses stringex's transliteration stuff
+
+Also, it's name is inspired by the Jason Wander series of books which I just happened to be
+reading when I had the need for this.
+
+### Why? ###
+
+I love the idea of friendly\_id, and most of the implementation but it felt bloated
+to me and my experiences on getting it to work correctly with Rails 3 left a base taste
+in my mouth / was altogether hacky.
+
+Pseudocephalopod is very much inspired by friendly id but with a much simpler codebase
+and built to work on Rails 3 from the start.
+
+## Usage ##
+
+Using Pseudocephalopod is simple. In Rails, simply drop this in your gemfile:
+
+    gem 'pseudocephalopod'
+    
+Optionally restricting the version.
+
+Next, if you wish to use slug history run:
+
+    $ rails generate pseudocephalopod:slugs
+    
+Otherwise, when calling is\_sluggable make sure to include :history => false
+
+Next, you need to add a cached slug column to your model and add an index. In your migration,
+you'd usually want something like:
+
+    add_column :users, :cached_slug, :string
+    add_index :users,  :cached_slug
+    
+Or, using our build in generator:
+
+    $ rails generate pseudocephalopod:slug_migration Model
+    
+Lastly, in your model, call is\_sluggable:
+
+    class User
+      is_sluggable :name
+    end
+    
+is\_sluggable accepts the source method name as a symbol, and an optional has of options including:
+
+* _:sync_ - when source column changes, save the result. Defaults to true.
+* _:convertor_ - a symbol (for a method) or block for how to generate the base slug. Defaults to :to\_url if available, parameterize otherwise.
+* _:history_ - use slug history (e.g. if the name changes, it records the previous version in a slugs table). Defaults to true
+* _:uuid_ - If the slug is blank, uses a generated uuid instead. Defaults to true
+* _:slug\_column_ - the column in which to store the slug. Defaults to _:cached\_slug_
+* _:to\_param_ - if true (by default), overrides to_param to use the slug
+* _:use\_cache_ - uses Pseudocephalopod.cache if available to cache any lookups e.g. in memcache.
+
+Once installed, it provides the following methods:
+
+### User.find\_using\_slug "some-slug" ###
+
+Finds a user from a slug (which can be the record's id, it's cached slug or, if enabled, slug history)
+
+### User.other\_than(record) ###
+
+Returns a relationship which returns records other than the given.
+
+### User.with\_cached\_slug(record) ###
+
+Returns a relationship which returns records with the given cached slug.
+
+### User#generate\_slug ###
+
+Forces the generation of a current slug
+
+### User#generate\_slug! ###
+
+Forces the generation of a current slug and saves it
+
+### User#autogenerate\_slug ###
+
+Generates a slug if not already present.
+
+### User#has\_better\_slug? ###
+
+When found via Model.find\_using\_slug, it will return try
+if there is a better slug available. Intended for use in redirects etc.
+
+## Working on Pseudocephalopod ##
+
+To run tests, simply do the following:
+
+    bundle install
+    rake
+
+And it's ready!
+
+## Note on Patches/Pull Requests ##
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright ##
+
+Copyright (c) 2010 Darcy Laycock. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,82 @@
+require 'rubygems'
+require 'rake'
+
+require File.expand_path('../lib/pseudocephalopod/version', __FILE__)
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.version     = Pseudocephalopod::Version::STRING
+    gem.name        = "pseudocephalopod"
+    gem.summary     = %Q{Super simple slugs for ActiveRecord 3.0 and higher, with support for slug history}
+    gem.description = %Q{Super simple slugs for ActiveRecord 3.0 and higher, with support for slug history}
+    gem.email       = "sutto@sutto.net"
+    gem.homepage    = "http://github.com/Sutto/pseudocephalopod"
+    gem.authors     = ["Darcy Laycock"]
+    gem.add_dependency "activerecord", ">= 3.0.0.beta2"
+    gem.add_development_dependency "shoulda", ">= 0"
+    gem.add_development_dependency "reversible_data"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+begin
+  require 'reek/adapters/rake_task'
+  Reek::RakeTask.new do |t|
+    t.fail_on_error = true
+    t.verbose = false
+    t.source_files = 'lib/**/*.rb'
+  end
+rescue LoadError
+  task :reek do
+    abort "Reek is not available. In order to run reek, you must: sudo gem install reek"
+  end
+end
+
+begin
+  require 'roodi'
+  require 'roodi_task'
+  RoodiTask.new do |t|
+    t.verbose = false
+  end
+rescue LoadError
+  task :roodi do
+    abort "Roodi is not available. In order to run roodi, you must: sudo gem install roodi"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "pseudocephalopod #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/generators/pseudocephalopod/slug_migration/slug_migration_generator.rb

@@ -0,0 +1,24 @@
+module Pseudocephalopod
+  module Generators
+    class SlugMigrationGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+      
+      def self.source_root
+        @_ps_source_root ||= File.expand_path("templates", File.dirname(__FILE__))
+      end
+      
+      def self.next_migration_number(dirname) #:nodoc:
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+      
+      def create_migration_file
+        migration_template "migration.rb", "db/migrate/add_cached_slug_to_#{table_name}.rb"
+      end
+      
+    end
+  end
+end

data/lib/generators/pseudocephalopod/slug_migration/templates/migration.rb

@@ -0,0 +1,12 @@
+class <%= migration_class_name %> < ActiveRecord::Migration
+  
+  def self.up
+    add_column <%= table_name.to_sym.inspect %>, :cached_slug, :string
+    add_index  <%= table_name.to_sym.inspect %>, :cached_slug
+  end
+
+  def self.down
+    remove_column <%= table_name.to_sym.inspect %>, :cached_slug
+  end
+  
+end

data/lib/generators/pseudocephalopod/slugs/slugs_generator.rb

@@ -0,0 +1,24 @@
+module Pseudocephalopod
+  module Generators
+    class SlugsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      
+      def self.source_root
+        @_ps_source_root ||= File.expand_path("templates", File.dirname(__FILE__))
+      end
+      
+      def self.next_migration_number(dirname) #:nodoc:
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+      
+      def create_migration_file
+        migration_template "migration.rb", "db/migrate/create_pseudocephalopod_slugs.rb"
+      end
+      
+    end
+  end
+end

data/lib/generators/pseudocephalopod/slugs/templates/migration.rb

@@ -0,0 +1,20 @@
+class CreatePseudocephalopodSlugs < ActiveRecord::Migration
+  
+  def self.up
+    create_table :slugs do |t|
+      t.string   :scope
+      t.string   :slug
+      t.integer  :record_id
+      t.datetime :created_at
+    end
+    add_index :slugs, [:scope, :slug]
+    add_index :slugs, [:scope, :record_id]
+    add_index :slugs, [:scope, :slug, :created_at]
+    add_index :slugs, [:scope, :record_id, :created_at]
+  end
+
+  def self.down
+    drop_table :slugs
+  end
+  
+end

data/lib/pseudocephalopod/active_record_methods.rb

@@ -0,0 +1,109 @@
+module Pseudocephalopod
+  module ActiveRecordMethods
+    
+    def is_sluggable(source = :name, options = {})
+      extend  ClassMethods
+      include InstanceMethods
+      extend Pseudocephalopod::Scopes
+      extend Pseudocephalopod::Finders
+      options.symbolize_keys!
+      # Define the attributes
+      class_attribute :cached_slug_column, :slug_source, :slug_source_convertor,
+                      :default_uuid_slug, :store_slug_history, :sync_slugs, :slug_scope
+      attr_accessor :found_via_slug
+      # Set attribute values
+      set_slug_convertor options[:convertor]
+      self.slug_source        = source.to_sym
+      self.cached_slug_column = (options[:slug_column] || :cached_slug).to_sym
+      self.default_uuid_slug  = !!options.fetch(:uuid, true)
+      self.store_slug_history = !!options.fetch(:history, true)
+      self.sync_slugs         = !!options.fetch(:sync, true)
+      self.slug_scope         = options[:slug_scope]
+      include Pseudocephalopod::Caching if !!options.fetch(:use_cache, true)
+      alias_method :to_param, :to_slug if !!options.fetch(:to_param, true)
+      include Pseudocephalopod::SlugHistory if self.store_slug_history
+      before_validation :autogenerate_slug
+    end
+    
+    module InstanceMethods
+      
+      def to_slug
+        cached_slug.present? ? cached_slug : id.to_s
+      end
+      
+      def generate_slug
+        slug_value = send(self.slug_source)
+        slug_value = self.slug_source_convertor.call(slug_value) if slug_value.present?
+        if slug_value.present?
+          scope = self.class.other_than(self).slug_scope_relation(self)
+          slug_value = Pseudocephalopod.next_value(scope, slug_value)
+          write_attribute self.cached_slug_column, slug_value
+        elsif self.default_uuid_slug
+          write_attribute self.cached_slug_column, Pseudocephalopod.generate_uuid_slug
+        else
+          write_attribute self.cached_slug_column, nil
+        end
+      end
+      
+      def generate_slug!
+        generate_slug
+        save :validate => false
+      end
+      
+      def autogenerate_slug
+        generate_slug if should_generate_slug?
+      end
+      
+      def should_generate_slug?
+        send(self.cached_slug_column).blank? || (self.sync_slugs && send(:"#{self.slug_source}_changed?"))
+      end
+      
+      def has_better_slug?
+        found_via_slug.present? && found_via_slug != to_slug
+      end
+      
+      def slug_scope_key(nested_scope = [])
+        self.class.slug_scope_key(nested_scope)
+      end
+      
+    end
+    
+    module ClassMethods
+      
+      def update_all_slugs!
+        find_each { |r| r.generate_slug! }
+      end
+      
+      def slug_scope_key(nested_scope = [])
+        ([table_name, slug_scope] + Array(nested_scope)).flatten.compact.join("|")
+      end
+      
+      def slug_scope_relation(record)
+        has_slug_scope? ? where(slug_scope => record.send(slug_scope)) : unscoped
+      end
+      
+      protected
+      
+      def has_slug_scope?
+        self.slug_scope.present?
+      end
+      
+      def set_slug_convertor(convertor)
+        if convertor.present?
+          if convertor.is_a?(Symbol)
+            self.slug_source_convertor = proc { |r| r.try(convertor) }
+          elsif convertor.respond_to?(:call)
+            self.slug_source_convertor = convertor
+          end
+        else
+          if "".respond_to?(:to_url)
+            self.slug_source_convertor = proc { |r| r.to_s.to_url }
+          else
+            self.slug_source_convertor = proc { |r| ActiveSupport::Multibyte::Chars.new(r.to_s).parameterize }
+          end
+        end
+      end
+      
+    end    
+  end
+end

data/lib/pseudocephalopod/caching.rb

@@ -0,0 +1,62 @@
+require 'digest/sha2'
+
+module Pseudocephalopod
+  module Caching
+   
+    def self.included(parent)
+      parent.extend ClassMethods
+      
+      parent.class_eval do
+        include InstanceMethods
+        extend  ClassMethods
+        after_save :globally_cache_slug
+      end
+    end
+   
+    module InstanceMethods
+      def globally_cache_slug
+        return unless send(:"#{self.cached_slug_column}_changed?")
+        value = self.to_slug
+        self.class.cache_slug_lookup!(value, self) if value.present?
+        unless store_slug_history
+          value = send(:"#{self.cached_slug_column}_was")
+          self.class.cache_slug_lookup!(value, nil)
+        end
+      end
+    end
+   
+    module ClassMethods
+      
+      def find_using_slug(slug, options = {})
+        # First, attempt to load an id and then record from the cache.
+        if (cached_id = lookup_cached_id_from_slug(slug)).present?
+          return find(cached_id, options).tap { |r| r.found_via_slug = slug }
+        end
+        # Otherwise, fallback to the normal approach.
+        super.tap do |record|
+          cache_slug_lookup!(slug, record) if record.present?
+        end
+      end
+      
+      def slug_cache_key(slug)
+        [Pseudocephalopod.cache_key_prefix, slug_scope_key(Digest::SHA256.hexdigest(slug.to_s.strip))].compact.join("/")
+      end
+      
+      def has_cache_for_slug?(slug)
+        lookup_cached_id_from_slug(slug).present?
+      end
+      
+      def cache_slug_lookup!(slug, record)
+        Pseudocephalopod.cache && Pseudocephalopod.cache.write(slug_cache_key(slug), record && record.id)
+      end
+      
+      protected
+      
+      def lookup_cached_id_from_slug(slug)
+        Pseudocephalopod.cache && Pseudocephalopod.cache.read(slug_cache_key(slug))
+      end
+      
+    end
+    
+  end
+end

data/lib/pseudocephalopod/finders.rb

@@ -0,0 +1,19 @@
+module Pseudocephalopod
+  module Finders
+    
+    def find_using_slug(slug, options = {})
+      slug = slug.to_s
+      value = nil
+      value ||= find_by_id(slug.to_i, options) if slug =~ /\A\d+\Z/
+      value ||= with_cached_slug(slug).first(options)
+      value ||= find_using_slug_history(slug, options) if store_slug_history
+      value.found_via_slug = slug if value.present?
+      value
+    end
+    
+    def find_using_slug!(slug, options = {})
+      find_using_slug(slug, options) or raise ActiveRecord::RecordNotFound
+    end
+    
+  end
+end

data/lib/pseudocephalopod/memory_cache.rb

@@ -0,0 +1,19 @@
+module Pseudocephalopod
+  class MemoryCache
+    
+    @@cache = {}
+    
+    def self.write(key, value)
+      @@cache[key.to_s] = value
+    end
+    
+    def self.read(key)
+      @@cache[key.to_s]
+    end
+    
+    def self.reset!
+      @@cache = {}
+    end
+    
+  end
+end

data/lib/pseudocephalopod/railtie.rb

@@ -0,0 +1,9 @@
+module Pseudocephalopod
+  class Railtie < Rails::Railtie
+    
+    initializer "pseudocephalopod.initialize_cache" do
+      Pseudocephalopod.cache = Rails.cache if Rails.cache.present?
+    end
+    
+  end
+end

data/lib/pseudocephalopod/scopes.rb

@@ -0,0 +1,13 @@
+module Pseudocephalopod
+  module Scopes
+    
+    def with_cached_slug(slug)
+      where(self.cached_slug_column => slug.to_s)
+    end
+    
+    def other_than(record)
+      record.new_record? ? unscoped : where("#{quoted_table_name}.id != ?", record.id)
+    end
+    
+  end
+end

data/lib/pseudocephalopod/slug.rb

@@ -0,0 +1,32 @@
+module Pseudocephalopod
+  class Slug < ActiveRecord::Base
+    set_table_name "slugs"
+  
+    validates_presence_of :record_id, :slug, :scope
+  
+    scope :ordered,    order('created_at DESC')
+    scope :only_slug,  select(:slug)
+    scope :for_record, lambda { |r| where(:record_id => r.id, :scope => Pseudocephalopod.key_for_scope(r)) }
+    scope :for_slug,   lambda { |scope, slug| where(:scope=> scope.to_s, :slug => slug.to_s)}
+  
+    def self.id_for(scope, slug)
+      ordered.for_slug(scope, slug).first.try(:record_id)
+    end
+    
+    def self.record_slug(record, slug)
+      scope = Pseudocephalopod.key_for_scope(record)
+      # Clear slug history in this scope before recording the new slug
+      for_slug(scope, slug).delete_all
+      create :scope => scope, :record_id => record.id, :slug => slug.to_s
+    end
+    
+    def self.previous_for(record)
+      ordered.only_slug.for_record(record).all.map(&:slug)
+    end
+    
+    def self.remove_history_for(record)
+      for_record(record).delete_all
+    end
+  
+  end
+end

data/lib/pseudocephalopod/slug_history.rb

@@ -0,0 +1,43 @@
+module Pseudocephalopod
+  module SlugHistory
+   
+    def self.included(parent)
+      parent.class_eval do
+        include InstanceMethods
+        extend  ClassMethods
+        after_save :record_slug_changes
+        after_destroy :remove_slug_history
+      end
+    end
+   
+    module InstanceMethods
+      
+      def previous_slugs
+        Pseudocephalopod.previous_slugs_for(self)
+      end
+      
+      protected
+      
+      def record_slug_changes
+        return unless send(:"#{self.cached_slug_column}_changed?")
+        value = send(:"#{self.cached_slug_column}_was")
+        Pseudocephalopod.record_slug(self, value) if value.present?
+      end
+      
+      def remove_slug_history
+        Pseudocephalopod.remove_slug_history_for(self)
+      end
+      
+    end
+    
+    module ClassMethods
+      
+      def find_using_slug_history(slug, options = {})
+        id = Pseudocephalopod.last_known_slug_id(self, slug)
+        id.present? ? find_by_id(id, options) : nil
+      end
+      
+    end
+    
+  end
+end

data/lib/pseudocephalopod/version.rb

@@ -0,0 +1,8 @@
+module Pseudocephalopod
+  module Version
+    MAJOR  = 0
+    MINOR  = 1
+    PATCH  = 0
+    STRING = [MAJOR, MINOR, PATCH].join(".")
+  end
+end

data/lib/pseudocephalopod.rb

@@ -0,0 +1,69 @@
+require 'uuid'
+
+module Pseudocephalopod
+  
+  class << self
+    
+    attr_accessor :cache_key_prefix, :cache
+    
+    def with_counter(prefix, counter = 0)
+      counter < 1 ? prefix : "#{prefix}--#{counter}"
+    end
+    
+    def next_value(scope, prefix)
+      counter = 0
+      slug    = self.with_counter(prefix, counter)
+      while scope.with_cached_slug(slug).exists?
+        counter += 1
+        slug = self.with_counter(prefix, counter)
+      end
+      slug
+    end
+    
+    def generate_uuid_slug
+      UUID.new.generate
+    end
+    
+    def last_known_slug_id(scope, slug)
+      Pseudocephalopod::Slug.id_for(Pseudocephalopod.key_for_scope(scope), slug)
+    end
+    
+    def record_slug(record, slug)
+      Pseudocephalopod::Slug.record_slug(record, slug)
+    end
+    
+    def previous_slugs_for(record)
+      Pseudocephalopod::Slug.previous_for(record)
+    end
+    
+    def remove_slug_history_for(record)
+      Pseudocephalopod::Slug.remove_history_for(record)
+    end
+    
+    def key_for_scope(scope)
+      if scope.respond_to?(:slug_scope_key)
+        scope.slug_scope_key
+      elsif scope.class.respond_to?(:slug_scope_key)
+        scope.class.slug_scope_key
+      else
+        scope.to_s
+      end
+    end
+    
+  end
+  
+  self.cache_key_prefix ||= "cached-slugs"
+  
+  autoload :Caching,     'pseudocephalopod/caching'
+  autoload :Scopes,      'pseudocephalopod/scopes'
+  autoload :Finders,     'pseudocephalopod/finders'
+  autoload :SlugHistory, 'pseudocephalopod/slug_history'
+  autoload :Slug,        'pseudocephalopod/slug'
+  autoload :MemoryCache, 'pseudocephalopod/memory_cache'
+  
+  require 'pseudocephalopod/active_record_methods'
+  ActiveRecord::Base.extend Pseudocephalopod::ActiveRecordMethods
+  
+  require 'pseudocephalopod/railtie' if defined?(Rails::Railtie)
+  
+end

data/test/caching_test.rb

@@ -0,0 +1,60 @@
+require 'helper'
+
+class CachingTest < Test::Unit::TestCase
+  with_tables :slugs, :users, :unslugged_users do
+    
+    setup { Pseudocephalopod::MemoryCache.reset! }
+    
+    should 'store a cache automatically after finding it' do
+      assert !User.has_cache_for_slug?("bob")
+      u = User.create :name => "Bob"
+      assert User.has_cache_for_slug?("bob")
+      Pseudocephalopod::MemoryCache.reset!
+      assert !User.has_cache_for_slug?("bob")
+      assert_equal u, User.find_using_slug("bob")
+      assert User.has_cache_for_slug?("bob")
+      # Second find from cache
+      assert_equal u, User.find_using_slug("bob")
+    end
+    
+    should 'remove cache on models without history' do
+      UnsluggedUser.is_sluggable :name, :history => false
+      u = UnsluggedUser.create :name => "Bob"
+      assert UnsluggedUser.has_cache_for_slug?("bob")
+      assert !UnsluggedUser.has_cache_for_slug?("red")
+      assert !UnsluggedUser.has_cache_for_slug?("sam")
+      u.update_attributes :name => "Red"
+      u.update_attributes :name => "Sam"
+      assert !UnsluggedUser.has_cache_for_slug?("bob")
+      assert !UnsluggedUser.has_cache_for_slug?("red")
+      assert UnsluggedUser.has_cache_for_slug?("sam")
+    end
+    
+    should 'automatically keep cache entries for history by default' do
+      assert !User.has_cache_for_slug?("bob")
+      assert !User.has_cache_for_slug?("red")
+      assert !User.has_cache_for_slug?("sam")
+      user = User.create :name => "bob"
+      assert User.has_cache_for_slug?("bob")
+      assert !User.has_cache_for_slug?("red")
+      assert !User.has_cache_for_slug?("sam")
+      user.update_attributes :name => "Red"
+      assert User.has_cache_for_slug?("bob")
+      assert User.has_cache_for_slug?("red")
+      assert !User.has_cache_for_slug?("sam")
+      user.update_attributes :name => "Sam"
+      assert User.has_cache_for_slug?("bob")
+      assert User.has_cache_for_slug?("red")
+      assert User.has_cache_for_slug?("sam")
+    end
+   
+    should 'allow you to disable caching' do
+      UnsluggedUser.is_sluggable :name, :use_cache => false
+      assert !UnsluggedUser.respond_to?(:has_cache_for_slug?)
+    end
+    
+    # Ensure we destroy the contents of the cache after each test.
+    teardown { Pseudocephalopod::MemoryCache.reset! }
+    
+  end
+end

data/test/helper.rb

@@ -0,0 +1,22 @@
+$KCODE = 'UTF8'
+
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+Bundler.require
+
+require 'test/unit'
+require 'shoulda'
+require 'redgreen' if RUBY_VERSION < '1.9'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'pseudocephalopod'
+require 'model_definitions'
+
+# Use a memory cache for testing.
+Pseudocephalopod.cache = Pseudocephalopod::MemoryCache
+
+class Test::Unit::TestCase
+  extend ReversibleData::ShouldaMacros
+end

data/test/is_sluggable_test.rb

@@ -0,0 +1,89 @@
+require 'helper'
+require 'digest/md5'
+
+class IsSluggableTest < Test::Unit::TestCase
+  with_tables :slugs, :users, :unslugged_users do
+    
+    should 'correctly sluggify a value' do
+      user = User.create(:name => "Bob")
+      assert_equal "bob", user.to_param
+      assert_equal "bob", user.cached_slug
+    end
+    
+    should 'generate a uuid in place of a slug' do
+      user = User.create(:name => '')
+      assert user.cached_slug.present?
+    end
+    
+    should 'return need to generate a slug when the cahced slug is blank' do
+      user = User.new(:name => "Ninja Stuff")
+      assert user.cached_slug.blank?
+      assert user.should_generate_slug?
+      user.save
+      assert user.cached_slug.present?
+      assert !user.should_generate_slug?
+      user.name = 'Awesome'
+      assert user.should_generate_slug?
+    end
+    
+    should 'let you disable syncing a slug' do
+      UnsluggedUser.is_sluggable :name, :sync => false
+      user = UnsluggedUser.create(:name => "Ninja User")
+      assert !user.should_generate_slug?
+      user.name = "Another User Name"
+      assert !user.should_generate_slug?
+    end
+    
+    should 'by default record slug history' do
+      user = User.create :name => "Bob"
+      assert_equal [], user.previous_slugs
+      user.update_attributes! :name => "Sal"
+      user.update_attributes! :name => "Red"
+      user.update_attributes! :name => "Jim"
+      assert_equal ["red", "sal", "bob"], user.previous_slugs
+      assert_equal user, User.find_using_slug("red")
+      assert_equal user, User.find_using_slug("sal")
+      assert_equal user, User.find_using_slug("bob")
+      assert_equal user, User.find_using_slug("jim")
+    end
+    
+    should 'let you disable recording of slug history' do
+      UnsluggedUser.is_sluggable :name, :history => false
+      user = UnsluggedUser.create(:name => "Bob")
+      assert !user.respond_to?(:previous_slugs)
+      user.update_attributes! :name => "Red"
+      assert_equal user,     UnsluggedUser.find_using_slug("red")
+      assert_not_equal user, UnsluggedUser.find_using_slug("bob")
+      assert UnsluggedUser.find_using_slug("bob").blank?
+    end
+    
+    should "let you find a record by it's id as needed" do
+      user = User.create :name => "Bob"
+      assert_equal user, User.find_using_slug(user.id)
+      assert_equal user, User.find_using_slug(user.id.to_i)
+    end
+    
+    should 'default to generate a uuid' do
+      user = User.create :name => ""
+      assert_match /\A[a-zA-Z0-9]{32}\Z/, user.cached_slug.gsub("-", "")
+      user = User.create
+      assert_match /\A[a-zA-Z0-9]{32}\Z/, user.cached_slug.gsub("-", "")
+    end
+    
+    should 'automatically append a sequence to the end of conflicting slugs' do
+      u1 = User.create :name => "ninjas Are awesome"
+      u2 = User.create :name => "Ninjas are awesome"
+      assert_equal "ninjas-are-awesome", u1.to_slug
+      assert_equal "ninjas-are-awesome--1", u2.to_slug
+    end
+    
+    should 'let you find out if there is a better way of finding a slug' do
+      user = User.create :name => "Bob"
+      user.update_attributes! :name => "Ralph"
+      assert !User.find_using_slug("ralph").has_better_slug?
+      assert User.find_using_slug("bob").has_better_slug?
+      assert User.find_using_slug(user.id).has_better_slug?
+    end
+    
+  end
+end

data/test/model_definitions.rb

@@ -0,0 +1,28 @@
+require 'reversible_data'
+
+ReversibleData.in_memory!
+
+# Define models here.
+
+ReversibleData.add :slugs do |t|
+  t.string  :scope
+  t.string  :slug
+  t.integer :record_id
+  t.datetime :created_at
+end
+
+user = ReversibleData.add :users do |u|
+  u.string :name
+  u.string :cached_slug
+  u.timestamps
+end
+
+user.define_model do
+  is_sluggable :name
+end
+
+ReversibleData.add :unslugged_users do |u|
+  u.string :name
+  u.string :cached_slug
+  u.timestamps
+end

data/test/pseudocephalopod_test.rb

@@ -0,0 +1,13 @@
+require 'helper'
+
+class PseudocephalopodTest < Test::Unit::TestCase
+  
+  should 'return the correct counter versions' do
+    assert_equal 'awesome',      Pseudocephalopod.with_counter('awesome')
+    assert_equal 'awesome',      Pseudocephalopod.with_counter('awesome', 0)
+    assert_equal 'awesome',      Pseudocephalopod.with_counter('awesome', -1)
+    assert_equal 'awesome--2',   Pseudocephalopod.with_counter('awesome', 2)
+    assert_equal 'awesome--100', Pseudocephalopod.with_counter('awesome', 100)
+  end
+  
+end

data/test/slug_history_test.rb

@@ -0,0 +1,30 @@
+require 'helper'
+
+class FakedModel
+  attr_reader :id
+  def self.slug_scope_key; "faked_models"; end
+  def initialize(id); @id = id; end
+end
+
+class SlugHistoryTest < Test::Unit::TestCase
+  with_tables :slugs do
+    
+    setup do
+      @record_a = FakedModel.new(12)
+      @record_b = FakedModel.new(4)
+      Pseudocephalopod.record_slug(@record_a, "awesome")
+      Pseudocephalopod.record_slug(@record_b, "awesome-1")
+      Pseudocephalopod.record_slug(@record_a, "ninjas")
+    end
+    
+    should 'let you lookup a given record id easily' do
+      assert Pseudocephalopod.last_known_slug_id(FakedModel, "felafel").blank?
+      assert Pseudocephalopod.last_known_slug_id(FakedModel, "ninjas-2").blank?
+      assert_equal 12, Pseudocephalopod.last_known_slug_id(FakedModel, "awesome")
+      assert_equal 4,  Pseudocephalopod.last_known_slug_id(FakedModel, "awesome-1")
+      assert_equal 12, Pseudocephalopod.last_known_slug_id(FakedModel, "ninjas")
+    end
+    
+  end
+  
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification 
+name: pseudocephalopod
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Darcy Laycock
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-23 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        - beta2
+        version: 3.0.0.beta2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: reversible_data
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Super simple slugs for ActiveRecord 3.0 and higher, with support for slug history
+email: sutto@sutto.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/generators/pseudocephalopod/slug_migration/slug_migration_generator.rb
+- lib/generators/pseudocephalopod/slug_migration/templates/migration.rb
+- lib/generators/pseudocephalopod/slugs/slugs_generator.rb
+- lib/generators/pseudocephalopod/slugs/templates/migration.rb
+- lib/pseudocephalopod.rb
+- lib/pseudocephalopod/active_record_methods.rb
+- lib/pseudocephalopod/caching.rb
+- lib/pseudocephalopod/finders.rb
+- lib/pseudocephalopod/memory_cache.rb
+- lib/pseudocephalopod/railtie.rb
+- lib/pseudocephalopod/scopes.rb
+- lib/pseudocephalopod/slug.rb
+- lib/pseudocephalopod/slug_history.rb
+- lib/pseudocephalopod/version.rb
+- test/caching_test.rb
+- test/helper.rb
+- test/is_sluggable_test.rb
+- test/model_definitions.rb
+- test/pseudocephalopod_test.rb
+- test/slug_history_test.rb
+has_rdoc: true
+homepage: http://github.com/Sutto/pseudocephalopod
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Super simple slugs for ActiveRecord 3.0 and higher, with support for slug history
+test_files: 
+- test/caching_test.rb
+- test/helper.rb
+- test/is_sluggable_test.rb
+- test/model_definitions.rb
+- test/pseudocephalopod_test.rb
+- test/slug_history_test.rb