has_machine_tags 0.1.6

data/CHANGELOG.rdoc

@@ -0,0 +1,19 @@
+== 0.1.6
+* Release to rubyforge
+* Allow default_predicates to be a proc
+
+== 0.1.5
+* Added finder tests
+* Added some helper methods
+
+== 0.1.4
+* Added console option and methods
+* Bug fix for init.rb
+
+== 0.1.3
+* Added quick mode
+* Added machine tag finders
+* Added reverse_has_many option
+
+== 0.1.0
+* Initial release

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT LICENSE
+
+Copyright (c) 2009 Gabriel Horner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,143 @@
+== Description
+
+This plugin implements Flickr's machine tags as explained
+here[http://www.flickr.com/groups/api/discuss/72157594497877875]
+while still maintaining standard tagging behavior.
+
+Basically, a machine tag has a namespace, a predicate and a value in the format
+    [namespace]:[predicate]=[value] 
+
+This allows for more precise tagging as tags can have unlimited contexts provided
+by combinations of namespaces and predicates. These unlimited contexts also make
+machine tags ripe for modeling relationships between objects. Read the HasMachineTags::TagMethods class
+documentation for a more thorough explanation.
+
+A demo app using this plugin is {here}[http://github.com/cldwalker/tag-tree].
+
+== Install
+
+Install as a gem
+
+    bash> gem install has_machine_tags
+
+    # add in your environment.rb
+    config.gem "has_machine_tags"
+
+Or as a plugin
+
+    bash> script/plugin install git://github.com/cldwalker/has_machine_tags.git
+
+
+Migrate your database from Rails root:
+  
+    bash> script/generate has_machine_tags_migration
+    bash> rake db:migrate
+
+== Usage
+
+Setup a model to use has_machine_tags
+
+  class Url < ActiveRecord::Base
+    has_machine_tags
+  end
+
+Let's create some urls with machine tags!
+
+    url = Url.create(:name=>"http://github.com/cldwalker/has_machine_tags",
+      :tag_list=>'gem:type=tagging,flickr')
+
+    url2 = Url.create(:name=>"http://github.com/giraffesoft/is_taggable",
+      :tag_list=>'gem:type=tagging, gem:user=giraffesoft')
+
+    url3 = Url.create(:name=>"http://github.com/datamapper/data_mapper/tree/master",
+      :tag_list=>'gem:type=orm')
+
+    url.tag_list # => ["gem:type=tagging", "flickr"]
+    
+    url.tags # => [<Tag name:"gem:type=tagging">, <Tag name:"flickr">]
+
+Let's query them:
+
+    # Query urls tagged as a gem having type tagging
+    Url.tagged_with 'gem:type=tagging'  # => [url, url2] from above
+
+    # Non-machine tags work of course
+    Url.tagged_with 'flickr'  # => [url] from above
+
+    # tagged_with() is a named_scope so do your sweet chaining
+    Url.tagged_with('flickr').yet_another_finder(:sweet).paginate(:per_page=>30)
+
+Nothing interesting so far. We could've done the same with normal tagging.
+
+But when we start with wildcard machine tag syntax, machine tags become more valuable:
+
+    # Query urls tagged as gems (namespace = 'gem')
+    Url.tagged_with 'gem:'  # => [url, url2, url3] from above
+
+    # Query urls tagged as having a user, regardless of namespace and value (predicate = 'user')
+    Url.tagged_with 'user='  # => [url2] from above
+
+    # Query urls tagged as gems having a user ( namespace ='gem' AND predicate = 'user')
+    Url.tagged_with 'gem:user'  # => [url2] from above
+
+    # Query urls tagged as having a tagging value, regardless of namespace and predicate (value = 'tagging')
+    Url.tagged_with '=tagging'  # => [url, url2] from above
+
+More details on machine tag syntax can be found in the Tag class.
+
+=== More Usage
+
+The wildcard machine tag syntax can also be used to fetch tags:
+
+    # Tags that are gems
+    Tag.machine_tags 'gem:' # => [<Tag name:"gem:type=tagging">, <Tag name:"gem:user=giraffesoft">]
+
+    # Tags that have a user predicate
+    Tag.machine_tags 'user=' # => [<Tag name:"gem:user=giraffesoft">]
+
+Of course you can do the standard tag_list manipulation:
+
+    url.tag_list = "comma, delimited"
+    url.save
+    url.tag_list # =>['comma', 'delimited']
+
+    url.tag_list = ['or', 'an', 'array']
+    url.save
+    url.tag_list # =>['or', 'an' 'array']
+
+    #Add a tag
+    url.tag_list << 'another_tag' 
+    url.save
+    url.tag_list # => ["gem:type=tagging", "flickr", "another_tag']
+
+    #Delete a tag
+    url.tag_list.delete('another_tag')
+    url.save
+    url.tag_list # => ["gem:type=tagging", "flickr"]
+
+
+== Caveats
+
+This is an experiment in progress so the api is subject to change.
+
+Since machine tags require special characters to implement its goodness,
+these characters are off limit unless used in the machine tag context:
+
+  '.', ':' , '*' , '=' , ','
+
+== Todo
+
+* Add a match_all option to tagged_with().
+* More helper methods ie for showing relations between namespaces, predicates + values
+* Possible add support for other ORM's ie DataMapper.
+* Play friendly with other tagging plugins as needed.
+
+== Issues
+Please report them {on github}[http://github.com/cldwalker/has_machine_tags/issues].
+
+== Credits
+
+Thanks goes to Flickr for popularizing this tagging model.
+Thanks also goes to the {acts-as-taggable-on plugin}[http://github.com/mbleigh/acts-as-taggable-on/tree/master]
+for their finder code and the {is_taggable plugin}[http://github.com/giraffesoft/is_taggable/tree/master]
+for demonstrating sane testing for a Rails plugin.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts = ["-T -x '/Library/Ruby/*'"]
+    t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available. Install it for rcov-related tasks with: sudo gem install rcov"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "has_machine_tags"
+    s.summary = "A rails tagging plugin implementing flickr's machine tags + maybe more (semantic tags)."
+    s.description = "This plugin implements Flickr's machine tags while still maintaining standard tagging behavior. This allows for more precise tagging as tags can have unlimited contexts provided by combinations of namespaces and predicates. These unlimited contexts also make machine tags ripe for modeling relationships between objects."
+    s.email = "gabriel.horner@gmail.com"
+    s.homepage = "http://tagaholic.me/has_machine_tags/"
+    s.authors = ["Gabriel Horner"]
+    s.rubyforge_project = ['tagaholic']
+    s.has_rdoc = true
+    s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+    s.files = FileList["CHANGELOG.rdoc", "README.rdoc", "LICENSE.txt", "init.rb", "Rakefile", "VERSION.yml", "{rails,generators,bin,lib,test}/**/*"]
+  end
+
+rescue LoadError
+  puts "Jeweler not available. Install it for jeweler-related tasks with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'test'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 6

data/generators/has_machine_tags_migration/has_machine_tags_migration_generator.rb

@@ -0,0 +1,7 @@
+class HasMachineTagsMigrationGenerator < Rails::Generator::Base 
+  def manifest 
+    record do |m| 
+      m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => "has_machine_tags_migration"
+    end
+  end
+end

data/generators/has_machine_tags_migration/templates/migration.rb

@@ -0,0 +1,26 @@
+class HasMachineTagsMigration < ActiveRecord::Migration
+  def self.up
+    create_table :tags do |t|
+      t.string :name
+      t.string :namespace
+      t.string :predicate
+      t.string :value
+      t.datetime :created_at
+    end
+    
+    create_table :taggings do |t|
+      t.integer :tag_id
+      t.integer :taggable_id
+      t.string :taggable_type
+      t.datetime :created_at
+    end
+    
+    add_index :taggings, :tag_id
+    add_index :taggings, [:taggable_id, :taggable_type]
+  end
+  
+  def self.down
+    drop_table :taggings
+    drop_table :tags
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'rails', 'init.rb')

data/lib/has_machine_tags/console.rb

@@ -0,0 +1,44 @@
+module HasMachineTags
+  # Methods for console/irb use.
+  module Console
+    module InstanceMethods
+      # Removes first list, adds second list and saves changes.
+      def tag_add_and_remove(remove_list, add_list)
+        self.class.transaction do
+          tag_add_and_save(add_list)
+          tag_remove_and_save(remove_list)
+        end
+      end
+
+      # Adds given list and saves.
+      def tag_add_and_save(add_list)
+        self.tag_list = self.tag_list + current_tag_list(add_list)
+        self.save
+        self.tag_list
+      end
+      
+      # Removes given list and saves.
+      def tag_remove_and_save(remove_list)
+        self.tag_list = self.tag_list - current_tag_list(remove_list)
+        self.save
+        self.tag_list
+      end
+      
+      # Resets tag_list to given tag_list and saves.
+      def tag_and_save(tag_list)
+        self.tag_list = tag_list
+        self.save
+        self.tag_list
+      end
+    end
+    
+    module ClassMethods
+      # Updates items tagged with an old tag to use the given new tag in place of the old tag.
+      def find_and_change_tag(old_tag, new_tag)
+        results = tagged_with(old_tag)
+        results.each {|e| e.tag_add_and_remove(old_tag, new_tag)}
+        puts "Changed tag for #{results.length} records"
+      end
+    end
+  end
+end

data/lib/has_machine_tags/finder.rb

@@ -0,0 +1,91 @@
+module HasMachineTags
+  module Finder
+    # Takes a string of delimited tags or an array of tags.
+    # Note that each tag is interpreted as a possible wildcard machine tag.
+    # 
+    # Options:
+    #   :conditions - A piece of SQL conditions to add to the query.
+    #
+    # Example:
+    #  Url.tagged_with 'something' # => fetches urls tagged with 'something'
+    #  Url.tagged_with 'gem:'      # => fetches urls tagged with tags that have namespace gem
+    #  Url.tagged_with 'gem, something' # =>  fetches urls that are tagged with 'something'
+    #    or 'gem'
+    #   
+    #  Note: This method really only needs to be used with Rails < 2.1 . 
+    #  Rails 2.1 and greater should use tagged_with(), which acts the same but with
+    #  the benefits of named_scope.
+    #
+    def find_tagged_with(*args)
+      options = find_options_for_tagged_with(*args)
+      options.blank? ? [] : find(:all,options)
+    end
+    
+    # :stopdoc:
+    def find_options_for_tagged_with(tags, options = {})
+      tags = TagList.new(tags)
+      return {} if tags.empty?
+      conditions = []
+      conditions << sanitize_sql(options.delete(:conditions)) if options[:conditions]
+      conditions << condition_from_tags(tags)
+      default_find_options_for_tagged_with.update(:conditions=>conditions.join(" AND ")).update(options)
+    end
+    
+    def condition_from_tags(tags)
+      tag_sql = tags.map {|t|
+        if match = Tag.match_wildcard_machine_tag(t)
+          string = match.map {|k,v|
+            sanitize_sql(["#{tags_alias}.#{k} = ?", v])
+          }.join(" AND ")
+          "(#{string})"
+        else
+          sanitize_sql(["#{tags_alias}.name = ?", t])
+        end
+      }.join(" OR ")
+    end
+    
+    def taggings_alias
+      "#{table_name}_taggings"
+    end
+    
+    def tags_alias
+      "#{table_name}_tags"
+    end
+      
+    def default_find_options_for_tagged_with
+      { :select => "DISTINCT #{table_name}.*",
+        :joins => "LEFT OUTER JOIN #{Tagging.table_name} #{taggings_alias} ON #{taggings_alias}.taggable_id = #{table_name}.#{primary_key} AND #{taggings_alias}.taggable_type = #{quote_value(base_class.name)} " +
+                  "LEFT OUTER JOIN #{Tag.table_name} #{tags_alias} ON #{tags_alias}.id = #{taggings_alias}.tag_id",
+        # :group      => group
+      }
+    end
+    
+    # TODO: add back in options as needed.
+    # Options:
+    #   :exclude - Find models that are not tagged with the given tags.
+    #   :match_all - Find models that match all of the given tags, not just one (doesn't work with machine tags yet).
+    def old_find_options_for_find_tagged_with(tags, options = {}) #:nodoc:
+      # options.reverse_merge!(:match_all=>true)
+      machine_tag_used = false
+      if options.delete(:exclude)
+        tags_conditions = tags.map { |t| sanitize_sql(["#{Tag.table_name}.name = ?", t]) }.join(" OR ")
+        conditions << sanitize_sql(["#{table_name}.id NOT IN (SELECT #{Tagging.table_name}.taggable_id FROM #{Tagging.table_name} LEFT OUTER JOIN #{Tag.table_name} ON #{Tagging.table_name}.tag_id = #{Tag.table_name}.id WHERE (#{tags_conditions}) AND #{Tagging.table_name}.taggable_type = #{quote_value(base_class.name)})", tags])
+      else
+        conditions << condition_from_tags(tags)
+        
+        if options.delete(:match_all)
+          group = "#{taggings_alias}.taggable_id HAVING COUNT(#{taggings_alias}.taggable_id) = "
+          if machine_tag_used
+            #Since a machine tag matches multiple tags per given tag, we need to dynamically calculate the count
+            #TODO: this select needs to return differently for each taggable_id
+            group += "(SELECT count(id) FROM #{Tag.table_name} #{tags_alias} WHERE #{tag_sql})"
+          else
+            group += tags.size.to_s
+          end
+        end
+      end
+      default_find_options_for_tagged_with.update(:conditions=>conditions.join(" AND ")).update(options)
+    end
+    # :startdoc:
+  end
+end

data/lib/has_machine_tags/tag.rb

@@ -0,0 +1,3 @@
+class ::Tag < ActiveRecord::Base #:nodoc:
+  include HasMachineTags::TagMethods
+end

data/lib/has_machine_tags/tag_console.rb

@@ -0,0 +1,32 @@
+module HasMachineTags
+  module TagConsole #:nodoc:
+    def self.included(base)
+      base.class_eval %[
+        named_scope :namespace_counts, :select=>'*, namespace as counter, count(namespace) as count', :group=>"namespace HAVING count(namespace)>=1"
+        named_scope :predicate_counts, :select=>'*, predicate as counter, count(predicate) as count', :group=>"predicate HAVING count(predicate)>=1"
+        named_scope :value_counts, :select=>'*, value as counter, count(value) as count', :group=>"value HAVING count(value)>=1"
+        named_scope :distinct_namespaces, :select=>"distinct namespace"
+        named_scope :distinct_predicates, :select=>"distinct predicate"
+        named_scope :distinct_values, :select=>"distinct value"
+      ]
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      #:stopdoc:
+      def namespaces; distinct_namespaces.map(&:namespace).compact; end
+      def predicates; distinct_predicates.map(&:predicate).compact; end
+      def values; distinct_values.map(&:value).compact; end
+      #:startdoc:
+  
+      # To be used with the *counts methods.
+      # For example:
+      #   stat(:namespace_counts) 
+      # This prints out pairs of a namespaces and their counts in the tags table.
+      def stat(type)
+        shortcuts = {:n=>:namespace_counts, :p=>:predicate_counts, :v=>:value_counts }
+        send(shortcuts[type] || type).map {|e| [e.counter, e.count] }
+      end
+    end
+  end
+end

data/lib/has_machine_tags/tag_list.rb

@@ -0,0 +1,69 @@
+module HasMachineTags
+  class TagList < Array
+    cattr_accessor :delimiter
+    self.delimiter = ','
+    cattr_accessor :default_predicate
+    self.default_predicate = 'tags'
+    QUICK_MODE_DELIMITER = ';'
+  
+    # ==== Options:
+    # [:quick_mode]  
+    #   When true enables a quick mode for inputing multiple machine tags under the same namespace.
+    #   These machine tags are delimited by QUICK_MODE_DELIMITER. If a predicate is not specified, default_predicate() is used.
+    #     Examples:
+    #     # Namespace is added to tag 'type=test'.
+    #     HasMachineTags::TagList.new("gem:name=flog;type=test, user:name=seattlerb", :quick_mode=>true)
+    #     => ["gem:name=flog", "gem:type=test", "user:name=seattlerb"]
+    #
+    #     # Namespace and default predicate (tags) are added to tag 'git'.
+    #     HasMachineTags::TagList.new("gem:name=grit;git, user:name=mojombo")
+    #     => ["gem:name=grit", "gem:tags=git", "user:name=mojombo"]
+    def initialize(string_or_array, options={})
+      @options = options
+      array = string_or_array.is_a?(Array) ? string_or_array : string_or_array.split(/\s*#{delimiter}\s*/)
+      array = parse_quick_mode(array) if @options[:quick_mode]
+      concat array
+    end
+
+    def parse_quick_mode(mtag_list) #:nodoc:
+      mtag_list = mtag_list.map {|e|
+        if e.include?(Tag::PREDICATE_DELIMITER)
+          namespace, remainder = e.split(Tag::PREDICATE_DELIMITER)
+          remainder.split(QUICK_MODE_DELIMITER).map {|e| 
+            e.include?(Tag::VALUE_DELIMITER) ? "#{namespace}#{Tag::PREDICATE_DELIMITER}#{e}" :
+            (@options[:default_predicate] ? Tag.build_machine_tag(namespace, @options[:default_predicate].call(e, namespace), e) :
+            Tag.build_machine_tag(namespace, default_predicate, e))
+          }
+        else
+          e
+        end
+      }.flatten
+    end
+
+    def namespace_hashes #:nodoc:
+      self.inject({}) {|h, e|
+        namespace, *predicate_value = Tag.split_machine_tag(e)
+        (h[namespace] ||= []) << predicate_value unless namespace.nil?
+        h
+      }
+    end
+
+    def non_machine_tags
+      self.reject {|e| Tag.machine_tag?(e)}
+    end
+
+    # Converts tag_list to a stringified version of quick_mode.
+    def to_quick_mode_string
+      machine_tags = namespace_hashes.map {|namespace, predicate_values|
+        "#{namespace}:" + predicate_values.map {|pred, value|
+          pred == self.default_predicate ? value : "#{pred}#{Tag::VALUE_DELIMITER}#{value}"
+        }.join(QUICK_MODE_DELIMITER)
+      }
+      (machine_tags + non_machine_tags).join("#{delimiter} ")
+    end
+
+    def to_s #:nodoc:
+      join("#{delimiter} ")
+    end
+  end
+end

data/lib/has_machine_tags/tag_methods.rb

@@ -0,0 +1,153 @@
+module HasMachineTags
+# == Machine Tags
+# Machine tags, also known as triple tags, are in the format: 
+#   [namespace]:[predicate]=[value]
+# 
+# As explained here[http://www.flickr.com/groups/api/discuss/72157594497877875],
+# a namespace and predicate must start with a letter a-z while its remaining characters can be any lowercase alphanumeric character
+# and underscore. A value can contain any characters that normal tags use.
+# 
+# == Wildcard Machine Tags
+# Wildcard machine tag syntax is used with Tag.machine_tags() and {tagged_with() or find_tagged_with()}[link:classes/HasMachineTags/Finder.html] of tagged objects.
+# This syntax allows one to fetch items that fall under a group of tags, as specified by namespace, predicate, value or
+# a combination of these ways. While this plugin supports {Flickr's wildcard format}[http://code.flickr.com/blog/2008/07/18/wildcard-machine-tag-urls/],
+# it also supports its own slightly shorter format.
+#
+# === Examples
+# 
+# For a tag 'user:name=john', the following wildcards would match it:
+#
+# * Wild namespace (any tag with namespace user)
+#     Tag.machine_tags 'user:'   # Our way
+#     Tag.machine_tags 'user:*=' # Flickr way
+#
+# * Wild predicate (any tag with predicate name)
+#     Tag.machine_tags 'name='   # Our way
+#     Tag.machine_tags '*:name=' # Flickr way
+#
+# * Wild predicate (any tag with value john)
+#     Tag.machine_tags '=john'    # Our way
+#     Tag.machine_tags '*:*=john' # Flickr way
+#
+# * Wild namespace and predicate (any tag with namespace user and predicate name)
+#     Tag.machine_tags 'user:name'  # Our way
+#     Tag.machine_tags 'user:name=' # Flickr way
+#
+# * Wild predicate and value (any tag with predicate name and value john)
+#     Tag.machine_tags 'name=john'   # Our way
+#     Tag.machine_tags '*:name=john' # Flickr way
+#
+# * Wild namespace and value (any tag with namespace user and value john)
+#     Tag.machine_tags 'user.john'   # Our way
+#     Tag.machine_tags 'user:*=john' # Flickr way
+#
+# == Food For Thought
+# So what's so great about being able to give a tag a namespace and a predicate?
+# * It allows for more fine-grained tag queries by giving multiple contexts:
+#
+#   Say instead of having tagged with 'user:name=john' we had tagged with the traditional separate
+#   tags: user, name and john. How would we know that we had meant an item to be tagged
+#   as a user ie with namespace user? We wouldn't know. Any query for 'user' would return
+#   all user-tagged items <b>without context</b>. With machine tags, we can have 'user' refer
+#   to a particular combination of namespace, predicate and value.
+#
+# * It keeps tag-spaces cleaner because there are more contexts:
+#
+#   With traditional separate tags, tags just have a global context. So
+#   if different users decide to give different meaning to the same tag, the tag starts to become
+#   polluted and loses its usefulness. With the limitless contexts provided by machine tags,
+#   a machine tag is less likely to pollute other tags.
+#
+# * It allows tagging to serve as a medium for defining relationships between objects:
+#   
+#   Since a machine tag tracks three attributes (namespace, predicate and value), it's possible to develop relationships
+#   between the attributes. This means namespaces can have many predicates and predicates can have many values.
+#   Since this closely resembles object modeling, we can start to use tagging to form relationships between tagged items and other objects.
+  module TagMethods
+    NAMESPACE_REGEX = "[a-z](?:[a-z0-9_]+)"
+    PREDICATE_REGEX = "[a-z](?:[a-z0-9_-]+)"
+    VALUE_REGEX = '.+'
+    #TODO: use delimiters in this file
+    PREDICATE_DELIMITER = ':'
+    VALUE_DELIMITER = '='
+
+    def self.included(base) #:nodoc:
+      name_format = /\A(([^\*\=\:\.,]+)|(#{NAMESPACE_REGEX}\:#{PREDICATE_REGEX}\=#{VALUE_REGEX}))\Z/
+      base.class_eval %[
+        has_many :taggings
+  
+        validates_presence_of :name
+        validates_uniqueness_of :name
+        before_save :update_name_related_columns
+  
+        #disallow machine tags special characters and tag list delimiter OR allow machine tag format
+        validates_format_of :name, :with=>name_format
+      ]
+      base.extend(ClassMethods)
+      base.send :include, InstanceMethods
+    end
+    
+    module ClassMethods
+      # Takes a wildcard machine tag and returns matching tags.
+      def machine_tags(name)
+        conditions = if (match = match_wildcard_machine_tag(name))
+          match.map {|k,v|
+            sanitize_sql(["#{k} = ?", v])
+          }.join(" AND ")
+        else
+          sanitize_sql(["name = ?", name])
+        end
+        find(:all, :conditions=>conditions)
+      end
+      
+      # Builds a machine tag string given namespace, predicate and value.
+      def build_machine_tag(namespace, predicate, value)
+        "#{namespace}:#{predicate}=#{value}"
+      end
+      
+      # Returns an array of machine tag parts: [namespace, predicate, value]
+      def split_machine_tag(machine_tag)
+        extract_from_name(machine_tag) || []
+      end
+      
+      # Boolean indicating if given tag is a machine tag.
+      def machine_tag?(machine_tag)
+        !extract_from_name(machine_tag).nil?
+      end
+      
+      def extract_from_name(tag_name) #:nodoc:
+        (tag_name =~ /^(#{NAMESPACE_REGEX})\:(#{PREDICATE_REGEX})\=(#{VALUE_REGEX})$/) ? [$1, $2, $3] : nil
+      end
+
+      # Valid wildcards with their equivalent shortcuts
+      # namespace:*=* -> namespace:
+      # *:predicate=* -> predicate=
+      # *:*=value     -> :value
+      def match_wildcard_machine_tag(name) #:nodoc:
+        if name =~ /^(#{NAMESPACE_REGEX}|\*)\:(#{PREDICATE_REGEX}|\*)\=(#{VALUE_REGEX}|\*)?$/
+          result = [[:namespace, $1], [:predicate, $2], [:value, $3]].select {|k,v| ![nil,'*'].include?(v) }
+          result.size == 3 ? nil : result
+        #duo shortcuts
+        elsif name =~ /^(#{NAMESPACE_REGEX}\:#{PREDICATE_REGEX})|(#{PREDICATE_REGEX}\=#{VALUE_REGEX})|(#{NAMESPACE_REGEX}\.#{VALUE_REGEX})$/
+          $1 ? [:namespace, :predicate].zip($1.split(":")) : ($2 ? [:predicate, :value].zip($2.split("=")) :
+            [:namespace, :value].zip($3.split('.')) )
+        #single shortcuts
+        elsif name =~ /^((#{NAMESPACE_REGEX})(?:\:)|(#{PREDICATE_REGEX})(?:\=)|(?:\=)(#{VALUE_REGEX}))$/
+          $2 ? [[:namespace, $2]] : ($3 ? [[:predicate, $3]] : [[:value, $4]])
+        else
+          nil
+        end
+      end
+    end
+  
+    module InstanceMethods
+      private
+  
+      def update_name_related_columns
+        if self.changed.include?('name') && (arr = self.class.extract_from_name(self.name))
+          self[:namespace], self[:predicate], self[:value] = arr
+        end
+      end
+    end
+  end
+end

data/lib/has_machine_tags/tagging.rb

@@ -0,0 +1,4 @@
+class Tagging < ActiveRecord::Base #:nodoc:
+  belongs_to :tag
+  belongs_to :taggable, :polymorphic => true
+end

data/lib/has_machine_tags.rb

@@ -0,0 +1,88 @@
+current_dir = File.dirname(__FILE__)
+$:.unshift(current_dir) unless $:.include?(current_dir) || $:.include?(File.expand_path(current_dir))
+require 'has_machine_tags/finder'
+require 'has_machine_tags/tag_list'
+require 'has_machine_tags/console'
+
+module HasMachineTags
+  def self.included(base) #:nodoc:
+    base.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    # ==== Options:
+    # [:console] When true, adds additional helper methods from HasMachineTags::Console to use mainly in irb.
+    # [:reverse_has_many] Defines a has_many :through from tags to the model using the plural of the model name.
+    # [:quick_mode] When true, enables a quick mode to input machine tags with HasMachineTags::InstanceMethods.tag_list=(). See examples at HasMachineTags::TagList.new().
+    def has_machine_tags(options={})
+      cattr_accessor :quick_mode
+      self.quick_mode = options[:quick_mode] || false
+      self.class_eval do
+        has_many :taggings, :as=>:taggable, :dependent=>:destroy
+        has_many :tags, :through=>:taggings
+        after_save :save_tags
+        
+        include HasMachineTags::InstanceMethods
+        extend HasMachineTags::Finder
+        if options[:console]
+          include HasMachineTags::Console::InstanceMethods
+          extend HasMachineTags::Console::ClassMethods
+        end
+        if respond_to?(:named_scope)
+          named_scope :tagged_with, lambda{ |*args|
+            find_options_for_tagged_with(*args)
+          }
+        end
+      end
+      if options[:reverse_has_many]
+        model = self.to_s
+        'Tag'.constantize.class_eval do
+          has_many(model.tableize, :through => :taggings, :source => :taggable, :source_type =>model)
+        end
+      end
+    end
+  end
+    
+  module InstanceMethods
+    # Set tag list with an array of tags or comma delimited string of tags.
+    def tag_list=(list)
+      @tag_list = current_tag_list(list)
+    end
+    
+    def current_tag_list(list) #:nodoc:
+      TagList.new(list, :quick_mode=>self.quick_mode)
+    end
+    
+    # Fetches latest tag list for an object
+    def tag_list
+      @tag_list ||= TagList.new(self.tags.map(&:name))
+    end
+    
+    def quick_mode_tag_list
+      tag_list.to_quick_mode_string
+    end
+    
+    protected
+    # :stopdoc:
+    def save_tags
+      self.class.transaction do
+        delete_unused_tags
+        add_new_tags
+      end
+    end
+
+    def delete_unused_tags
+      unused_tags = tags.select {|e| !tag_list.include?(e.name) }
+      tags.delete(*unused_tags)
+    end
+
+    def add_new_tags
+      new_tags = tag_list - (self.tags || []).map(&:name)
+      new_tags.each do |t|
+        self.tags << Tag.find_or_initialize_by_name(t)
+      end
+    end
+    #:startdoc:
+  end
+  
+end

data/rails/init.rb

@@ -0,0 +1,13 @@
+require 'has_machine_tags'
+require 'has_machine_tags/tag_methods'
+
+#attempt to load constant
+::Tag rescue nil
+if Object.const_defined? :Tag
+  ::Tag.class_eval %[include HasMachineTags::TagMethods]
+else
+  require 'has_machine_tags/tag'
+end
+
+require 'has_machine_tags/tagging'
+ActiveRecord::Base.send :include, HasMachineTags

data/test/finder_test.rb

@@ -0,0 +1,84 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class HasMachineTags::FinderTest < Test::Unit::TestCase
+  before(:each) { 
+    [Tag, Tagging, TaggableModel].each {|e| e.delete_all}
+  }
+  
+  def create_extra_taggable
+    TaggableModel.create(:tag_list=>"blah:blih=bluh")
+  end
+  
+  context "TaggableModel" do
+    context "finds by" do
+      before(:each) { 
+        @taggable = TaggableModel.create(:tag_list=>"url:lang=ruby")
+        create_extra_taggable
+      }
+    
+      test "namespace wildcard machine tag" do
+        TaggableModel.tagged_with("url:").should == [@taggable]
+      end
+    
+      test "predicate wildcard machine tag" do
+        TaggableModel.tagged_with("lang=").should == [@taggable]
+      end
+    
+      test "value wildcard machine tag" do
+        TaggableModel.tagged_with("=ruby").should == [@taggable]
+      end
+    
+      test "namespace-value wildcard machine tag" do
+        TaggableModel.tagged_with("url.ruby").should == [@taggable]
+      end
+      
+      test "predicate-value wildcard machine tag" do
+        TaggableModel.tagged_with("lang=ruby").should == [@taggable]
+      end
+    end
+    
+    context "finds with" do
+      test "multiple machine tags as an array" do
+        @taggable = TaggableModel.create(:tag_list=>"article:todo=later")
+        @taggable2 = TaggableModel.create(:tag_list=>"article:tags=funny")
+        create_extra_taggable
+        results = TaggableModel.tagged_with(["article:todo=later", "article:tags=funny"])
+        results.size.should == 2
+        results.include?(@taggable).should be(true)
+        results.include?(@taggable2).should be(true)
+      end
+      
+      test "multiple machine tags as a delimited string" do
+        @taggable = TaggableModel.create(:tag_list=>"article:todo=later")
+        @taggable2 = TaggableModel.create(:tag_list=>"article:tags=funny")
+        create_extra_taggable
+        results = TaggableModel.tagged_with("article:todo=later, article:tags=funny")
+        results.size.should == 2
+        results.include?(@taggable).should be(true)
+        results.include?(@taggable2).should be(true)
+      end
+      
+      test "condition option" do
+        @taggable = TaggableModel.create(:title=>"so limiting", :tag_list=>"url:tags=funny" )
+        create_extra_taggable
+        TaggableModel.tagged_with("url:tags=funny", :conditions=>"title = 'so limiting'").should == [@taggable]
+      end
+    end
+
+    context "when queried with normal tag" do
+      before(:each) { @taggable = TaggableModel.new }
+      test "doesn't find if machine tagged" do
+        @taggable.tag_list = 'url:tags=square'
+        @taggable.save
+        Tag.count.should == 1
+        TaggableModel.tagged_with("square").should == []
+      end
+    
+      test "finds if tagged normally" do
+        @taggable.tag_list = 'square, some:machine=tag'
+        @taggable.save
+        TaggableModel.tagged_with("square").should == [@taggable]
+      end
+    end        
+  end  
+end

data/test/has_machine_tags_test.rb

@@ -0,0 +1,72 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class HasMachineTagsTest < Test::Unit::TestCase
+  context "TagList" do
+    before(:each) { @taggable = TaggableModel.new }
+    
+    test "sets tag list with array" do
+      arr = ['some', 'tag:name=blah']
+      @taggable.tag_list = arr
+      @taggable.tag_list.should == arr
+    end
+    
+    test "sets tag list with delimited string" do
+      arr = ['more', 'tag:type=clever']
+      @taggable.tag_list = arr.join(", ")
+      @taggable.tag_list.should == arr
+    end
+    
+    test "sets tag list with messy delimited string" do
+      arr = ['more', 'tag:type=dumb', 'really']
+      @taggable.tag_list = "more,tag:type=dumb,   really"
+      @taggable.tag_list.should == arr
+      @taggable.tag_list.to_s.should == arr.join(", ")
+    end
+    
+    context "with quick_mode" do
+      before(:all) { TaggableModel.quick_mode = true }
+      after(:all) { TaggableModel.quick_mode = false }
+      
+      test "sets tag list normally with non quick_mode characters" do
+        arr = ['more', 'tag:type=dumb', 'really']
+        @taggable.tag_list = "more,tag:type=dumb,   really"
+        @taggable.tag_list.should == arr
+      end
+      
+      test "sets default predicate and infers namespace" do
+        @taggable.tag_list = "gem:irb;name=utility_belt, article"
+        @taggable.tag_list.should == ["gem:tags=irb", "gem:name=utility_belt", "article"]
+      end
+    end
+  end
+  
+  context "InstanceMethods" do
+    before(:each) { @taggable = TaggableModel.new }
+  
+    test "creates all tags" do
+      tags = ['some', 'tag:name=blah']
+      @taggable.tag_list = tags
+      @taggable.save!
+      @taggable.tags.map(&:name).should == tags
+    end
+    
+    test "only creates new tags" do
+      @taggable.tag_list = "bling"
+      @taggable.save!
+      tag_count = Tag.count
+      @taggable.tag_list = "bling, bling2"
+      @taggable.save!
+      @taggable.taggings.size.should == 2
+      Tag.count.should == tag_count + 1
+    end
+    
+    test "deletes unused tags" do
+      @taggable.tag_list == 'bling, bling3'
+      @taggable.save!
+      @taggable.tag_list = "bling4"
+      @taggable.save!
+      @taggable.taggings.size.should == 1
+      @taggable.tags.map(&:name).should == ['bling4']
+    end
+  end
+end

data/test/schema.rb

@@ -0,0 +1,20 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :taggable_models do |t|
+    t.string  :title
+  end
+
+  create_table :tags do |t|
+    t.string :name
+    t.string :namespace
+    t.string :predicate
+    t.string :value
+    t.datetime :created_at
+  end
+
+  create_table :taggings do |t|
+    t.integer :tag_id
+    t.string  :taggable_type
+    t.integer :taggable_id
+    t.datetime :created_at
+  end
+end

data/test/tag_methods_test.rb

@@ -0,0 +1,109 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class HasMachineTags::TagMethodsTest < Test::Unit::TestCase
+  test "create with normal tag name only touches name" do
+    obj = Tag.create(:name=>'blah1')
+    [:name, :namespace, :predicate, :value].map {|e| obj.send(e)}.should == ['blah1', nil, nil, nil]
+  end
+  
+  test "create with machine tag name sets all name fields" do
+    obj = Tag.create(:name=>'gem:name=machine')
+    [:name, :namespace, :predicate, :value].map {|e| obj.send(e)}.should == ['gem:name=machine', 'gem', 'name', 'machine']
+  end
+  
+  context "update" do
+    before(:each) { @obj = Tag.new }
+    
+    test "with normal tag name only touches name" do
+      @obj.update_attributes :name=> 'bling'
+      [:name, :namespace, :predicate, :value].map {|e| @obj.send(e)}.should == ['bling', nil, nil, nil]
+    end
+
+    test "with machine tag name sets all name fields" do
+      @obj.update_attributes :name=>'gem:prop=value'
+      [:name, :namespace, :predicate, :value].map {|e| @obj.send(e)}.should == ['gem:prop=value', 'gem', 'prop', 'value']
+    end
+
+    test "with no name sets no name fields" do
+      @obj.update_attributes :name=>'blah2'
+      @obj.update_attributes :predicate=>'changed'
+      @obj.name.should == 'blah2'
+    end
+  end
+  
+  context "match_wildcard_machine_tag" do
+    test "matches namespace with asterisk" do
+      Tag.match_wildcard_machine_tag('name:*=').should == [[:namespace,'name']]
+    end
+    
+    test "matches namespace without asterisk" do
+      Tag.match_wildcard_machine_tag('name:').should == [[:namespace,'name']]
+    end
+    
+    test "matches predicate with asterisk" do
+      Tag.match_wildcard_machine_tag('*:pred=').should == [[:predicate,'pred']]
+    end
+    
+    test "matches predicate without asterisk" do
+      Tag.match_wildcard_machine_tag('pred=').should == [[:predicate,'pred']]
+    end
+    
+    test "matches value with asterisk" do
+      Tag.match_wildcard_machine_tag('*:*=val').should == [[:value, 'val']]
+    end
+    
+    test "matches value without asterisk" do
+      Tag.match_wildcard_machine_tag('=val').should == [[:value, 'val']]
+    end
+    
+    test "matches namespace and predicate without asterisk" do
+      Tag.match_wildcard_machine_tag('name:pred').should == [[:namespace, 'name'], [:predicate, 'pred']]
+    end
+
+    test "matches namespace and predicate with asterisk" do
+      Tag.match_wildcard_machine_tag('name:pred=').should == [[:namespace, 'name'], [:predicate, 'pred']]
+    end
+    
+    test "matches predicate and value without asterisk" do
+      Tag.match_wildcard_machine_tag('pred=val').should == [[:predicate, 'pred'], [:value, 'val']]
+    end
+
+    test "matches predicate and value with asterisk" do
+      Tag.match_wildcard_machine_tag('*:pred=val').should == [[:predicate, 'pred'], [:value, 'val']]
+    end
+    
+    test "matches namespace and value without asterisk" do
+      Tag.match_wildcard_machine_tag('name.val').should == [[:namespace, 'name'], [:value, 'val']]
+    end
+
+    test "matches namespace and value with asterisk" do
+      Tag.match_wildcard_machine_tag('name:*=val').should == [[:namespace, 'name'], [:value, 'val']]
+    end
+    
+    test "doesn't match total wildcard" do
+      Tag.match_wildcard_machine_tag('*:*=').should == []
+    end
+
+    test "doesn't match machine tag" do
+      Tag.match_wildcard_machine_tag('name:pred=val').should == nil
+    end
+    
+    test "doesn't match normal tag" do
+      Tag.match_wildcard_machine_tag('name').should == nil
+    end
+  end
+  
+  test "validates name when no invalid characters" do
+    Tag.new(:name=>'valid!name_really?').valid?.should be(true)
+  end
+
+  test "validates name when machine tag format" do
+    Tag.new(:name=>'name:pred=value').valid?.should be(true)
+  end
+
+  test "invalidates name when invalid characters present" do
+    %w{some.tag another:tag so=invalid yet,another whoop*}.each do |e|
+      Tag.new(:name=>e).valid?.should be(false)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,26 @@
+require 'rubygems'
+require 'activerecord'
+require 'test/unit'
+require 'context' #gem install jeremymcanally-context -s http://gems.github.com
+require 'matchy' #gem install jeremymcanally-matchy -s http://gems.github.com
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(File.dirname(__FILE__), '..', 'init')
+
+#Setup logger
+require 'logger'
+# ActiveRecord::Base.logger = Logger.new(File.join(File.dirname(__FILE__), "test.log"))
+ActiveRecord::Base.logger = Logger.new(STDERR)
+ActiveRecord::Base.logger.level = Logger::WARN
+
+#Setup db
+ActiveRecord::Base.configurations = {'sqlite3' => {:adapter => 'sqlite3', :database => ':memory:'}}
+ActiveRecord::Base.establish_connection('sqlite3')
+
+#Define schema
+require File.join(File.dirname(__FILE__), 'schema')
+class TaggableModel < ActiveRecord::Base
+  has_machine_tags
+end
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: has_machine_tags
+version: !ruby/object:Gem::Version 
+  version: 0.1.6
+platform: ruby
+authors: 
+- Gabriel Horner
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-22 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: This plugin implements Flickr's machine tags while still maintaining standard tagging behavior. This allows for more precise tagging as tags can have unlimited contexts provided by combinations of namespaces and predicates. These unlimited contexts also make machine tags ripe for modeling relationships between objects.
+email: gabriel.horner@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- CHANGELOG.rdoc
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- generators/has_machine_tags_migration/has_machine_tags_migration_generator.rb
+- generators/has_machine_tags_migration/templates/migration.rb
+- init.rb
+- lib/has_machine_tags.rb
+- lib/has_machine_tags/console.rb
+- lib/has_machine_tags/finder.rb
+- lib/has_machine_tags/tag.rb
+- lib/has_machine_tags/tag_console.rb
+- lib/has_machine_tags/tag_list.rb
+- lib/has_machine_tags/tag_methods.rb
+- lib/has_machine_tags/tagging.rb
+- rails/init.rb
+- test/finder_test.rb
+- test/has_machine_tags_test.rb
+- test/schema.rb
+- test/tag_methods_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://tagaholic.me/has_machine_tags/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+- tagaholic
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A rails tagging plugin implementing flickr's machine tags + maybe more (semantic tags).
+test_files: 
+- test/finder_test.rb
+- test/has_machine_tags_test.rb
+- test/schema.rb
+- test/tag_methods_test.rb
+- test/test_helper.rb