friendly_id 5.4.1 → 5.5.1

data/gemfiles/Gemfile.rails-6.1.rb

@@ -0,0 +1,22 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activerecord", "~> 6.1.4"
+gem "railties", "~> 6.1.4"
+
+# Database Configuration
+group :development, :test do
+  platforms :jruby do
+    gem "activerecord-jdbcmysql-adapter", "~> 61.0"
+    gem "activerecord-jdbcpostgresql-adapter", "~> 61.0"
+    gem "kramdown"
+  end
+
+  platforms :ruby, :rbx do
+    gem "sqlite3"
+    gem "mysql2"
+    gem "pg"
+    gem "redcarpet"
+  end
+end

data/gemfiles/Gemfile.rails-7.0.rb

@@ -0,0 +1,22 @@
+source "https://rubygems.org"
+
+gemspec path: "../"
+
+gem "activerecord", "~> 7.0.0"
+gem "railties", "~> 7.0.0"
+
+# Database Configuration
+group :development, :test do
+  platforms :jruby do
+    gem "activerecord-jdbcmysql-adapter", "~> 61.0"
+    gem "activerecord-jdbcpostgresql-adapter", "~> 61.0"
+    gem "kramdown"
+  end
+
+  platforms :ruby, :rbx do
+    gem "sqlite3"
+    gem "mysql2"
+    gem "pg"
+    gem "redcarpet"
+  end
+end

data/guide.rb

@@ -3,14 +3,21 @@
 # This script generates the Guide.md file included in the Yard docs.
 
 def comments_from path
-  path  = File.expand_path("../lib/friendly_id/#{path}", __FILE__)
-  match = File.read(path).match(/\n=begin(.*)\n=end/m)[1].to_s
-  match.split("\n").reject {|x| x =~ /^@/}.join("\n").strip
+  path = File.expand_path("../lib/friendly_id/#{path}", __FILE__)
+  matches = File.read(path).match(/\n\s*# @guide begin\n(.*)\s*# @guide end/m)
+
+  return if matches.nil?
+
+  match = matches[1].to_s
+  match.split("\n")
+    .map { |x| x.sub(/^\s*#\s?/, "") } # Strip off the comment, leading whitespace, and the space after the comment
+    .reject { |x| x =~ /^@/ }         # Ignore yarddoc tags for the guide
+    .join("\n").strip
 end
 
-File.open(File.expand_path('../Guide.md', __FILE__), 'w:utf-8') do |guide|
-  ['../friendly_id.rb', 'base.rb', 'finders.rb', 'slugged.rb', 'history.rb',
-  'scoped.rb', 'simple_i18n.rb', 'reserved.rb'].each do |file|
+File.open(File.expand_path("../Guide.md", __FILE__), "w:utf-8") do |guide|
+  ["../friendly_id.rb", "base.rb", "finders.rb", "slugged.rb", "history.rb",
+    "scoped.rb", "simple_i18n.rb", "reserved.rb"].each do |file|
     guide.write comments_from file
     guide.write "\n"
   end

data/lib/friendly_id/base.rb

@@ -1,62 +1,61 @@
 module FriendlyId
-=begin
-
-## 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
-{FriendlyId::Base#friendly_id friendly_id} method to configure your desired
-options:
-
-    class Foo < ActiveRecord::Base
-      include FriendlyId
-      friendly_id :bar, :use => [:slugged, :simple_i18n]
-    end
-
-The most important option is `:use`, which you use to tell FriendlyId which
-addons it should use. See the documentation for {FriendlyId::Base#friendly_id} for a list of all
-available addons, or skim through the rest of the docs to get a high-level
-overview.
-
-*A note about single table inheritance (STI): you must extend FriendlyId in
-all classes that participate in STI, both your parent classes and their
-children.*
-
-### 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
-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.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
-value is unique and admissible in a URL:
-
-    class City < ActiveRecord::Base
-      extend FriendlyId
-      friendly_id :name
-    end
-
-    @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
-in a URL can be repetitive and surprisingly tricky, so for this reason it's
-often better and easier to use {FriendlyId::Slugged slugs}.
-
-=end
+  # @guide begin
+  #
+  # ## 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
+  # {FriendlyId::Base#friendly_id friendly_id} method to configure your desired
+  # options:
+  #
+  #     class Foo < ActiveRecord::Base
+  #       include FriendlyId
+  #       friendly_id :bar, :use => [:slugged, :simple_i18n]
+  #     end
+  #
+  # The most important option is `:use`, which you use to tell FriendlyId which
+  # addons it should use. See the documentation for {FriendlyId::Base#friendly_id} for a list of all
+  # available addons, or skim through the rest of the docs to get a high-level
+  # overview.
+  #
+  # *A note about single table inheritance (STI): you must extend FriendlyId in
+  # all classes that participate in STI, both your parent classes and their
+  # children.*
+  #
+  # ### 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
+  # 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.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
+  # value is unique and admissible in a URL:
+  #
+  #     class City < ActiveRecord::Base
+  #       extend FriendlyId
+  #       friendly_id :name
+  #     end
+  #
+  #     @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
+  # in a URL can be repetitive and surprisingly tricky, so for this reason it's
+  # often better and easier to use {FriendlyId::Slugged slugs}.
+  #
+  # @guide end
   module Base
-
     # Configure FriendlyId's behavior in a model.
     #
     #     class Post < ActiveRecord::Base
@@ -205,10 +204,10 @@ often better and easier to use {FriendlyId::Slugged slugs}.
     #
     # @yieldparam config The model class's {FriendlyId::Configuration friendly_id_config}.
     def friendly_id(base = nil, options = {}, &block)
-      yield friendly_id_config if block_given?
+      yield friendly_id_config if block
       friendly_id_config.dependent = options.delete :dependent
       friendly_id_config.use options.delete :use
-      friendly_id_config.send :set, base ? options.merge(:base => base) : options
+      friendly_id_config.send :set, base ? options.merge(base: base) : options
       include Model
     end
 
@@ -270,7 +269,7 @@ often better and easier to use {FriendlyId::Slugged slugs}.
 
     # Clears slug on duplicate records when calling `dup`.
     def dup
-      super.tap { |duplicate| duplicate.slug = nil if duplicate.respond_to?('slug=') }
+      super.tap { |duplicate| duplicate.slug = nil if duplicate.respond_to?("slug=") }
     end
   end
 end

data/lib/friendly_id/candidates.rb

@@ -1,11 +1,9 @@
-require 'securerandom'
+require "securerandom"
 
 module FriendlyId
-
   # This class provides the slug candidate functionality.
   # @see FriendlyId::Slugged
   class Candidates
-
     include Enumerable
 
     def initialize(object, *array)
@@ -14,8 +12,8 @@ module FriendlyId
     end
 
     def each(*args, &block)
-      return candidates unless block_given?
-      candidates.each{ |candidate| yield candidate }
+      return candidates unless block
+      candidates.each { |candidate| yield candidate }
     end
 
     private
@@ -29,13 +27,13 @@ module FriendlyId
 
     def normalize(candidates)
       candidates.map do |candidate|
-        @object.normalize_friendly_id(candidate.map(&:call).join(' '))
-      end.select {|x| wanted?(x)}
+        @object.normalize_friendly_id(candidate.map(&:call).join(" "))
+      end.select { |x| wanted?(x) }
     end
 
     def filter(candidates)
-      unless candidates.all? {|x| reserved?(x)}
-        candidates.reject! {|x| reserved?(x)}
+      unless candidates.all? { |x| reserved?(x) }
+        candidates.reject! { |x| reserved?(x) }
       end
       candidates
     end
@@ -44,7 +42,7 @@ module FriendlyId
       array.map do |candidate|
         case candidate
         when String
-          [->{candidate}]
+          [-> { candidate }]
         when Array
           to_candidate_array(object, candidate).flatten
         when Symbol
@@ -53,7 +51,7 @@ module FriendlyId
           if candidate.respond_to?(:call)
             [candidate]
           else
-            [->{candidate.to_s}]
+            [-> { candidate.to_s }]
           end
         end
       end

data/lib/friendly_id/configuration.rb

@@ -2,7 +2,6 @@ module FriendlyId
   # The configuration parameters passed to {Base#friendly_id} will be stored in
   # this object.
   class Configuration
-
     attr_writer :base
 
     # The default configuration options.
@@ -25,10 +24,10 @@ module FriendlyId
     attr_accessor :routes
 
     def initialize(model_class, values = nil)
-      @base           = nil
-      @model_class    = model_class
-      @defaults       = {}
-      @modules        = []
+      @base = nil
+      @model_class = model_class
+      @defaults = {}
+      @modules = []
       @finder_methods = FriendlyId::FinderMethods
       self.routes = :friendly
       set values
@@ -102,11 +101,11 @@ module FriendlyId
     private
 
     def get_module(object)
-      Module === object ? object : FriendlyId.const_get(object.to_s.titleize.camelize.gsub(/\s+/, ''))
+      Module === object ? object : FriendlyId.const_get(object.to_s.titleize.camelize.gsub(/\s+/, ""))
     end
 
     def set(values)
-      values and values.each {|name, value| self.send "#{name}=", value}
+      values&.each { |name, value| send "#{name}=", value }
     end
   end
 end

data/lib/friendly_id/finder_methods.rb

@@ -1,7 +1,5 @@
 module FriendlyId
-
   module FinderMethods
-
     # Finds a record using the given id.
     #
     # If the id is "unfriendly", it will call the original find method.
@@ -9,19 +7,33 @@ module FriendlyId
     # id matching '123' and then fall back to looking for a record with the
     # numeric id '123'.
     #
+    # @param [Boolean] allow_nil (default: false)
+    # Use allow_nil: true if you'd like the finder to return nil instead of
+    # raising ActivRecord::RecordNotFound
+    #
+    # ### Example
+    #
+    #     MyModel.friendly.find("bad-slug")
+    #     #=> raise ActiveRecord::RecordNotFound
+    #
+    #     MyModel.friendly.find("bad-slug", allow_nil: true)
+    #     #=> nil
+    #
     # Since FriendlyId 5.0, if the id is a nonnumeric 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)
+    def find(*args, allow_nil: false)
       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 potential_primary_key?(id)
-      raise_not_found_exception id
-      
+      return super(*args) if args.count != 1 || id.unfriendly_id?
+      first_by_friendly_id(id).tap { |result| return result unless result.nil? }
+      return super(*args) if potential_primary_key?(id)
+
+      raise_not_found_exception(id) unless allow_nil
+    rescue ActiveRecord::RecordNotFound => exception
+      raise exception unless allow_nil
     end
 
     # Returns true if a record with the given id exists.
@@ -35,11 +47,11 @@ module FriendlyId
     # `find`.
     # @raise ActiveRecord::RecordNotFound
     def find_by_friendly_id(id)
-      first_by_friendly_id(id) or raise raise_not_found_exception(id)
+      first_by_friendly_id(id) or raise_not_found_exception(id)
     end
 
     def exists_by_friendly_id?(id)
-      where(friendly_id_config.query_field => id).exists?
+      where(friendly_id_config.query_field => parse_friendly_id(id)).exists?
     end
 
     private
@@ -50,7 +62,11 @@ module FriendlyId
       key_type = key_type.type if key_type.respond_to?(:type)
       case key_type
       when :integer
-        Integer(id, 10) rescue false
+        begin
+          Integer(id, 10)
+        rescue
+          false
+        end
       when :uuid
         id.match(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/)
       else
@@ -59,17 +75,49 @@ module FriendlyId
     end
 
     def first_by_friendly_id(id)
-      find_by(friendly_id_config.query_field => id.downcase)
+      find_by(friendly_id_config.query_field => parse_friendly_id(id))
+    end
+
+    # Parse the given value to make it suitable for use as a slug according to
+    # your application's rules.
+    #
+    # This method is not intended to be invoked directly; FriendlyId uses it
+    # internally to process a slug into string to use as a finder.
+    #
+    # However, if FriendlyId's default slug parsing doesn't suit your needs,
+    # you can override this method in your model class to control exactly how
+    # slugs are generated.
+    #
+    # ### Example
+    #
+    #     class Person < ActiveRecord::Base
+    #       extend FriendlyId
+    #       friendly_id :name_and_location
+    #
+    #       def name_and_location
+    #         "#{name} from #{location}"
+    #       end
+    #
+    #       # Use default slug, but lower case
+    #       # If `id` is "Jane-Doe" or "JANE-DOE", this finds data by "jane-doe"
+    #       def parse_friendly_id(slug)
+    #         super.downcase
+    #       end
+    #     end
+    #
+    # @param [#to_s] value The slug to be parsed.
+    # @return The parsed slug, which is not modified by default.
+    def parse_friendly_id(value)
+      value
     end
 
     def raise_not_found_exception(id)
       message = "can't find record with friendly id: #{id.inspect}"
-      if ActiveRecord.version < Gem::Version.create('5.0') then 
+      if ActiveRecord.version < Gem::Version.create("5.0")
         raise ActiveRecord::RecordNotFound.new(message)
-      else 
+      else
         raise ActiveRecord::RecordNotFound.new(message, name, friendly_id_config.query_field, id)
       end
     end
-
   end
 end

data/lib/friendly_id/finders.rb

@@ -1,73 +1,73 @@
 module FriendlyId
-=begin
-## Performing Finds with FriendlyId
-
-FriendlyId offers enhanced finders which will search for your record by
-friendly id, and fall back to the numeric id if necessary. This makes it easy
-to add FriendlyId to an existing application with minimal code modification.
-
-By default, these methods are available only on the `friendly` scope:
-
-    Restaurant.friendly.find('plaza-diner') #=> works
-    Restaurant.friendly.find(23)            #=> also works
-    Restaurant.find(23)                     #=> still works
-    Restaurant.find('plaza-diner')          #=> will not work
-
-### Restoring FriendlyId 4.0-style finders
-
-Prior to version 5.0, FriendlyId overrode the default finder methods to perform
-friendly finds all the time. This required modifying parts of Rails that did
-not have a public API, which was harder to maintain and at times caused
-compatiblity problems. In 5.0 we decided to change the library's defaults and add
-the friendly finder methods only to the `friendly` scope in order to boost
-compatiblity. However, you can still opt-in to original functionality very
-easily by using the `:finders` addon:
-
-    class Restaurant < ActiveRecord::Base
-      extend FriendlyId
-
-      scope :active, -> {where(:active => true)}
-
-      friendly_id :name, :use => [:slugged, :finders]
-    end
-
-    Restaurant.friendly.find('plaza-diner') #=> works
-    Restaurant.find('plaza-diner')          #=> now also works
-    Restaurant.active.find('plaza-diner')   #=> now also works
-
-### Updating your application to use FriendlyId's finders
-
-Unless you've chosen to use the `:finders` addon, be sure to modify the finders
-in your controllers to use the `friendly` scope. For example:
-
-    # before
-    def set_restaurant
-      @restaurant = Restaurant.find(params[:id])
-    end
-
-    # after
-    def set_restaurant
-      @restaurant = Restaurant.friendly.find(params[:id])
-    end
-
-#### Active Admin
-
-Unless you use the `:finders` addon, you should modify your admin controllers
-for models that use FriendlyId with something similar to the following:
-
-    controller do
-      def find_resource
-        scoped_collection.friendly.find(params[:id])
-      end
-    end
-
-=end
+  # @guide begin
+  #
+  # ## Performing Finds with FriendlyId
+  #
+  # FriendlyId offers enhanced finders which will search for your record by
+  # friendly id, and fall back to the numeric id if necessary. This makes it easy
+  # to add FriendlyId to an existing application with minimal code modification.
+  #
+  # By default, these methods are available only on the `friendly` scope:
+  #
+  #     Restaurant.friendly.find('plaza-diner') #=> works
+  #     Restaurant.friendly.find(23)            #=> also works
+  #     Restaurant.find(23)                     #=> still works
+  #     Restaurant.find('plaza-diner')          #=> will not work
+  #
+  # ### Restoring FriendlyId 4.0-style finders
+  #
+  # Prior to version 5.0, FriendlyId overrode the default finder methods to perform
+  # friendly finds all the time. This required modifying parts of Rails that did
+  # not have a public API, which was harder to maintain and at times caused
+  # compatiblity problems. In 5.0 we decided to change the library's defaults and add
+  # the friendly finder methods only to the `friendly` scope in order to boost
+  # compatiblity. However, you can still opt-in to original functionality very
+  # easily by using the `:finders` addon:
+  #
+  #     class Restaurant < ActiveRecord::Base
+  #       extend FriendlyId
+  #
+  #       scope :active, -> {where(:active => true)}
+  #
+  #       friendly_id :name, :use => [:slugged, :finders]
+  #     end
+  #
+  #     Restaurant.friendly.find('plaza-diner') #=> works
+  #     Restaurant.find('plaza-diner')          #=> now also works
+  #     Restaurant.active.find('plaza-diner')   #=> now also works
+  #
+  # ### Updating your application to use FriendlyId's finders
+  #
+  # Unless you've chosen to use the `:finders` addon, be sure to modify the finders
+  # in your controllers to use the `friendly` scope. For example:
+  #
+  #     # before
+  #     def set_restaurant
+  #       @restaurant = Restaurant.find(params[:id])
+  #     end
+  #
+  #     # after
+  #     def set_restaurant
+  #       @restaurant = Restaurant.friendly.find(params[:id])
+  #     end
+  #
+  # #### Active Admin
+  #
+  # Unless you use the `:finders` addon, you should modify your admin controllers
+  # for models that use FriendlyId with something similar to the following:
+  #
+  #     controller do
+  #       def find_resource
+  #         scoped_collection.friendly.find(params[:id])
+  #       end
+  #     end
+  #
+  # @guide end
   module Finders
-
     module ClassMethods
       if (ActiveRecord::VERSION::MAJOR == 4) && (ActiveRecord::VERSION::MINOR == 0)
         def relation_delegate_class(klass)
-          relation_class_name = :"#{klass.to_s.gsub('::', '_')}_#{self.to_s.gsub('::', '_')}"
+          relation_class_name = :"#{klass.to_s.gsub("::", "_")}_#{to_s.gsub("::", "_")}"
           klass.const_get(relation_class_name)
         end
       end
@@ -82,7 +82,7 @@ for models that use FriendlyId with something similar to the following:
       end
 
       # Support for friendly finds on associations for Rails 4.0.1 and above.
-      if ::ActiveRecord.const_defined?('AssociationRelation')
+      if ::ActiveRecord.const_defined?("AssociationRelation")
         model_class.extend(ClassMethods)
         association_relation_delegate_class = model_class.relation_delegate_class(::ActiveRecord::AssociationRelation)
         association_relation_delegate_class.send(:include, model_class.friendly_id_config.finder_methods)