friendly_id4 4.0.0.pre → 4.0.0.pre3

data/README.md

@@ -1,74 +1,92 @@
-# FriendlyId 4
+<hr>
+**NOTE** This is FriendlyId4 - a rewrite of FriendlyId. For more info about this
+rewrite, and the changes it brings, read [this
+document](https://github.com/norman/friendly_id_4/blob/master/ABOUT.md).
 
-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.
+For the current stable FriendlyId, please see:
 
-Please don't use this yet for anything real but feel free to try it and give
-your feedback via the issues tracker.
+[https://github.com/norman/friendly_id](https://github.com/norman/friendly_id_4)
+<hr>
+# FriendlyId
 
-## Back to basics
+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 isn't the "big rewrite," it's the "small rewrite."
+Using FriendlyId, it's easy to make your application use URL's like:
 
-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.
+    http://example.com/states/washington
 
-Let's see how small we can make this!
+instead of:
 
-Here's what's changed:
+    http://example.com/states/4323454
 
-## Active Record 3+ only
+## FriendlyId Features
 
-For 2.3 support, you can use FriendlyId 3, which will continue to be maintained
-until people don't want it any more.
+FriendlyId offers many advanced features, including: slug history and
+versioning, scoped slugs, reserved words, custom slug generators, and
+excellent Unicode support. For complete information on using FriendlyId,
+please see the [FriendlyId Guide](http://norman.github.com/friendly_id/file.Guide.html).
 
-## Remove Babosa
+FriendlyId is compatible with Active Record **3.0** and **3.1**.
 
-Babosa is FriendlyId 3's slugging library.
+## Docs, Info and Support
 
-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.
+* [FriendlyId Guide](http://norman.github.com/friendly_id/file.Guide.html)
+* [API Docs](http://norman.github.com/friendly_id)
+* [Google Group](http://groups.google.com/group/friendly_id)
+* [Source Code](http://github.com/norman/friendly_id/)
+* [Issue Tracker](http://github.com/norman/friendly_id/issues)
 
-## In-table slugs
+## Rails Quickstart
 
-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).
+    gem install friendly_id
 
-## No more finder status
+    rails new my_app
 
-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:
+    cd my_app
 
-    if request.path != person_path(@person)
-      return redirect_to @person, :status => :moved_permanently
+    # add to Gemfile
+    gem "friendly_id", "~> 4.0.0"
+
+    rails generate scaffold user name:string slug:string
+
+    # edit db/migrate/*_create_users.rb
+    add_index :users, :slug, :unique => true
+
+    rake db:migrate
+
+    # edit app/models/user.rb
+    class User < ActiveRecord::Base
+      include FriendlyId::Slugged
+      has_friendly_id :name
     end
 
-## No more multiple finds
+    User.create! :name => "Joe Schmoe"
+
+    rails server
+
+    GET http://localhost:3000/users/joe-schmoe
 
-    Person.find "joe-schmoe"               # Supported
-    Person.find ["joe-schmoe", "john-doe"] # No longer supported
+## Bugs
 
-If you want find by more than one friendly id, build your own query:
+Please report them on the [Github issue tracker](http://github.com/norman/friendly_id/issues)
+for this project.
 
-    Person.where(:slug => ["joe-schmoe", "john-doe"])
+If you have a bug to report, please include the following information:
 
-This lets us do *far* less monkeypatching in Active Record.
+* **Version information for FriendlyId, Rails and Ruby.**
+* Stack trace and error message.
+* Any snippets of relevant model, view or controller code that shows how your
+  are using FriendlyId.
 
-## No more reserved words
+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.
 
-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.
+## Credits
 
-    validates_exclusion_of :name, :in => ["bad", "word"]
+FriendlyId was created by Norman Clarke, Adrian Mugnolo, and Emilio Tagua, and
+has had significant contributions over the years from [many
+volunteers](https://github.com/norman/friendly_id/contributors).
 
-You can configure the default words reserved by FriendlyId in
-`FriendlyId::Configuration::DEFAULTS[:reserved_words]`.
+Copyright (c) 2008-2011 Norman Clarke, released under the MIT license.

data/Rakefile

@@ -1,24 +1,20 @@
-require "rake"
-require "rake/testtask"
-require "rake/gempackagetask"
-require "rake/clean"
+require "cutest"
 
 task :default => :test
+task :test do
+  Cutest.run(Dir["test/*_test.rb"])
+end
 
-CLEAN << "pkg" << "doc" << "coverage" << ".yardoc"
-
-Rake::TestTask.new(:test) { |t| t.pattern = "test/**/*test.rb" }
+task :clean do
+  %x{rm -rf *.gem doc}
+end
 
-begin
-  require 'reek/rake/task'
-  Reek::Rake::Task.new do |t|
-    t.fail_on_error = false
-  end
-rescue LoadError
+task :gem do
+  %x{gem build friendly_id.gemspec}
 end
 
-gemspec = File.expand_path("../friendly_id.gemspec", __FILE__)
-if File.exists? gemspec
-  Rake::GemPackageTask.new(eval(File.read("friendly_id.gemspec"))) { |pkg| }
+task :yard do
+  %x{yard doc}
 end
 
+task :doc => :yard

data/bench.rb

@@ -0,0 +1,71 @@
+require File.expand_path("../test/helper", __FILE__)
+require "ffaker"
+require "friendly_id/migration"
+
+N = 1000
+
+migration do |m|
+  m.add_column :users, :slug, :string
+  m.add_index  :users, :slug, :unique => true
+end
+
+migration do |m|
+  m.create_table :posts do |t|
+    t.string :name
+    t.string :slug
+  end
+  m.add_index  :posts, :slug, :unique => true
+end
+CreateFriendlyIdSlugs.up
+
+
+class Array
+  def rand
+    self[Kernel.rand(length)]
+  end
+end
+
+class User
+  include FriendlyId::Slugged
+  has_friendly_id :name
+end
+
+class Post < ActiveRecord::Base
+  include FriendlyId::History
+  has_friendly_id :name
+end
+
+USERS = []
+BOOKS = []
+POSTS = []
+
+100.times do
+  name = Faker::Name.name
+  USERS << (User.create! :name => name).friendly_id
+  POSTS << (Post.create! :name => name).friendly_id
+  BOOKS << (Book.create! :name => name).id
+end
+
+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 {User.find USERS.rand}
+  end
+  x.report 'find (external slug)' do
+    N.times {Post.find_by_friendly_id POSTS.rand}
+  end
+
+  x.report 'insert (without FriendlyId)' do
+    N.times {transaction {Book.create :name => Faker::Name.name}}
+  end
+
+  x.report 'insert (in-table-slug)' do
+    N.times {transaction {User.create :name => Faker::Name.name}}
+  end
+
+  x.report 'insert (external slug)' do
+    N.times {transaction {Post.create :name => Faker::Name.name}}
+  end
+end

data/friendly_id.gemspec

@@ -0,0 +1,29 @@
+# encoding: utf-8
+$:.push File.expand_path("../lib", __FILE__)
+
+require "friendly_id/version"
+
+Gem::Specification.new do |s|
+  s.name              = "friendly_id4"
+  s.version           = FriendlyId::Version::STRING
+  s.authors           = ["Norman Clarke"]
+  s.email             = ["norman@njclarke.com"]
+  s.homepage          = "http://norman.github.com/friendly_id"
+  s.summary           = "A comprehensive slugging and pretty-URL plugin."
+  s.rubyforge_project = "friendly_id"
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files -- {test}/*`.split("\n")
+  s.require_paths     = ["lib"]
+
+  s.add_development_dependency "activerecord", "~> 3.0"
+  s.add_development_dependency "sqlite3", "~> 1.3"
+  s.add_development_dependency "cutest", "~> 1.1.2"
+  s.add_development_dependency "ffaker"
+  s.add_development_dependency "yard"
+
+  s.description       = <<-EOM
+    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 ActiveRecord models.
+  EOM
+end

data/lib/friendly_id.rb

@@ -1,121 +1,14 @@
+require "friendly_id/base"
+require "friendly_id/model"
+require "friendly_id/object_utils"
+require "friendly_id/configuration"
+require "friendly_id/finder_methods"
+
 # FriendlyId is a comprehensive Ruby library for ActiveRecord permalinks and
 # slugs.
 # @author Norman Clarke
 module FriendlyId
-
-  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
-
-    def friendly_id_config
-      @friendly_id_config ||= Configuration.new(self)
-    end
-
-    def uses_friendly_id?
-      !! @friendly_id_config
-    end
-  end
-
-  # Instance methods that will be added to all classes using FriendlyId.
-  module Model
-
-    # Convenience method for accessing the class method of the same name.
-    def friendly_id_config
-      self.class.friendly_id_config
-    end
-
-    # Get the instance's friendly_id.
-    def friendly_id
-      send friendly_id_config.query_field
-    end
-
-    # Either the friendly_id, or the numeric id cast to a string.
-    def to_param
-      (friendly_id or id).to_s
-    end
-  end
-
-  # The configuration paramters passed to +has_friendly_id+ will be stored
-  # in this object.
-  class Configuration
-    attr_accessor :base
-    attr_reader   :klass
-
-    DEFAULTS = {
-      :config_error_message => 'FriendlyId has no such config option "%s"',
-      :reserved_words       => ["new", "edit"]
-    }
-
-    def initialize(klass, values = nil)
-      @klass = klass
-      set values
-    end
-
-    def method_missing(symbol, *args, &block)
-      option = symbol.to_s.gsub(/=\z/, '')
-      raise ArgumentError, DEFAULTS[:config_error_message] % option
-    end
-
-    def set(values)
-      values and values.each {|name, value| self.send "#{name}=", value}
-    end
-
-    def query_field
-      base
-    end
-  end
-
-  # 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
-
-    # 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
-
-  # These methods will override the finder methods in ActiveRecord::Relation.
-  module FinderMethods
-
-    protected
-
-    # @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
-
-  end
+  autoload :Slugged,  "friendly_id/slugged"
+  autoload :Scoped,   "friendly_id/scoped"
+  autoload :History,  "friendly_id/history"
 end
-
-ActiveRecord::Base.extend FriendlyId::Base
-ActiveRecord::Relation.send :include, FriendlyId::FinderMethods
-Object.send :include, FriendlyId::ObjectUtils

data/lib/friendly_id/base.rb

@@ -0,0 +1,29 @@
+module FriendlyId
+  # 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
+      self
+    end
+
+    def friendly_id_config
+      @friendly_id_config ||= Configuration.new(self)
+    end
+
+    def uses_friendly_id?
+      defined? @friendly_id_config
+    end
+  end
+end
+
+ActiveRecord::Base.extend FriendlyId::Base

data/lib/friendly_id/configuration.rb

@@ -0,0 +1,31 @@
+module FriendlyId
+  # The configuration paramters passed to +has_friendly_id+ will be stored
+  # in this object.
+  class Configuration
+    attr_accessor :base
+    attr_reader   :klass
+
+    DEFAULTS = {
+      :config_error_message => 'FriendlyId has no such config option "%s"',
+      :reserved_words       => ["new", "edit"]
+    }
+
+    def initialize(klass, values = nil)
+      @klass = klass
+      set values
+    end
+
+    def method_missing(symbol, *args, &block)
+      option = symbol.to_s.gsub(/=\z/, '')
+      raise ArgumentError, DEFAULTS[:config_error_message] % option
+    end
+
+    def set(values)
+      values and values.each {|name, value| self.send "#{name}=", value}
+    end
+
+    def query_field
+      base
+    end
+  end
+end