slugalicious 1.0.0

data/.document

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

data/.gitignore

@@ -0,0 +1,26 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+.bundle
+.rvmrc
+test.sqlite
+
+## PROJECT::DOCUMENTATION
+.yardoc
+doc

data/.rspec

@@ -0,0 +1 @@
+-cfs

data/Gemfile

@@ -0,0 +1,17 @@
+source :rubygems
+
+# DEPENDENCIES
+gem 'rails', '>= 3.0'
+gem 'stringex'
+
+# DEVELOPMENT
+gem 'jeweler'
+gem 'yard'
+gem 'RedCloth', require: 'redcloth'
+gem 'sqlite3'
+
+# TEST
+gem 'rspec'
+group :test do
+  gem 'factory_girl'
+end

data/Gemfile.lock

@@ -0,0 +1,107 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    RedCloth (4.2.3)
+    abstract (1.0.0)
+    actionmailer (3.0.1)
+      actionpack (= 3.0.1)
+      mail (~> 2.2.5)
+    actionpack (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4.1)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.12)
+      rack-test (~> 0.5.4)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.1)
+      activesupport (= 3.0.1)
+      builder (~> 2.1.2)
+      i18n (~> 0.4.1)
+    activerecord (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
+      arel (~> 1.0.0)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
+    activesupport (3.0.1)
+    arel (1.0.1)
+      activesupport (~> 3.0.0)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    factory_girl (1.3.2)
+    ffi (0.6.3)
+      rake (>= 0.8.7)
+    gemcutter (0.6.1)
+    git (1.2.5)
+    i18n (0.4.2)
+    jeweler (1.4.0)
+      gemcutter (>= 0.1.0)
+      git (>= 1.2.5)
+      rubyforge (>= 2.0.0)
+    json_pure (1.4.6)
+    mail (2.2.9)
+      activesupport (>= 2.3.6)
+      i18n (~> 0.4.1)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    polyglot (0.3.1)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rails (3.0.1)
+      actionmailer (= 3.0.1)
+      actionpack (= 3.0.1)
+      activerecord (= 3.0.1)
+      activeresource (= 3.0.1)
+      activesupport (= 3.0.1)
+      bundler (~> 1.0.0)
+      railties (= 3.0.1)
+    railties (3.0.1)
+      actionpack (= 3.0.1)
+      activesupport (= 3.0.1)
+      rake (>= 0.8.4)
+      thor (~> 0.14.0)
+    rake (0.8.7)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    sqlite3 (0.1.1)
+      ffi (>= 0.6.3)
+    stringex (1.2.0)
+    thor (0.14.3)
+    treetop (1.4.8)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.23)
+    yard (0.6.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  RedCloth
+  factory_girl
+  jeweler
+  rails (>= 3.0)
+  rspec
+  sqlite3
+  stringex
+  yard

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Tim Morgan
+
+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.textile

@@ -0,0 +1,197 @@
+h1. Slugalicious -- Easy and powerful URL slugging for Rails 3
+
+_*(no monkey-patching required)*_
+
+| *Author* | Tim Morgan |
+| *Version* | 1.0 (Oct 30, 2010) |
+| *License* | Released under the MIT license. |
+
+h2. About
+
+Slugalicious is an easy-to-use slugging library that helps you generate pretty
+URLs for your ActiveRecord objects. It's built for Rails 3 and is cordoned off
+in a monkey patching-free zone.
+
+Slugalicious is easy to use and powerful enough to cover all of the most common
+use-cases for slugging. Slugs are stored in a separate table, meaning you don't
+have to make schema changes to your models, and you can change slugs while still
+keeping the old URLs around for redirecting purposes.
+
+Slugalicious is an intelligent slug generator: You can specify multiple ways to
+generate slugs, and Slugalicious will try them all until it finds one that
+generates a unique slug. If all else fails, Slugalicious will fall back on a
+less pretty but guaranteed-unique backup slug generation strategy.
+
+Slugalicious works with the Stringex Ruby library, meaning you get meaningful
+slugs via the @String#to_url@ method. Below are two examples of how powerful
+Stringex is:
+
+<pre><code>
+"$6 Dollar Burger".to_url #=> "six-dollar-burger"
+"新年好".to_url #=> "xin-nian-hao"
+</code></pre>
+
+h2. Installation
+
+*Important Note:* Slugalicious is written for Rails 3.0 and Ruby 1.9 only.
+
+Firstly, add the gem to your Rails project's @Gemfile@:
+
+<pre><code>
+gem 'slugalicious'
+</code></pre>
+
+Next, use the generator to add the @Slug@ model and its migration to your
+project:
+
+<pre><code>
+rails generate slugalicious
+</code></pre>
+
+Then run the migration to set up your database.
+
+h2. Usage
+
+For any model you want to slug, include the @Slugalicious@ module and call
+@slugged@:
+
+<pre><code>
+class User < ActiveRecord::Base
+  include Slugalicious
+  slugged ->(user) { "#{user.first_name} #{user.last_name}" }
+end
+</code></pre>
+
+Doing this sets the @to_param@ method, so you can go ahead and start generating
+URLs using your models. You can use the @find_from_slug@ method to load a record
+from a slug:
+
+<pre><code>
+user = User.find_from_slug(params[:id])
+</code></pre>
+
+h3. Multiple slug generators
+
+The @slugged@ method takes a list of method names (as symbols) or @Procs@ that
+each attempt to generate a slug. Each of these generators is tried in order
+until a unique slug is generated. (The output of each of these generators is run
+through the slugifier to convert it to a URL-safe string. The slugifier is by
+default @String#to_url@, provided by the Stringex gem.)
+
+So, if we had our @User@ class, and we first wanted to slug by last name only,
+but then add in the first name if two people share a last name, we'd call
+@slugged@ like so:
+
+<pre><code>
+slugged :last_name, ->(user) { "#{user.first_name} #{user.last_name}" }
+</code></pre>
+
+In the event that none of these generators manages to make a unique slug, a
+fallback generator is used. This generator prepends the ID of the record, making
+it guaranteed unique. Let's use the example generators shown above. If we create
+a user with the name "Sancho Sample", he will get the slug "sample". Create
+another user with the same name, and that user will get the slug
+"sancho-sample;2". The semicolon is the default ID separator (and it can be
+overridden).
+
+h3. Scoped slugs
+
+Slugs must normally be unique for a single model type. Thus, if you have a
+@User@ named Hammer and a @Product@ named hammer, they can both share the
+"hammer" slug.
+
+If you want to decrease the uniqueness scope of a slug, you can do so with the
+@:scope@ option on the @slugged@ method. Let's say you wanted to limit the scope
+of a @Product@'s slug to its associated @Department@; that way you could have a
+product named "keyboard" in both the Computer Supplies and the Music Supplies
+departments. To do so, override the @:scope@ option with a method name (as
+symbol) or a @Proc@ that limits the scope of the uniqueness requirement:
+
+<pre><code>
+class Product < ActiveRecord::Base
+  include Slugalicious
+  belongs_to :department
+  slugged :name, scope: :department_url_component
+
+  private
+
+  def department_url_component
+    department.name.to_url + "/"
+  end
+end
+</code></pre>
+
+Now, your computer keyboard's slug will be "computer-supplies/keyboard" and your
+piano keyboard's slug will be "music-supplies/keyboard". There's an important
+thing to notice here: The method or proc you use to scope the slug must return a
+proper URL substring. That typically means you need to URL-escape it and add a
+slash at the end, as shown in the example above.
+
+When you call @to_param@ on your piano keyboard, instead of just "keyboard", you
+will get "music-supplies/keyboard". Likewise, you can use the
+@find_from_slug_path@ method to find a record from its full path, slug and scope
+included. You would usually use this method in conjunction with route globbing.
+For example, we could set up our @routes.rb@ file like so:
+
+<pre><code>
+get '/products/*path', 'products#show', as: :products
+</code></pre>
+
+Then, in our @ProductsController@, we load the product from the path slug like
+so:
+
+<pre><code>
+def find_product
+  @product = Product.find_from_slug_path(params[:path])
+end
+</code></pre>
+
+This is why it's very convenient to have your @:scope@ method/proc not only
+return the uniqueness constraint, but also the scoped portion of the URL
+preceding the slug.
+
+h3. Altering and expiring slugs
+
+When a model is created, it gets one slug, marked as the active slug (by
+default). This slug is the first generator that produces a unique slug string.
+
+If a model is updated, its slug is regenerated. Each of the slug generators is
+invoked, and if any of them produces an existing slug assigned to the object,
+that slug is made the active slug. (Priority goes to the first slug generator
+that produces an existing slug [active or inactive]).
+
+If none of the slug generators generates a known, existing slug belonging to the
+object, then the first unique slug is used. A new @Slug@ instance is created and
+marked as active, and any other slugs belonging to the object are marked as
+inactive.
+
+Inactive slugs do not act any differently from active slugs. An object can be
+found by its inactive slug just as well as its active slug. The flag is there so
+you can alter the behavior of your application depending on whether the slug is
+current.
+
+A common application of this is to have inactive slugs 301-redirect to the
+active slug, as a way of both updating search engines' indexes and ensuring that
+people know the URL has changed. As an example of how do this, we alter the
+@find_product@ method shown above to be like so:
+
+<pre><code>
+def find_product
+  @product = Product.find_from_slug_path(params[:path])
+  unless @product.active_slug?(params[:path].split('/').last)
+    redirect_to product_url(@product), status: :moved_permanently
+    return false
+  end
+  return true
+end
+</code></pre>
+
+The old URL will remain indefinitely, but users who hit it will be redirected to the new URL. Ideally, links to the old URL will be replaced over time with links to the new URL.
+
+The problem is that even though the old slug is inactive, it's still "taken." If you create a product called "Keyboard", but then rename it to "Piano", the product will claim both the "keyboard" and "piano" slugs. If you had renamed it to make room for a different product called "Keyboard" (like a computer keyboard), you'd find its slug is "keyboard;2" or similar.
+
+To prevent the slug namespace from becoming more and more polluted over time, websites generally expire inactive slugs after a period of time. To do this in Slugalicious, write a task that periodically checks for and deletes old, inactive @Slug@ records. Such a task could be invoked through a cron job, for instance. An example:
+
+<pre><code>
+Slug.inactive.where([ "created_at < ?", 30.days.ago ]).delete_all
+</code></pre>

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+begin
+  require 'bundler'
+rescue LoadError
+  puts "Bundler is not installed; install with `gem install bundler`."
+  exit 1
+end
+
+Bundler.require :default
+
+Jeweler::Tasks.new do |gem|
+  gem.name = "slugalicious"
+  gem.summary = %Q{Easy-to-use and powerful slugging for Rails 3}
+  gem.description = %Q{Slugalicious adds simple and powerful slugging to your ActiveRecord models.}
+  gem.email = "git@timothymorgan.info"
+  gem.homepage = "http://github.com/riscfuture/slugalicious"
+  gem.authors = [ "Tim Morgan" ]
+  gem.required_ruby_version = '>= 1.9'
+  gem.add_dependency "rails", ">= 3.0"
+  gem.add_dependency 'stringex'
+end
+Jeweler::GemcutterTasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+YARD::Rake::YardocTask.new('doc') do |doc|
+  doc.options << "-m" << "textile"
+  doc.options << "--protected"
+  doc.options << "-r" << "README.textile"
+  doc.options << "-o" << "doc"
+  doc.options << "--title" << "Slugalicious Documentation".inspect
+  
+  doc.files = [ 'lib/**/*', 'README.textile', 'templates/slug.rb' ]
+end
+
+task(default: :spec)

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/slugalicious.rb

@@ -0,0 +1,242 @@
+require 'slugalicious_generator'
+require 'stringex'
+
+# Adds the @slugged@ method to an @ActiveRecord::Base@ subclass. You can then
+# call this method to add slugging support to your model. See the
+# {ClassMethods#slugged} method for more details.
+#
+# @example Basic example of a slugged model
+#  class Widget < ActiveRecord::Base
+#    include Slugalicious
+#    slugged :title
+#  end
+
+module Slugalicious
+  extend ActiveSupport::Concern
+
+  # The maximum length of a slug.
+  MAX_SLUG_LENGTH = 126
+
+  included do
+    extend ActiveSupport::Memoizable
+    memoize :slug, :active_slug?
+    alias_method :to_param, :slug_with_path
+    has_many :slugs, as: :sluggable
+  end
+
+  # Methods added to the class when this module is included.
+
+  module ClassMethods
+    
+    # Locates a record matching a given slug.
+    #
+    # @param [String] slug The slug to locate.
+    # @param [String] scope The scope to search in (for use with scoped-unique
+    #   slugs). This should be a string equal to the portion of the URL path
+    #   preceding the slug.
+    # @return [ActiveRecord::Base] The object with that slug.
+    # @raise [ActiveRecord::RecordNotFound] If no object with that slug is
+    #   found.
+
+    def find_from_slug(slug, scope=nil)
+      Slug.from_slug(self, scope, slug).first.try(:sluggable) || raise(ActiveRecord::RecordNotFound)
+    end
+
+    # Locates a record from a given path, that consists of a slug and its scope,
+    # as would appear in a URL path component.
+    #
+    # @param [String] path The scope and slug concatenated together.
+    # @return [ActiveRecord::Base] The object with that slug.
+    # @raise [ActiveRecord::RecordNotFound] If no object with that slug is
+    #   found.
+
+    def find_from_slug_path(path)
+      slug = path.split('/').last
+      scope = path[0..(-(slug.size + 1))]
+      find_from_slug slug, scope
+    end
+
+    protected
+    
+    # Call this method to indicate that your model uses slugging. Pass a list of
+    # *slug generators*: either symbols (method names) or procs that return
+    # strings. These strings will be used to generate the slug. You must pass at
+    # least one generator. If you pass more than one, the first one that returns
+    # a unique slug will be used.
+    #
+    # The generator does not need to sanitize or parameterize its output; the
+    # @:slugifier@ option can be used to override the default parameterization.
+    #
+    # In the event that no generator returns a unique slug, the slug returned by
+    # the last generator will have the ID of the record appended to it. The ID
+    # and the slug will be separated by the @:id_separator@ option (semicolon by
+    # default). _This_ slug is hopefully unique, because if not, an exception is
+    # raised.
+    #
+    # Slugs are automatically generated before validation and updated when
+    # necessary.
+    #
+    # h2. Scopes
+    #
+    # You can scope your slugs to certain URL subpaths using the @:scope@
+    # option. The @:scope:@ option takes a method name or a @Proc@ that, when
+    # run, returns a string that scopes the uniqueness constraint of a slug.
+    # Rather than being globally unique, the slug must only be unique among
+    # other slugs that share the same scope.
+    #
+    # *Important note:* The method or @Proc@ that you use for the @:scope@
+    # option should return the portion of the URL preceding the slug, _slash
+    # included_. Let's say you have slugged your @User@ model's @login@ field,
+    # and you have two scopes: customers and merchants. In that case, you would
+    # want the @:scope@ method/proc to return either "clients/" or "merchants/".
+    #
+    # The string returned by the @:scope@ option will be used to build the full
+    # URL to an object. If you have a client @User@ with login "fancylad", a
+    # call to @to_param@ will return "clients/fancyland". The scope portion of
+    # that URL path is used un-sanitized, un-escaped, and un-processed. It is
+    # therefore up to _you_ to ensure your scopes are valid URL strings, using
+    # say @String#to_url@ (included as part of this gem).
+    #
+    # @overload slugged(generator, ..., options={})
+    #   @param [Proc, Symbol] generator If it's a @Symbol@, indicates a method
+    #     that will be called that will return a @String@ to be used for the
+    #     slug.
+    #   @param [Hash] options Additonal options that control slug generation.
+    #   @option options [Proc] :slugifier (&:to_url) A proc that, when given a
+    #     string, produces a URL-safe slugged version of that string.
+    #   @option options [String] :id_separator (';') A separator to be used in
+    #     the "last-resort" slug between the slug and the model ID. This should
+    #     be an URL-safe character that would never be produced by your
+    #     slugifier.
+    #   @option options [Symbol, Proc] :scope A method name or @Proc@ to run
+    #     (receives the object being slugged) that returns a string. Slugs must
+    #     be unique across all objects for which this method/proc returns the
+    #     same value. If not provided, slugs must be globally unique for this
+    #     model. The string returned should be equal to the portion of the URL
+    #     path that precedes the slug.
+    #   @option options [Array<String>, String] :blacklist ([ 'new', 'edit', 'delete' ])
+    #     A list of slugs that are disallowed. You would use this to prevent
+    #     slugs from sharing the same name as actions in your resource
+    #     controller.
+    # @raise [ArgumentError] If no generators are provided.
+
+    def slugged(*slug_procs)
+      options = slug_procs.extract_options!
+      raise ArgumentError, "Must provide at least one field or proc to slug" if slug_procs.empty?
+
+      class_inheritable_array :_slug_procs, :_slug_blacklist
+      class_inheritable_accessor :_slugifier, :_slug_id_separator, :_slug_scope
+
+      self._slug_procs = slug_procs.map { |slug_proc| slug_proc.kind_of?(Symbol) ? ->(obj) { obj.send(slug_proc) } : slug_proc }
+      self._slugifier = options[:slugifier] || ->(string) { string.to_url }
+      self._slug_id_separator = options[:id_separator] || ';'
+      self._slug_scope = if options[:scope].kind_of?(Symbol) then
+                           ->(record) { record.send(options[:scope]).to_s }
+                         elsif options[:scope].kind_of?(Proc) then
+                           options[:scope]
+                         elsif options[:scope] then
+                           raise ArgumentError, ":scope must be a symbol or proc"
+                         end
+      self._slug_blacklist = Array.wrap(options[:blacklist] || %w( new edit delete ))
+
+      after_save :make_slug
+    end
+  end
+
+  # Methods added to instances when this module is included.
+
+  module InstanceMethods
+
+    # @return [String, nil] The slug for this object, or @nil@ if none has been
+    #   assigned.
+
+    def slug
+      (slugs.loaded? ? slugs.detect(&:active?) : slugs.active.first).try(:slug)
+    end
+
+    # @return [String, nil] The full slug and path for this object, with scope
+    #   included, or @nil@ if none has been assigned.
+
+    def slug_with_path
+      slug = slugs.loaded? ? slugs.detect(&:active) : slugs.active.first
+      if slug then
+        slug.scope.to_s + slug.slug
+      else
+        nil
+      end
+    end
+
+    # @param [String] slug A slug for this object.
+    # @return [true, false, nil] @true@ if the slug is the currently active one
+    #   (should not redirect), @false@ if it's inactive (should redirect), and
+    #   @nil@ if it's not a known slug for the object (should 404).
+
+    def active_slug?(slug)
+      slug = if slugs.loaded? then
+               slugs.detect { |s| s.slug.downcase == slug.downcase }
+             else
+               slugs.where(slug: slug).first
+             end
+      if slug then
+        slug.active?
+      else
+        nil
+      end
+    end
+
+    private
+
+    def make_slug
+      slugs_in_use = if slugs.loaded? then
+                       slugs.map(&:slug)
+                     else
+                       slugs.select(:slug).all.map(&:slug)
+                     end
+
+      # grab a list of all potential slugs derived from the generators
+      potential_slugs = self.class._slug_procs.map { |slug_proc| slug_proc[self] }.
+        compact.
+        map { |slug| self.class._slugifier[slug] }.
+        map { |slug| slug[0, MAX_SLUG_LENGTH] }
+      raise "All slug generators returned nil for #{self.inspect}" if potential_slugs.empty?
+      # include the last-resort slug, trimmed for length
+      last_resort_append = "#{self.class._slug_id_separator}#{id}"
+      potential_slugs << "#{potential_slugs.first[0, [ 1, MAX_SLUG_LENGTH - last_resort_append.length ].max]}#{last_resort_append}"[0, MAX_SLUG_LENGTH]
+      # subtract out blacklisted slugs
+      potential_slugs -= self.class._slug_blacklist
+      
+      # if one of these slugs is already in use, we don't need to change the slug
+      # instead, activate the one of highest prioirty and we're done
+      valid_slugs_in_use = potential_slugs & slugs_in_use
+      unless valid_slugs_in_use.empty?
+        Slug.transaction do
+          slugs.update_all(active: false)
+          slugs.where(slug: valid_slugs_in_use.first).update_all(active: true)
+        end
+        return
+      end
+
+      Slug.transaction do
+        # grab a list of all the slugs we can't use
+        scope = Slug.select(:slug).where(sluggable_type: self.class.to_s, slug: potential_slugs)
+        if self.class._slug_scope then
+          scope = scope.where(scope: self.class._slug_scope[self])
+        end
+        taken_slug_objects = scope.all
+
+        # subtract them out from all the potential slugs to make the available slugs
+        available_slugs = potential_slugs - taken_slug_objects.map(&:slug)
+        # no slugs available? nothing much else we can do
+        raise "Couldn't find a slug for #{self.inspect}; tried #{potential_slugs.join(', ')}" if available_slugs.empty?
+        
+        slugs.update_all(active: false)
+        Slug.create!(sluggable: self,
+                     slug: available_slugs.first,
+                     active: true,
+                     scope: self.class._slug_scope.try(:call, self))
+      end
+
+      unmemoize_all
+    end
+  end
+end

data/lib/slugalicious_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators'
+require 'rails/generators'
+require 'rails/generators/migration'
+
+# @private
+class SlugaliciousGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  
+  source_root "#{File.dirname __FILE__}/../templates"
+  
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations then
+      Time.now.utc.strftime "%Y%m%d%H%M%S"
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+  
+  def copy_files
+    copy_file 'slug.rb', 'app/models/slug.rb'
+    migration_template "create_slugs.rb", "db/migrate/create_slugs.rb"
+  end
+end

data/slugalicious.gemspec

@@ -0,0 +1,68 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{slugalicious}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Morgan"]
+  s.date = %q{2010-10-30}
+  s.description = %q{Slugalicious adds simple and powerful slugging to your ActiveRecord models.}
+  s.email = %q{git@timothymorgan.info}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     ".rspec",
+     "Gemfile",
+     "Gemfile.lock",
+     "LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "lib/slugalicious.rb",
+     "lib/slugalicious_generator.rb",
+     "slugalicious.gemspec",
+     "spec/factories.rb",
+     "spec/slug_spec.rb",
+     "spec/slugalicious_spec.rb",
+     "spec/spec_helper.rb",
+     "templates/create_slugs.rb",
+     "templates/slug.rb"
+  ]
+  s.homepage = %q{http://github.com/riscfuture/slugalicious}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new(">= 1.9")
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Easy-to-use and powerful slugging for Rails 3}
+  s.test_files = [
+    "spec/factories.rb",
+     "spec/slug_spec.rb",
+     "spec/slugalicious_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rails>, [">= 3.0"])
+      s.add_runtime_dependency(%q<stringex>, [">= 0"])
+    else
+      s.add_dependency(%q<rails>, [">= 3.0"])
+      s.add_dependency(%q<stringex>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rails>, [">= 3.0"])
+    s.add_dependency(%q<stringex>, [">= 0"])
+  end
+end
+

data/spec/factories.rb

@@ -0,0 +1,14 @@
+Factory.define :slug do |f|
+  f.sequence(:slug) { |n| "slug-#{n}" }
+  f.active true
+end
+
+Factory.define :user do |f|
+  f.first_name "Doctor"
+  f.last_name "Spaceman"
+end
+
+Factory.define :abuser do |f|
+  f.first_name "Doctor"
+  f.last_name "Spaceman"
+end

data/spec/slug_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe Slug do
+  before :each do
+    @record = Factory(:user)
+    Slug.delete_all
+  end
+
+  describe "validation" do
+    it "should not allow an active slug to be created if one already exists" do
+      Factory(:slug, sluggable: @record)
+      slug = Factory.build(:slug, sluggable: @record)
+      slug.should_not be_valid
+      slug.errors[:active].should_not be_empty
+    end
+
+    it "should not allow a slug to be made active if one already exists" do
+      Factory(:slug, sluggable: @record)
+      slug = Factory(:slug, sluggable: @record, active: false)
+      slug.active = true
+      slug.should_not be_valid
+      slug.errors[:active].should_not be_empty
+    end
+
+    it "should allow an active slug to be created if none exists" do
+      slug = Factory.build(:slug, sluggable: @record)
+      slug.should be_valid
+    end
+
+    it "should allow a slug to be made active if none exists" do
+      slug = Factory(:slug, sluggable: @record, active: false)
+      slug.active = true
+      slug.should be_valid
+    end
+
+    it "should allow an inactive slug to be modified if the active field is not changing" do
+      Factory(:slug, sluggable: @record)
+      slug = Factory(:slug, sluggable: @record, active: false)
+      slug.scope = 'test'
+      slug.should be_valid
+    end
+  end
+
+  describe "#activate!" do
+    it "should mark the slug as active" do
+      slug = Factory(:slug, sluggable: Factory(:user), active: false)
+      slug.activate!
+      slug.should be_active
+    end
+
+    it "should deactivate all the record's other slugs" do
+      record = Factory(:user)
+      s1 = Slug.for(record).first
+      s2 = Factory(:slug, sluggable: record, active: false)
+      s3 = Factory(:slug, sluggable: record, active: false)
+
+      slug = Factory(:slug, sluggable: record, active: false)
+      slug.activate!
+
+      s1.reload.should_not be_active
+      s2.reload.should_not be_active
+      s3.reload.should_not be_active
+    end
+  end
+end

data/spec/slugalicious_spec.rb

@@ -0,0 +1,232 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Slugalicious do
+  before :each do
+    @model = Class.new
+    @model.send :include, ActiveModel::Validations
+    @model.send :include, ActiveModel::Validations::Callbacks
+    @model.send :include, ActiveRecord::Callbacks
+    @model.send :include, ActiveRecord::Validations
+    @model.stub!(:has_many)
+    @model.send :include, Slugalicious
+  end
+
+  describe "#slugged" do
+    it "should raise an error if no generators are given" do
+      expect { @model.send(:slugged, { options: 'here' }) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "#to_param" do
+    it "should return the slug" do
+      user = Factory(:user)
+      user.slug.should_not be_nil
+      user.to_param.should eql(user.slug)
+    end
+
+    it "should return the full slug path when scoped" do
+      User._slug_procs.clear
+      User.send :slugged, :first_name, scope: :last_name
+      
+      user = Factory(:user, last_name: 'test/')
+      user.to_param.should eql('test/doctor')
+    end
+  end
+
+  context "slug generation" do
+    before :each do
+      User._slug_procs.clear
+      User._slug_blacklist.clear
+    end
+
+    it "should set the slug according to the generator and apply the slugifier" do
+      User.send :slugged, :first_name
+      object = Factory(:user, first_name: "Sancho", last_name: "Sample")
+      object.slug.should eql("sancho")
+    end
+
+    it "should generate from a proc as well as a symbol" do
+      User.send :slugged, ->(person) { "#{person.first_name} #{person.last_name}" }
+      object = Factory(:user, first_name: "Foo", last_name: "bar")
+      object.slug.should eql("foo-bar")
+    end
+
+    it "should give priority to the first non-nil slug" do
+      User.send :slugged, :gender, :last_name
+      object = Factory(:user, gender: nil, last_name: "Bar")
+      object.slug.should eql("bar")
+    end
+    
+    it "should not create a new slug if an existing one matches" do
+      User.send :slugged, :first_name, :last_name
+      object = Factory(:user, first_name: 'Foo', last_name: "Bar")
+      object.slug.should eql("foo")
+      other_slug = Factory(:slug, slug: 'bar', sluggable: object, active: false)
+      
+      object.update_attribute :last_name, 'baz'
+      object.slug.should eql("foo")
+      other_slug.reload.active.should be_false
+    end
+
+    it "should ignore slugs from other models" do
+      User.send :slugged, :first_name, :last_name
+      Factory(:abuser, last_name: 'Foo').slug.should eql('foo')
+      Factory(:user, first_name: 'Foo', last_name: 'Foo').slug.should eql('foo')
+    end
+
+    it "should use the last-resort generator if nothing else is unique" do
+      User.send :slugged, :first_name, :last_name
+      Factory(:user, first_name: 'Foo', last_name: 'Bar').slug.should eql('foo')
+      Factory(:user, first_name: 'Foo', last_name: 'Bar').slug.should eql('bar')
+      user = Factory(:user, first_name: 'Foo', last_name: 'Bar')
+      user.slug.should eql("foo;#{user.id}")
+    end
+
+    it "should raise an error if all generators return nil" do
+      User.send :slugged, :gender, :birthdate
+      -> { Factory(:user, gender: nil, birthdate: nil) }.should raise_error
+    end
+    
+    it "should use the first non-nil slug for the last-resort generator" do
+      User.send :slugged, :gender, :first_name, :last_name
+      Factory(:user, first_name: 'Foo', last_name: 'Bar', gender: nil)
+      Factory(:user, first_name: 'Foo', last_name: 'Bar', gender: nil)
+      user = Factory(:user, first_name: 'Foo', last_name: 'Bar', gender: nil)
+      user.slug.should eql("foo;#{user.id}")
+    end
+
+    it "should use a custom id separator if given" do
+      User.send :slugged, :first_name, :last_name, id_separator: ':'
+      Factory(:user, first_name: 'Foo', last_name: 'Bar')
+      Factory(:user, first_name: 'Foo', last_name: 'Bar')
+      user = Factory(:user, first_name: 'Foo', last_name: 'Bar')
+      user.slug.should eql("foo:#{user.id}")
+    end
+    
+    it "should avoid blacklisted slugs" do
+      User.send :slugged, :first_name, :last_name
+      Factory(:user, first_name: 'New', last_name: 'Bar').slug.should eql('bar')
+    end
+
+    it "should use a custom blacklist" do
+      User.send :slugged, :first_name, :last_name, blacklist: %w( foo bar )
+      Factory(:user, first_name: 'Foo', last_name: 'Baz').slug.should eql('baz')
+    end
+
+    it "should wrap the blacklist array" do
+      User.send :slugged, :first_name, :last_name, blacklist: 'foo'
+      Factory(:user, first_name: 'Foo', last_name: 'Baz').slug.should eql('baz')
+    end
+    
+    it "should only search for available slugs inside the scope if given" do
+      User.send :slugged, :first_name, :last_name, scope: :callsign
+
+      Factory(:user, first_name: 'Foo', last_name: 'Bar', callsign: 'One').slug.should eql('foo')
+      Factory(:user, first_name: 'Foo', last_name: 'Baz', callsign: 'One').slug.should eql('baz')
+      Factory(:user, first_name: 'Boo', last_name: 'Bar', callsign: 'One').slug.should eql('boo')
+      
+      Factory(:user, first_name: 'Foo', last_name: 'Bar', callsign: 'Two').slug.should eql('foo')
+      Factory(:user, first_name: 'Foo', last_name: 'Baz', callsign: 'Two').slug.should eql('baz')
+    end
+
+    it "should accept a proc for a scope" do
+      User.send :slugged, :first_name, :last_name, scope: ->(object) { object.callsign[0] }
+
+      Factory(:user, first_name: 'Foo', last_name: 'Bar', callsign: 'One').slug.should eql('foo')
+      Factory(:user, first_name: 'Foo', last_name: 'Baz', callsign: 'Only').slug.should eql('baz')
+      Factory(:user, first_name: 'Boo', last_name: 'Bar', callsign: 'Ocho').slug.should eql('boo')
+
+      Factory(:user, first_name: 'Foo', last_name: 'Bar', callsign: 'Two').slug.should eql('foo')
+      Factory(:user, first_name: 'Foo', last_name: 'Baz', callsign: 'Tres').slug.should eql('baz')
+    end
+
+    it "should enforce a maximum length of 126 characters" do
+      User.send :slugged, :first_name
+
+      user = Factory(:user)
+      user.first_name = 'A'*500
+      user.save(validate: false)
+      user.slug.should eql('a'*126)
+    end
+
+    it "should shorten left of the ID separator" do
+      User.send :slugged, :first_name
+
+      user1 = Factory(:user)
+      user1.first_name = 'A'*500
+      user1.save(validate: false)
+
+      user2 = Factory(:user)
+      user2.first_name = 'A'*500
+      user2.save(validate: false)
+
+      user2.slug.size.should eql(126)
+      user2.slug.should match(/^a+;#{user2.id}$/)
+    end
+
+    it "should raise an error if no unique slugs are available" do
+      old_length = Slugalicious::MAX_SLUG_LENGTH
+      Slugalicious::MAX_SLUG_LENGTH = 1
+
+      User.send :slugged, ->(object) { 'f' }, blacklist: 'f'
+      -> { Factory(:user, first_name: 'Foo', last_name: 'Bar') }.should raise_error
+      
+      Slugalicious::MAX_SLUG_LENGTH = old_length
+    end
+  end
+
+  describe "#find_from_slug" do
+    it "should return a Slug object for a slug" do
+      User.send :slugged, :first_name, :last_name
+      user1 = Factory(:user, first_name: "FN1", last_name: "LN1")
+      User.find_from_slug('fn1').should eql(user1)
+    end
+
+    it "should exclude slugs of other models" do
+      User.send :slugged, :first_name, :last_name
+      user1 = Factory(:user, first_name: "FN1", last_name: "LN1")
+      Factory(:abuser, first_name: 'FN1')
+      User.find_from_slug('fn1').should eql(user1)
+    end
+
+    it "should locate an object within a given scope" do
+      User.send :slugged, :first_name, scope: :last_name
+      user1 = Factory(:user, first_name: "FN1", last_name: "LN1")
+      user2 = Factory(:user, first_name: "FN1", last_name: "LN2")
+      User.find_from_slug('fn1', 'LN1').should eql(user1)
+      User.find_from_slug('fn1', 'LN2').should eql(user2)
+    end
+
+    it "should raise ActiveRecord::RecordNotFound if the slug does not exist" do
+      -> { User.find_from_slug('nonexist') }.should raise_error(ActiveRecord::RecordNotFound)
+    end
+
+    it "should raise ActiveRecord::RecordNotFound if the slug does not exist in scope" do
+      User.send :slugged, :first_name, scope: :last_name
+      Factory(:user, first_name: "FN1", last_name: "LN1")
+      Factory(:user, first_name: "FN2", last_name: "LN2")
+      -> { User.find_from_slug('fn2', 'ln1') }.should raise_error(ActiveRecord::RecordNotFound)
+    end
+
+    it "should find inactive slugs" do
+      User.send :slugged, :first_name
+      user = Factory(:user, first_name: 'New')
+      Factory(:slug, sluggable: user, slug: 'old', active: false)
+      User.find_from_slug('old').should eql(user)
+    end
+  end
+
+  describe "#find_from_slug_path" do
+    it "should call #find_from_slug with the slug and no scope for unscoped models" do
+      User.send :slugged, :first_name
+      User.should_receive(:find_from_slug).once.with("test", '')
+      User.find_from_slug_path("test")
+    end
+
+    it "should call #find_from_slug with the slug and scope for scoped models" do
+      User.send :slugged, :first_name, scope: :last_name
+      User.should_receive(:find_from_slug).once.with("test", "path/to/")
+      User.find_from_slug_path("path/to/test")
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,45 @@
+Bundler.require :default, :test
+require 'active_support'
+require 'active_record'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'slugalicious'
+
+ActiveRecord::Base.establish_connection(
+  adapter: 'sqlite3',
+  database: 'test.sqlite'
+)
+require "#{File.dirname __FILE__}/../templates/slug"
+
+class User < ActiveRecord::Base
+  include Slugalicious
+  slugged :last_name, ->(user) { "#{user.first_name} #{user.last_name}" }
+end
+class Abuser < ActiveRecord::Base
+  include Slugalicious
+  slugged :last_name, ->(user) { "#{user.first_name} #{user.last_name}" }
+end
+
+require "#{File.dirname __FILE__}/factories"
+
+RSpec.configure do |config|
+  config.before(:each) do
+    Slug.connection.execute "DROP TABLE IF EXISTS slugs"
+    Slug.connection.execute <<-SQL
+      CREATE TABLE slugs (
+        id INTEGER PRIMARY KEY ASC,
+        sluggable_type VARCHAR(126) NOT NULL,
+        sluggable_id INTEGER NOT NULL,
+        active BOOLEAN NOT NULL DEFAULT 1,
+        slug VARCHAR(126) NOT NULL,
+        scope VARCHAR(126)
+      )
+    SQL
+    User.connection.execute "DROP TABLE IF EXISTS users"
+    User.connection.execute "CREATE TABLE users (id INTEGER PRIMARY KEY ASC, first_name TEXT, last_name TEXT, callsign TEXT, gender VARCHAR(7))"
+    Abuser.connection.execute "DROP TABLE IF EXISTS abusers"
+    Abuser.connection.execute "CREATE TABLE abusers (id INTEGER PRIMARY KEY ASC, first_name TEXT, last_name TEXT, callsign TEXT, gender VARCHAR(7))"
+  end
+end

data/templates/create_slugs.rb

@@ -0,0 +1,20 @@
+class CreateSlugs < ActiveRecord::Migration
+  def self.up
+    create_table :slugs do |t|
+      t.belongs_to :sluggable, polymorphic: true, null: false
+      t.boolean :active, null: false, default: true
+      t.string :slug, null: false, limit: 126
+      t.string :scope, limit: 126
+      t.datetime :created_at
+    end
+    
+    change_table :slugs do |t|
+      t.index [ :sluggable_type, :sluggable_id, :active ], name: 'slugs_for_record'
+      t.index [ :sluggable_type, :scope, :slug ], unique: true, name: 'slugs_unique'
+    end
+  end
+
+  def self.down
+    drop_table :slugs
+  end
+end

data/templates/slug.rb

@@ -0,0 +1,63 @@
+# Stores slugs used to prettify URLs. For more information, see the
+# {Slugalicious} mixin.
+#
+# As new slugs are created, old ones are marked as inactive and kept around for
+# redirect purposes. Once a slug is old enough, it is deleted and its value can
+# be used for new records (no longer redirects).
+#
+# h2. Associations
+#
+# | @sluggable@ | The record that this slug references. |
+#
+# h2. Properties
+#
+# | @slug@ | The slug, lowercased and normalized. Slugs must be unique to their @sluggable_type@ and @scope@. |
+# | @active@ | Whether this is the most recently generated slug for the sluggable. |
+# | @scope@ | Freeform data scoping this slug to a certain subset of records within the model. |
+
+class Slug < ActiveRecord::Base
+  belongs_to :sluggable, polymorphic: true
+
+  scope :for, ->(object_or_type, object_id=nil) {
+    object_type = object_id ? object_or_type : object_or_type.class.to_s
+    object_id ||= object_or_type.id
+    where(sluggable_type: object_type, sluggable_id: object_id)
+  }
+  scope :for_class, ->(model) { where(sluggable_type: model.to_s) }
+  scope :from_slug, ->(klass, scope, slug) {
+    where(sluggable_type: klass.to_s, slug: slug, scope: scope)
+  }
+  scope :active, where(active: true)
+  scope :inactive, where(active: false)
+
+  validates :sluggable_type,
+            presence: true
+  validates :sluggable_id,
+            presence: true,
+            numericality: { only_integer: true }
+  validates :slug,
+            presence: true,
+            length: { maximum: 126 },
+            uniqueness: { case_sensitive: false, scope: [ :scope, :sluggable_type ] } #TODO validate scope case-insensitively
+  validates :scope,
+            length: { maximum: 126 },
+            allow_blank: true
+  validate :one_active_slug_per_object
+  
+  # Marks a slug as active and deactivates all other slugs assigned to the
+  # record.
+
+  def activate!
+    self.class.transaction do
+      Slug.for(sluggable_type, sluggable_id).update_all(active: false)
+      update_attribute :active, true
+    end
+  end
+
+  private
+
+  def one_active_slug_per_object
+    return unless new_record? or (active? and active_changed?)
+    errors.add(:active, :one_per_sluggable) if active? and Slug.active.for(sluggable_type, sluggable_id).count > 0
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: slugalicious
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-30 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: stringex
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+description: Slugalicious adds simple and powerful slugging to your ActiveRecord models.
+email: git@timothymorgan.info
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- .document
+- .gitignore
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.textile
+- Rakefile
+- VERSION
+- lib/slugalicious.rb
+- lib/slugalicious_generator.rb
+- slugalicious.gemspec
+- spec/factories.rb
+- spec/slug_spec.rb
+- spec/slugalicious_spec.rb
+- spec/spec_helper.rb
+- templates/create_slugs.rb
+- templates/slug.rb
+has_rdoc: true
+homepage: http://github.com/riscfuture/slugalicious
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 9
+      version: "1.9"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Easy-to-use and powerful slugging for Rails 3
+test_files: 
+- spec/factories.rb
+- spec/slug_spec.rb
+- spec/slugalicious_spec.rb
+- spec/spec_helper.rb