friendly_id4 4.0.0.beta4 → 4.0.0.beta5

data/.yardopts

@@ -0,0 +1,4 @@
+--files=*.md
+--protected
+--list-undoc
+--exclude lib/friendly_id/migration

data/README.md

@@ -1,17 +1,8 @@
-<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).
-
-For the current stable FriendlyId, please see:
-
-[https://github.com/norman/friendly_id](https://github.com/norman/friendly_id_4)
-<hr>
 # FriendlyId
 
 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.
+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.
 
 Using FriendlyId, it's easy to make your application use URL's like:
 
@@ -24,20 +15,10 @@ instead of:
 ## FriendlyId Features
 
 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).
+versioning, scoped slugs, reserved words, and custom slug generators.
 
 FriendlyId is compatible with Active Record **3.0** and **3.1**.
 
-## Docs, Info and Support
-
-* [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)
-
 ## Rails Quickstart
 
     gem install friendly_id
@@ -46,8 +27,10 @@ FriendlyId is compatible with Active Record **3.0** and **3.1**.
 
     cd my_app
 
-    # add to Gemfile
-    gem "friendly_id", "~> 4.0.0"
+    # 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"
+
 
     rails generate scaffold user name:string slug:string
 
@@ -68,6 +51,20 @@ FriendlyId is compatible with Active Record **3.0** and **3.1**.
 
     GET http://localhost:3000/users/joe-schmoe
 
+
+### 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).
+
+
 ## Bugs
 
 Please report them on the [Github issue

data/Rakefile

@@ -45,7 +45,7 @@ task :gem do
 end
 
 task :yard do
-  puts %x{bundle exec yard doc --files=*.md}
+  puts %x{bundle exec yard}
 end
 
 task :bench do

data/friendly_id.gemspec

@@ -1,11 +1,11 @@
 # encoding: utf-8
 $:.push File.expand_path("../lib", __FILE__)
 
-require "friendly_id/version"
+require "friendly_id"
 
 Gem::Specification.new do |s|
   s.name              = "friendly_id4"
-  s.version           = FriendlyId::Version::STRING
+  s.version           = FriendlyId::VERSION
   s.authors           = ["Norman Clarke"]
   s.email             = ["norman@njclarke.com"]
   s.homepage          = "http://norman.github.com/friendly_id"

data/lib/friendly_id.rb

@@ -1,17 +1,94 @@
+# 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"
 
-# FriendlyId is a comprehensive Ruby library for ActiveRecord permalinks and
-# slugs.
-#
-# @author Norman Clarke
+=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
+
+    # with FriendlyId
+    http://example.com/states/washington
+
+It requires few changes to your application code and offers flexibility,
+performance and a well-documented codebase.
+
+=== Concepts
+
+Although FriendlyId helps with URLs, it does all of its work inside your models,
+not your routes.
+
+=== 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
+updated. The most common example of this is a user name:
+
+    class User < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :login
+      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
+
+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:
+
+    class City < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :name
+    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.
+
+=== Slugged Models
+
+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.
+
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :slugged
+    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
+
+In general, use slugs by default unless you know for sure you don't need them.
+
+@author Norman Clarke
+=end
 module FriendlyId
-  autoload :Slugged,  "friendly_id/slugged"
-  autoload :Scoped,   "friendly_id/scoped"
+
+  # The current version.
+  VERSION = "4.0.0.beta5"
+
+  @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
@@ -20,7 +97,7 @@ module FriendlyId
   # 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
+  # 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
@@ -39,7 +116,24 @@ module FriendlyId
     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
     end
     ActiveRecord::Relation.send :include, FriendlyId::FinderMethods
   end
-end
+
+  # Set global defaults for all models using FriendlyId.
+  #
+  # @example
+  #   FriendlyId.defaults do |config|
+  #     config.base = :name
+  #     config.use :slugged
+  #   end
+  def self.defaults(&block)
+    @mutex.synchronize do
+      @defaults = block if block_given?
+    end
+    @defaults
+  end
+end

data/lib/friendly_id/base.rb

@@ -1,31 +1,99 @@
 module FriendlyId
-  # Class methods that will be added to ActiveRecord::Base.
+  # Class methods that will be added to model classes that extend {FriendlyId}.
   module Base
 
-    # Configure FriendlyId for a model. Use this method to configure FriendlyId
-    # for your model.
+    # Configure FriendlyId's behavior in a model.
     #
     #   class Post < ActiveRecord::Base
     #     extend FriendlyId
     #     friendly_id :title, :use => :slugged
     #   end
     #
-    # @option options [Symbol] :use The name of an addon to use. By default, FriendlyId
-    #   provides {FriendlyId::Slugged :slugged}, {FriendlyId::History :history}
-    #   and {FriendlyId::Scoped :scoped}.
+    # When given the optional block, this method will yield the class's instance
+    # of {FriendlyId::Configuration} to the block before evaluating other
+    # arguments, so configuration values set in the block may be overwritten by
+    # the arguments. This order was chosen to allow passing the same proc to
+    # multiple models, while being able to override the values it sets. Here
+    # is a contrived example:
+    #
+    #   $friendly_id_config_proc = Proc.new do |config|
+    #     config.base = :name
+    #     config.use :slugged
+    #   end
+    #
+    #   class Foo < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id &$friendly_id_config_proc
+    #   end
+    #
+    #   class Bar < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :title, &$friendly_id_config_proc
+    #   end
+    #
+    # However, it's usually better to use {FriendlyId.defaults} for this:
+    #
+    #   FriendlyId.defaults do |config|
+    #     config.base = :name
+    #     config.use :slugged
+    #   end
+    #
+    #   class Foo < ActiveRecord::Base
+    #     extend FriendlyId
+    #   end
+    #
+    #   class Bar < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :title
+    #   end
+    #
+    # In general you should use the block syntax either because of your personal
+    # aesthetic preference, or because you need to share some functionality
+    # between multiple models that can't be well encapsulated by
+    # {FriendlyId.defaults}.
+    #
+    # @option options [Symbol] :use The name of an addon to use. By default,
+    #   FriendlyId provides {FriendlyId::Slugged :slugged},
+    #   {FriendlyId::History :history}, {FriendlyId::Reserved :reserved}, and
+    #   {FriendlyId::Scoped :scoped}.
+    #
+    # @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+.
+    #   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+.
+    #   Configures the sequence of characters used to separate a slug from a
+    #   sequence. Defaults to +--+.
+    #
     # @option options [Symbol] :slug_column Available when using +:slugged+.
     #   Configures the name of the column where FriendlyId will store the slug.
     #   Defaults to +:slug+.
+    #
+    # @option options [Symbol] :slug_sequencer_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::SlugSequencer}.
+    #
+    # @yield Provides access to the model class's friendly_id_config, which
+    #   allows an alternate configuration syntax, and conditional configuration
+    #   logic.
+    #
+    # @yieldparam config The model class's {FriendlyId::Configuration friendly_id_config}.
     def friendly_id(base = nil, options = {}, &block)
-      @friendly_id_config.use options.delete :use
-      @friendly_id_config.send :set, options.merge(:base => base)
       yield @friendly_id_config if block_given?
+      @friendly_id_config.use options.delete :use
+      @friendly_id_config.send :set, base ? options.merge(:base => base) : options
       before_save do |record|
         record.instance_eval {@current_friendly_id = friendly_id}
       end
       include Model
     end
 
+    # Returns the model class's {FriendlyId::Configuration friendly_id_config}.
     def friendly_id_config
       @friendly_id_config
     end

data/lib/friendly_id/configuration.rb

@@ -25,39 +25,21 @@ module FriendlyId
     #     extend FriendlyId
     #     friendly_id :name
     #   end
-    attr_reader :base
+    attr_accessor :base
 
-    # The model class that this configuration belongs to.
-    # @return ActiveRecord::Base
-    attr_reader :klass
-
-    # The configuration parameters for the {#klass model class} using FriendlyId.
-    # @return Hash
+    # The default configuration options.
     attr_reader :defaults
 
-    @@defaults = {
-      :reserved_words => ["new", "edit"]
-    }
-
-    # The default configuration parameters for models using FriendlyId.
-    # @return Hash
-    def self.defaults
-      @@defaults
-    end
+    # The model class that this configuration belongs to.
+    # @return ActiveRecord::Base
+    attr_reader :model_class
 
-    def initialize(klass, values = nil)
-      @klass = klass
-      @defaults = self.class.defaults.dup
+    def initialize(model_class, values = nil)
+      @model_class = model_class
+      @defaults    = {}
       set values
     end
 
-    def base=(base)
-      @base = base
-      if @base.respond_to?(:to_s)
-        @klass.validates_exclusion_of @base, :in => defaults[:reserved_words]
-      end
-    end
-
     # Lets you specify the modules to use with FriendlyId.
     #
     # This method is invoked by {FriendlyId::Base#friendly_id friendly_id} when
@@ -74,7 +56,7 @@ module FriendlyId
     #   default FriendlyId provides +:slugged+, +:history+ and +:scoped+.
     def use(*modules)
       modules.to_a.flatten.compact.map do |name|
-        klass.send :include, FriendlyId.const_get(name.to_s.classify)
+        model_class.send :include, FriendlyId.const_get(name.to_s.classify)
       end
     end
 

data/lib/friendly_id/finder_methods.rb

@@ -4,6 +4,14 @@ module FriendlyId
 
     protected
 
+    # FriendlyId overrides this method to make it possible to use friendly id's
+    # identically to numeric ids in finders.
+    #
+    # @example
+    #  person = Person.find(123)
+    #  person = Person.find("joe")
+    #
+    # @see FriendlyId::ObjectUtils
     def find_one(id)
       return super if !@klass.respond_to?(:friendly_id) || id.unfriendly_id?
       where(@klass.friendly_id_config.query_field => id).first or super

data/lib/friendly_id/history.rb

@@ -1,8 +1,40 @@
 require "friendly_id/slug"
 
 module FriendlyId
+
+=begin
+FriendlyId can maintain a history of your record's older slugs, so if your
+record's friendly_id changes, your URL's won't break.
+
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :history
+    end
+
+    class PostsController < ApplicationController
+
+      before_filter :find_post
+
+      ...
+      def find_post
+        return unless params[:id]
+        @post = begin
+          Post.find params[:id]
+        rescue ActiveRecord::RecordNotFound
+          Post.find_by_friendly_id params[:id]
+        end
+        # If an old id or a numeric id was used to find the record, then
+        # the request path will not match the post_path, and we should do
+        # a 301 redirect that uses the current friendly_id
+        if request.path != post_path(@post)
+          return redirect_to @post, :status => :moved_permanently
+        end
+      end
+    end
+=end
   module History
 
+    # Configures the model instance to use the History add-on.
     def self.included(klass)
       klass.instance_eval do
         raise "FriendlyId::History is incompatibe with FriendlyId::Scoped" if self < Scoped
@@ -21,7 +53,10 @@ module FriendlyId
     end
   end
 
+  # Adds a finder that explictly uses slugs from the slug table.
   module Finder
+
+    # Search for a record in the slugs table using the specified slug.
     def find_by_friendly_id(*args)
       with_friendly_id(args.shift).first(*args)
     end