make_taggable 0.7.4 → 1.0.0

data/lib/make_taggable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "make_taggable/version"
 require "active_record"
 require "active_record/version"
@@ -11,6 +13,21 @@ end
 
 require "digest/sha1"
 
+##
+# Tagging for Active Record models, across any number of named contexts.
+#
+# Make a model taggable with {MakeTaggable::Taggable#make_taggable}, and configure the library
+# through {MakeTaggable.setup}. Every setting on {MakeTaggable::Configuration} can also be read and
+# written directly here.
+#
+# @example
+#   class Book < ActiveRecord::Base
+#     make_taggable :genres
+#   end
+#
+#   Book.create!(genre_list: "sci-fi, classic")
+#   Book.tagged_with("sci-fi")
+#
 module MakeTaggable
   extend ActiveSupport::Autoload
 
@@ -28,23 +45,52 @@ module MakeTaggable
     autoload :Cache
     autoload :Collection
     autoload :Core
-    autoload :Dirty
     autoload :Ownership
     autoload :Related
     autoload :TagListType
   end
 
   autoload :Utils
-  autoload :Compatibility
 
+  ##
+  # Raised when a tag name is taken by a competing write and cannot be resolved by retrying.
+  #
   class DuplicateTagError < StandardError
   end
 
+  ##
+  # Yields the configuration so settings can be assigned in one block.
+  #
+  # Called without a block it only ensures the configuration exists, which is how the library
+  # initialises itself on load.
+  #
+  # @yieldparam configuration [MakeTaggable::Configuration] the current configuration
+  # @return [MakeTaggable::Configuration, NilClass] the configuration when no block is given
+  #
+  # @example
+  #   MakeTaggable.setup do |config|
+  #     config.force_lowercase = true
+  #     config.remove_unused_tags = true
+  #   end
+  #
   def self.setup
     @configuration ||= Configuration.new
     yield @configuration if block_given?
   end
 
+  ##
+  # Forwards unknown calls to the configuration, so every setting can be read and written directly
+  # on `MakeTaggable` as well as inside a {setup} block.
+  #
+  # @param method_name [Symbol] the configuration reader or writer
+  # @param args [Array<Object>] arguments forwarded to the configuration
+  # @return [Object] whatever the configuration returns
+  # @raise [NoMethodError] when the configuration has no such setting
+  #
+  # @example
+  #   MakeTaggable.force_lowercase = true
+  #   MakeTaggable.force_lowercase # => true
+  #
   def self.method_missing(method_name, *args, &block)
     if @configuration.respond_to?(method_name)
       @configuration.send(method_name, *args, &block)
@@ -53,16 +99,70 @@ module MakeTaggable
     end
   end
 
+  ##
+  # Reports the configuration's settings as available on `MakeTaggable` itself.
+  #
+  # @param method_name [Symbol] the method being tested
+  # @param include_private [TrueClass, FalseClass] whether private methods count
+  # @return [TrueClass, FalseClass]
+  #
   def self.respond_to_missing?(method_name, include_private = false)
-    @configuration.respond_to? method_name
+    @configuration.respond_to?(method_name, include_private) || super
   end
 
+  ##
+  # The string used to join tags back together for display, derived from the configured delimiter.
+  #
+  # A trailing space is added when the delimiter does not already end in one, so a comma delimiter
+  # renders as `"one, two"` rather than `"one,two"`. When several delimiters are configured the
+  # first is used.
+  #
+  # @return [String] the delimiter, guaranteed to end in a space
+  #
+  # @example
+  #   MakeTaggable.glue # => ", "
+  #
   def self.glue
     setting = @configuration.delimiter
     delimiter = setting.is_a?(Array) ? setting[0] : setting
     delimiter.end_with?(" ") ? delimiter : "#{delimiter} "
   end
 
+  ##
+  # The library's settings.
+  #
+  # Reach these through {MakeTaggable.setup} or directly on `MakeTaggable`, which forwards to the
+  # single instance held here.
+  #
+  # @!attribute [rw] force_lowercase
+  #   Whether tag names are downcased before they are saved.
+  #   @return [TrueClass, FalseClass] defaults to `false`
+  # @!attribute [rw] force_parameterize
+  #   Whether tag names are parameterized before they are saved.
+  #   @return [TrueClass, FalseClass] defaults to `false`
+  # @!attribute [rw] remove_unused_tags
+  #   Whether a tag row is destroyed once its last tagging goes away. Requires `tags_counter`.
+  #   @return [TrueClass, FalseClass] defaults to `false`
+  # @!attribute [rw] default_parser
+  #   The class used to turn tag input into a {MakeTaggable::TagList}.
+  #   @return [Class] defaults to {MakeTaggable::DefaultParser}
+  # @!attribute [rw] tags_counter
+  #   Whether taggings maintain a counter cache on their tag.
+  #   @return [TrueClass, FalseClass] defaults to `true`
+  # @!attribute [rw] tags_table
+  #   The table backing {MakeTaggable::Tag}.
+  #   @return [Symbol, String] defaults to `:tags`
+  # @!attribute [rw] taggings_table
+  #   The table backing {MakeTaggable::Tagging}.
+  #   @return [Symbol, String] defaults to `:taggings`
+  # @!attribute [r] delimiter
+  #   The delimiter, or delimiters, separating tags in a string. Metacharacters are escaped, so
+  #   each one is matched literally.
+  #   @return [String, Array<String>] defaults to `","`
+  # @!attribute [r] strict_case_match
+  #   Whether tag lookups are case sensitive.
+  #   @return [TrueClass, FalseClass] defaults to `false`
+  #
   class Configuration
     attr_accessor :force_lowercase, :force_parameterize,
       :remove_unused_tags, :default_parser,
@@ -70,6 +170,11 @@ module MakeTaggable
       :taggings_table
     attr_reader :delimiter, :strict_case_match
 
+    ##
+    # Builds the configuration with the library's defaults.
+    #
+    # @return [MakeTaggable::Configuration]
+    #
     def initialize
       @delimiter = ","
       @force_lowercase = false
@@ -83,19 +188,49 @@ module MakeTaggable
       @taggings_table = :taggings
     end
 
+    ##
+    # Sets whether tag lookups are case sensitive.
+    #
+    # Ignored while {#force_binary_collation=} is on, which already implies case sensitivity.
+    #
+    # @param force_cs [TrueClass, FalseClass] whether to match case exactly
+    # @return [TrueClass, FalseClass]
+    #
     def strict_case_match=(force_cs)
       @strict_case_match = force_cs unless @force_binary_collation
     end
 
+    ##
+    # Sets the delimiter separating tags in a string.
+    #
+    # @deprecated Configure a {#default_parser} instead. This will be removed in a future release.
+    #
+    # @param string [String, Array<String>] one delimiter, or several
+    # @return [String, Array<String>]
+    #
+    # @example Several delimiters, matched literally
+    #   MakeTaggable.delimiter = [",", "|"]
+    #
     def delimiter=(string)
-      ActiveRecord::Base.logger.warn <<~WARNING
-        MakeTaggable.delimiter is deprecated \
-        and will be removed from v4.0+, use  \
-        a MakeTaggable.default_parser instead
-      WARNING
+      # Active Record does not always have a logger -- a plain Active Record
+      # process, or an initializer running before the logger is assigned, will
+      # both leave it nil.
+      ActiveRecord::Base.logger&.warn(
+        "MakeTaggable.delimiter is deprecated and will be removed in a future " \
+        "release. Configure a MakeTaggable.default_parser instead."
+      )
       @delimiter = string
     end
 
+    ##
+    # Switches the MySQL tag name column between a binary and a case-insensitive collation.
+    #
+    # A binary collation makes tag names compare exactly, including accented and other multi-byte
+    # characters, and forces {#strict_case_match} on. Does nothing on other adapters.
+    #
+    # @param force_bin [TrueClass, FalseClass] whether to apply the binary collation
+    # @return [TrueClass, FalseClass]
+    #
     def force_binary_collation=(force_bin)
       if Utils.using_mysql?
         if force_bin
@@ -109,6 +244,16 @@ module MakeTaggable
       end
     end
 
+    ##
+    # Alters the MySQL tag name column to the requested collation.
+    #
+    # Failures are reported rather than raised: the column does not exist yet the first time the
+    # migrations run, and that is not an error.
+    #
+    # @param bincoll [TrueClass, FalseClass] `true` for `utf8mb4_bin`, `false` for
+    #   `utf8mb4_general_ci`
+    # @return [NilClass]
+    #
     def self.apply_binary_collation(bincoll)
       if Utils.using_mysql?
         coll = "utf8mb4_general_ci"

data/make_taggable.gemspec

@@ -6,37 +6,30 @@ Gem::Specification.new do |spec|
   spec.authors = ["Matthew Kennedy", "Michael Bleigh", "Joost Baaij"]
   spec.email = %w[m.kennedy@me.com]
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 3.2"
 
   spec.summary = "Advanced Tagging For Rails"
-  spec.description = "MakeTaggable is a fork of Acts-As-Taggable-On with code updates & fresh migrations"
+  spec.description = "MakeTaggable lets Active Record models carry tags across any number of " \
+    "named contexts, with ownership, ordering, custom parsers and tag-cloud calculations."
 
   spec.homepage = "https://github.com/MatthewKennedy/make_taggable"
   spec.license = "MIT"
 
-  spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "https://github.com/MatthewKennedy/make_taggable/blob/master/CHANGELOG.md"
-
-  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "#{spec.homepage}/blob/master/docs"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(spec|gemfiles|\.github)/}) || f.match(%r{\A(\.|Appraisals|Rakefile|Gemfile)})
+    end
   end
 
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord", ">= 5.2.0", "<= 7.5.0"
-
-  spec.add_development_dependency "rails", ">= 5.2.0", "<= 7.5.0"
-  spec.add_development_dependency "appraisal", "~> 2.3.0"
-  spec.add_development_dependency "mysql2", "~> 0.5.0"
-  spec.add_development_dependency "pg", "~> 1.2.0"
-  spec.add_development_dependency "rspec", "~> 3.10.0"
-  spec.add_development_dependency "rspec-rails", "~> 4.0.0"
-  spec.add_development_dependency "standard", "~> 0.10.0"
-  spec.add_development_dependency "sqlite3", "~> 1.4.0"
-  spec.add_development_dependency "rails-dummy", "~> 0.1.0"
+  spec.add_dependency "activerecord", ">= 7.2"
 
   if File.exist?("UPGRADING.md")
     spec.post_install_message = File.read("UPGRADING.md")

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Matthew Kennedy
 - Michael Bleigh
 - Joost Baaij
-autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2021-03-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -18,173 +17,27 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.0
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: 7.5.0
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.0
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: 7.5.0
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 5.2.0
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: 7.5.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 5.2.0
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: 7.5.0
-- !ruby/object:Gem::Dependency
-  name: appraisal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.3.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.3.0
-- !ruby/object:Gem::Dependency
-  name: mysql2
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.5.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.5.0
-- !ruby/object:Gem::Dependency
-  name: pg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.2.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.2.0
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.10.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.10.0
-- !ruby/object:Gem::Dependency
-  name: rspec-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 4.0.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 4.0.0
-- !ruby/object:Gem::Dependency
-  name: standard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.10.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.10.0
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.4.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.4.0
-- !ruby/object:Gem::Dependency
-  name: rails-dummy
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-description: MakeTaggable is a fork of Acts-As-Taggable-On with code updates & fresh
-  migrations
+        version: '7.2'
+description: MakeTaggable lets Active Record models carry tags across any number of
+  named contexts, with ownership, ordering, custom parsers and tag-cloud calculations.
 email:
 - m.kennedy@me.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".dummyrc"
-- ".github/workflows/ci.yml"
-- ".github/workflows/standard-ci.yml"
-- ".gitignore"
-- ".rspec"
-- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
-- Gemfile
 - LICENSE.md
 - README.md
-- Rakefile
 - UPGRADING.md
 - bin/console
 - bin/setup
@@ -193,10 +46,16 @@ files:
 - db/migrate/3_change_tag_name_collation_mysql.rb
 - db/migrate/4_add_index_to_tags.rb
 - db/migrate/5_add_index_to_taggings.rb
-- gemfiles/rails_5.gemfile
-- gemfiles/rails_6.gemfile
-- gemfiles/rails_6_1.gemfile
-- gemfiles/rails_master.gemfile
+- docs/caching.md
+- docs/configuration.md
+- docs/contexts.md
+- docs/database.md
+- docs/getting-started.md
+- docs/migrating-from-aato.md
+- docs/ownership.md
+- docs/parsers.md
+- docs/querying.md
+- docs/tag-clouds.md
 - lib/make_taggable.rb
 - lib/make_taggable/default_parser.rb
 - lib/make_taggable/engine.rb
@@ -220,22 +79,49 @@ files:
 - lib/make_taggable/tags_helper.rb
 - lib/make_taggable/utils.rb
 - lib/make_taggable/version.rb
-- lib/tasks/setup_test_db.rake
 - lib/tasks/tags_collate_utf8.rake
 - make_taggable.gemspec
 homepage: https://github.com/MatthewKennedy/make_taggable
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/MatthewKennedy/make_taggable
   source_code_uri: https://github.com/MatthewKennedy/make_taggable
   changelog_uri: https://github.com/MatthewKennedy/make_taggable/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/MatthewKennedy/make_taggable/issues
+  documentation_uri: https://github.com/MatthewKennedy/make_taggable/blob/master/docs
+  rubygems_mfa_required: 'true'
 post_install_message: |
-  When upgrading run the migrations generator
+  Upgrading to MakeTaggable 1.0
+
+  This release renames the declaration methods and changes how delimiters are escaped.
+
+  1. Rename the declarations in your models:
+
+       acts_as_taggable                    ->  make_taggable
+       acts_as_taggable_on :skills         ->  make_taggable :skills
+       acts_as_ordered_taggable            ->  make_ordered_taggable
+       acts_as_ordered_taggable_on :skills ->  make_ordered_taggable :skills
+       acts_as_tagger                      ->  make_tagger
+
+     Everything generated per context keeps its name: skill_list, skills,
+     skill_counts, top_skills, skills_from, find_related_skills.
+
+  2. If you configure a delimiter containing a regular expression
+     metacharacter, unescape it. Delimiters are now literal strings:
+
+       MakeTaggable.delimiter = ['\|']  ->  MakeTaggable.delimiter = ["|"]
+
+  3. If you rely on `make_taggable` with no arguments adding no contexts,
+     note that it now tags on :tags.
+
+  4. Requirements are now Ruby 3.2 and Active Record 7.2 or newer.
+
+  Install any new migrations:
 
       rails make_taggable_engine:install:migrations
+      rails db:migrate
 
-  This will create any new migrations and skip existing ones
+  Full notes: https://github.com/MatthewKennedy/make_taggable/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -243,15 +129,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.14
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Advanced Tagging For Rails
 test_files: []

data/.dummyrc

@@ -1,17 +0,0 @@
---skip-bootsnap
---skip-webpack
---skip-action-cable
---skip-spring
---skip-coffee
---skip-turbolinks
---skip-listen
---skip-action-text
---skip-active-storage
---skip-action-cable
---skip-action-mailer
---skip-action-mailbox
---skip-active-job
---skip-javascript
---skip-test
-
---template=spec/template/test_app_template.rb