sluggable 0.1.0

data/README.rdoc

@@ -0,0 +1,64 @@
+= Sluggable
+
+== Description
+
+This gem allows you to easily create slugs for your ActiveRecord models.
+
+== Installation
+
+    sudo gem install sluggable -s http://gemcutter.org
+
+== Usage
+
+In `config/environment.rb`, add the following:
+
+    config.gem 'sluggable', :source => 'http://gemcutter.org'
+    
+Then, in your ActiveRecord model you just need to include the module
+and provide the column to use when generating the slug.  For example, 
+if we had a Post model with:
+
+    class Post < ActiveRecord::Base
+      # Columns:
+      #  title: string
+      #  body:  text
+      #  slug:  string
+  
+      include Sluggable
+      slug_column :title
+  
+      before_validation :generate_slug
+  
+    end
+
+This sets it up so that the value of the `title` column is used as the
+source when generating the slug.  The module also provides a private
+method (`generate_slug`) to generate and store the slug for this record.  
+It requires that the table have a column called `slug` and is typically
+called in a lifecycle hook, though it can be called from anywhere you 
+need it.
+
+== License
+
+Copyright (c) 2009 Patrick Reagan (mailto:reaganpr@gmail.com)
+
+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/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/sluggable/version'
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'sluggable'
+  s.version          = Sluggable::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  s.summary          = "This gem provides an easy way to create slugs for your ActiveRecord models"
+  s.author           = 'Patrick Reagan'
+  s.email            = 'reaganpr@gmail.com'
+  s.homepage         = 'http://sneaq.net'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
+  
+  s.add_dependency('activesupport', '>= 2.1.1')
+  s.add_dependency('activerecord', '>= 2.1.1')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new(:coverage) do |t|
+    t.libs       = ['test']
+    t.test_files = FileList["test/**/*_test.rb"]
+    t.verbose    = true
+    t.rcov_opts  = ['--text-report', "-x #{Gem.path}", '-x /Library/Ruby', '-x /usr/lib/ruby']
+  end
+  
+  task :default => :coverage
+  
+rescue LoadError
+  warn "\n**** Install rcov (sudo gem install relevance-rcov) to get coverage stats ****\n"
+  task :default => :test
+end
+
+desc 'Generate the gemspec for the Gem (useful when serving from Github)'
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end
+
+task :github => :gemspec

data/lib/core_ext/nil_class.rb

@@ -0,0 +1,7 @@
+class NilClass
+  
+  # The slug for nil is, indeed, an empty string
+  def sluggify
+    ''
+  end
+end

data/lib/core_ext/string.rb

@@ -0,0 +1,9 @@
+class String
+  
+  # Generate the slug version for this string
+  def sluggify
+    slug = self.downcase.gsub(/[^0-9a-z_ -]/i, '')
+    slug = slug.gsub(/\s+/, '-').squeeze('-')
+    slug
+  end
+end

data/lib/sluggable.rb

@@ -0,0 +1,51 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'core_ext/nil_class'
+require 'core_ext/string'
+
+module Sluggable
+  module ClassMethods
+    
+    # Find all the other slugs in the database that don't belong to the 
+    # record specified by the +:id+ parameter.
+    def others_by_slug(id, slug)
+      conditions = id.nil? ? {} : {:conditions => ['id != ?', id]}
+      find_by_slug(slug, conditions)
+    end
+    
+    # Determine the database column to use when generating the slug
+    def slug_column(column)
+      define_method(:slug_column) do
+        column
+      end
+    end
+    
+  end
+  
+  module InstanceMethods
+    
+    def next_available_slug(base_slug) # :nodoc:
+      valid_slug = base_slug
+
+      index = 2
+      while self.class.others_by_slug(self.id, valid_slug)
+        valid_slug = base_slug + "-#{index}"
+        index+= 1
+      end
+      valid_slug
+    end
+    
+    def generate_slug # :nodoc:
+      self.slug = next_available_slug(self.send(slug_column).sluggify)
+    end
+    
+    private :next_available_slug, :generate_slug
+    
+  end
+  
+  def self.included(other) # :nodoc:
+    other.send(:extend, Sluggable::ClassMethods)
+    other.send(:include, Sluggable::InstanceMethods)
+  end
+  
+end

data/lib/sluggable/version.rb

@@ -0,0 +1,13 @@
+module Sluggable
+  module Version
+    
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    
+    def self.to_s # :nodoc:
+      [MAJOR, MINOR, TINY].join('.')
+    end
+    
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+# http://sneaq.net/textmate-wtf
+$:.reject! { |e| e.include? 'TextMate' }
+
+require 'rubygems'
+require 'throat_punch'
+
+require File.dirname(__FILE__) + '/../lib/sluggable'

data/test/unit/core_ext/nil_class_test.rb

@@ -0,0 +1,13 @@
+require File.dirname(__FILE__) + '/../../test_helper'
+
+class NilClassTest < Test::Unit::TestCase
+  
+  context "An instance of NilClass" do
+    
+    should "return an empty string as a slug" do
+      assert_equal '', nil.sluggify
+    end
+    
+  end
+  
+end

data/test/unit/core_ext/string_test.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/../../test_helper'
+
+class StringTest < Test::Unit::TestCase
+  
+  context "An instance of String" do
+    context "when creating a slug" do
+      
+      should "remove non-word characters" do
+        assert_equal 'postname', '!#pos$%t+name'.sluggify
+      end
+      
+      should "transform a space into a dash" do
+        assert_equal 'post-name', 'post name'.sluggify
+      end
+      
+      should "transform multiple spaces into a single dash" do
+        assert_equal 'post-name', "post   name".sluggify
+      end
+      
+      should "downcase the original string when creating the slug" do
+        assert_equal 'postname', 'PostName'.sluggify
+      end
+      
+      should "consolidate multiple dashes in the output" do
+        assert_equal 'post-name', 'post- name'.sluggify
+      end
+      
+    end
+  end
+  
+end

data/test/unit/sluggable_test.rb

@@ -0,0 +1,80 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class SluggableImplementation
+  include Sluggable
+end
+
+class SluggableImplementationTest < Test::Unit::TestCase
+  
+  def stub_others_by_slug(id, *slugs)
+    slugs.each do |slug|
+      return_val = (slug == slugs.last) ? nil : stub()
+      SluggableImplementation.stubs(:others_by_slug).with(@id, slug).returns(return_val)
+    end
+  end
+  
+  context "The SluggableImplmentation class" do
+    setup do
+      @object = stub()
+      @slug   = 'sample-slug'
+    end
+    
+    should "be able to find others by slug when provided an ID" do
+      id = 1
+      SluggableImplementation.expects(:find_by_slug).with(@slug, {:conditions => ['id != ?', id]}).returns(@object)
+      assert_equal @object, SluggableImplementation.others_by_slug(id, @slug)
+    end
+    
+    should "be able to find others by slug when not provided an ID" do
+      SluggableImplementation.expects(:find_by_slug).with(@slug, {}).returns(@object)
+      assert_equal @object, SluggableImplementation.others_by_slug(nil, @slug)
+    end
+    
+    should "be able to record the column for use when generating the slug" do
+      SluggableImplementation.slug_column :title
+      @sluggable = SluggableImplementation.new
+      
+      assert_equal :title, @sluggable.slug_column
+    end
+    
+  end
+  
+  context "An instance of SluggableImplementation" do
+    
+    setup do
+      @id   = 1
+      @slug = 'title'
+      
+      @sluggable = SluggableImplementation.new
+      @sluggable.stubs(:id).returns(@id)
+    end
+    
+    should "know the next available slug when the original is taken" do
+      stub_others_by_slug(@id, 'title', 'title-2')
+      assert_equal "title-2", @sluggable.send(:next_available_slug, 'title')
+    end
+    
+    should "incrementally suggest slugs until it finds an available one" do
+      stub_others_by_slug(@id, 'title', 'title-2', 'title-3')
+      assert_equal 'title-3', @sluggable.send(:next_available_slug, 'title')
+    end
+    
+    should "know not to suggest an incremental slug when the existing slug belongs to the current record" do
+      SluggableImplementation.stubs(:id).with().returns(@id)
+      SluggableImplementation.stubs(:others_by_slug).with(@id, @slug).returns(nil)
+      
+      assert_equal @slug, @sluggable.send(:next_available_slug, @slug)
+    end
+    
+    should "be able to assign a valid slug to the slug property" do
+      @sluggable.stubs(:slug_column).with().returns(:title)
+      @sluggable.stubs(:title).with().returns(stub(:sluggify => @slug))
+      @sluggable.stubs(:next_available_slug).with(@slug).returns(@slug)
+      @sluggable.expects(:slug=).with(@slug)
+      
+      @sluggable.send(:generate_slug)
+    end
+    
+  end
+  
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: sluggable
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Patrick Reagan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-30 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.1.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.1.1
+    version: 
+description: 
+email: reaganpr@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/core_ext/nil_class.rb
+- lib/core_ext/string.rb
+- lib/sluggable/version.rb
+- lib/sluggable.rb
+- test/test_helper.rb
+- test/unit/core_ext/nil_class_test.rb
+- test/unit/core_ext/string_test.rb
+- test/unit/sluggable_test.rb
+has_rdoc: true
+homepage: http://sneaq.net
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: This gem provides an easy way to create slugs for your ActiveRecord models
+test_files: []
+