spraypaint 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+test/log/*
+test/db/*.sqlite3
+pkg/*

data/CHANGELOG

@@ -0,0 +1,4 @@
+0.9.1
+
+* Changed Rakefile to use secret new penknife plugin tasks
+* Improved documentation and TODO list

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Tom Ward (tom@popdog.net)
+
+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

@@ -0,0 +1,17 @@
+Features:
+
+f = Film.find_by_title("The Umbrella's of Cherbourg")
+f.tags
+=> ["french", "umbrella", "catherine-deneuve"]
+
+Tags can be added using standard array methods
+
+f.tags << "jacques-demy"
+f.save!
+f.reload
+f.tags
+=> ["french", "umbrella", "catherine-deneuve", "jacques-demy"]
+
+Tags maintain their order
+
+

data/Rakefile

@@ -0,0 +1,21 @@
+$: << File.expand_path(File.join(File.dirname(__FILE__), "lib"))
+$: << File.expand_path(File.join(File.dirname(__FILE__), "vendor/penknife/lib"))
+
+require 'penknife/rake/plugin_tasks'
+
+namespace :spraypaint do
+  Penknife::Rake::PluginTasks.new do |plugin|
+    plugin.plugin_root = File.dirname(File.expand_path(__FILE__))
+    plugin.name = 'spraypaint'
+    plugin.summary = 'Simple tagging in a can'
+    plugin.authors = ['Tom Ward (tomafro)']
+    plugin.email = 'tom@popdog.net'
+    plugin.homepage = 'http://github.com/tomafro/spraypaint'
+    plugin.code = 'http://github.com/tomafro/spraypaint.git'
+    plugin.license = 'MIT'
+    plugin.rails_version = '2.3+'
+    plugin.files = `git ls-files`.split("\n")
+  end
+end
+
+task 'default' => ['spraypaint:spec', 'spraypaint:features']

data/TODO

@@ -0,0 +1,7 @@
+1.1 
+
+* Add namespace, predicate and value columns - very simple machine tagging
+
+1.2 
+
+* Add ownership of tags 

data/VERSION.yml

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

data/about.yml

@@ -0,0 +1,10 @@
+--- 
+:version: 1.0.0
+:license: MIT
+:rails_version: 2.3+
+:author: Tom Ward (tomafro)
+:summary: Simple tagging in a can
+:plugin: http://github.com/tomafro/spraypaint.git
+:email: tom@popdog.net
+:name: spraypaint
+:homepage: http://github.com/tomafro/spraypaint

data/generators/spraypaint_migration/spraypaint_migration_generator.rb

@@ -0,0 +1,21 @@
+require 'spraypaint'
+
+class SpraypaintMigrationGenerator < Rails::Generator::NamedBase  
+  def initialize(runtime_args, runtime_options)
+    super(["create_spraypnt_tagging_tables"], runtime_options)
+  end
+  
+  def manifest
+    record do |m|
+      m.migration_template 'spraypaint_migration.rb', 'db/migrate'
+    end
+  end
+  
+  def tags_table
+    Spraypaint::Model::Tag.table_name
+  end
+  
+  def taggings_table
+    Spraypaint::Model::Tagging.table_name
+  end
+end

data/generators/spraypaint_migration/templates/spraypaint_migration.rb

@@ -0,0 +1,25 @@
+class <%= class_name.underscore.camelize %> < ActiveRecord::Migration
+  def self.up
+    create_table '<%= tags_table %>', :force => true do |table|
+      table.string 'name', :null => false
+    end
+    
+    add_index '<%= tags_table %>', 'name', :unique => true
+    
+    create_table '<%= taggings_table %>', :force => true do |table|
+      table.integer 'spraypaint_tag_id', :null => false
+      table.integer 'target_id', :null => false
+      table.string 'target_type', :null => false
+    end
+
+    add_index '<%= taggings_table %>', 'target_id'
+    add_index '<%= taggings_table %>', 'target_type'
+    add_index '<%= taggings_table %>', 'spraypaint_tag_id'
+    add_index '<%= taggings_table %>', ['target_type', 'target_id', 'spraypaint_tag_id'], :unique => true, :name => 'spraypaint_unique_tagging_index'
+  end
+  
+  def self.down
+    drop_table '<%= taggings_table %>'
+    drop_table '<%= tags_table %>'
+  end
+end

data/lib/spraypaint.rb

@@ -0,0 +1,59 @@
+# = Spraypaint - simple tagging in a can
+#
+# == Getting started
+#
+# Generate and run the spraypaint migration
+#   script/generate spraypaint_migration
+#   rake db:migrate
+#
+# Enable spraypaint in a model
+#   class Film < ActiveRecord::Base
+#     tag_with_spraypaint
+#
+#     def inspect
+#       "<#{self.title}>"
+#     end
+#   end
+# 
+# Create some tagged films:
+#   Film.create! :title => 'The Umbrellas of Cherbourg', :director => 'Demy', :tags => ['umbrellas', 'french', 'musical']  
+#   Film.create! :title => 'Jules Et Jim', :director => 'Truffaut', :tags => ['threesome', 'bicycle', 'french']
+#   Film.create! :title => 'Shoot The Pianist', :director => 'Truffaut', :tags => ['piano', 'gangster', 'french']
+#   Film.create! :title => 'The Sound of Music', :tags => ['musical', 'ww2']                    
+# 
+# Use the tagged_with method to find records matching tags
+#   Film.tagged_with('musical')
+#     => [<The Umbrellas Of Cherbourg>, <The Sound Of Music>]
+#   Film.tagged_with('french', 'musical')
+#     => [<The Umbrellas Of Cherbourg>]
+# 
+# As tagged_with is just a scope, you can chain it with standard finders or calculations
+#   Film.tagged_with('french').all(:order => 'title')
+#     => [<Jules Et Jim>, <Shoot The Pianist>, <The Umbrellas Of Cherbourg>]
+#   Film.tagged_with('musicl').all(:conditions => "name like '%Music%'")
+#     => [<The Sound Of Music>]
+#   Film.tagged_with('french').count
+#     => 3
+#     
+# To find all tags on a model use #tags
+#   Film.tags 
+#     => ['umbrellas', 'french', 'musical', 'threesome', 'bicycle', 'piano', 'gangster', 'ww2']
+#     
+# The #tags method also plays nicely with scopes
+#   Film.all(:conditions => {'director' => 'Truffaut'}).tags
+#     => ['french', 'threesome', 'bicycle', 'piano', 'gangster']
+#   Film.tagged_with('french').tags
+#     => ['musical', 'french', 'threesome', 'bicycle', 'piano', 'gangster']
+# 
+
+module Spraypaint
+  def self.activate_plugin
+    ActiveRecord::Base.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    def tag_with_spraypaint(options = {})
+      include Spraypaint::Behaviour
+    end
+  end
+end

data/lib/spraypaint/behaviour.rb

@@ -0,0 +1,11 @@
+require 'spraypaint'
+
+module Spraypaint::Behaviour
+  include Manipulation, Persistence, Discovery
+  
+  def self.included(base)
+    self.included_modules.each do |m|
+      m.__send__ :included, base
+    end
+  end
+end

data/lib/spraypaint/behaviour/discovery.rb

@@ -0,0 +1,57 @@
+module Spraypaint::Behaviour::Discovery
+  def self.included(base)
+    unless base == parent
+      base.named_scope :tagged_with, lambda {|*tags|
+        base.spraypaint_condition_hash_for(tags)
+      }
+      
+      base.extend(ClassMethods)
+    end
+  end
+  
+  module ClassMethods
+    class TagString < String
+      def initialize(string, count)
+        super(string)
+        @tag_count = count.to_i
+      end
+      
+      def frequency
+        @tag_count
+      end
+    end
+    
+    def spraypaint_condition_hash_for(tags)
+      tags = self.tag_sanitizer.sanitize_array([*tags])  
+      {:conditions => %{
+        EXISTS (
+          SELECT 1 FROM #{Spraypaint::Model::Tag.table_name}, #{Spraypaint::Model::Tagging.table_name}
+          WHERE #{Spraypaint::Model::Tagging.table_name}.target_id = #{self.table_name}.id
+          AND #{Spraypaint::Model::Tagging.table_name}.target_type = '#{self.base_class.name}'
+          AND #{Spraypaint::Model::Tag.table_name}.id = #{Spraypaint::Model::Tagging.table_name}.tag_id            
+          AND (#{Spraypaint::Model::Tag.tag_condition(tags)})
+          GROUP BY #{Spraypaint::Model::Tagging.table_name}.target_id 
+          HAVING count(distinct #{Spraypaint::Model::Tagging.table_name}.tag_id) = #{tags.size} 
+        )
+      }}
+    end
+    
+    def tags(options = {})
+      
+      self.all({
+        :select => ['spraypaint_tags.id, spraypaint_tags.name tag_name, count(*) tag_count'],
+        :joins => %{
+          INNER JOIN spraypaint_taggings ON (spraypaint_taggings.target_id = #{self.table_name}.#{self.primary_key} AND spraypaint_taggings.target_type = '#{self.base_class.name}')
+          INNER JOIN spraypaint_tags ON (spraypaint_tags.id = spraypaint_taggings.tag_id)
+        },
+        :group => 'spraypaint_tags.id',
+        :order => 'count(*) desc, spraypaint_tags.name', 
+      }.merge(options.slice(:conditions, :limit, :offset, :order))).collect {|tag| TagString.new(tag.tag_name, tag.tag_count) }
+    end
+    
+    def related_tags(*tags)
+      options = tags.extract_options!
+      tags(options)
+    end
+  end
+end

data/lib/spraypaint/behaviour/manipulation.rb

@@ -0,0 +1,71 @@
+module Spraypaint::Behaviour::Manipulation
+  def self.included(base)
+    unless base == parent
+      base.alias_method_chain :read_attribute, :spraypaint
+      base.alias_method_chain :create_or_update, :spraypaint
+      base.extend ClassMethods
+    end
+  end
+
+  def tags
+    read_attribute('tags')
+  end
+  
+  def tags=(tags)
+    write_attribute('tags', self.class.tag_sanitizer.sanitize_array([*tags]))
+  end
+  
+  def tag_string
+    read_attribute('tag_string') || tags.join(", ")
+  end
+  
+  def tag_string=(string)
+    write_attribute('tag_string', string)
+    self.tags = string && string.split(",").collect(&:strip)
+  end
+  
+  def tags_changed?
+    attribute_changed?('tags')
+  end
+
+  def tags_change
+    attribute_change('tags')
+  end
+
+  def tags_was
+    attribute_was('tags')
+  end
+  
+  def tags_will_change!
+    attribute_will_change('tags')
+  end
+  
+  private
+  
+  def create_or_update_with_spraypaint
+    change = tags_change
+    returning create_or_update_without_spraypaint do |result|
+      if result && change
+        save_tag_names(change.last)
+      end
+    end 
+  end
+  
+  def read_attribute_with_spraypaint(attribute)
+    if attribute.to_s == "tags"
+      read_attribute_without_spraypaint(attribute) || load_tag_names
+    else
+      read_attribute_without_spraypaint(attribute)
+    end
+  end
+  
+  module ClassMethods
+    def tag_sanitizer
+      @tag_sanitizer ||= Spraypaint::DefaultSanitizer.new
+    end
+    
+    def tag_sanitizer=(sanitizer)
+      @tag_sanitizer = sanitizer
+    end
+  end
+end

data/lib/spraypaint/behaviour/persistence.rb

@@ -0,0 +1,24 @@
+module Spraypaint::Behaviour::Persistence  
+  def self.included(base)
+    unless base == parent
+      base.has_many 'spraypaint_taggings', :as => 'target', :dependent => :destroy, :class_name => 'Spraypaint::Model::Tagging'
+      base.has_many 'spraypaint_tags', :through => 'spraypaint_taggings', :source => 'tag', :class_name => '::Spraypaint::Model::Tag', :order => 'spraypaint_taggings.id'
+    end
+  end
+  
+  private
+  
+  def load_tag_names
+    self.spraypaint_tags.collect(&:name)
+  end
+  
+  def save_tag_names(names)
+    transaction do
+      spraypaint_taggings.destroy_all
+      names.each do |tag_name|
+        tag = Spraypaint::Model::Tag.find_or_create_by_name(tag_name)
+        self.spraypaint_tags << tag
+      end
+    end
+  end
+end

data/lib/spraypaint/default_sanitizer.rb

@@ -0,0 +1,17 @@
+class Spraypaint::DefaultSanitizer
+  include Spraypaint::Sanitizer
+  
+  attr_accessor :allowed_characters
+
+  def initialize(allowed_characters = /[\w -]/)
+    self.allowed_characters = allowed_characters
+  end
+
+  def sanitize_tag(tag)
+    return nil if tag.nil?
+    string = tag.strip
+    string = string.mb_chars.normalize(:d).gsub(/[^\0-\x80]/, '')
+    string = string.scan(self.allowed_characters).join
+    string.empty? ? nil : string.to_s
+  end
+end

data/lib/spraypaint/model/tag.rb

@@ -0,0 +1,15 @@
+class Spraypaint::Model::Tag < ActiveRecord::Base
+  # By default spraypaint uses the spraypaint namespace for all its tables, so
+  # the tags themselves are stored in spraypaint_tags.  To change this, simply
+  # set the table name to something else
+  #   Spraypaint::Model::Tag.set_table_name 'special_tags'
+  set_table_name :spraypaint_tags
+  
+  # All tags must have a name. In practise this is enforced by the way tags are 
+  # set and in the database, so this validation is redundant in normal usage
+  validates_presence_of :name
+  
+  def self.tag_condition(tag)
+    sanitize_sql(:name => tag)
+  end
+end

data/lib/spraypaint/model/tagging.rb

@@ -0,0 +1,11 @@
+class Spraypaint::Model::Tagging < ActiveRecord::Base
+  set_table_name :spraypaint_taggings
+  
+  # Main association between an individual tagging and the actual tag
+  belongs_to :tag, :class_name => 'Spraypaint::Model::Tag'
+  
+  # Association between the tagging and the object being tagged
+  belongs_to :target, :polymorphic => true
+  
+  validates_presence_of :tag, :target
+end

data/lib/spraypaint/sanitizer.rb

@@ -0,0 +1,11 @@
+module Spraypaint::Sanitizer
+  
+  # Sanitizes an array of tags, passing each one through #sanitize_tag and removing
+  # all nils and duplicates.
+  
+  def sanitize_array(array)
+    array.collect do |tag|
+      sanitize_tag(tag)
+    end.compact.uniq
+  end
+end

data/rails/init.rb

@@ -0,0 +1,3 @@
+require 'spraypaint'
+
+Spraypaint.activate_plugin

data/spraypaint.gemspec

@@ -0,0 +1,78 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{spraypaint}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tom Ward (tomafro)"]
+  s.date = %q{2009-10-18}
+  s.email = %q{tom@popdog.net}
+  s.extra_rdoc_files = [
+    "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "CHANGELOG",
+     "MIT-LICENSE",
+     "Rakefile",
+     "TODO",
+     "VERSION.yml",
+     "about.yml",
+     "generators/spraypaint_migration/spraypaint_migration_generator.rb",
+     "generators/spraypaint_migration/templates/spraypaint_migration.rb",
+     "lib/spraypaint.rb",
+     "lib/spraypaint/behaviour.rb",
+     "lib/spraypaint/behaviour/discovery.rb",
+     "lib/spraypaint/behaviour/manipulation.rb",
+     "lib/spraypaint/behaviour/persistence.rb",
+     "lib/spraypaint/default_sanitizer.rb",
+     "lib/spraypaint/model/tag.rb",
+     "lib/spraypaint/model/tagging.rb",
+     "lib/spraypaint/sanitizer.rb",
+     "rails/init.rb",
+     "spraypaint.gemspec",
+     "test/config/boot.rb",
+     "test/config/database.yml",
+     "test/config/environment.rb",
+     "test/config/environments/test.rb",
+     "test/db/schema.rb",
+     "test/spec/default_sanitizer_spec.rb",
+     "test/spec/models/tag_spec.rb",
+     "test/spec/models/tagging_spec.rb",
+     "test/spec/spec_helper.rb",
+     "test/spec/spraypaint_spec.rb",
+     "vendor/penknife/lib/penknife.rb",
+     "vendor/penknife/lib/penknife/rake.rb",
+     "vendor/penknife/lib/penknife/rake/plugin_tasks.rb"
+  ]
+  s.homepage = %q{http://github.com/tomafro/spraypaint}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Simple tagging in a can}
+  s.test_files = [
+    "test/config/boot.rb",
+     "test/config/environment.rb",
+     "test/config/environments/test.rb",
+     "test/db/schema.rb",
+     "test/spec/default_sanitizer_spec.rb",
+     "test/spec/models/tag_spec.rb",
+     "test/spec/models/tagging_spec.rb",
+     "test/spec/spec_helper.rb",
+     "test/spec/spraypaint_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end