friendly_id 5.0.0.alpha.1 → 5.0.0.beta1

data/README.md

@@ -4,14 +4,14 @@
 
 **Rails 4**:
 Master branch of this repository contains FriendlyId 5 which is compatible with Rails 4.
-This version is under active development and not yet fully stable.
+This version is in beta and will be released soon.
 
 **Rails 3**:
 If you wish to use this gem with Rails 3.1 or 3.2 you need to use FriendlyId version 4, which is the current stable release.
 Please see [4.0-stable
-branch](https://github.com/FriendlyId/friendly_id/tree/4.0-stable).
+branch](https://github.com/norman/friendly_id/tree/4.0-stable).
 
-[![Build Status](https://travis-ci.org/FriendlyId/friendly_id.png)](https://travis-ci.org/FriendlyId/friendly_id)
+[![Build Status](https://travis-ci.org/norman/friendly_id.png)](https://travis-ci.org/norman/friendly_id)
 
 FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for
 Ruby on Rails. It allows you to create pretty URLs and work with human-friendly
@@ -96,10 +96,10 @@ restaurant.friendly_id # the-plaza-diner
 ## Docs
 
 The current docs can always be found
-[here](http://rubydoc.info/github/FriendlyId/friendly_id/master/frames).
+[here](http://rubydoc.info/github/norman/friendly_id/master/frames).
 
 The best place to start is with the
-[Guide](http://rubydoc.info/github/FriendlyId/friendly_id/master/file/Guide.rdoc),
+[Guide](http://rubydoc.info/github/norman/friendly_id/master/file/Guide.md),
 which compiles the top-level RDocs into one outlined document.
 
 You might also want to watch Ryan Bates's [Railscast on FriendlyId](http://railscasts.com/episodes/314-pretty-urls-with-friendlyid),
@@ -113,9 +113,10 @@ cd my_app
 ```
 ```ruby
 # Gemfile
-gem 'friendly_id', github: 'FriendlyId/friendly_id', branch: 'master' # Note: You MUST use 5.0.0 or greater for Rails 4.0+
+gem 'friendly_id', '5.0.0.beta1' # Note: You MUST use 5.0.0 or greater for Rails 4.0+
 ```
 ```shell
+rails generate friendly_id
 rails generate scaffold user name:string slug:string
 ```
 ```ruby
@@ -158,7 +159,7 @@ The latest benchmarks for FriendlyId are maintained
 ## Bugs
 
 Please report them on the [Github issue
-tracker](http://github.com/FriendlyId/friendly_id/issues) for this project.
+tracker](http://github.com/norman/friendly_id/issues) for this project.
 
 If you have a bug to report, please include the following information:
 
@@ -180,7 +181,7 @@ significant help early in its life by Emilio Tagua. It is now maintained by
 Norman Clarke and Philip Arndt.
 
 We're deeply grateful for the generous contributions over the years from [many
-volunteers](https://github.com/FriendlyId/friendly_id/contributors).
+volunteers](https://github.com/norman/friendly_id/contributors).
 
 ## License
 

data/Rakefile

@@ -36,7 +36,7 @@ task :bench => :load_path do
   require File.expand_path("../bench", __FILE__)
 end
 
-desc "Generate Guide.rdoc"
+desc "Generate Guide.md"
 task :guide do
   def read_comments(path)
     path  = File.expand_path("../#{path}", __FILE__)
@@ -54,8 +54,7 @@ task :guide do
   buffer << read_comments("lib/friendly_id/simple_i18n.rb")
   buffer << read_comments("lib/friendly_id/reserved.rb")
 
-  File.open("Guide.rdoc", "w") do |file|
-    file.write("#encoding: utf-8\n")
+  File.open("Guide.md", "w") do |file|
     file.write(buffer.join("\n"))
   end
 end

data/bench.rb

@@ -42,11 +42,13 @@ Benchmark.bmbm do |x|
   x.report 'find (without FriendlyId)' do
     N.times {Book.find BOOKS.rand}
   end
+
   x.report 'find (in-table slug)' do
-    N.times {Journalist.find JOURNALISTS.rand}
+    N.times {Journalist.friendly.find JOURNALISTS.rand}
   end
+
   x.report 'find (external slug)' do
-    N.times {Manual.find MANUALS.rand}
+    N.times {Manual.friendly.find MANUALS.rand}
   end
 
   x.report 'insert (without FriendlyId)' do
@@ -60,4 +62,4 @@ Benchmark.bmbm do |x|
   x.report 'insert (external slug)' do
     N.times {transaction {Manual.create :name => Faker::Name.name}}
   end
-end
+end

data/friendly_id.gemspec

@@ -16,14 +16,15 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 1.9.3'
 
-  s.add_development_dependency "railties", "~> 4.0.0"
-  s.add_development_dependency "activerecord", "~> 4.0.0"
-  s.add_development_dependency "minitest", ">= 4.4.0"
-  s.add_development_dependency "mocha", "~> 0.13.3"
-  s.add_development_dependency "yard"
-  s.add_development_dependency "i18n"
-  s.add_development_dependency "ffaker"
-  s.add_development_dependency "simplecov"
+  s.add_development_dependency 'railties', '~> 4.0.0'
+  s.add_development_dependency 'activerecord', '~> 4.0.0'
+  s.add_development_dependency 'minitest', '>= 4.4.0'
+  s.add_development_dependency 'mocha', '~> 0.13.3'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'i18n'
+  s.add_development_dependency 'ffaker'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'redcarpet'
 
   s.description = <<-EOM
 FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for

data/lib/friendly_id.rb

@@ -3,11 +3,11 @@ require "thread"
 require "friendly_id/base"
 require "friendly_id/object_utils"
 require "friendly_id/configuration"
-require "friendly_id/scopes"
+require "friendly_id/finders"
 
 =begin
 
-== About FriendlyId
+## About FriendlyId
 
 FriendlyId is an add-on to Ruby's Active Record that allows you to replace ids
 in your URLs with strings:
@@ -21,25 +21,24 @@ in your URLs with strings:
 It requires few changes to your application code and offers flexibility,
 performance and a well-documented codebase.
 
-=== Core Concepts
+### Core Concepts
 
-==== Slugs
+#### Slugs
 
-The concept of "slugs[http://en.wikipedia.org/wiki/Slug_(web_publishing)]" is at
-the heart of FriendlyId.
+The concept of *slugs* is at the heart of FriendlyId.
 
 A slug is the part of a URL which identifies a page using human-readable
 keywords, rather than an opaque identifier such as a numeric id. This can make
 your application more friendly both for users and search engine.
 
-==== Finders: Slugs Act Like Numeric IDs
+#### Finders: Slugs Act Like Numeric IDs
 
 To the extent possible, FriendlyId lets you treat text-based identifiers like
 normal IDs. This means that you can perform finds with slugs just like you do
 with numeric ids:
 
     Person.find(82542335)
-    Person.find("joe")
+    Person.friendly.find("joe")
 
 =end
 module FriendlyId

data/lib/friendly_id/base.rb

@@ -1,7 +1,7 @@
 module FriendlyId
 =begin
 
-== Setting Up FriendlyId in Your Model
+## Setting Up FriendlyId in Your Model
 
 To use FriendlyId in your ActiveRecord models, you must first either extend or
 include the FriendlyId module (it makes no difference), then invoke the
@@ -18,7 +18,7 @@ addons it should use. See the documentation for this method for a list of all
 available addons, or skim through the rest of the docs to get a high-level
 overview.
 
-=== The Default Setup: Simple Models
+### The Default Setup: Simple Models
 
 The simplest way to use FriendlyId is with a model that has a uniquely indexed
 column with no spaces or special characters, and that is seldom or never
@@ -30,9 +30,9 @@ updated. The most common example of this is a user name:
       validates_format_of :login, :with => /\A[a-z0-9]+\z/i
     end
 
-    @user = User.find "joe"   # the old User.find(1) still works, too
-    @user.to_param            # returns "joe"
-    redirect_to @user         # the URL will be /users/joe
+    @user = User.friendly.find "joe"   # the old User.find(1) still works, too
+    @user.to_param                     # returns "joe"
+    redirect_to @user                  # the URL will be /users/joe
 
 In this case, FriendlyId assumes you want to use the column as-is; it will never
 modify the value of the column, and your application should ensure that the
@@ -43,7 +43,7 @@ value is unique and admissible in a URL:
       friendly_id :name
     end
 
-    @city.find "Viña del Mar"
+    @city.friendly.find "Viña del Mar"
     redirect_to @city # the URL will be /cities/Viña%20del%20Mar
 
 Writing the code to process an arbitrary string into a good identifier for use
@@ -103,7 +103,7 @@ often better and easier to use {FriendlyId::Slugged slugs}.
     # between multiple models that can't be well encapsulated by
     # {FriendlyId.defaults}.
     #
-    # === Order Method Calls in a Block vs Ordering Options
+    # ### Order Method Calls in a Block vs Ordering Options
     #
     # When calling this method without a block, you may set the hash options in
     # any order.
@@ -112,7 +112,7 @@ often better and easier to use {FriendlyId::Slugged slugs}.
     # FriendlyId::Configuration's {FriendlyId::Configuration#use use} method
     # *prior* to the associated configuration options, because it will include
     # modules into your class, and these modules in turn may add required
-    # configuration options to the +@friendly_id_configuraton+'s class:
+    # configuration options to the `@friendly_id_configuraton`'s class:
     #
     #   class Person < ActiveRecord::Base
     #     friendly_id do |config|
@@ -130,7 +130,7 @@ often better and easier to use {FriendlyId::Slugged slugs}.
     #     end
     #   end
     #
-    # === Including Your Own Modules
+    # ### Including Your Own Modules
     #
     # Because :use can accept a name or a Module, {FriendlyId.defaults defaults}
     # can be a convenient place to set up behavior common to all classes using
@@ -158,23 +158,23 @@ often better and easier to use {FriendlyId::Slugged slugs}.
     #   {FriendlyId::History :history}, {FriendlyId::Reserved :reserved}, and
     #   {FriendlyId::Scoped :scoped}, and {FriendlyId::SimpleI18n :simple_i18n}.
     #
-    # @option options [Array] :reserved_words Available when using +:reserved+,
+    # @option options [Array] :reserved_words Available when using `:reserved`,
     #   which is loaded by default. Sets an array of words banned for use as
     #   the basis of a friendly_id. By default this includes "edit" and "new".
     #
-    # @option options [Symbol] :scope Available when using +:scoped+.
+    # @option options [Symbol] :scope Available when using `:scoped`.
     #   Sets the relation or column used to scope generated friendly ids. This
     #   option has no default value.
     #
-    # @option options [Symbol] :sequence_separator Available when using +:slugged+.
+    # @option options [Symbol] :sequence_separator Available when using `:slugged`.
     #   Configures the sequence of characters used to separate a slug from a
-    #   sequence. Defaults to +-+.
+    #   sequence. Defaults to `-`.
     #
-    # @option options [Symbol] :slug_column Available when using +:slugged+.
+    # @option options [Symbol] :slug_column Available when using `:slugged`.
     #   Configures the name of the column where FriendlyId will store the slug.
-    #   Defaults to +:slug+.
+    #   Defaults to `:slug`.
     #
-    # @option options [Symbol] :slug_generator_class Available when using +:slugged+.
+    # @option options [Symbol] :slug_generator_class Available when using `:slugged`.
     #   Sets the class used to generate unique slugs. You should not specify this
     #   unless you're doing some extensive hacking on FriendlyId. Defaults to
     #   {FriendlyId::SlugGenerator}.
@@ -189,7 +189,21 @@ often better and easier to use {FriendlyId::Slugged slugs}.
       friendly_id_config.use options.delete :use
       friendly_id_config.send :set, base ? options.merge(:base => base) : options
       include Model
-      extend Scopes
+    end
+
+    # Return a scope that includes the friendly finders.
+    # @see FriendlyId::Finders
+    def friendly
+      # Guess what? This causes Rails to invoke `extend` on the scope, which has
+      # the well-known effect of blowing away Ruby's method cache. It would be
+      # possible to make this more performant by subclassing the model's
+      # relation class, extending that, and returning an instance of it in this
+      # method. FriendlyId 4.0 did something similar. However in 5.0 I've
+      # decided to only use Rails's public API in order to improve compatibility
+      # and maintainability. If you'd like to improve the performance, your
+      # efforts would be best directed at improving it at the root cause
+      # of the problem - in Rails - because it would benefit more people.
+      all.extending(Finders)
     end
 
     # Returns the model class's {FriendlyId::Configuration friendly_id_config}.

data/lib/friendly_id/candidates.rb

@@ -2,6 +2,8 @@ require 'securerandom'
 
 module FriendlyId
 
+  # This class provides the slug candidate functionality.
+  # @see FriendlyId::Slugged
   class Candidates
 
     include Enumerable
@@ -11,6 +13,8 @@ module FriendlyId
       @candidates = to_candidate_array(object, array.flatten(1))
     end
 
+
+    # Visits each slug candidate, calls it, passes it to `normalize_friendly_id` and yields the result.
     def each(*args, &block)
       @candidates.each(*args) do |candidate|
         yield @object.normalize_friendly_id(candidate.map(&:call).join(' '))

data/lib/friendly_id/configuration.rb

@@ -16,9 +16,9 @@ module FriendlyId
     # FriendlyId will take care of transforming the human-readable title into
     # something suitable for use in a URL.
     #
-    # @param [Symbol] A symbol referencing a column or method in the model. This
-    #   value is usually set by passing it as the first argument to
-    #   {FriendlyId::Base#friendly_id friendly_id}:
+    # A symbol referencing a column or method in the model. This
+    # value is usually set by passing it as the first argument to
+    # {FriendlyId::Base#friendly_id friendly_id}:
     #
     # @example
     #   class Book < ActiveRecord::Base
@@ -55,7 +55,7 @@ module FriendlyId
     #     extend FriendlyId
     #     friendly_id :name, :use => :slugged
     #   end
-    # @param [#to_s,Module] *modules Arguments should be Modules, or symbols or
+    # @param [#to_s,Module] modules Arguments should be Modules, or symbols or
     #   strings that correspond with the name of a module inside the FriendlyId
     #   namespace. By default FriendlyId provides +:slugged+, +:history+,
     #   +:simple_i18n+, and +:scoped+.

data/lib/friendly_id/finders.rb

@@ -0,0 +1,51 @@
+module FriendlyId
+
+  # These are the finder methods that are added to the +friendly+ scope.
+  module Finders
+
+    # Finds a record using the given id.
+    #
+    # If the id is "unfriendly", it will call the original find method.
+    # If the id is a numeric string like '123' it will first look for a friendly
+    # id matching '123' and then fall back to looking for a record with the
+    # numeric id '123'.
+    #
+    # Since FriendlyId 5.0, if the id is a numeric string like '123-foo' it
+    # will *only* search by friendly id and not fall back to the regular find
+    # method.
+    #
+    # If you want to search only by the friendly id, use {#find_by_friendly_id}.
+    # @raise ActiveRecord::RecordNotFound
+    def find(*args)
+      id = args.first
+      return super if args.count != 1 || id.unfriendly_id?
+      first_by_friendly_id(id).tap {|result| return result unless result.nil?}
+      return super if Integer(id, 10) rescue nil
+      raise ActiveRecord::RecordNotFound
+    end
+
+    # Returns true if a record with the given id exists.
+    def exists?(conditions = :none)
+      return super unless conditions.friendly_id?
+      exists_by_friendly_id?(conditions)
+    end
+
+    # Finds exclusively by the friendly id, completely bypassing original
+    # +find+.
+    # @raise ActiveRecord::RecordNotFound
+    def find_by_friendly_id(id)
+      first_by_friendly_id(id) or raise ActiveRecord::RecordNotFound
+    end
+
+    private
+
+    def first_by_friendly_id(id)
+      where(friendly_id_config.query_field => id).first
+    end
+
+    def exists_by_friendly_id?(id)
+      where(friendly_id_config.query_field => id).exists?
+    end
+
+  end
+end

data/lib/friendly_id/history.rb

@@ -2,7 +2,7 @@ module FriendlyId
 
 =begin
 
-== History: Avoiding 404's When Slugs Change
+## History: Avoiding 404's When Slugs Change
 
 FriendlyId's {FriendlyId::History History} module adds the ability to store a
 log of a model's slugs, so that when its friendly id changes, it's still
@@ -10,26 +10,24 @@ possible to perform finds by the old id.
 
 The primary use case for this is avoiding broken URLs.
 
-=== Setup
+### Setup
 
 In order to use this module, you must add a table to your database schema to
 store the slug records. FriendlyId provides a generator for this purpose:
 
-  rails generate friendly_id
-  rake db:migrate
+    rails generate friendly_id
+    rake db:migrate
 
-This will add a table named +friendly_id_slugs+, used by the {FriendlyId::Slug}
+This will add a table named `friendly_id_slugs`, used by the {FriendlyId::Slug}
 model.
 
-=== Considerations
-
-This module is incompatible with the +:scoped+ module.
+### Considerations
 
 Because recording slug history requires creating additional database records,
-this module has an impact on the performance of the associated model's +create+
+this module has an impact on the performance of the associated model's `create`
 method.
 
-=== Example
+### Example
 
     class Post < ActiveRecord::Base
       extend FriendlyId
@@ -66,18 +64,30 @@ method.
           :dependent  => :destroy,
           :class_name => Slug.to_s
         }
+
         after_save :create_slug
-        def self.find_by_friendly_id(id)
-          includes(:slugs).where(slug_history_clause(id)).references(:slugs).first
-        end
 
-        def self.exists_by_friendly_id?(id)
-          includes(:slugs).where(arel_table[friendly_id_config.query_field].eq(id).or(slug_history_clause(id))).exists?
+        def self.friendly
+          all.extending(HistoryFinders)
         end
+      end
+    end
 
-        def self.slug_history_clause(id)
-          Slug.arel_table[:sluggable_type].eq(base_class.to_s).and(Slug.arel_table[:slug].eq(id))
-        end
+    module HistoryFinders
+      include Finders
+
+      private
+
+      def first_by_friendly_id(id)
+        joins(:slugs).where(slug_history_clause(id)).readonly(false).first
+      end
+
+      def exists_by_friendly_id?(id)
+        joins(:slugs).where(arel_table[friendly_id_config.query_field].eq(id).or(slug_history_clause(id))).exists?
+      end
+
+      def slug_history_clause(id)
+        Slug.arel_table[:sluggable_type].eq(base_class.to_s).and(Slug.arel_table[:slug].eq(id))
       end
     end