make_taggable 0.7.4 → 1.0.0

data/docs/ownership.md

@@ -0,0 +1,111 @@
+# Tag ownership
+
+A tag can be applied *by* someone. That someone is a tagger, and the tags they applied are owned by
+them. It is how you build "your tags" alongside everyone else's on the same record.
+
+## Declaring a tagger
+
+```ruby
+class User < ApplicationRecord
+  make_tagger
+end
+
+class Photo < ApplicationRecord
+  make_taggable :locations
+end
+```
+
+`make_tagger` adds two associations to the model: `owned_taggings` and `owned_tags`.
+
+## Applying owned tags
+
+```ruby
+user.tag(photo, with: "paris, normandy", on: :locations)
+```
+
+`with` and `on` are both required — `tag` raises without them. The taggable is saved for you unless
+you pass `skip_save: true`:
+
+```ruby
+user.tag(photo, with: "paris", on: :locations, skip_save: true)
+photo.save # when you're ready
+```
+
+By default you may tag in a context the model does not declare. Pass `force: false` to require a
+declared context:
+
+```ruby
+user.tag(photo, with: "paris", on: :undeclared, force: false)
+# => RuntimeError: No context :undeclared defined in Photo
+```
+
+## The one thing that surprises everyone
+
+**`tag_list` never returns owned tags.** It returns only tags with no owner.
+
+```ruby
+photo.tag_list        # => []           <- not what most people expect
+photo.all_tags_list   # => ["paris", "normandy"]
+```
+
+The same split applies per context: `location_list` excludes owned tags, `all_locations_list`
+includes them. If every tag on a record is applied by a tagger, `tag_list` will always look empty.
+
+So: use `all_*_list` to display what a record is tagged with, and `*_list` only when you
+specifically mean the unowned tags.
+
+## Reading owned tags
+
+```ruby
+photo.locations_from(user)              # => ["paris", "normandy"]
+photo.owner_tags_on(user, :locations)   # => [#<MakeTaggable::Tag name: "paris">, ...]
+photo.owner_tags_on(nil, :locations)    # => every tag on the photo, owned or not
+
+user.owned_taggings
+user.owned_tags
+```
+
+Find records by who tagged them:
+
+```ruby
+Photo.tagged_with("paris", on: :locations, owned_by: user)
+```
+
+## Owned tags are replaced, not appended
+
+Assigning an owner's tags overwrites everything that owner previously applied in that context:
+
+```ruby
+user.tag(photo, with: "paris", on: :locations)
+user.tag(photo, with: "normandy", on: :locations)
+
+photo.locations_from(user) # => ["normandy"]   <- "paris" is gone
+```
+
+To add to what is already there, read the current list and write it back with the addition:
+
+```ruby
+def add_owned_tag(photo, user, tag)
+  current = photo.locations_from(user)
+  user.tag(photo, with: (current + [tag]).join(", "), on: :locations)
+  photo.save
+end
+```
+
+And to remove one:
+
+```ruby
+def remove_owned_tag(photo, user, tag)
+  current = photo.locations_from(user)
+  user.tag(photo, with: (current - [tag]).join(", "), on: :locations)
+  photo.save
+end
+```
+
+Joining with `", "` matches the default delimiter. If you have configured a different one, use
+`MakeTaggable.glue` instead of a literal.
+
+## Ordering
+
+On a model declared with `make_ordered_taggable`, owned tags keep the order they were applied in,
+the same as unowned ones. See [contexts.md](contexts.md).

data/docs/parsers.md

@@ -0,0 +1,109 @@
+# Parsers and delimiters
+
+Every string that becomes a tag list goes through a parser. The default splits on commas and
+understands quoting.
+
+## The default parser
+
+```ruby
+MakeTaggable::DefaultParser.new("One , Two,  Three").parse
+# => ["One", "Two", "Three"]
+```
+
+A tag containing the delimiter can be quoted, with single or double quotes:
+
+```ruby
+MakeTaggable::DefaultParser.new('"Ruby, Rails", Hotwire').parse
+# => ["Ruby, Rails", "Hotwire"]
+```
+
+`TagList#to_s` quotes on the way back out, so a list survives a round trip through a text field:
+
+```ruby
+MakeTaggable::TagList.new("Round", "Square,Cube").to_s
+# => 'Round, "Square,Cube"'
+```
+
+## Delimiters
+
+The delimiter defaults to `","`. Set one, or several:
+
+```ruby
+MakeTaggable.delimiter = ";"
+MakeTaggable.delimiter = [",", "|", ";"]
+```
+
+**Delimiters are literal strings.** Regular expression metacharacters are escaped for you, so
+`"|"`, `"."` and `"("` all mean themselves:
+
+```ruby
+MakeTaggable.delimiter = [",", "|"]
+MakeTaggable::DefaultParser.new("a|b,c").parse # => ["a", "b", "c"]
+```
+
+> **Changed in 1.0.** Delimiters used to be interpolated into a pattern unescaped, which meant you
+> had to pass `'\|'` to split on a pipe, and a `"."` delimiter silently matched every character and
+> discarded the whole list. If you are passing pre-escaped delimiters, unescape them.
+
+`MakeTaggable.delimiter=` is deprecated in favour of a parser, and warns when Active Record has a
+logger. It still works, and reading `MakeTaggable.delimiter` is not deprecated.
+
+Related: `MakeTaggable.glue` is what tags are joined with for display. It is the first configured
+delimiter, with a trailing space added if it has none, which is why a comma delimiter renders as
+`"one, two"`.
+
+## Writing a parser
+
+Subclass `MakeTaggable::GenericParser` and implement `parse`, returning a `TagList`. The raw input
+is in `@tag_list`.
+
+```ruby
+class PipeParser < MakeTaggable::GenericParser
+  def parse
+    MakeTaggable::TagList.new.tap do |tag_list|
+      tag_list.add @tag_list.split("|")
+    end
+  end
+end
+```
+
+Use it for one call:
+
+```ruby
+user.tag_list.add("north|west", parser: PipeParser)
+```
+
+For one list:
+
+```ruby
+user.tag_list.parser = PipeParser
+user.tag_list.add("north|west")
+```
+
+Or everywhere:
+
+```ruby
+MakeTaggable.default_parser = PipeParser
+```
+
+The global setting is what `tag_list=` uses, so it is the only one of the three that changes how
+assignment behaves:
+
+```ruby
+MakeTaggable.default_parser = PipeParser
+user.tag_list = "east|south"
+user.tag_list # => ["east", "south"]
+```
+
+`GenericParser` is itself a working parser — it splits on commas, ignoring surrounding whitespace
+and empty entries — so subclass it when you want a different format, and use it directly when you
+want comma splitting without the quoting rules.
+
+## What happens after parsing
+
+Whatever a parser returns is cleaned before it is stored: entries are converted to strings,
+stripped of surrounding whitespace, and blanks and duplicates are dropped. Two settings also apply
+here — `force_lowercase` and `force_parameterize` — see [configuration.md](configuration.md).
+
+Duplicate detection follows `strict_case_match`: with it off, `"Ruby"` and `"ruby"` are the same
+tag; with it on, they are two.

data/docs/querying.md

@@ -0,0 +1,163 @@
+# Querying
+
+## `tagged_with`
+
+`tagged_with` returns a relation, so it chains with your own scopes, with `order`, and with
+pagination.
+
+```ruby
+User.tagged_with("awesome").by_join_date.limit(20)
+```
+
+By default every tag given must be present:
+
+```ruby
+User.tagged_with(["awesome", "cool"])              # carries awesome AND cool
+User.tagged_with(["awesome", "cool"], any: true)   # carries awesome OR cool
+User.tagged_with(["awesome", "cool"], exclude: true) # carries NEITHER
+```
+
+Passing nothing matches nothing. `User.tagged_with([])` and `User.tagged_with("")` both return an
+empty relation rather than every record — worth knowing when the tags come from user input.
+
+### Options
+
+| Option | Effect |
+|---|---|
+| `:any` | Match records carrying at least one of the tags |
+| `:exclude` | Match records carrying none of the tags |
+| `:match_all` | Match records carrying only these tags and no others |
+| `:wild` | Match tags *containing* the given text, i.e. `%awesome%` |
+| `:on` | Restrict to one context |
+| `:owned_by` | Restrict to tags applied by one tagger |
+| `:order_by_matching_tag_count` | With `:any`, order by how many tags matched, most first |
+| `:start_at` | Only tags applied after this time |
+| `:end_at` | Only tags applied before this time |
+
+`:wild` combines with `:any` or `:exclude`:
+
+```ruby
+User.tagged_with(["awe", "co"], any: true, wild: true)
+```
+
+Contexts are matched one call at a time, so chain to combine them:
+
+```ruby
+User
+  .tagged_with(["awesome", "cool"], on: :tags, any: true)
+  .tagged_with(["smart", "shy"], on: :skills, any: true)
+```
+
+### Case sensitivity
+
+Tag matching is case insensitive by default: `tagged_with("Ruby")` finds records tagged `"ruby"`.
+Set `MakeTaggable.strict_case_match = true` to match exactly. See
+[configuration.md](configuration.md), and the SQLite note in [database.md](database.md) — SQLite
+cannot change the case of non-ASCII characters without an extension.
+
+## Counting tags
+
+`tag_counts_on` returns tags with a `count` attribute, which is what tag clouds are built from.
+
+```ruby
+Book.tag_counts_on(:genres)
+book.tag_counts_on(:genres)      # just this book's genres
+Book.genre_counts                # the same, generated per context
+Book.top_genres(10)              # the ten most used, most first
+```
+
+`count` is an attribute on the returned tags, not a method call on the relation:
+
+```ruby
+Book.tag_counts_on(:genres).each do |tag|
+  puts "#{tag.name}: #{tag.count}"
+end
+```
+
+### `all_tags` and `all_tag_counts`
+
+The generated methods above are wrappers around these two, which take the full option set:
+
+```ruby
+Book.all_tag_counts(
+  on: :genres,
+  at_least: 5,
+  at_most: 100,
+  order: "count desc",
+  limit: 20,
+  start_at: 1.month.ago
+)
+```
+
+| Option | `all_tags` | `all_tag_counts` | Effect |
+|---|:--:|:--:|---|
+| `:on` | ✓ | ✓ | Restrict to one context |
+| `:start_at` | ✓ | ✓ | Only tags applied after this time |
+| `:end_at` | ✓ | ✓ | Only tags applied before this time |
+| `:conditions` | ✓ | ✓ | SQL conditions added to the tag query |
+| `:order` | ✓ | ✓ | SQL to order by |
+| `:limit` | ✓ | ✓ | Most tags to return |
+| `:at_least` | | ✓ | Skip tags used fewer times than this |
+| `:at_most` | | ✓ | Skip tags used more times than this |
+
+Use `all_tags` when you only need the names: it skips the join onto the taggable table, so it is
+noticeably cheaper on a large table.
+
+## Related records
+
+Records sharing tags with this one, ordered by how many tags matched:
+
+```ruby
+tom.skill_list      # => ["hacking", "jogging", "diving"]
+bobby.skill_list    # => ["jogging", "diving"]
+frankie.skill_list  # => ["hacking"]
+
+tom.find_related_skills     # => [bobby, frankie]
+bobby.find_related_skills   # => [tom]
+```
+
+Ignore some tags, or search a different model:
+
+```ruby
+tom.find_related_skills(ignore: ["jogging"])
+tom.find_related_skills_for(Company)
+```
+
+To match one context's tags against a different context's, use `find_matching_contexts`:
+
+```ruby
+# users whose :interests match this user's :skills
+user.find_matching_contexts(:skills, :interests)
+user.find_matching_contexts_for(Company, :skills, :markets)
+```
+
+Both return records carrying a `count` attribute holding the number of matching tags.
+
+## Tags directly
+
+`MakeTaggable::Tag` is an ordinary model, so query it when you want the vocabulary rather than the
+records:
+
+```ruby
+MakeTaggable::Tag.most_used            # default limit 20
+MakeTaggable::Tag.least_used(10)
+MakeTaggable::Tag.named("ruby")        # exact, honouring case sensitivity
+MakeTaggable::Tag.named_any(%w[ruby rails])
+MakeTaggable::Tag.named_like("rub")    # contains
+MakeTaggable::Tag.for_context(:skills) # used in this context, on any model
+```
+
+`most_used` and `least_used` read the `taggings_count` counter cache, so they do not aggregate at
+query time. If you set `MakeTaggable.tags_counter = false` that counter is not maintained and both
+scopes will be wrong.
+
+## Performance notes
+
+- `tagged_with` with several tags and no `:any` adds one join per tag. Matching a dozen tags in a
+  single call generates a dozen joins; prefer `any: true` where the semantics allow it.
+- `:order_by_matching_tag_count` adds a correlated subquery to the `ORDER BY`. It is fine for a
+  page of results and expensive across a whole table.
+- `all_tag_counts` joins the taggables to count them. Reach for `all_tags` when the counts are not
+  needed.
+- Caching a rendered list in a column avoids loading tags to display them. See
+  [caching.md](caching.md).

data/docs/tag-clouds.md

@@ -0,0 +1,74 @@
+# Tag clouds
+
+A tag cloud sizes each tag by how often it is used. MakeTaggable gives you the counts and a helper
+that maps them onto CSS classes.
+
+## Getting the counts
+
+```ruby
+class BooksController < ApplicationController
+  def tag_cloud
+    @tags = Book.tag_counts_on(:genres)
+  end
+end
+```
+
+`tag_counts_on` returns tags carrying a `count` attribute. Limit it to the tags worth showing:
+
+```ruby
+@tags = Book.all_tag_counts(on: :genres, at_least: 3, limit: 50, order: "count desc")
+```
+
+Counts also work per record and per association:
+
+```ruby
+book.tag_counts_on(:genres)
+user.books.tag_counts_on(:genres)
+```
+
+## The helper
+
+`MakeTaggable::TagsHelper` is mixed into Action View automatically, so `tag_cloud` is available in
+any view. It yields each tag with the CSS class matching its frequency, smallest class first:
+
+```erb
+<% tag_cloud(@tags, %w[cloud1 cloud2 cloud3 cloud4]) do |tag, css_class| %>
+  <%= link_to tag.name, books_path(tag: tag.name), class: css_class %>
+<% end %>
+```
+
+```css
+.cloud1 { font-size: 1.0em; }
+.cloud2 { font-size: 1.2em; }
+.cloud3 { font-size: 1.4em; }
+.cloud4 { font-size: 1.6em; }
+```
+
+The classes are spread across the range between the least and most used tag in the set you pass, so
+the same tag can land in a different band depending on what it is shown alongside.
+
+Two things to know:
+
+- `tag_cloud` requires a block, and returns an empty array without calling it when `@tags` is empty.
+- It reads `taggings_count`, not the `count` attribute from the query. That means it reflects how
+  often a tag is used **overall**, not how often within the scope you counted. For a cloud of one
+  user's tags, sizing by global popularity is usually not what you want — build the markup yourself
+  from `tag.count` in that case:
+
+```erb
+<% max = @tags.map(&:count).max.to_f %>
+<% @tags.each do |tag| %>
+  <%= link_to tag.name, books_path(tag: tag.name),
+        style: "font-size: #{1.0 + (tag.count / max)}em" %>
+<% end %>
+```
+
+## Using it outside Action View
+
+Include the module wherever you need it:
+
+```ruby
+module PostsHelper
+  include MakeTaggable::TagsHelper
+end
+```

data/lib/make_taggable/default_parser.rb

@@ -1,11 +1,26 @@
+# frozen_string_literal: true
+
 module MakeTaggable
   ##
-  # Returns a new TagList using the given tag string.
+  # The parser the library uses unless told otherwise.
+  #
+  # It splits on the configured delimiter, or delimiters, and understands quoting: a tag wrapped in
+  # single or double quotes may contain the delimiter itself.
+  #
+  # @example
+  #   MakeTaggable::DefaultParser.new("One , Two,  Three").parse
+  #   # => ["One", "Two", "Three"]
+  #
+  # @example A tag containing the delimiter
+  #   MakeTaggable::DefaultParser.new('"Ruby, Rails", Hotwire').parse
+  #   # => ["Ruby, Rails", "Hotwire"]
   #
-  # Example:
-  #   tag_list = MakeTaggable::DefaultParser.parse("One , Two,  Three")
-  #   tag_list # ["One", "Two", "Three"]
   class DefaultParser < GenericParser
+    ##
+    # Splits the input into tags, honouring quotes and every configured delimiter.
+    #
+    # @return [MakeTaggable::TagList] the parsed tags
+    #
     def parse
       string = @tag_list
 
@@ -33,41 +48,39 @@ module MakeTaggable
       end
     end
 
-    # private
+    ##
+    # The configured delimiters as a regular expression source, ready to interpolate into a pattern.
+    #
+    # @return [String]
+    #
+    # @api private
+    #
     def delimiter
-      # Parse the quoted tags
-      d = MakeTaggable.delimiter
-      # Separate multiple delimiters by bitwise operator
-      d = d.join("|") if d.is_a?(Array)
-      d
+      # Delimiters are literal strings, so any regular expression metacharacter
+      # they contain has to be escaped before it reaches a pattern. Regexp.union
+      # handles both the escaping and the alternation between multiple
+      # delimiters.
+      Regexp.union(Array(MakeTaggable.delimiter)).source
     end
 
-    # (             # Tag start delimiter ($1)
-    # \A       |  # Either string start or
-    # #{delimiter}        # a delimiter
-    # )
-    # \s*"          # quote (") optionally preceded by whitespace
-    # (.*?)         # Tag ($2)
-    # "\s*          # quote (") optionally followed by whitespace
-    # (?=           # Tag end delimiter (not consumed; is zero-length lookahead)
-    # #{delimiter}\s*  |  # Either a delimiter optionally followed by whitespace or
-    # \z          # string end
-    # )
+    ##
+    # Matches a double-quoted tag, bounded by the start of the string or a delimiter.
+    #
+    # @return [Regexp]
+    #
+    # @api private
+    #
     def double_quote_pattern
       /(\A|#{delimiter})\s*"(.*?)"\s*(?=#{delimiter}\s*|\z)/
     end
 
-    # (             # Tag start delimiter ($1)
-    # \A       |  # Either string start or
-    # #{delimiter}        # a delimiter
-    # )
-    # \s*'          # quote (') optionally preceded by whitespace
-    # (.*?)         # Tag ($2)
-    # '\s*          # quote (') optionally followed by whitespace
-    # (?=           # Tag end delimiter (not consumed; is zero-length lookahead)
-    # #{delimiter}\s*  | d # Either a delimiter optionally followed by whitespace or
-    # \z          # string end
-    # )
+    ##
+    # Matches a single-quoted tag, bounded by the start of the string or a delimiter.
+    #
+    # @return [Regexp]
+    #
+    # @api private
+    #
     def single_quote_pattern
       /(\A|#{delimiter})\s*'(.*?)'\s*(?=#{delimiter}\s*|\z)/
     end

data/lib/make_taggable/engine.rb

@@ -1,4 +1,10 @@
+# frozen_string_literal: true
+
 module MakeTaggable
+  ##
+  # Mounts the gem's migrations into a host Rails application, so they can be installed with
+  # `rails make_taggable_engine:install:migrations`.
+  #
   class Engine < Rails::Engine
   end
 end

data/lib/make_taggable/generic_parser.rb

@@ -1,15 +1,41 @@
+# frozen_string_literal: true
+
 module MakeTaggable
   ##
-  # Returns a new TagList using the given tag string.
+  # The base class for tag parsers, and a working parser in its own right: it splits on commas and
+  # ignores surrounding whitespace.
+  #
+  # Subclass it to accept a different format, and point {MakeTaggable::Configuration#default_parser}
+  # at the subclass, or pass it per call as the `:parser` option to {MakeTaggable::TagList#add}.
+  #
+  # @example A parser splitting on pipes
+  #   class PipeParser < MakeTaggable::GenericParser
+  #     def parse
+  #       MakeTaggable::TagList.new.tap do |tag_list|
+  #         tag_list.add @tag_list.split("|")
+  #       end
+  #     end
+  #   end
   #
-  # Example:
-  # tag_list = MakeTaggable::GenericParser.new.parse("One , Two, Three")
-  # tag_list # ["One", "Two", "Three"]
   class GenericParser
+    ##
+    # Holds the input until {#parse} is called.
+    #
+    # @param tag_list [String, Array<String>, MakeTaggable::TagList] the tag input to parse
+    # @return [MakeTaggable::GenericParser]
+    #
     def initialize(tag_list)
       @tag_list = tag_list
     end
 
+    ##
+    # Splits the input on commas.
+    #
+    # @return [MakeTaggable::TagList] the parsed tags
+    #
+    # @example
+    #   MakeTaggable::GenericParser.new("One , Two, Three").parse # => ["One", "Two", "Three"]
+    #
     def parse
       TagList.new.tap do |tag_list|
         tag_list.add @tag_list.split(",").map(&:strip).reject(&:empty?)