make_taggable 0.7.4 → 1.0.0

data/lib/make_taggable/tag.rb

@@ -1,4 +1,21 @@
+# frozen_string_literal: true
+
 module MakeTaggable
+  ##
+  # A tag name, shared by every record tagged with it.
+  #
+  # Tags are found and created through the class methods here rather than directly, so that the
+  # configured case sensitivity is applied consistently. Subclass it to keep a separate vocabulary
+  # for one context, and point at the subclass from
+  # {MakeTaggable::Taggable::Core#find_or_create_tags_from_list_with_context}.
+  #
+  # @!attribute [rw] name
+  #   The tag itself.
+  #   @return [String]
+  # @!attribute [rw] taggings_count
+  #   How many taggings reference this tag, maintained as a counter cache.
+  #   @return [Integer]
+  #
   class Tag < ::ActiveRecord::Base
     self.table_name = MakeTaggable.tags_table
 
@@ -10,7 +27,13 @@ module MakeTaggable
     validates_uniqueness_of :name, if: :validates_name_uniqueness?, case_sensitive: true
     validates_length_of :name, maximum: 255
 
-    # Monkey patch this method if don't need name uniqueness validation
+    ##
+    # Whether the uniqueness validation on `name` runs.
+    #
+    # Override this in a subclass to allow tag names to repeat.
+    #
+    # @return [TrueClass, FalseClass] always `true` here
+    #
     def validates_name_uniqueness?
       true
     end
@@ -19,26 +42,53 @@ module MakeTaggable
     scope :most_used, ->(limit = 20) { order("taggings_count desc").limit(limit) }
     scope :least_used, ->(limit = 20) { order("taggings_count asc").limit(limit) }
 
+    ##
+    # Tags matching a name exactly, honouring the configured case sensitivity.
+    #
+    # @param name [String] the name to match
+    # @return [ActiveRecord::Relation]
+    #
     def self.named(name)
       if MakeTaggable.strict_case_match
-        where(["name = #{binary}?", as_8bit_ascii(name)])
+        where(["name = #{binary}?", name.to_s])
       else
-        where(["LOWER(name) = LOWER(?)", as_8bit_ascii(unicode_downcase(name))])
+        where(["LOWER(name) = LOWER(?)", name.to_s.downcase])
       end
     end
 
+    ##
+    # Tags matching any of the given names exactly.
+    #
+    # @param list [Array<String>] the names to match
+    # @return [ActiveRecord::Relation]
+    #
     def self.named_any(list)
       clause = list.map { |tag|
-        sanitize_sql_for_named_any(tag).force_encoding("BINARY")
+        sanitize_sql_for_named_any(tag)
       }.join(" OR ")
       where(clause)
     end
 
+    ##
+    # Tags whose name contains the given fragment.
+    #
+    # Case insensitive on PostgreSQL, which uses `ILIKE`; otherwise it follows the column's
+    # collation.
+    #
+    # @param name [String] the fragment to look for
+    # @return [ActiveRecord::Relation]
+    #
     def self.named_like(name)
       clause = ["name #{MakeTaggable::Utils.like_operator} ? ESCAPE '!'", "%#{MakeTaggable::Utils.escape_like(name)}%"]
       where(clause)
     end
 
+    ##
+    # Tags whose name contains any of the given fragments.
+    #
+    # @param list [Array<String>] the fragments to look for
+    # @return [ActiveRecord::Relation]
+    #
     def self.named_like_any(list)
       clause = list.map { |tag|
         sanitize_sql(["name #{MakeTaggable::Utils.like_operator} ? ESCAPE '!'", "%#{MakeTaggable::Utils.escape_like(tag.to_s)}%"])
@@ -46,6 +96,15 @@ module MakeTaggable
       where(clause)
     end
 
+    ##
+    # Tags used in a given context, whatever the record they were applied to.
+    #
+    # @param context [String, Symbol] the tagging context
+    # @return [ActiveRecord::Relation]
+    #
+    # @example
+    #   MakeTaggable::Tag.for_context(:skills)
+    #
     def self.for_context(context)
       joins(:taggings)
         .where(["#{MakeTaggable.taggings_table}.context = ?", context])
@@ -53,29 +112,61 @@ module MakeTaggable
     end
 
     ### CLASS METHODS:
+
+    ##
+    # Finds a tag by name, creating it when it does not exist yet.
+    #
+    # The name is matched in full. Honours the configured case sensitivity.
+    #
+    # @param name [String] the tag name
+    # @return [MakeTaggable::Tag]
+    #
+    # @example
+    #   MakeTaggable::Tag.find_or_create_with_like_by_name("ruby")
+    #
     def self.find_or_create_with_like_by_name(name)
       if MakeTaggable.strict_case_match
         find_or_create_all_with_like_by_name([name]).first
       else
-        named_like(name).first || create(name: name)
+        # Matching has to happen in Ruby's terms rather than the column's: the
+        # MySQL migration collates tag names as utf8mb4_bin, which would make a
+        # LIKE comparison case sensitive whatever strict_case_match says.
+        named(name).first || create(name: name)
       end
     end
 
+    ##
+    # Finds every tag in a list by name, creating those that do not exist yet.
+    #
+    # A competing write that takes a name first is retried up to three times before giving up.
+    #
+    # @param list [Array<String>] the tag names
+    # @return [Array<MakeTaggable::Tag>] in the order the names were given
+    # @raise [MakeTaggable::DuplicateTagError] when a name stays taken after three attempts
+    #
+    # @example
+    #   MakeTaggable::Tag.find_or_create_all_with_like_by_name(%w[ruby rails])
+    #
     def self.find_or_create_all_with_like_by_name(*list)
       list = Array(list).flatten
 
       return [] if list.empty?
 
-      existing_tags = named_any(list)
+      existing_tags = named_any(list).to_a
       list.map do |tag_name|
         tries ||= 3
         comparable_tag_name = comparable_name(tag_name)
         existing_tag = existing_tags.find { |tag| comparable_name(tag.name) == comparable_tag_name }
-        existing_tag || create(name: tag_name)
+        next existing_tag if existing_tag
+
+        # Tags created earlier in this call have to stay visible to the names
+        # that follow, or a list holding both "Ruby" and "ruby" resolves to two
+        # rows even though the two names compare equal.
+        create(name: tag_name).tap { |tag| existing_tags << tag }
       rescue ActiveRecord::RecordNotUnique
         if (tries -= 1).positive?
           ActiveRecord::Base.connection.execute "ROLLBACK"
-          existing_tags = named_any(list)
+          existing_tags = named_any(list).to_a
           retry
         end
 
@@ -84,14 +175,33 @@ module MakeTaggable
     end
 
     ### INSTANCE METHODS:
+
+    ##
+    # Compares tags by name, so a saved tag and an unsaved one with the same name are equal.
+    #
+    # @param other [Object] the object to compare against
+    # @return [TrueClass, FalseClass]
+    #
     def ==(other)
       super || (other.is_a?(Tag) && name == other.name)
     end
 
+    ##
+    # The tag's name, so a tag renders as itself in a view or a string.
+    #
+    # @return [String]
+    #
     def to_s
       name
     end
 
+    ##
+    # How many times this tag matched, on relations that select a count alongside the tag columns.
+    #
+    # Zero on a tag loaded without one.
+    #
+    # @return [Integer]
+    #
     def count
       read_attribute(:count).to_i
     end
@@ -103,7 +213,7 @@ module MakeTaggable
         if MakeTaggable.strict_case_match
           str
         else
-          unicode_downcase(str.to_s)
+          str.to_s.downcase
         end
       end
 
@@ -111,19 +221,11 @@ module MakeTaggable
         MakeTaggable::Utils.using_mysql? ? "BINARY " : nil
       end
 
-      def as_8bit_ascii(string)
-        string.to_s.mb_chars
-      end
-
-      def unicode_downcase(string)
-        as_8bit_ascii(string).downcase
-      end
-
       def sanitize_sql_for_named_any(tag)
         if MakeTaggable.strict_case_match
-          sanitize_sql(["name = #{binary}?", as_8bit_ascii(tag)])
+          sanitize_sql(["name = #{binary}?", tag.to_s])
         else
-          sanitize_sql(["LOWER(name) = LOWER(?)", as_8bit_ascii(unicode_downcase(tag))])
+          sanitize_sql(["LOWER(name) = LOWER(?)", tag.to_s.downcase])
         end
       end
     end

data/lib/make_taggable/tag_list.rb

@@ -1,22 +1,55 @@
+# frozen_string_literal: true
+
 require "active_support/core_ext/module/delegation"
 
 module MakeTaggable
+  ##
+  # The list of tag names held against one context of one record.
+  #
+  # A tag list is an Array, so everything Array offers works on it. What it adds is parsing, and
+  # cleaning: blank entries are dropped, entries are converted to strings and stripped, and
+  # duplicates are removed according to the configured case sensitivity.
+  #
+  # @example
+  #   list = MakeTaggable::TagList.new("Fun", "Happy")
+  #   list.add("Sad, Lonely", parse: true)
+  #   list # => ["Fun", "Happy", "Sad", "Lonely"]
+  #
+  # @!attribute [rw] owner
+  #   The tagger whose tags these are, when the list belongs to an owner.
+  #   @return [ActiveRecord::Base, NilClass]
+  # @!attribute [rw] parser
+  #   The parser used when this list is asked to parse a string.
+  #   @return [Class]
+  #
   class TagList < Array
     attr_accessor :owner
     attr_accessor :parser
 
+    ##
+    # Builds a tag list from the given names.
+    #
+    # @param args [Array<String, Symbol>] the tag names, optionally followed by an options hash
+    #   accepted by {#add}
+    # @return [MakeTaggable::TagList]
+    #
     def initialize(*args)
       @parser = MakeTaggable.default_parser
       add(*args)
     end
 
     ##
-    # Add tags to the tag_list. Duplicate or blank tags will be ignored.
-    # Use the <tt>:parse</tt> option to add an unparsed tag string.
+    # Adds tags to the list, ignoring duplicates and blanks.
+    #
+    # @param names [Array<String, Symbol>] the tags to add, optionally followed by an options hash
+    # @option names [TrueClass, FalseClass] :parse whether to parse the input as a delimited string
+    # @option names [Class] :parser a parser to use for this call only
+    # @return [MakeTaggable::TagList] self, so calls can be chained
     #
-    # Example:
+    # @example
     #   tag_list.add("Fun", "Happy")
-    #   tag_list.add("Fun, Happy", :parse => true)
+    #   tag_list.add("Fun, Happy", parse: true)
+    #
     def add(*names)
       extract_and_apply_options!(names)
       concat(names)
@@ -24,32 +57,48 @@ module MakeTaggable
       self
     end
 
-    # Append---Add the tag to the tag_list. This
-    # expression returns the tag_list itself, so several appends
-    # may be chained together.
+    ##
+    # Adds one tag to the list.
+    #
+    # @param obj [String, Symbol] the tag to add
+    # @return [MakeTaggable::TagList] self, so appends can be chained
+    #
     def <<(obj)
       add(obj)
     end
 
-    # Concatenation --- Returns a new tag list built by concatenating the
-    # two tag lists together to produce a third tag list.
+    ##
+    # Joins two tag lists into a third, leaving both untouched.
+    #
+    # @param other [Array<String>] the tags to append
+    # @return [MakeTaggable::TagList] a new list
+    #
     def +(other)
       TagList.new.add(self).add(other)
     end
 
-    # Appends the elements of +other_tag_list+ to +self+.
+    ##
+    # Appends another list's tags to this one.
+    #
+    # @param other_tag_list [Array<String>] the tags to append
+    # @return [MakeTaggable::TagList] self
+    #
     def concat(other_tag_list)
-      super(other_tag_list).send(:clean!)
+      super.send(:clean!)
       self
     end
 
     ##
-    # Remove specific tags from the tag_list.
-    # Use the <tt>:parse</tt> option to add an unparsed tag string.
+    # Removes tags from the list.
+    #
+    # @param names [Array<String, Symbol>] the tags to remove, optionally followed by an options
+    #   hash accepted by {#add}
+    # @return [MakeTaggable::TagList] self
     #
-    # Example:
+    # @example
     #   tag_list.remove("Sad", "Lonely")
-    #   tag_list.remove("Sad, Lonely", :parse => true)
+    #   tag_list.remove("Sad, Lonely", parse: true)
+    #
     def remove(*names)
       extract_and_apply_options!(names)
       delete_if { |name| names.include?(name) }
@@ -57,20 +106,24 @@ module MakeTaggable
     end
 
     ##
-    # Transform the tag_list into a tag string suitable for editing in a form.
-    # The tags are joined with <tt>TagList.delimiter</tt> and quoted if necessary.
+    # Renders the list as a delimited string, suitable for a form field.
+    #
+    # Tags containing the delimiter are quoted, so the string parses back into the same list.
+    #
+    # @return [String]
+    #
+    # @example
+    #   MakeTaggable::TagList.new("Round", "Square,Cube").to_s
+    #   # => 'Round, "Square,Cube"'
     #
-    # Example:
-    #   tag_list = TagList.new("Round", "Square,Cube")
-    #   tag_list.to_s # 'Round, "Square,Cube"'
     def to_s
       tags = frozen? ? dup : self
       tags.send(:clean!)
 
+      delimiter = Regexp.union(Array(MakeTaggable.delimiter))
+
       tags.map { |name|
-        d = MakeTaggable.delimiter
-        d = Regexp.new d.join("|") if d.is_a? Array
-        name.index(d) ? "\"#{name}\"" : name
+        name.index(delimiter) ? "\"#{name}\"" : name
       }.join(MakeTaggable.glue)
     end
 
@@ -81,7 +134,7 @@ module MakeTaggable
       reject!(&:blank?)
       map!(&:to_s)
       map!(&:strip)
-      map! { |tag| tag.mb_chars.downcase.to_s } if MakeTaggable.force_lowercase
+      map!(&:downcase) if MakeTaggable.force_lowercase
       map!(&:parameterize) if MakeTaggable.force_parameterize
 
       MakeTaggable.strict_case_match ? uniq! : uniq! { |tag| tag.downcase }

data/lib/make_taggable/taggable/cache.rb

@@ -1,22 +1,39 @@
+# frozen_string_literal: true
+
 module MakeTaggable::Taggable
+  ##
+  # Keeps a rendered copy of a tag list in a column on the taggable itself, so a list can be shown
+  # without loading its tags.
+  #
+  # Caching switches itself on for any context the model has a matching `cached_<context>_list`
+  # column for. Nothing else is required.
+  #
+  # @example Caching the default context
+  #   add_column :books, :cached_tag_list, :string
+  #
   module Cache
+    ##
+    # @param base [Class] the model being made taggable
+    # @return [void]
+    #
+    # @api private
+    #
     def self.included(base)
       # When included, conditionally adds tag caching methods when the model
       #   has any "cached_#{tag_type}_list" column
       base.extend Columns
     end
 
+    ##
+    # Intercepts the model's column lookup so caching can be wired up the first time the schema is
+    # known, without opening a database connection when the class is loaded.
+    #
     module Columns
-      # ActiveRecord::Base.columns makes a database connection and caches the
-      #   calculated columns hash for the record as @columns.  Since we don't
-      #   want to add caching methods until we confirm the presence of a
-      #   caching column, and we don't want to force opening a database
-      #   connection when the class is loaded, here we intercept and cache
-      #   the call to :columns as @make_taggable_cache_columns
-      #   to mimic the underlying behavior.  While processing this first
-      #   call to columns, we do the caching column check and dynamically add
-      #   the class and instance methods
-      #   FIXME: this method cannot compile in rubinius
+      ##
+      # The model's columns, injecting the caching methods the first time they are asked for.
+      #
+      # @return [Array<ActiveRecord::ConnectionAdapters::Column>]
+      #
       def columns
         @make_taggable_cache_columns ||= begin
           db_columns = super
@@ -25,6 +42,11 @@ module MakeTaggable::Taggable
         end
       end
 
+      ##
+      # Forgets the cached column lookup along with Active Record's own.
+      #
+      # @return [void]
+      #
       def reset_column_information
         super
         @make_taggable_cache_columns = nil
@@ -51,7 +73,15 @@ module MakeTaggable::Taggable
       end
     end
 
+    ##
+    # Added to a model once it has at least one caching column.
+    #
     module ClassMethods
+      ##
+      # Defines a `caching_<context>_list?` predicate for each context.
+      #
+      # @return [void]
+      #
       def initialize_tags_cache
         tag_types.map(&:to_s).each do |tag_type|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -62,17 +92,37 @@ module MakeTaggable::Taggable
         end
       end
 
+      ##
+      # Adds contexts and refreshes the caching predicates.
+      #
+      # @param args [Array<Symbol, String>] the contexts to add
+      # @return [void]
+      #
       def make_taggable(*args)
-        super(*args)
+        super
         initialize_tags_cache
       end
 
+      ##
+      # Whether a context's tag list is cached on the model.
+      #
+      # @param context [Symbol, String] the tagging context
+      # @return [TrueClass, FalseClass]
+      #
       def caching_tag_list_on?(context)
         column_names.include?("cached_#{context.to_s.singularize}_list")
       end
     end
 
+    ##
+    # Added to a model once it has at least one caching column.
+    #
     module InstanceMethods
+      ##
+      # Writes each cached tag list into its column. Runs before save.
+      #
+      # @return [TrueClass]
+      #
       def save_cached_tag_list
         tag_types.map(&:to_s).each do |tag_type|
           if self.class.send("caching_#{tag_type.singularize}_list?")