geothird_friendly_id 4.0.9.1

data/lib/friendly_id/slugged.rb

@@ -0,0 +1,329 @@
+# encoding: utf-8
+require "friendly_id/slug_generator"
+
+module FriendlyId
+=begin
+
+== Slugged Models
+
+FriendlyId can use a separate column to store slugs for models which require
+some text processing.
+
+For example, blog applications typically use a post title to provide the basis
+of a search engine friendly URL. Such identifiers typically lack uppercase
+characters, use ASCII to approximate UTF-8 character, and strip out other
+characters which may make them aesthetically unappealing or error-prone when
+used in a URL.
+
+    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.
+To activate the slugging functionality, use the {FriendlyId::Slugged} module.
+
+FriendlyId will generate slugs from a method or column that you specify, and
+store them in a field in your model. By default, this field must be named
++:slug+, though you may change this using the
+{FriendlyId::Slugged::Configuration#slug_column slug_column} configuration
+option. You should add an index to this column, and in most cases, make it
+unique. You may also wish to constrain it to NOT NULL, but this depends on your
+app's behavior and requirements.
+
+=== Example Setup
+
+    # your model
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :slugged
+      validates_presence_of :title, :slug, :body
+    end
+
+    # a migration
+    class CreatePosts < ActiveRecord::Migration
+      def self.up
+        create_table :posts do |t|
+          t.string :title, :null => false
+          t.string :slug, :null => false
+          t.text :body
+        end
+
+        add_index :posts, :slug, :unique => true
+      end
+
+      def self.down
+        drop_table :posts
+      end
+    end
+
+=== Working With Slugs
+
+==== Formatting
+
+By default, FriendlyId uses Active Support's
+paramaterize[http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize]
+method to create slugs. This method will intelligently replace spaces with
+dashes, and Unicode Latin characters with ASCII approximations:
+
+  movie = Movie.create! :title => "Der Preis fürs Überleben"
+  movie.slug #=> "der-preis-furs-uberleben"
+
+==== Uniqueness
+
+When you try to insert a record that would generate a duplicate friendly id,
+FriendlyId will append a sequence to the generated slug to ensure uniqueness:
+
+  car = Car.create :title => "Peugot 206"
+  car2 = Car.create :title => "Peugot 206"
+
+  car.friendly_id #=> "peugot-206"
+  car2.friendly_id #=> "peugot-206--2"
+
+==== Sequence Separator - The Two Dashes
+
+By default, FriendlyId uses two dashes to separate the slug from a sequence.
+
+You can change this with the {FriendlyId::Slugged::Configuration#sequence_separator
+sequence_separator} configuration option.
+
+==== Column or Method?
+
+FriendlyId always uses a method as the basis of the slug text - not a column. It
+first glance, this may sound confusing, but remember that Active Record provides
+methods for each column in a model's associated table, and that's what
+FriendlyId uses.
+
+Here's an example of a class that uses a custom method to generate the slug:
+
+  class Person < ActiveRecord::Base
+    friendly_id :name_and_location
+    def name_and_location
+      "#{name} from #{location}"
+    end
+  end
+
+  bob = Person.create! :name => "Bob Smith", :location => "New York City"
+  bob.friendly_id #=> "bob-smith-from-new-york-city"
+
+==== Providing Your Own Slug Processing Method
+
+You can override {FriendlyId::Slugged#normalize_friendly_id} in your model for
+total control over the slug format.
+
+==== Deciding When to Generate New Slugs
+
+Overriding {FriendlyId::Slugged#should_generate_new_friendly_id?} lets you
+control whether new friendly ids are created when a model is updated. For
+example, if you only want to generate slugs once and then treat them as
+read-only:
+
+  class Post < ActiveRecord::Base
+    extend FriendlyId
+    friendly_id :title, :use => :slugged
+
+    def should_generate_new_friendly_id?
+      new_record?
+    end
+  end
+
+  post = Post.create!(:title => "Hello world!")
+  post.slug #=> "hello-world"
+  post.title = "Hello there, world!"
+  post.save!
+  post.slug #=> "hello-world"
+
+==== Locale-specific Transliterations
+
+Active Support's +parameterize+ uses
+transliterate[http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-transliterate],
+which in turn can use I18n's transliteration rules to consider the current
+locale when replacing Latin characters:
+
+  # config/locales/de.yml
+  de:
+    i18n:
+      transliterate:
+        rule:
+          ü: "ue"
+          ö: "oe"
+          etc...
+
+  movie = Movie.create! :title => "Der Preis fürs Überleben"
+  movie.slug #=> "der-preis-fuers-ueberleben"
+
+This functionality was in fact taken from earlier versions of FriendlyId.
+
+==== Gotchas: Common Problems
+
+===== Slugs That Begin With Numbers
+
+Ruby's `to_i` function casts strings to integers in such a way that +23abc.to_i+
+returns 23. Because FriendlyId falls back to finding by numeric id, this means
+that if you attempt to find a record with a non-existant slug, and that slug
+begins with a number, your find will probably return the wrong record.
+
+There are two fairly simple ways to avoid this:
+
+* Use validations to ensure that slugs don't begin with numbers.
+* Use explicit finders like +find_by_id+ to always find by the numeric id, or
+  +find_by_slug+ to always find using the friendly id.
+
+===== Concurrency Issues
+
+FriendlyId uses a before_validation callback to generate and set the slug. This
+means that if you create two model instances before saving them, it's possible
+they will generate the same slug, and the second save will fail.
+
+This can happen in two fairly normal cases: the first, when a model using nested
+attributes creates more than one record for a model that uses friendly_id. The
+second, in concurrent code, either in threads or multiple processes.
+
+To solve the nested attributes issue, I recommend simply avoiding them when
+creating more than one nested record for a model that uses FriendlyId. See {this
+Github issue}[https://github.com/norman/friendly_id/issues/185] for discussion.
+
+To solve the concurrency issue, I recommend locking the model's table against
+inserts while when saving the record. See {this Github
+issue}[https://github.com/norman/friendly_id/issues/180] for discussion.
+
+=end
+  module Slugged
+
+    # Sets up behavior and configuration options for FriendlyId's slugging
+    # feature.
+    def self.included(model_class)
+      model_class.friendly_id_config.instance_eval do
+        self.class.send :include, Configuration
+        self.slug_generator_class     ||= Class.new(SlugGenerator)
+        defaults[:slug_column]        ||= 'slug'
+        defaults[:sequence_separator] ||= '--'
+      end
+      model_class.before_validation :set_slug
+    end
+
+    # Process the given value to make it suitable for use as a slug.
+    #
+    # This method is not intended to be invoked directly; FriendlyId uses it
+    # internaly to process strings into slugs.
+    #
+    # However, if FriendlyId's default slug generation doesn't suite your needs,
+    # you can override this method in your model class to control exactly how
+    # slugs are generated.
+    #
+    # === Example
+    #
+    #   class Person < ActiveRecord::Base
+    #     friendly_id :name_and_location
+    #
+    #     def name_and_location
+    #       "#{name} from #{location}"
+    #     end
+    #
+    #     # Use default slug, but upper case and with underscores
+    #     def normalize_friendly_id(string)
+    #       super.upcase.gsub("-", "_")
+    #     end
+    #   end
+    #
+    #   bob = Person.create! :name => "Bob Smith", :location => "New York City"
+    #   bob.friendly_id #=> "BOB_SMITH_FROM_NEW_YORK_CITY"
+    #
+    # === More Resources
+    #
+    # You might want to look into Babosa[https://github.com/norman/babosa],
+    # which is the slugging library used by FriendlyId prior to version 4, which
+    # offers some specialized functionality missing from Active Support.
+    #
+    # @param [#to_s] value The value used as the basis of the slug.
+    # @return The candidate slug text, without a sequence.
+    def normalize_friendly_id(value)
+      # Fix to number based slugs which get mistaken as id's
+      value = value.to_s.parameterize
+      is_number = true if Float(value) rescue false
+      if is_number
+        return "#{rand_slug}#{value}"
+      end
+      value
+    end
+
+    # Generate random 10 character string for use in number error situations
+    # Instead of rejecting id/number based slug
+    def rand_slug
+      (0...10).map{ ('a'..'z').to_a[rand(26)] }.join
+    end
+
+    # Whether to generate a new slug.
+    #
+    # You can override this method in your model if, for example, you only want
+    # slugs to be generated once, and then never updated.
+    def should_generate_new_friendly_id?
+      base       = send(friendly_id_config.base)
+      slug_value = send(friendly_id_config.slug_column)
+
+      # If the slug base is nil, and the slug field is nil, then we're going to
+      # leave the slug column NULL.
+      return false if base.nil? && slug_value.nil?
+      # Otherwise, if this is a new record, we're definitely going to try to
+      # create a new slug.
+      return true if new_record?
+      slug_base = normalize_friendly_id(base)
+      separator = Regexp.escape friendly_id_config.sequence_separator
+      # If the slug base (with and without sequence) is different from either the current
+      # friendly id or the slug value, then we'll generate a new friendly_id.
+      compare = (current_friendly_id || slug_value)
+      slug_base != compare && slug_base != compare.try(:sub, /#{separator}[\d]*\z/, '')
+    end
+
+    # Sets the slug.
+    # FIXME: This method sucks and the logic is pretty dubious.
+    def set_slug(normalized_slug = nil)
+      if normalized_slug || should_generate_new_friendly_id?
+        normalized_slug ||= normalize_friendly_id send(friendly_id_config.base)
+        generator = friendly_id_config.slug_generator_class.new self, normalized_slug
+        send "#{friendly_id_config.slug_column}=", generator.generate
+      end
+    end
+    private :set_slug
+
+    # This module adds the +:slug_column+, and +:sequence_separator+, and
+    # +:slug_generator_class+ configuration options to
+    # {FriendlyId::Configuration FriendlyId::Configuration}.
+    module Configuration
+      attr_writer :slug_column, :sequence_separator
+      attr_accessor :slug_generator_class
+
+      # Makes FriendlyId use the slug column for querying.
+      # @return String The slug column.
+      def query_field
+        slug_column
+      end
+
+      # The string used to separate a slug base from a numeric sequence.
+      #
+      # By default, +--+ is used to separate the slug from the sequence.
+      # FriendlyId uses two dashes to distinguish sequences from slugs with
+      # numbers in their name.
+      #
+      # You can change the default separator by setting the
+      # {FriendlyId::Slugged::Configuration#sequence_separator
+      # sequence_separator} configuration option.
+      #
+      # For obvious reasons, you should avoid setting it to "+-+" unless you're
+      # sure you will never want to have a friendly id with a number in it.
+      # @return String The sequence separator string. Defaults to "+--+".
+      def sequence_separator
+        @sequence_separator or defaults[:sequence_separator]
+      end
+
+      # The column that will be used to store the generated slug.
+      def slug_column
+        @slug_column or defaults[:slug_column]
+      end
+    end
+  end
+end

data/lib/friendly_id.rb

@@ -0,0 +1,114 @@
+# encoding: utf-8
+require "thread"
+require "friendly_id/base"
+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
+
+    # with FriendlyId
+    http://example.com/states/washington
+
+It requires few changes to your application code and offers flexibility,
+performance and a well-documented codebase.
+
+=== Core Concepts
+
+==== Slugs
+
+The concept of "slugs[http://en.wikipedia.org/wiki/Slug_(web_publishing)]" 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
+
+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")
+
+=end
+module FriendlyId
+
+  # The current version.
+  VERSION = "4.0.9.1"
+
+  @mutex = Mutex.new
+
+  autoload :History,    "friendly_id/history"
+  autoload :Slug,       "friendly_id/slug"
+  autoload :SimpleI18n, "friendly_id/simple_i18n"
+  autoload :Reserved,   "friendly_id/reserved"
+  autoload :Scoped,     "friendly_id/scoped"
+  autoload :Slugged,    "friendly_id/slugged"
+  autoload :Globalize,  "friendly_id/globalize"
+
+  # 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 have two 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(model_class)
+    return if model_class.respond_to? :friendly_id
+    class << model_class
+      alias relation_without_friendly_id relation
+    end
+    model_class.instance_eval do
+      extend Base
+      @friendly_id_config = Class.new(Configuration).new(self)
+      FriendlyId.defaults.call @friendly_id_config
+    end
+  end
+
+  # Allow developers to `include` FriendlyId or `extend` it.
+  def self.included(model_class)
+    model_class.extend self
+  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

data/lib/generators/friendly_id_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators'
+require "rails/generators/active_record"
+
+# This generator adds a migration for the {FriendlyId::History
+# FriendlyId::History} addon.
+class FriendlyIdGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  extend ActiveRecord::Generators::Migration
+
+  source_root File.expand_path('../../friendly_id', __FILE__)
+
+  # Copies the migration template to db/migrate.
+  def copy_files(*args)
+    migration_template 'migration.rb', 'db/migrate/create_friendly_id_slugs.rb'
+  end
+
+end

data/test/base_test.rb

@@ -0,0 +1,72 @@
+require "helper"
+
+class CoreTest < MiniTest::Unit::TestCase
+  include FriendlyId::Test
+
+  test "friendly_id can be added using 'extend'" do
+    klass = Class.new(ActiveRecord::Base) do
+      extend FriendlyId
+    end
+    assert klass.respond_to? :friendly_id
+  end
+
+  test "friendly_id can be added using 'include'" do
+    klass = Class.new(ActiveRecord::Base) do
+      include FriendlyId
+    end
+    assert klass.respond_to? :friendly_id
+  end
+
+  test "friendly_id should accept a base and a hash" do
+    klass = Class.new(ActiveRecord::Base) do
+      self.abstract_class = true
+      extend FriendlyId
+      friendly_id :foo, :use => :slugged, :slug_column => :bar
+    end
+    assert klass < FriendlyId::Slugged
+    assert_equal :foo, klass.friendly_id_config.base
+    assert_equal :bar, klass.friendly_id_config.slug_column
+  end
+
+
+  test "friendly_id should accept a block" do
+    klass = Class.new(ActiveRecord::Base) do
+      self.abstract_class = true
+      extend FriendlyId
+      friendly_id :foo do |config|
+        config.use :slugged
+        config.base = :foo
+        config.slug_column = :bar
+      end
+    end
+    assert klass < FriendlyId::Slugged
+    assert_equal :foo, klass.friendly_id_config.base
+    assert_equal :bar, klass.friendly_id_config.slug_column
+  end
+
+  test "the block passed to friendly_id should be evaluated before arguments" do
+    klass = Class.new(ActiveRecord::Base) do
+      self.abstract_class = true
+      extend FriendlyId
+      friendly_id :foo do |config|
+        config.base = :bar
+      end
+    end
+    assert_equal :foo, klass.friendly_id_config.base
+  end
+
+  test "should allow defaults to be set via a block" do
+    begin
+      FriendlyId.defaults do |config|
+        config.base = :foo
+      end
+      klass = Class.new(ActiveRecord::Base) do
+        self.abstract_class = true
+        extend FriendlyId
+      end
+      assert_equal :foo, klass.friendly_id_config.base
+    ensure
+      FriendlyId.instance_variable_set :@defaults, nil
+    end
+  end
+end

data/test/compatibility/ancestry/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+
+gem "sqlite3", "~> 1.3.4"
+gem "activerecord", "3.0.10"
+gem "minitest", "~> 2.4.0"
+gem "mocha", "~> 0.9.12"
+gem "ancestry"
+gem "rake"

data/test/compatibility/ancestry/ancestry_test.rb

@@ -0,0 +1,34 @@
+require File.expand_path("../../../helper", __FILE__)
+
+require "ancestry"
+
+ActiveRecord::Migration.create_table("things") do |t|
+  t.string  :name
+  t.string  :slug
+  t.string :ancestry
+end
+ActiveRecord::Migration.add_index :things, :ancestry
+
+class Thing < ActiveRecord::Base
+  extend FriendlyId
+  friendly_id do |config|
+    config.use :slugged
+    config.use :scoped
+    config.base  = :name
+    config.scope = :ancestry
+  end
+  has_ancestry
+end
+
+class AncestryTest < MiniTest::Unit::TestCase
+  include FriendlyId::Test
+
+  test "should sequence slugs when scoped by ancestry" do
+    3.times.inject([]) do |memo, _|
+      memo << Thing.create!(:name => "a", :parent => memo.last)
+    end.each do |thing|
+      assert_equal "a", thing.friendly_id
+    end
+  end
+end
+

data/test/compatibility/threading/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+
+gem "pg"
+gem "mysql2"
+gem "mocha"
+gem "activerecord", "3.1.1"
+gem "sqlite3"
+gem "fatalistic"

data/test/compatibility/threading/Gemfile.lock

@@ -0,0 +1,37 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.1.1)
+      activesupport (= 3.1.1)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activerecord (3.1.1)
+      activemodel (= 3.1.1)
+      activesupport (= 3.1.1)
+      arel (~> 2.2.1)
+      tzinfo (~> 0.3.29)
+    activesupport (3.1.1)
+      multi_json (~> 1.0)
+    arel (2.2.1)
+    builder (3.0.0)
+    fatalistic (0.0.1)
+    i18n (0.6.0)
+    metaclass (0.0.1)
+    mocha (0.10.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.0.3)
+    mysql2 (0.3.11)
+    pg (0.11.0)
+    sqlite3 (1.3.5)
+    tzinfo (0.3.31)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (= 3.1.1)
+  fatalistic
+  mocha
+  mysql2
+  pg
+  sqlite3

data/test/compatibility/threading/threading.rb

@@ -0,0 +1,45 @@
+ENV["DB"] = "postgres"
+
+require "thread"
+require File.expand_path("../../../helper", __FILE__)
+require "active_record/locking/fatalistic"
+
+ActiveRecord::Migration.tap do |m|
+  m.drop_table "things"
+  m.create_table("things") do |t|
+    t.string  :name
+    t.string  :slug
+  end
+  m.add_index :things, :slug, :unique => true
+end
+
+class Thing < ActiveRecord::Base
+  extend FriendlyId
+  friendly_id :name, :use => :slugged
+end
+
+$things = 10.times.map do
+  Thing.new :name => "a b c"
+end
+
+$mutex = Mutex.new
+
+def save_thing
+  thing = $mutex.synchronize do
+    $things.pop
+  end
+  if thing.nil? then return end
+  Thing.lock do
+    thing.save!
+    print "#{thing.friendly_id}\n"
+  end
+  true
+end
+
+2.times.map do
+  Thread.new do
+    while true do
+      break unless save_thing
+    end
+  end
+end.map(&:value)