schnecke 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 144b6900260d2c6d5d9f293cee58c0ceb25ec663ff00c77bf1d2d72f9d79fc78
-  data.tar.gz: 6332f95d24fcc612fd1be9147f2e816c55a9484c4ac2582e9be21691902272e9
+  metadata.gz: fc2bd819b79ff41a6fe04c425c2dd21243bf4250f12d75dfe2fa4d2fea926ae1
+  data.tar.gz: 21b1aafaa43ca42f633072d722f9d35e6dbc21a1594195228a22df884c7f65b3
 SHA512:
-  metadata.gz: 906f07f820ffe12443424f5c0e1427a5b942537911a6026f6b9644b3acdd40a817227642f86b7d01123bac0beeaed31eebf522b6e7442206cf3b16c6e4b0444e
-  data.tar.gz: 61f35e4e5322dd7a7fc967c093697150e56d1d2c17b8f15890bf262ffdeec9306ebb7790748e06691b082ec9ac006bd163a427b4e963363fa0affbbdb8ff2e9b
+  metadata.gz: fd9094457874a4c7a629e007747c6931367a67655d2c343f9aab91ee3c160340250c08119267e4dd3a576a043bd8b8ba5e22413f13deb6602640715a5e927316
+  data.tar.gz: 776c13331c63092e759103488cd55b4feabd36697909c90a9aabdc108d437c0b32475a572f9e5fdb262b1bcac42ce1ede6e9a279bc9d8d4be431116ceae3b386

data/.rubocop.yml

@@ -44,6 +44,8 @@ Metrics/MethodLength:
 
 Metrics/ModuleLength:
   Max: 100
+  Exclude:
+    - 'lib/schnecke/schnecke.rb'
 
 Minitest/MultipleAssertions:
   Max: 10

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    schnecke (0.2.0)
+    schnecke (0.4.0)
       activerecord (> 4.2.0)
       activesupport (> 4.2.0)
 

data/README.md

@@ -22,10 +22,10 @@ Or install it yourself as:
 
 ## Usage
 
-Given a class `A` which has the attribute `name` and has a `slug` column defined, we can do the following:
+Given a class `SomeObject` which has the attribute `name` and has a `slug` column defined, we can do the following:
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name
 end
@@ -34,18 +34,75 @@ end
 This will take the value in `name` and automatically set the slug based on it. If the slug needs to be based on multiple attributes of a model, simply pass in the array of attributes as follows:
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug [:first_name, :last_name]
 end
 ```
 
+Under the hood, this library adds a `before_validate` callback that automatically runs a method called `assign_slug`. You are welcome to call this method explicity if you so desire.
+
+```ruby
+obj = SomeObject.new(name: 'Hello World!')
+obj.assign_slug
+```
+
+It is important to note that if the attribute used to hold the slug (`slug` by default, see next section) already contains a value, the slug assignment **WILL NOT HAPPEN**. This means, if you manually assign the slug by explicitly setting the slug value yourself, it will not be modified. If you would like the slug to be overwrriten you can explicitly call the `reassign_slug` method.
+
+```ruby
+obj = SomeObject.new(name: 'Hello World!', slug: 'hi')
+
+# This will do nothing as the slug was already set
+obj.assign_slug
+
+# This will cause the slug to be assigned
+obj.reassign_slug
+```
+
+### Using a method to define a slug source
+
+There are times when the source of the slug needs to be set based on some other values (e.g. a parent object, random number, etc). In this case, simply define a method that is to be used to set the soure of the slug. This method can be public, protected, or private.
+
+```ruby
+class SomeObject
+  include Schnecke
+  slug :parent_slug
+
+  belongs_to :parent_object
+
+  protected
+
+  def parent_slug
+    parent_object.slug
+  end
+end
+```
+
+Just like if one is using a plain old attributes, one can mix and match methods and attributes if the slug is to be derived from multiple sources
+
+```ruby
+class SomeObject
+  include Schnecke
+  slug [:name, :parent_slug]
+
+  belongs_to :parent_object
+
+  protected
+
+  def parent_slug
+    parent_object.slug
+  end
+end
+```
+
+And this will take the `:name` attribute and the result from `parent_slug` and create a slug from the two things combined. 
+
 ### Slug column
 
 By default it is assumed that the generated slug will be assigned to the `slug` attribute of the model. If one needs to place the slug in a different columm, this can be done by defining the `column` attribute:
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name, column: :some_other_column
 end
@@ -59,14 +116,14 @@ By default the maxium length of a slug is 32 characters *NOT INCLUDING* any pote
 
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name, limit_length: 15
 end
 ```
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name, limit_length: false
 end
@@ -74,21 +131,21 @@ end
 
 ### Slug Uniquness
 
-By default slugs are unique to the object that defines the slug. For example if we have the 2 objects, `A` and `B` as defined as below, then the slugs will be unique for all slugs for all type `A` objcets and all type `B` objects. 
+By default slugs are unique to the object that defines the slug. For example if we have the 2 objects, `SomeObject` and `SomeOtherObject` as defined as below, then the slugs will be unique for all slugs for all type `SomeObject` objcets and all type `SomeOtherObject` objects. 
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name
 end
 
-class B
+class SomeOtherObject
   include Schnecke
   slug :name
 end
 ```
 
-This means that the slug `foo` can exists 2 times; once for any object of type `A` and once for any object of type `B`. Currently there is no way to create globally unique slugs. If this is something that is required, then something like [`friendly_id`](https://github.com/norman/friendly_id) might be more appropriate for your use case.
+This means that the slug `foo` can exists 2 times; once for any object of type `SomeObject` and once for any object of type `SomeOtherObject`. Currently there is no way to create globally unique slugs. If this is something that is required, then something like [`friendly_id`](https://github.com/norman/friendly_id) might be more appropriate for your use case.
 
 ### Handling non-unique slugs
 
@@ -98,7 +155,7 @@ It is important to note that the maximum length of a slug does not include the a
 
 ### Defining a custom uniqueness scope
 
-There are times when we want slugs not be unique for all objects of type `A`, but rather for a smaller scope. For example, let's say we have a system with multiple `Accounts`, each containing `Record`s. If we want the slug for the `Record` to be unique only within the scope of an `account` we can do by providing the uniqueness scope when setting up the slug.
+There are times when we want slugs not be unique for all objects of type `SomeObject`, but rather for a smaller scope. For example, let's say we have a system with multiple `Accounts`, each containing `Record`s. If we want the slug for the `Record` to be unique only within the scope of an `account` we can do by providing the uniqueness scope when setting up the slug.
 
 ```ruby
 class Record
@@ -121,12 +178,33 @@ class Tag
 end
 ```
 
+### Callbacks
+
+Two callbacks, `before_assign_slug` and `after_assign_slug`, are provided so that you can run arbitrary code before and after the slug assignment process. Both of these callbacks will always run regardless of whether or not a slug is to be assigned. The only time `after_assign_slug` is not run is if there is an exception raised during the assignment process.
+
+Note, since `reassign_slug` is just a forced assignment of a slug, both callbacks will run as well.
+
+```ruby
+class SomeObject
+  include Schnecke
+  slug :name
+
+  def before_assign_slug(opts={})
+    puts 'Hello world! I get run before the slug assignment process'
+  end
+
+  def after_assign_slug(opts={})
+    puts 'Goodbye world! I get run after the slug assignment process'
+  end
+end
+```
+
 ### Advanced Usage
 
 If you need to change how the slug is generated, how duplicates are handled, etc., you can overwrite the methods in your class. For example to change how slugs are generated you can overwrite the `slugify` method.
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name
 
@@ -140,7 +218,7 @@ end
 Note, by default the library will validate to ensure that the slug only contains lowercase alpphanumeric letters and '-' or '_'. If your new method changes the alloweable set of characters you can either disable this validation, or pass in your own validation pattern.
 
 ```ruby
-class A
+class SomeObject
   include Schnecke
   slug :name, require_format: false
 
@@ -149,7 +227,7 @@ class A
   end
 end
 
-class B
+class SomeOtherObject
   include Schnecke
   slug :name, require_format: /\A[a-z]+\z/
 

data/lib/schnecke/schnecke.rb

@@ -64,7 +64,47 @@ module Schnecke
     # Note, a slug will not be assigned if one already exists. If one needs to
     # force the assignment of a slug, pass `force: true`
     def assign_slug(opts = {})
-      validate_source
+      before_assign_slug(opts)
+      perform_slug_assign(opts)
+      after_assign_slug(opts)
+    end
+
+    # Reassign the slug
+    #
+    # Unlike assign_slug, this will cause a slug to be created even if one
+    # already exists.
+    def reassign_slug(opts = {})
+      opts[:force] = true
+      assign_slug(opts)
+    end
+
+    # Callback that is handled before the slug assignment process.
+    #
+    # When this is called, no validations, or decisions about whether or not
+    # a slug should be created have been made. As such, this will always run
+    # regardless of whether or not the slug assignment process proceeds or not.
+    def before_assign_slug(opts = {})
+      # Left blank, but can be implemented by user
+    end
+
+    # Callback that is handled after the slug is assigned
+    #
+    # Unless an error is raised during the slug assignment process, this method
+    # will always be called regardless of whether or not the slug was assigned
+    def after_assign_slug(opts = {})
+      # Left blank, but can be implemented by user
+    end
+
+    protected
+
+    # Assign the slug
+    #
+    # This is automatically called before model validation.
+    #
+    # Note, a slug will not be assigned if one already exists. If one needs to
+    # force the assignment of a slug, pass `force: true`
+    def perform_slug_assign(opts = {})
+      validate_slug_source
       validate_slug_column
 
       return if !should_create_slug? && !opts[:force]
@@ -79,7 +119,7 @@ module Schnecke
       end
 
       # Make sure it is not too long
-      candidate_slug = truncate(candidate_slug)
+      candidate_slug = truncate_slug(candidate_slug)
 
       # If there is a duplicate, create a unique one
       if slug_exists?(candidate_slug)
@@ -89,16 +129,6 @@ module Schnecke
       self[schnecke_config[:slug_column]] = candidate_slug
     end
 
-    # Reassign the slug
-    #
-    # Unlike assign_slug, this will cause a slug to be created even if one
-    # already exists.
-    def reassign_slug
-      assign_slug(force: true)
-    end
-
-    protected
-
     # Slugify a string
     #
     # This will take a string and convert it to a slug by removing punctuation
@@ -106,9 +136,9 @@ module Schnecke
     #
     # This can be overriden if a different slug generation method is needed
     def slugify(str)
-      return if str.blank?
+      return str if str.blank?
 
-      str.gsub!(/[\p{Pc}\p{Ps}\p{Pe}\p{Pi}\p{Pf}\p{Po}]/, '')
+      str = str.gsub(/[\p{Pc}\p{Ps}\p{Pe}\p{Pi}\p{Pf}\p{Po}]/, '')
       str.parameterize
     end
 
@@ -131,7 +161,7 @@ module Schnecke
     #
     # This can be overriden if a different behavior is desired
     def slugify_duplicate(slug)
-      return if slug.blank?
+      return slug if slug.blank?
 
       seq = 2
       new_slug = slug_concat([slug, seq])
@@ -156,10 +186,10 @@ module Schnecke
 
     private
 
-    def validate_source
+    def validate_slug_source
       source = arrayify(schnecke_config[:slug_source])
       source.each do |attr|
-        unless respond_to?(attr)
+        unless respond_to?(attr, true)
           raise ArgumentError,
                 "Source '#{attr}' does not exist."
         end
@@ -185,9 +215,9 @@ module Schnecke
       parts.join(schnecke_config[:slug_separator])
     end
 
-    def truncate(slug)
-      return if slug.blank?
-      return if schnecke_config[:limit_length].blank?
+    def truncate_slug(slug)
+      return slug if slug.blank?
+      return slug if schnecke_config[:limit_length].blank?
 
       slug[0, schnecke_config[:limit_length]]
     end

data/lib/schnecke/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Schnecke
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: schnecke
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrick R. Schmid
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-01 00:00:00.000000000 Z
+date: 2022-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler