friendly_id4 4.0.0.beta6 → 4.0.0.pre

data/README.md

@@ -1,95 +1,74 @@
-# FriendlyId
+# FriendlyId 4
 
-FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for
-Ruby on Rails. It allows you to create pretty URL's and work with human-friendly
-strings as if they were numeric ids for Active Record models.
+This is an in-progress rethink of the FriendlyId plugin. It will probably be
+released some time in August or September 2011, once I've had the chance to
+actually use it in a real website for a while.
 
-Using FriendlyId, it's easy to make your application use URL's like:
+Please don't use this yet for anything real but feel free to try it and give
+your feedback via the issues tracker.
 
-    http://example.com/states/washington
+## Back to basics
 
-instead of:
+This isn't the "big rewrite," it's the "small rewrite."
 
-    http://example.com/states/4323454
+Adding new features with each release is not sustainable. This release *removes*
+features, but makes it possible to add them back as addons. We can also remove
+some complexity by relying on the better default functionality provided by newer
+versions of Active Support and Active Record.
 
+Let's see how small we can make this!
 
-## FriendlyId Features
+Here's what's changed:
 
-FriendlyId offers many advanced features, including: slug history and
-versioning, scoped slugs, reserved words, and custom slug generators.
+## Active Record 3+ only
 
-FriendlyId is compatible with Active Record **3.0** and **3.1**.
+For 2.3 support, you can use FriendlyId 3, which will continue to be maintained
+until people don't want it any more.
 
-## Rails Quickstart
+## Remove Babosa
 
-    gem install friendly_id
+Babosa is FriendlyId 3's slugging library.
 
-    rails new my_app
+FriendlyId 4 doesn't use it by default any more because the most important
+pieces of it were already accepted into Active Support 3. You can still just
+override `#normalize_friendly_id` in your model if you want to use Babosa.
 
-    cd my_app
+## In-table slugs
 
-    # Add to Gemfile - this will change once version 4 is no longer
-    # in beta, but for now do this:
-    gem "friendly_id4", "4.0.0.beta4", :require => "friendly_id"
+FriendlyId no longer creates a separate slugs table - it just stores the
+generated slug value in the model table, which is simpler, faster and what most
+people seem to want. Keeping slugs in a separate table is an optional add-on for
+FriendlyId 4 (not implemented yet).
 
+## No more finder status
 
-    rails generate scaffold user name:string slug:string
+FriendlyId 3 offered finder statuses to help you determine when an outdated
+or non-friendly id was used to find the record, so that you could decide whether
+to permanently redirect to the canonical URL. However, there's a simpler way to
+do that, so this feature has been removed:
 
-    # edit db/migrate/*_create_users.rb
-    add_index :users, :slug, :unique => true
-
-    rake db:migrate
-
-    # edit app/models/user.rb
-    class User < ActiveRecord::Base
-      extend FriendlyId
-      friendly_id :name, :use => :slugged
+    if request.path != person_path(@person)
+      return redirect_to @person, :status => :moved_permanently
     end
 
-    User.create! :name => "Joe Schmoe"
-
-    rails server
-
-    GET http://localhost:3000/users/joe-schmoe
-
-## Docs
-
-The current docs can be found
-[here](http://rdoc.info/github/norman/friendly_id/a4128af31d85ee29ad8f/frames).
-
-## Future Compatibility
-
-FriendlyId will always remain compatible with the current release of Rails, and
-at least one stable release behind. That means that support for 3.0.x will not be
-dropped until a stable release of 3.2 is out, or possibly longer.
-
-
-## Benchmarks
-
-The latest benchmarks for FriendlyId are maintained
-[here](https://gist.github.com/1129745).
-
+## No more multiple finds
 
-## Bugs
+    Person.find "joe-schmoe"               # Supported
+    Person.find ["joe-schmoe", "john-doe"] # No longer supported
 
-Please report them on the [Github issue
-tracker](http://github.com/norman/friendly_id/issues) for this project.
+If you want find by more than one friendly id, build your own query:
 
-If you have a bug to report, please include the following information:
+    Person.where(:slug => ["joe-schmoe", "john-doe"])
 
-* **Version information for FriendlyId, Rails and Ruby.**
-* Stack trace and error message.
- * Any snippets of relevant model, view or controller code that shows how you
-  are using FriendlyId.
+This lets us do *far* less monkeypatching in Active Record.
 
-If you are able to, it helps even more if you can fork FriendlyId on Github,
-and add a test that reproduces the error you are experiencing.
+## No more reserved words
 
-## Credits
+Rather than use a custom reserved words validator, use the validations provided
+by Active Record. FriendlyId still reserves "new" and "edit" by default to avoid
+routing problems.
 
-FriendlyId was originally created by Norman Clarke and Adrian Mugnolo, with
-significant help early in its life by Emilio Tagua. I'm deeply gratful for the
-generous contributions over the years from [many
-volunteers](https://github.com/norman/friendly_id/contributors).
+    validates_exclusion_of :name, :in => ["bad", "word"]
 
-Copyright (c) 2008-2011 Norman Clarke, released under the MIT license.
+You can configure the default words reserved by FriendlyId in
+`FriendlyId::Configuration::DEFAULTS[:reserved_words]`.

data/Rakefile

@@ -1,119 +1,24 @@
-require "rubygems"
+require "rake"
 require "rake/testtask"
-
-def rubies(&block)
-  ["ruby-1.9.2-p180", "ree-1.8.7-2011.03", "jruby-1.6.2", "rbx-2.0.0pre"].each do |ruby|
-    old = ENV["RB"]
-    ENV["RB"] = ruby
-    yield
-    ENV["RB"] = old
-  end
-end
-
-def versions(&block)
-  ["3.1.0.rc5", "3.0.9"].each do |version|
-    old = ENV["AR"]
-    ENV["AR"] = version
-    yield
-    ENV["AR"] = old
-  end
-end
-
-def adapters(&block)
-  ["mysql", "mysql2", "postgres", "sqlite3"].each do |adapter|
-    old = ENV["DB"]
-    ENV["DB"] = adapter
-    ENV["DB_VERSION"] = "~> 0.3.6" if adapter == "mysql2" && ENV["AR"] && ENV["AR"][0..2] >= "3.1"
-    yield
-    ENV["DB"] = old
-  end
-end
+require "rake/gempackagetask"
+require "rake/clean"
 
 task :default => :test
 
-Rake::TestTask.new do |t|
-  t.test_files = FileList['test/*_test.rb']
-  t.verbose = true
-end
-
-task :clean do
-  %x{rm -rf *.gem doc pkg coverage}
-  %x{rm -f `find . -name '*.rbc'`}
-end
-
-task :gem do
-  %x{gem build friendly_id.gemspec}
-end
-
-task :yard do
-  puts %x{bundle exec yard}
-end
-
-task :bench do
-  require File.expand_path("../bench", __FILE__)
-end
-
-desc "Bundle for all supported Ruby/AR versions"
-task :bundle do
-  rubies do
-    versions do
-      command = "#{ENV["RB"]} -S bundle"
-      puts "#{command} (with #{ENV['AR']})"
-      `#{command}`
-    end
-  end
-end
-
-namespace :test do
-
-  desc "Test with all configured adapters"
-  task :adapters do
-    adapters {|a| puts %x{rake test}}
-  end
-
-  desc "Test with all configured Rubies"
-  task :rubies do
-    rubies {|r| puts %x{rake-#{ENV["RB"]} test}}
-  end
-
-  desc "Test with all configured versions"
-  task :versions do
-    versions {|v| puts %x{rake test}}
-  end
+CLEAN << "pkg" << "doc" << "coverage" << ".yardoc"
 
-  desc "Test all rubies, versions and adapters"
-  task :prerelease do
-    rubies do
-      versions do
-        adapters do
-          puts %x{rake test}
-        end
-      end
-    end
-  end
+Rake::TestTask.new(:test) { |t| t.pattern = "test/**/*test.rb" }
 
-  desc "Run each test class in a separate process"
-  task :isolated do
-    dir = File.expand_path("../test", __FILE__)
-    Dir["#{dir}/*_test.rb"].each do |test|
-      puts "Running #{test}:"
-      puts %x{ruby #{test}}
-    end
+begin
+  require 'reek/rake/task'
+  Reek::Rake::Task.new do |t|
+    t.fail_on_error = false
   end
+rescue LoadError
 end
 
-namespace :db do
-  desc "Set up the database schema"
-  task :up do
-    require File.expand_path("../test/helper", __FILE__)
-    FriendlyId::Test::Schema.up
-  end
-
-  desc "Destroy the database schema"
-  task :down do
-    require File.expand_path("../test/helper", __FILE__)
-    FriendlyId::Test::Schema.down
-  end
+gemspec = File.expand_path("../friendly_id.gemspec", __FILE__)
+if File.exists? gemspec
+  Rake::GemPackageTask.new(eval(File.read("friendly_id.gemspec"))) { |pkg| }
 end
 
-task :doc => :yard

data/lib/friendly_id.rb

@@ -1,141 +1,121 @@
-# encoding: utf-8
-require "thread"
-require "friendly_id/base"
-require "friendly_id/model"
-require "friendly_id/object_utils"
-require "friendly_id/configuration"
-require "friendly_id/finder_methods"
-
-=begin
-
-== About FriendlyId
-
-FriendlyId is an add-on to Ruby's Active Record that allows you to replace ids
-in your URLs with strings:
-
-    # without FriendlyId
-    http://example.com/states/4323454
+# FriendlyId is a comprehensive Ruby library for ActiveRecord permalinks and
+# slugs.
+# @author Norman Clarke
+module FriendlyId
 
-    # with FriendlyId
-    http://example.com/states/washington
+  autoload :Slugged, "friendly_id/slugged"
+  autoload :Scoped,  "friendly_id/scoped"
+
+  # Class methods that will be added to ActiveRecord::Base.
+  module Base
+    extend self
+
+    def has_friendly_id(*args)
+      options = args.extract_options!
+      base = args.shift
+      friendly_id_config.set options.merge(:base => base)
+      include Model
+      # @NOTE: AR-specific code here
+      validates_exclusion_of base, :in => Configuration::DEFAULTS[:reserved_words]
+      before_save do |record|
+        record.instance_eval {@_current_friendly_id = friendly_id}
+      end
+    end
 
-It requires few changes to your application code and offers flexibility,
-performance and a well-documented codebase.
+    def friendly_id_config
+      @friendly_id_config ||= Configuration.new(self)
+    end
 
-=== Concepts
+    def uses_friendly_id?
+      !! @friendly_id_config
+    end
+  end
 
-Although FriendlyId helps with URLs, it does all of its work inside your models,
-not your routes.
+  # Instance methods that will be added to all classes using FriendlyId.
+  module Model
 
-=== Simple Models
+    # Convenience method for accessing the class method of the same name.
+    def friendly_id_config
+      self.class.friendly_id_config
+    end
 
-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
-updated. The most common example of this is a user name:
+    # Get the instance's friendly_id.
+    def friendly_id
+      send friendly_id_config.query_field
+    end
 
-    class User < ActiveRecord::Base
-      extend FriendlyId
-      friendly_id :login
-      validates_format_of :login, :with => /\A[a-z0-9]+\z/i
+    # Either the friendly_id, or the numeric id cast to a string.
+    def to_param
+      (friendly_id or id).to_s
     end
+  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
+  # The configuration paramters passed to +has_friendly_id+ will be stored
+  # in this object.
+  class Configuration
+    attr_accessor :base
+    attr_reader   :klass
 
-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
-value is admissible in a URL:
+    DEFAULTS = {
+      :config_error_message => 'FriendlyId has no such config option "%s"',
+      :reserved_words       => ["new", "edit"]
+    }
 
-    class City < ActiveRecord::Base
-      extend FriendlyId
-      friendly_id :name
+    def initialize(klass, values = nil)
+      @klass = klass
+      set values
     end
 
-    @city.find "Viña del Mar"
-    redirect_to @city # the URL will be /cities/Viña%20del%20Mar
-
-For this reason, it is often more convenient to use "slugs" rather than a single
-column.
+    def method_missing(symbol, *args, &block)
+      option = symbol.to_s.gsub(/=\z/, '')
+      raise ArgumentError, DEFAULTS[:config_error_message] % option
+    end
 
-=== Slugged Models
+    def set(values)
+      values and values.each {|name, value| self.send "#{name}=", value}
+    end
 
-FriendlyId can uses a separate column to store slugs for models which require
-some processing of the friendly_id text. The most common example is a blog
-post's title, which may have spaces, uppercase characters, or other attributes
-you wish to modify to make them more suitable for use in URL's.
+    def query_field
+      base
+    end
+  end
 
-    class Post < ActiveRecord::Base
-      extend FriendlyId
-      friendly_id :title, :use => :slugged
+  # Utility methods that are in Object because it's impossible to predict what
+  # kinds of objects get passed into FinderMethods#find_one and
+  # Model#normalize_friendly_id.
+  module ObjectUtils
+
+    # True is the id is definitely friendly, false if definitely unfriendly,
+    # else nil.
+    def friendly_id?
+      if kind_of?(Integer) or kind_of?(Symbol) or self.class.respond_to? :friendly_id_config
+        false
+      elsif to_i.to_s != to_s
+        true
+      end
     end
 
-    @post = Post.create(:title => "This is the first post!")
-    @post.friendly_id   # returns "this-is-the-first-post"
-    redirect_to @post   # the URL will be /posts/this-is-the-first-post
+    # True if the id is definitely unfriendly, false if definitely friendly,
+    # else nil.
+    def unfriendly_id?
+      val = friendly_id? ; !val unless val.nil?
+    end
+  end
 
-In general, use slugs by default unless you know for sure you don't need them.
+  # These methods will override the finder methods in ActiveRecord::Relation.
+  module FinderMethods
 
-@author Norman Clarke
-=end
-module FriendlyId
+    protected
 
-  # The current version.
-  VERSION = "4.0.0.beta6"
-
-  @mutex = Mutex.new
-
-  autoload :History,  "friendly_id/history"
-  autoload :Reserved, "friendly_id/reserved"
-  autoload :Scoped,   "friendly_id/scoped"
-  autoload :Slugged,  "friendly_id/slugged"
-
-  # FriendlyId takes advantage of `extended` to do basic model setup, primarily
-  # extending {FriendlyId::Base} to add {FriendlyId::Base#friendly_id
-  # friendly_id} as a class method.
-  #
-  # Previous versions of FriendlyId simply patched ActiveRecord::Base, but this
-  # version tries to be less invasive.
-  #
-  # In addition to adding {FriendlyId::Base#friendly_id friendly_id}, the class
-  # instance variable +@friendly_id_config+ is added. This variable is an
-  # instance of an anonymous subclass of {FriendlyId::Configuration}. This
-  # allows subsequently loaded modules like {FriendlyId::Slugged} and
-  # {FriendlyId::Scoped} to add functionality to the configuration class only
-  # for the current class, rather than monkey patching
-  # {FriendlyId::Configuration} directly. This isolates other models from large
-  # feature changes an addon to FriendlyId could potentially introduce.
-  #
-  # The upshot of this is, you can htwo Active Record models that both have a
-  # @friendly_id_config, but each config object can have different methods and
-  # behaviors depending on what modules have been loaded, without conflicts.
-  # Keep this in mind if you're hacking on FriendlyId.
-  #
-  # For examples of this, see the source for {Scoped.included}.
-  def self.extended(base)
-    base.instance_eval do
-      extend FriendlyId::Base
-      @friendly_id_config = Class.new(FriendlyId::Configuration).new(base)
-      if defaults = FriendlyId.defaults
-        defaults.yield @friendly_id_config
-      end
+    # @NOTE AR-specific code here
+    def find_one(id)
+      return super if !@klass.uses_friendly_id? or id.unfriendly_id?
+      where(@klass.friendly_id_config.query_field => id).first or super
     end
-    ActiveRecord::Relation.send :include, FriendlyId::FinderMethods
-  end
 
-  # Set global defaults for all models using FriendlyId.
-  #
-  # The default defaults are to use the +:reserved+ module and nothing else.
-  #
-  # @example
-  #   FriendlyId.defaults do |config|
-  #     config.base = :name
-  #     config.use :slugged
-  #   end
-  def self.defaults(&block)
-    @mutex.synchronize do
-      @defaults = block if block_given?
-      @defaults ||= lambda {|config| config.use :reserved}
-    end
   end
-end
+end
+
+ActiveRecord::Base.extend FriendlyId::Base
+ActiveRecord::Relation.send :include, FriendlyId::FinderMethods
+Object.send :include, FriendlyId::ObjectUtils