acts-as-taggable-on 2.0.0.rc2 → 2.0.0

data/README.rdoc

@@ -71,7 +71,9 @@ rake spec:plugins
 = Usage
 
     class User < ActiveRecord::Base
-      acts_as_taggable_on :tags, :skills, :interests
+      # Alias for <tt>acts_as_taggable_on :tags</tt>:
+      acts_as_taggable
+      acts_as_taggable_on :skills, :interests
     end
 
     @user = User.new(:name => "Bobby")

data/VERSION

@@ -1 +1 @@
-2.0.0.rc2
+2.0.0

data/lib/acts_as_taggable_on/acts_as_taggable_on.rb

@@ -4,20 +4,32 @@ module ActsAsTaggableOn
       false
     end
 
+    ##
+    # This is an alias for calling <tt>acts_as_taggable_on :tags</tt>.
+    #
+    # Example:
+    #   class Book < ActiveRecord::Base
+    #     acts_as_taggable
+    #   end
     def acts_as_taggable
       acts_as_taggable_on :tags
     end
 
+    ##
+    # Make a model taggable on specified contexts.
+    #
+    # @param [Array] tag_types An array of taggable contexts
+    #
+    # Example:
+    #   class User < ActiveRecord::Base
+    #     acts_as_taggable_on :languages, :skills
+    #   end
     def acts_as_taggable_on(*tag_types)
       tag_types = tag_types.to_a.flatten.compact.map(&:to_sym)
 
       if taggable?
         write_inheritable_attribute(:tag_types, (self.tag_types + tag_types).uniq)
       else
-        if ::ActiveRecord::VERSION::MAJOR < 3
-          include ActsAsTaggableOn::ActiveRecord::Backports
-        end
-
         write_inheritable_attribute(:tag_types, tag_types)
         class_inheritable_reader(:tag_types)
         

data/lib/acts_as_taggable_on/acts_as_taggable_on/collection.rb

@@ -38,17 +38,18 @@ module ActsAsTaggableOn::Taggable
         all_tag_counts(options.merge({:on => context.to_s}))
       end
       
+      ##
       # Calculate the tag counts for all tags.
       #
-      # Options:
-      #  :start_at - Restrict the tags to those created after a certain time
-      #  :end_at - Restrict the tags to those created before a certain time
-      #  :conditions - A piece of SQL conditions to add to the query
-      #  :limit - The maximum number of tags to return
-      #  :order - A piece of SQL to order by. Eg 'tags.count desc' or 'taggings.created_at desc'
-      #  :at_least - Exclude tags with a frequency less than the given value
-      #  :at_most - Exclude tags with a frequency greater than the given value
-      #  :on - Scope the find to only include a certain context
+      # @param [Hash] options Options:
+      #                       * :start_at   - Restrict the tags to those created after a certain time
+      #                       * :end_at     - Restrict the tags to those created before a certain time
+      #                       * :conditions - A piece of SQL conditions to add to the query
+      #                       * :limit      - The maximum number of tags to return
+      #                       * :order      - A piece of SQL to order by. Eg 'tags.count desc' or 'taggings.created_at desc'
+      #                       * :at_least   - Exclude tags with a frequency less than the given value
+      #                       * :at_most    - Exclude tags with a frequency greater than the given value
+      #                       * :on         - Scope the find to only include a certain context
       def all_tag_counts(options = {})
         options.assert_valid_keys :start_at, :end_at, :conditions, :at_least, :at_most, :order, :limit, :on, :id
 

data/lib/acts_as_taggable_on/acts_as_taggable_on/core.rb

@@ -51,6 +51,20 @@ module ActsAsTaggableOn::Taggable
         object.column_names.map { |column| "#{object.table_name}.#{column}" }.join(", ")
       end
 
+      ##
+      # Return a scope of objects that are tagged with the specified tags.
+      #
+      # @param tags The tags that we want to query for
+      # @param [Hash] options A hash of options to alter you query:
+      #                       * <tt>:exclude</tt> - if set to true, return objects that are *NOT* tagged with the specified tags
+      #                       * <tt>:any</tt> - if set to true, return objects that are tagged with *ANY* of the specified tags
+      #                       * <tt>:match_all</tt> - if set to true, return objects that are *ONLY* tagged with the specified tags
+      #
+      # Example:
+      #   User.tagged_with("awesome", "cool")                     # Users that are tagged with awesome and cool
+      #   User.tagged_with("awesome", "cool", :exclude => true)   # Users that are not tagged with awesome or cool
+      #   User.tagged_with("awesome", "cool", :any => true)       # Users that are tagged with awesome or cool
+      #   User.tagged_with("awesome", "cool", :match_all => true) # Users that are tagged with just awesome and cool
       def tagged_with(tags, options = {})
         tag_list = TagList.from(tags)
 
@@ -100,7 +114,10 @@ module ActsAsTaggableOn::Taggable
         end
 
 
-        joins(joins.join(" ")).group(group).where(conditions.join(" AND ")).readonly(false)
+        scoped(:joins      => joins.join(" "),
+               :group      => group,
+               :conditions => conditions.join(" AND "),
+               :readonly   => false)
       end
 
       def is_taggable?

data/lib/acts_as_taggable_on/acts_as_taggable_on/related.rb

@@ -42,10 +42,10 @@ module ActsAsTaggableOn::Taggable
         exclude_self = "#{klass.table_name}.id != #{id} AND" if self.class == klass
         
         klass.scoped({ :select     => "#{klass.table_name}.*, COUNT(#{Tag.table_name}.id) AS count",
-                 :from       => "#{klass.table_name}, #{Tag.table_name}, #{Tagging.table_name}",
-                 :conditions => ["#{exclude_self} #{klass.table_name}.id = #{Tagging.table_name}.taggable_id AND #{Tagging.table_name}.taggable_type = '#{klass.to_s}' AND #{Tagging.table_name}.tag_id = #{Tag.table_name}.id AND #{Tag.table_name}.name IN (?) AND #{Tagging.table_name}.context = ?", tags_to_find, result_context],
-                 :group      => grouped_column_names_for(klass),
-                 :order      => "count DESC" }.update(options))
+                       :from       => "#{klass.table_name}, #{Tag.table_name}, #{Tagging.table_name}",
+                       :conditions => ["#{exclude_self} #{klass.table_name}.id = #{Tagging.table_name}.taggable_id AND #{Tagging.table_name}.taggable_type = '#{klass.to_s}' AND #{Tagging.table_name}.tag_id = #{Tag.table_name}.id AND #{Tag.table_name}.name IN (?) AND #{Tagging.table_name}.context = ?", tags_to_find, result_context],
+                       :group      => grouped_column_names_for(klass),
+                       :order      => "count DESC" }.update(options))
       end
       
       def related_tags_for(context, klass, options = {})
@@ -54,10 +54,10 @@ module ActsAsTaggableOn::Taggable
         exclude_self = "#{klass.table_name}.id != #{id} AND" if self.class == klass
 
         klass.scoped({ :select     => "#{klass.table_name}.*, COUNT(#{Tag.table_name}.id) AS count",
-                 :from       => "#{klass.table_name}, #{Tag.table_name}, #{Tagging.table_name}",
-                 :conditions => ["#{exclude_self} #{klass.table_name}.id = #{Tagging.table_name}.taggable_id AND #{Tagging.table_name}.taggable_type = '#{klass.to_s}' AND #{Tagging.table_name}.tag_id = #{Tag.table_name}.id AND #{Tag.table_name}.name IN (?)", tags_to_find],
-                 :group      => grouped_column_names_for(klass),
-                 :order      => "count DESC" }.update(options))
+                       :from       => "#{klass.table_name}, #{Tag.table_name}, #{Tagging.table_name}",
+                       :conditions => ["#{exclude_self} #{klass.table_name}.id = #{Tagging.table_name}.taggable_id AND #{Tagging.table_name}.taggable_type = '#{klass.to_s}' AND #{Tagging.table_name}.tag_id = #{Tag.table_name}.id AND #{Tag.table_name}.name IN (?)", tags_to_find],
+                       :group      => grouped_column_names_for(klass),
+                       :order      => "count DESC" }.update(options))
       end
     end
   end

data/lib/acts_as_taggable_on/acts_as_tagger.rb

@@ -5,10 +5,20 @@ module ActsAsTaggableOn
     end
 
     module ClassMethods
+      ##
+      # Make a model a tagger. This allows an instance of a model to claim ownership
+      # of tags.
+      #
+      # Example:
+      #   class User < ActiveRecord::Base
+      #     acts_as_tagger
+      #   end
       def acts_as_tagger(opts={})
-        has_many :owned_taggings, opts.merge(:as => :tagger, :dependent => :destroy,
-                                             :include => :tag, :class_name => "Tagging")
-        has_many :owned_tags, :through => :owned_taggings, :source => :tag, :uniq => true
+        class_eval do
+          has_many :owned_taggings, opts.merge(:as => :tagger, :dependent => :destroy,
+                                               :include => :tag, :class_name => "Tagging")
+          has_many :owned_tags, :through => :owned_taggings, :source => :tag, :uniq => true
+        end
 
         include ActsAsTaggableOn::Tagger::InstanceMethods
         extend ActsAsTaggableOn::Tagger::SingletonMethods
@@ -20,6 +30,16 @@ module ActsAsTaggableOn
     end
 
     module InstanceMethods
+      ##
+      # Tag a taggable model with tags that are owned by the tagger. 
+      #
+      # @param taggable The object that will be tagged
+      # @param [Hash] options An hash with options. Available options are:
+      #               * <tt>:with</tt> - The tags that you want to
+      #               * <tt>:on</tt>   - The context on which you want to tag
+      #
+      # Example:
+      #   @user.tag(@photo, :with => "paris, normandy", :on => :locations)
       def tag(taggable, opts={})
         opts.reverse_merge!(:force => true)
 

data/lib/acts_as_taggable_on/tag_list.rb

@@ -1,21 +1,40 @@
 class TagList < Array
 
   cattr_accessor :delimiter
-
   self.delimiter = ','
 
+  attr_accessor :owner
+
   def initialize(*args)
     add(*args)
   end
+  
+  ##
+  # Returns a new TagList using the given tag string.
+  #
+  # Example:
+  #   tag_list = TagList.from("One , Two,  Three")
+  #   tag_list # ["One", "Two", "Three"]
+  def self.from(string)
+    string = string.join(", ") if string.respond_to?(:join)
 
-  attr_accessor :owner
+    new.tap do |tag_list|
+      string = string.to_s.dup
+
+      # Parse the quoted tags
+      string.gsub!(/(\A|#{delimiter})\s*"(.*?)"\s*(#{delimiter}\s*|\z)/) { tag_list << $2; $3 }
+      string.gsub!(/(\A|#{delimiter})\s*'(.*?)'\s*(#{delimiter}\s*|\z)/) { tag_list << $2; $3 }
 
+      tag_list.add(string.split(delimiter))
+    end
+  end
+
+  ##
   # Add tags to the tag_list. Duplicate or blank tags will be ignored.
-  #
-  #   tag_list.add("Fun", "Happy")
-  #
   # Use the <tt>:parse</tt> option to add an unparsed tag string.
   #
+  # Example:
+  #   tag_list.add("Fun", "Happy")
   #   tag_list.add("Fun, Happy", :parse => true)
   def add(*names)
     extract_and_apply_options!(names)
@@ -24,12 +43,12 @@ class TagList < Array
     self
   end
 
+  ##
   # Remove specific tags from the tag_list.
+  # Use the <tt>:parse</tt> option to add an unparsed tag string.
   #
+  # Example:
   #   tag_list.remove("Sad", "Lonely")
-  #
-  # Like #add, the <tt>:parse</tt> option can be used to remove multiple tags in a string.
-  #
   #   tag_list.remove("Sad, Lonely", :parse => true)
   def remove(*names)
     extract_and_apply_options!(names)
@@ -37,9 +56,11 @@ class TagList < Array
     self
   end
 
+  ##
   # Transform the tag_list into a tag string suitable for edting in a form.
   # The tags are joined with <tt>TagList.delimiter</tt> and quoted if necessary.
   #
+  # Example:
   #   tag_list = TagList.new("Round", "Square,Cube")
   #   tag_list.to_s # 'Round, "Square,Cube"'
   def to_s
@@ -51,7 +72,8 @@ class TagList < Array
     end.join(delimiter.ends_with?(" ") ? delimiter : "#{delimiter} ")
   end
 
- private
+  private
+  
   # Remove whitespace, duplicates, and blanks.
   def clean!
     reject!(&:blank?)
@@ -70,26 +92,4 @@ class TagList < Array
     args.flatten!
   end
 
-  class << self
-
-    # Returns a new TagList using the given tag string.
-    #
-    #   tag_list = TagList.from("One , Two,  Three")
-    #   tag_list # ["One", "Two", "Three"]
-    def from(string)
-      string = string.join(", ") if string.respond_to?(:join)
-
-      new.tap do |tag_list|
-        string = string.to_s.dup
-
-        # Parse the quoted tags
-        string.gsub!(/(\A|#{delimiter})\s*"(.*?)"\s*(#{delimiter}\s*|\z)/) { tag_list << $2; $3 }
-        string.gsub!(/(\A|#{delimiter})\s*'(.*?)'\s*(#{delimiter}\s*|\z)/) { tag_list << $2; $3 }
-
-        tag_list.add(string.split(delimiter))
-      end
-    end
-
-  end
-
 end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: acts-as-taggable-on
 version: !ruby/object:Gem::Version 
-  prerelease: true
+  prerelease: false
   segments: 
   - 2
   - 0
   - 0
-  - rc2
-  version: 2.0.0.rc2
+  version: 2.0.0
 platform: ruby
 authors: 
 - Michael Bleigh
@@ -84,13 +83,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: