tagalong 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec/debug.log
+*.sqlite3

data/.rvmrc

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+
+# Check to see if brew is installed
+function check_for_brew() {
+  printf "Checking for brew - "
+  which brew > /dev/null
+  if [ $? -ne 0 ]; then
+    echo "NOT found"
+    echo "brew, could not be found!"
+    echo "Please install it using the instructions found on their site (http://mxcl.github.com/homebrew/).\n"
+    return 1
+  else
+    echo "found"
+  fi
+  return 0
+}
+
+# Given a brew package as the first argument check if that package has already been installed.
+function check_for_brew_package() {
+  printf "Checking for $1 - "
+  brew list | grep $1 > /dev/null
+  if [ $? -ne 0 ]; then
+    echo "NOT found"
+    echo "$1, could not be found."
+    echo "Please run brew update && brew install $1 to install it.\n"
+    return 1
+  else
+    echo "found"
+  fi
+  return 0
+}
+
+# This method takes two arguments. The first argument is the name of the gem to check for and install. The second argument is
+# the version of the gem to check for and install. Both arguments are required. If the gem is already installed an exit status
+# of 0 is set, if an install is required an exit status of 1 is set.
+function install_gem_if_not_found() {
+  printf "Checking for gem $1 ($2) - "
+  gem list | grep "$1.*$2.*" > /dev/null
+  if [ $? -ne 0 ]; then
+    echo "NOT found, installing for you"
+    gem install $1 -v $2
+    return 1
+  else
+    echo "found"
+  fi
+  return 0
+}
+
+function load_rvm_as_a_function() {
+  # Here I load rvm as a bash function rather than a binary. I do
+  # this because the binary version is limited and won't properly
+  # create or switch to gemsets. This was added specifically to
+  # handle the case where .rvmrc is loaded via rvm rvmrc load in
+  # a Capistrano deploy. However, it doesn't seem to hurt the
+  # normal dev workflow so I am just leaving it here. For more info
+  # on binary/function mode of RVM refer to the following url:
+  # http://beginrescueend.com/workflow/scripting/
+  if [[ -s "$HOME/.rvm/scripts/rvm" ]] ; then
+    # First try to load from a user install
+    source "$HOME/.rvm/scripts/rvm"
+  elif [[ -s "/usr/local/rvm/scripts/rvm" ]] ; then
+    # Then try to load from a root install
+    source "/usr/local/rvm/scripts/rvm"
+  else
+    printf "ERROR: An RVM installation was not found.\n"
+    return 1
+  fi
+  return 0
+}
+
+# Attempt to load the specified RVM environment where the RVM environment
+# is the first argument passed to this method when called in the form of
+# "ruby-1.9.3-p0@rpp_web_app"
+function load_rvm_environment() {
+  #
+  # First we attempt to load the desired environment directly from the environment
+  # file. This is very fast and efficient compared to running through the entire
+  # CLI and selector. If you want feedback on which environment was used then
+  # insert the word 'use' after --create as this triggers verbose mode.
+  #
+
+  if [[ -d "${rvm_path:-$HOME/.rvm}/environments" && -s "${rvm_path:-$HOME/.rvm}/environments/$1" ]]
+  then
+    source "${rvm_path:-$HOME/.rvm}/environments/$1"
+
+    if [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]]
+    then
+      source "${rvm_path:-$HOME/.rvm}/hooks/after_use"
+    fi
+    return 0
+  else
+    #If the environment file has not yet been created, use the RVM CLI to select.
+    if ! rvm --create  "$1"
+    then
+      echo "Failed to create RVM environment '$1'."
+      return 1
+    fi
+    return 0
+  fi
+
+  #
+  # If you use an RVM gemset file to install a list of gems (*.gems), you can have
+  # it be automatically loaded. Uncomment the following and adjust the filename if
+  # necessary.
+  #
+  # filename=".gems"
+  # if [[ -s "$filename" ]]
+  # then
+  #   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+  # fi  
+}
+
+# if [ `uname -s` == "Darwin" ]; then # we assume we are on a Mac OS X dev box
+#   missing_brew=0
+#   missing_brew_packages=0
+
+#   check_for_brew; if [ $? -ne 0 ]; then missing_brew=1; fi
+#   check_for_brew_package "readline"; if [ $? -ne 0 ]; then missing_brew_packages=1; fi
+#   check_for_brew_package "imagemagick"; if [ $? -ne 0 ]; then missing_brew_packages=1; fi
+#   check_for_brew_package "qt"; if [ $? -ne 0 ]; then missing_brew_packages=1; fi
+#   check_for_brew_package "wkhtmltopdf"; if [ $? -ne 0 ]; then missing_brew_packages=1; fi
+#   check_for_brew_package "mysql"; if [ $? -ne 0 ]; then missing_brew_packages=1; fi
+#   check_for_brew_package "redis"; if [ $? -ne 0 ]; then missing_brew_packages=1; fi
+
+#   if [ $missing_brew_packages -ne 0 ] || [ $missing_brew -ne 0 ]; then
+#     echo "YOU ARE MISSING THE ABOVE PACKAGES! YOU ARE NOT IN THE CORRECT RVM RUBY VERSION GEMSET COMBO!"
+#     cur_rvm=$(rvm current)
+#     echo "The rvm you are currently using is: $cur_rvm\n"
+
+#     echo "Please install them using the provided instructions above."
+#     echo "Once completed cd out of this directory and back into this directory to have this project specific .rvmrc script run again."
+#     return 1;
+#   fi
+# fi
+
+load_rvm_as_a_function; if [ $? -ne 0 ]; then return 1; fi
+#
+# Note: In order for this script to work, specifically the creation
+# of the gemset below with the rvm --create call, the user executing
+# this needs to have the following in their ~/.rvmrc:
+#
+# export rvm_is_not_a_shell_function=0
+#
+# This is only really needed for when it is being run via Capistrano
+# so it only needs to be in the deployment users ~/.rvmrc on
+# boxes you will be deploying to. This with the function loading
+# above is the magic that makes the rvm --create work in this script
+# when it is loaded via Capistrano.
+
+#
+# Note: We also use the following options in our deployment users ~/.rvmrc
+# files handle trusting, auto install of new ruby versions, auto creation
+# of gemsets, etc. The example of the full ~/.rvmrc file is as follows:
+#
+# export rvm_path="/home/rpi/.rvm"
+# export rvm_is_not_a_shell_function=0
+# rvm_trust_rvmrcs_flag=1
+# rvm_install_on_use_flag=1
+# rvm_gemset_create_on_use_flag=1
+#
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.9.3-p125@tagalong"
+
+load_rvm_environment $environment_id; if [ $? -ne 0 ]; then return 1; fi
+
+# At this point we should have the proper RVM environment and gemset loaded
+cur_rvm=$(rvm current)
+echo "Entered RVM environment '$cur_rvm'"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tagalong.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Andrew De Ponte
+
+MIT License
+
+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.md

@@ -0,0 +1,106 @@
+# Tagalong
+
+Tagalong is a Rails plugin that is intended to be a clean, efficient, and simple. I have tried very hard to have the API make sense in terms of OOP as I have seen many other tagging libraries that I don't think do a great job of this.
+
+The other key differentiation between Tagalong and many of the other tagging libraries out there is the relational database structure behind the scenes. This allows us to differentiate this tagging plugin in the following ways:
+
+* clean object oriented API
+* does NOT require saving of the model being tagged
+* keeps history of tags Taggers have used
+* allows defining multiple Taggers and Taggables
+* tracks number of times tags are used
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'tagalong'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tagalong
+
+## Usage
+
+### Migration Setup
+
+In order to use `tagalong` you have to generate the proper migrations so that the tags can be stored in the database. You can do this with the following command:
+
+    rails generate tagalong:migration
+
+The above will generate the migration and place it appropriately in the db/migrate/ project path so that the next time you `rake db:migrate` it will make the changes to the database.
+
+### Declaring Taggers and Taggables
+
+In order to use `tagalong` you need to first declare at least one Tagger and at least one Taggable. You do this as follows:
+
+    class Contact < ActiveRecord::Base
+      tagalong_taggable
+    end
+
+    class User < ActiveRecord::Base
+      tagalong_tagger
+    end
+
+### Tag things
+
+To tag things you must use the Tagger object and hand it a persisted Taggable object with the given tag that you want to apply as follows:
+
+    @user.tag(@contact, "sometag")
+
+### Untag things
+
+To untag things you must use the Tagger object and hand it a persisted Taggable object with the given tag that you want to untag as follows:
+
+    @user.untag(@contact, "sometag")
+
+### List tags
+
+You can get the list of tags for either a Tagger or a Taggable.
+
+When you get the tags from a Tagger you are getting a list of all tags that tagger has ever used. This can be done as follows:
+
+    @user.tags
+    # => ['some_tag', 'another_tag', 'woot_tag']
+
+When you get the tags from a Taggable you are getting a list of all the tags that taggable currently has applied. This can be done as follows:
+
+    @contact.tags
+    # => ['some_tag', 'woot_tag']
+
+Tags are returned ordered by how often the tags are used.
+
+### List tags with usage info
+
+Passing a taggable object to the tags method on the Tagger will return a list of hash objects containing the tag (`tag`), a boolean representing if the tag is applied to the passed taggable (`used`), and the number of applications of that tag by the Tagger (`number_of_references`).
+
+    @user.tags(@contact)
+    # => [
+           { tag: 'some_tag', :used => true, :number_of_references => 23 },
+           { tag: 'another_tag', :used => false, :number_of_references => 42 }
+         ]
+
+### List taggables that have a tag
+
+You can aquire an array of taggable objects that have a given tag using the `taggables_with` method on the Tagger object as follows:
+
+    @user.taggables_with('some_tag')
+    # => [Taggable Object, Taggable Object] (in this case Taggable Objects would be Contacts)
+
+## Credits
+
+I just wanted to thank all of the other open source Rails tagging plugins out there. Especially, acts-as-taggable-on, I learned a lot from you all. Thanks!
+
+## Contributing
+
+If you are interested in contributing code please follow the process below and please include tests. Also, please fill out issues if you have discovered a bug or simply want to request a feature on our GitHub issues page.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/generators/tagalong/migration/migration_generator.rb

@@ -0,0 +1,39 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Tagalong
+  class MigrationGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    desc "Generates migration for TagalongTag and TagalongTagging models"
+
+    def self.orm
+      Rails::Generators.options[:rails][:orm]
+    end
+
+    #source_root File.expand_path('../templates', __FILE__)
+    def self.source_root
+      File.join(File.dirname(__FILE__), 'templates', (orm.to_s unless orm.class.eql?(String)))
+    end
+
+    def self.orm_has_migration?
+      [:active_record].include? orm
+    end
+
+    def self.next_migration_number(dirname)
+      if ActiveRecord::Base.timestamped_migrations
+        migration_number = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        migration_number += 1
+        migration_number.to_s
+      else
+        "%.3d" % (current_migration_number(dirname) + 1)
+      end
+    end
+
+    def create_migration_file
+      if self.class.orm_has_migration?
+        migration_template 'migration.rb', 'db/migrate/tagalong_migration'
+      end
+    end
+  end
+end

data/lib/generators/tagalong/migration/templates/active_record/migration.rb

@@ -0,0 +1,34 @@
+class TagalongMigration < ActiveRecord::Migration
+  def self.up
+    create_table :tagalong_tags do |t|
+      t.string :name
+      t.integer :number_of_references
+      t.integer :tagger_id
+      t.string :tagger_type
+
+      t.timestamps
+    end
+
+    add_index :tagalong_tags, :tagger_id
+    add_index :tagalong_tags, :tagger_type
+    add_index :tagalong_tags, [:tagger_id, :tagger_type]
+
+    create_table :tagalong_taggings do |t|
+      t.integer :tagalong_tag_id
+      t.integer :taggable_id
+      t.string :taggable_type
+
+      t.timestamps
+    end
+
+    add_index :tagalong_taggings, :tagalong_tag_id
+    add_index :tagalong_taggings, :taggable_id
+    add_index :tagalong_taggings, :taggable_type
+    add_index :tagalong_taggings, [:taggable_id, :taggable_type]
+  end
+
+  def self.down
+    drop_table :tagalong_tags
+    drop_table :tagalong_taggings
+  end
+end

data/lib/tagalong/exceptions.rb

@@ -0,0 +1,4 @@
+module Tagalong
+  class TaggableNotPersisted < StandardError
+  end
+end

data/lib/tagalong/tag_manager.rb

@@ -0,0 +1,63 @@
+module Tagalong
+  class TagManager
+    def initialize(taggable, tagger)
+      @taggable = taggable
+      @tagger = tagger
+    end
+
+    def add_tag(name)
+      tagger_tag = tagger_used_tag?(name)
+      if (tagger_tag != nil)
+        if !taggable_has_tag?(name)
+          associate_tag_with_taggable(tagger_tag, @taggable)
+        end
+      else
+        tagger_tag = create_tag_for_tagger(name, @tagger)
+        associate_tag_with_taggable(tagger_tag, @taggable)
+      end
+    end
+
+    def remove_tag(name)
+      tagger_tag = tagger_used_tag?(name)
+      if tagger_tag && taggable_has_tag?(name)
+        disassociate_tag_from_taggable(tagger_tag, @taggable)
+      end
+    end
+
+    def tagger_used_tag?(name)
+      @tagger.tagalong_tags.find_by_name(name)
+    end
+
+    def taggable_has_tag?(name)
+      @taggable.tagalong_tags.find_by_name(name)
+    end
+
+    private
+
+    def create_tag_for_tagger(name, tagger)
+      return TagalongTag.create!(:tagger_id => tagger.id, :tagger_type => tagger.class.to_s, :name => name)
+    end
+    
+    def associate_tag_with_taggable(tag, taggable)
+      TagalongTagging.create!(:taggable_id => taggable.id, :taggable_type => taggable.class.to_s, :tagalong_tag_id => tag.id)
+      increment_tag_number_of_references(tag)
+    end
+
+    def disassociate_tag_from_taggable(tag, taggable)
+      taggable_tagging = TagalongTagging.find_by_tagalong_tag_id_and_taggable_id(tag.id, taggable.id)
+      TagalongTagging.destroy(taggable_tagging.id)
+      taggable.tagalong_tags(true)
+      decrement_tag_number_of_references(tag)
+    end
+
+    def increment_tag_number_of_references(tag)
+      tag.number_of_references = (tag.number_of_references || 0) + 1
+      tag.save!
+    end
+
+    def decrement_tag_number_of_references(tag)
+      tag.number_of_references = tag.number_of_references ? tag.number_of_references - 1 : 0
+      tag.save!
+    end
+  end
+end

data/lib/tagalong/tagalong_tag.rb

@@ -0,0 +1,13 @@
+module Tagalong
+  class TagalongTag < ::ActiveRecord::Base
+    has_many :tagalong_taggings, :dependent => :destroy, :class_name => 'Tagalong::TagalongTagging'
+    belongs_to :tagger, :polymorphic => true
+
+    validates_presence_of :name
+    validates_uniqueness_of :name, :scope => [ :tagger_id, :tagger_type ]
+
+    def taggables
+      tagalong_taggings.map { |tagging| tagging.taggable }
+    end
+  end
+end

data/lib/tagalong/tagalong_tagging.rb

@@ -0,0 +1,9 @@
+module Tagalong
+  class TagalongTagging < ::ActiveRecord::Base
+    belongs_to :tagalong_tag, :class_name => 'Tagalong::TagalongTag'
+    belongs_to :taggable, :polymorphic => true
+
+    validates_presence_of :tagalong_tag_id
+    validates_presence_of :tagalong_tag_id, :scope => [ :taggable_type, :taggable_id ]
+  end
+end

data/lib/tagalong/taggable.rb

@@ -0,0 +1,27 @@
+module Tagalong
+  module Taggable
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def tagalong_taggable
+        class_eval do
+          has_many :tagalong_taggings, :class_name => 'Tagalong::TagalongTagging', :as => :taggable
+          has_many :tagalong_tags, :class_name => 'Tagalong::TagalongTag', :through => :tagalong_taggings
+          include Tagalong::Taggable::InstanceMethods
+        end
+      end
+    end
+
+    module InstanceMethods
+      def has_tag?(name)
+        return self.tagalong_tags.map { |r| r.name }.include?(name)
+      end
+
+      def tags
+        return self.tagalong_tags.order("number_of_references DESC").map { |r| r.name }
+      end
+    end
+  end
+end

data/lib/tagalong/tagger.rb

@@ -0,0 +1,44 @@
+module Tagalong
+  module Tagger
+    def self.included(base)
+      base.extend Tagalong::Tagger::ClassMethods
+    end
+
+    module ClassMethods
+      def tagalong_tagger
+        class_eval do
+          has_many :tagalong_tags, :class_name => 'Tagalong::TagalongTag', :as => :tagger
+          include Tagalong::Tagger::InstanceMethods
+        end
+      end
+    end
+
+    module InstanceMethods
+      def tag(taggable_obj, tag_name)
+        raise Tagalong::TaggableNotPersisted, "Taggable must be persisted to tag it." if !taggable_obj.persisted?
+        tag_manager = Tagalong::TagManager.new(taggable_obj, self)
+        tag_manager.add_tag(tag_name)
+      end
+
+      def untag(taggable_obj, tag_name)
+        raise Tagalong::TaggableNotPersisted, "Taggable must be persisted to untag it." if !taggable_obj.persisted?
+        tag_manager = Tagalong::TagManager.new(taggable_obj, self)
+        tag_manager.remove_tag(tag_name)
+      end
+
+      def tags(taggable = nil)
+        if taggable == nil
+          return self.tagalong_tags.order("number_of_references DESC").map { |r| r.name }
+        else
+          return self.tagalong_tags.joins("LEFT OUTER JOIN tagalong_taggings ON tagalong_taggings.tagalong_tag_id = tagalong_tags.id").select("tagalong_tags.id, tagalong_tags.name, tagalong_tags.number_of_references, tagalong_taggings.id as used").order("number_of_references DESC").map { |r| { :tag => r.name, :used => !r.used.nil?, :number_of_references => r.number_of_references } }
+        end
+      end
+
+      def taggables_with(name)
+        self.tagalong_tags.where(:name => name).each do |t|
+          return t.taggables
+        end
+      end
+    end
+  end
+end

data/lib/tagalong/version.rb

@@ -0,0 +1,3 @@
+module Tagalong
+  VERSION = "0.0.1"
+end

data/lib/tagalong.rb

@@ -0,0 +1,16 @@
+require "active_record"
+
+require "tagalong/version"
+require "tagalong/exceptions"
+require "tagalong/tagalong_tag"
+require "tagalong/tagalong_tagging"
+require "tagalong/tag_manager"
+require "tagalong/taggable"
+require "tagalong/tagger"
+
+if defined?(ActiveRecord::Base)
+  class ActiveRecord::Base
+    include Tagalong::Taggable
+    include Tagalong::Tagger
+  end
+end

data/spec/database.yml

@@ -0,0 +1,4 @@
+sqlite3:
+  adapter: sqlite3
+  database: tagalong.sqlite3
+

data/spec/integration/tag_manager_integration_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+describe "TagManager Integration" do
+  before(:each) do
+    @contact = Contact.create!(:name => "Bob Bobster")
+    @user = User.create!(:name => "My User")
+    @contact_tag_manager = Tagalong::TagManager.new(@contact, @user)
+  end
+
+  describe "#add_tag" do
+    it "add new tag to contact" do
+      @contact_tag_manager.add_tag("fool")
+      @contact.tagalong_tags.map { |r| r.name }.should include("fool")
+    end
+
+    it "add an existing tag to contact" do
+      @contact_tag_manager.add_tag("bar")
+      @contact_tag_manager.add_tag("bar")
+    end
+  end
+
+  describe "#remove_tag" do
+    it "remove tag from contact" do
+      cm_contact_tag = @user.tagalong_tags.create!(:name => "crazy")
+      @contact.tagalong_taggings.create!(:tagalong_tag_id => cm_contact_tag.id)
+      @contact_tag_manager.remove_tag("crazy")
+      @contact.tagalong_tags.map { |r| r.name }.should_not include("crazy")
+    end
+  end
+end

data/spec/lib/tagalong/tag_manager_spec.rb

@@ -0,0 +1,196 @@
+require 'spec_helper'
+
+# class TagalongTag; end
+# class TagalongTagging; end
+
+describe Tagalong::TagManager do
+  before(:each) do
+    @taggable = stub('taggable', :id => 58, :class => "Contact", :reload => nil)
+    @tagger = stub('tagger', :id => 23, :class => "User")
+    @tag_manager = Tagalong::TagManager.new(@taggable, @tagger)
+  end
+
+  describe "#add_tag" do
+    context "tagger does NOT already have the tag" do
+      before(:each) do
+        @tag_manager.stub(:tagger_used_tag?).and_return(nil)
+      end
+
+      it "creates a tag for the tagger" do
+        @tag_manager.should_receive(:create_tag_for_tagger).with("foo_tag", @tagger)
+        @tag_manager.stub(:associate_tag_with_taggable)
+        @tag_manager.add_tag("foo_tag")
+      end
+
+      it "associates the created tagger tag with the taggable" do
+        tag = stub('tag', :id => 98)
+        @tag_manager.stub(:create_tag_for_tagger).and_return(tag)
+        @tag_manager.should_receive(:associate_tag_with_taggable).with(tag, @taggable)
+        @tag_manager.add_tag("foo_tag")
+      end
+    end
+
+    context "tagger already has the tag" do
+      before(:each) do
+        @tag = stub('tag', :id => 108)
+        @tag_manager.stub(:tagger_used_tag?).and_return(@tag)
+      end
+
+      it "does NOT create a new tag for the tagger" do
+        @tag_manager.stub(:taggable_has_tag?).and_return(@tag)
+        @tag_manager.should_not_receive(:create_tag_for_tagger)
+        @tag_manager.add_tag("foo_tag")
+      end
+
+      context "tag is already associated to the taggable" do
+        before(:each) do
+          @tag_manager.stub(:taggable_has_tag?).and_return(@tag)
+        end
+
+        it "does NOT associated the matching tag record with taggable" do
+          @tag_manager.should_not_receive(:associate_tag_with_taggable)
+          @tag_manager.add_tag("foo_tag")
+        end
+      end
+
+      context "tag is NOT associated to the taggable" do
+        before(:each) do
+          @tag_manager.stub(:taggable_has_tag?).and_return(nil)
+        end
+
+        it "associates the tagger matched tag record with the taggable" do
+          @tag_manager.should_receive(:associate_tag_with_taggable).with(@tag, @taggable)
+          @tag_manager.add_tag("foo_tag")
+        end
+      end
+    end
+  end
+
+  describe "#remove_tag" do
+    it "disassociates the tag from the taggable if the tag belongs to tagger" do
+      tag = stub('tag')
+      @tag_manager.stub(:tagger_used_tag?).and_return(tag)
+      @tag_manager.stub(:taggable_has_tag?).and_return(tag)
+      @tag_manager.should_receive(:disassociate_tag_from_taggable).with(tag, @taggable)
+      @tag_manager.remove_tag("foo_tag")
+    end
+
+    it "should NOT dissassociate the tag from the taggable if it does NOT belong to the tagger" do
+      @tag_manager.stub(:tagger_used_tag?).and_return(stub('tag'))
+      @tag_manager.stub(:taggable_has_tag?).and_return(nil)
+      @tag_manager.should_not_receive(:disassociate_tag_from_taggable)
+      @tag_manager.remove_tag("foo_tag")
+    end
+  end
+
+  describe "#tagger_used_tag?" do
+    it "returns the matching TagalongTag if the tagger has the tag" do
+      tag = stub('tag')
+      @tagger.stub_chain(:tagalong_tags, :find_by_name).and_return(tag)
+      @tag_manager.tagger_used_tag?("foo_tag").should == tag
+    end
+
+    it "returns nil if the tagger does NOT have the tag" do
+      @tagger.stub_chain(:tagalong_tags, :find_by_name).and_return(nil)
+      @tag_manager.tagger_used_tag?("foo_tag").should be_nil
+    end
+  end
+
+  describe "#taggable_has_tag?" do
+    it "returns matching TagalongTag if the taggable is already associated with the tag" do
+      tag = stub('tag')
+      @taggable.stub_chain(:tagalong_tags, :find_by_name).and_return(tag)
+      @tag_manager.taggable_has_tag?("foo_tag").should == tag
+    end
+
+    it "returns nil, if the tag is NOT already associated with the taggable" do
+      @taggable.stub_chain(:tagalong_tags, :find_by_name).and_return(nil)
+      @tag_manager.taggable_has_tag?("foo_tag").should be_nil
+    end
+  end
+
+  describe "#create_tag_for_tagger" do
+    it "creates a TagalongTag record with the given name, associated with the tagger object" do
+      Tagalong::TagalongTag.should_receive(:create!).with({ :tagger_id => @tagger.id, :tagger_type => "User", :name => "hoopty" })
+      @tag_manager.send(:create_tag_for_tagger, "hoopty", @tagger)
+    end
+  end
+
+  describe "#associate_tag_with_taggable" do
+    it "creates a TagalongTagging record associated with the given taggable and tag" do
+      tag = stub('tag', :id => 214)
+      @tag_manager.stub(:increment_tag_number_of_references)
+      Tagalong::TagalongTagging.should_receive(:create!).with({ :taggable_id => @taggable.id, :taggable_type => "Contact", :tagalong_tag_id => 214 })
+      @tag_manager.send(:associate_tag_with_taggable, tag, @taggable)
+    end
+
+    it "increments the reference count for the tag" do
+      tag = stub('tag', :id => stub)
+      Tagalong::TagalongTagging.stub(:create!)
+      @tag_manager.should_receive(:increment_tag_number_of_references).with(tag)
+      @tag_manager.send(:associate_tag_with_taggable, tag, @taggable)
+    end
+  end
+
+  describe "#disassociate_tag_from_taggable" do
+    it "destroys the TagalongTagging record that associates the given tag with the given taggable" do
+      tag = stub('tag', :id => 111)
+      tagging = mock('tagging', :id => 283)
+      @taggable.stub(:tagalong_tags)
+      Tagalong::TagalongTagging.stub(:find_by_tagalong_tag_id_and_taggable_id).with(111, @taggable.id).and_return(tagging)
+      @tag_manager.stub(:decrement_tag_number_of_references)
+      Tagalong::TagalongTagging.should_receive(:destroy).with(283)
+      @tag_manager.send(:disassociate_tag_from_taggable, tag, @taggable)
+    end
+
+    it "decrements the reference count of the tag" do
+      tag = stub('tag', :id => 111)
+      tagging = stub('tagging', :id => 283)
+      @taggable.stub(:tagalong_tags)
+      Tagalong::TagalongTagging.stub(:find_by_tagalong_tag_id_and_taggable_id).and_return(tagging)
+      Tagalong::TagalongTagging.stub(:destroy)
+      @tag_manager.should_receive(:decrement_tag_number_of_references).with(tag)
+      @tag_manager.send(:disassociate_tag_from_taggable, tag, @taggable)
+    end
+  end
+
+  describe "#increment_tag_number_of_references" do
+    it "increments the number of references for the tag" do
+      tag = mock('tag', :number_of_references => 13, :save! => nil)
+      tag.should_receive(:number_of_references=).with(14)
+      @tag_manager.send(:increment_tag_number_of_references, tag)
+    end
+
+    it "initializes number of referencs to 1 if number of references is nil" do
+      tag = mock('tag', :number_of_references => nil, :save! => nil)
+      tag.should_receive(:number_of_references=).with(1)
+      @tag_manager.send(:increment_tag_number_of_references, tag)
+    end
+
+    it "saves the changes to the database" do
+      tag = mock('tag', :number_of_references => 13, :number_of_references= => nil)
+      tag.should_receive(:save!)
+      @tag_manager.send(:increment_tag_number_of_references, tag)
+    end
+  end
+
+  describe "#decrement_tag_number_of_references" do
+    it "decrements the number of references for the tag" do
+      tag = mock('tag', :number_of_references => 13, :save! => nil)
+      tag.should_receive(:number_of_references=).with(12)
+      @tag_manager.send(:decrement_tag_number_of_references, tag)
+    end
+
+    it "initializes number of references to zero if number of references is nil" do
+      tag = mock('tag', :number_of_references => nil, :save! => nil)
+      tag.should_receive(:number_of_references=).with(0)
+      @tag_manager.send(:decrement_tag_number_of_references, tag)
+    end
+
+    it "saves the changes to the database" do
+      tag = mock('tag', :number_of_references => 13, :number_of_references= => nil)
+      tag.should_receive(:save!)
+      @tag_manager.send(:decrement_tag_number_of_references, tag)
+    end
+  end
+end

data/spec/lib/tagalong/taggable_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+
+# The Contact class which is used in this as our taggable model
+# is defined in the spec/models.rb file.
+
+describe "Taggable" do
+  before(:each) do
+    @user = User.create!(:name => "My Owner")
+    @contact = Contact.create!(:name => "My Taggable")
+  end
+
+  describe "Integration" do
+    describe "#has_tag?" do
+      it "returns true if the taggable has the given tag" do
+        tag = @user.tagalong_tags.create!(:name => "foo")
+        @contact.tagalong_taggings.create!(:tagalong_tag_id => tag.id)
+        @contact.has_tag?("foo").should be_true
+      end
+      
+      it "returns false if the taggable does NOT have the given tag" do
+        @contact.has_tag?("bar").should be_false
+      end
+    end
+
+    describe "#tags" do
+      it "returns list of tags currently applied to this taggable" do
+        @contact.tagalong_tags.create!(:name => "foo")
+        @contact.tagalong_tags.create!(:name => "bar")
+        @contact.tagalong_tags.create!(:name => "car")
+        @contact.tags.should == ["foo", "bar", "car"]
+      end
+
+      it "returns list of tags currently applied in descending order of references" do
+        @contact.tagalong_tags.create!(:name => "hoopty", :number_of_references => 5)
+        @contact.tagalong_tags.create!(:name => "doopty", :number_of_references => 99)
+        @contact.tagalong_tags.create!(:name => "toopty", :number_of_references => 4)
+        @contact.tags.should == ["doopty", "hoopty", "toopty"]
+      end
+    end
+  end
+
+  describe "Isolation" do
+  end
+end

data/spec/lib/tagalong/tagger_spec.rb

@@ -0,0 +1,114 @@
+require 'spec_helper'
+
+# The User class which is used in this spec as our tagger
+# model, it is defined in the spec/models.rb file.
+
+describe "Tagger" do
+  before(:each) do
+    @user = User.create!(:name => "My Owner")
+    @contact = Contact.create!(:name => "My Taggable")
+  end
+  
+  describe "Integration" do
+    describe "#tag" do
+      it "tags the given taggable object with the given tag name" do
+        @user.tag(@contact, "foo")
+        @contact.tagalong_tags.map { |r| r.name }.should include("foo")
+      end
+    end
+
+    describe "#untag" do
+      it "untags the tag from the given taggable object for the tagger" do
+        @contact.tagalong_tags.create!(:name => "bar", :tagger_id => @user.id, :tagger_type => @user.class.to_s)
+        @user.untag(@contact, "bar")
+        @contact.tagalong_tags.map { |r| r.name }.should_not include("bar")
+      end
+    end
+
+    describe "#tags" do
+      context "without a taggable" do
+        it "returns list of tags the tagger has used" do
+          @user.tagalong_tags.create!(:name => "foo")
+          @user.tagalong_tags.create!(:name => "bar")
+          @user.tagalong_tags.create!(:name => "car")
+          @user.tags.should == ["foo", "bar", "car"]
+        end
+
+        it "returns the list of tags in descending order of number of references" do
+          @user.tagalong_tags.create!(:name => "foo", :number_of_references => 20)
+          @user.tagalong_tags.create!(:name => "bar", :number_of_references => 100)
+          @user.tagalong_tags.create!(:name => "car", :number_of_references => 8)
+          @user.tags.should == ["bar", "foo", "car"]
+        end
+      end
+
+      context "with a taggable" do
+        it "returns a hash of the tags with usage information about the passed taggable" do
+          tag = @user.tagalong_tags.create!(:name => "foo", :number_of_references => 1)
+          @contact.tagalong_taggings.create!(:tagalong_tag_id => tag.id)
+          @user.tagalong_tags.create!(:name => "bar", :number_of_references => 0)
+          tag = @user.tagalong_tags.create!(:name => "car", :number_of_references => 1)
+          @contact.tagalong_taggings.create!(:tagalong_tag_id => tag.id)
+          @user.tags(@contact).should == [
+            { :tag => "foo", :used => true, :number_of_references => 1  },
+            { :tag => "car", :used => true, :number_of_references => 1 },
+            { :tag => "bar", :used => false, :number_of_references => 0 }
+          ]
+        end
+      end
+    end
+
+    describe "#taggables_with" do
+      it "returns a collection of the taggables tagged with the given tag" do
+        @user.tag(@contact, "jackson")
+        @user.taggables_with("jackson").should == [@contact]
+      end
+
+      it "returns an empty array if it has no matching taggables" do
+        @user.taggables_with("jackson_five").should == []
+      end
+    end
+  end
+
+  describe "Isolation" do
+    describe "#tag" do
+      it "creates an instance of the tag manager" do
+        tag_manager = stub('tag_manager', :add_tag => nil)
+        Tagalong::TagManager.should_receive(:new).with(@contact, @user).and_return(tag_manager)
+        @user.tag(@contact, "foo")
+      end
+
+      it "tells the tag manager instance to tag the given taggable for tagger (self)" do
+        tag_manager = mock('tag_manager')
+        Tagalong::TagManager.stub(:new).with(@contact, @user).and_return(tag_manager)
+        tag_manager.should_receive(:add_tag).with("foo")
+        @user.tag(@contact, "foo")
+      end
+
+      it "raises taggable not persisted exception if attempting to tag a non-persisted taggable" do
+        new_contact = Contact.new
+        lambda { @user.tag(new_contact, "bar") }.should raise_error(Tagalong::TaggableNotPersisted)
+      end
+    end
+
+    describe "#untag" do
+      it "creates an instance of the tag manager" do
+        tag_manager = stub('tag_manager', :remove_tag => nil)
+        Tagalong::TagManager.should_receive(:new).with(@contact, @user).and_return(tag_manager)
+        @user.untag(@contact, "bar")
+      end
+
+      it "tells the tag manager instance to untag the given taggable for tagger (self)" do
+        tag_manager = mock('tag_manager')
+        Tagalong::TagManager.stub(:new).with(@contact, @user).and_return(tag_manager)
+        tag_manager.should_receive(:remove_tag).with("bar")
+        @user.untag(@contact, "bar")
+      end
+
+      it "raises taggable not persisted exception if attempting to untag a non-persisted taggable" do
+        new_contact = Contact.new
+        lambda { @user.untag(new_contact, "bar") }.should raise_error(Tagalong::TaggableNotPersisted)
+      end
+    end
+  end
+end

data/spec/models.rb

@@ -0,0 +1,7 @@
+class Contact < ActiveRecord::Base
+  tagalong_taggable
+end
+
+class User < ActiveRecord::Base
+  tagalong_tagger
+end

data/spec/schema.rb

@@ -0,0 +1,37 @@
+ActiveRecord::Schema.define :version => 0 do
+  create_table "tagalong_taggings", :force => true do |t|
+    t.integer "tagalong_tag_id", :limit => 11
+    t.integer "taggable_id", :limit => 11
+    t.string "taggable_type"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  add_index "tagalong_taggings", ["tagalong_tag_id"], :name => "index_tagalong_taggings_on_tagalong_tag_id"
+  add_index "tagalong_taggings", ["taggable_id", "taggable_type"], :name => "index_tagalong_taggings_on_taggable_id_and_taggable_type"
+
+  create_table "tagalong_tags", :force => true do |t|
+    t.integer "tagger_id", :limit => 11
+    t.string "tagger_type"
+    t.string "name"
+    t.integer "number_of_references", :limit => 11
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  add_index "tagalong_tags", ["tagger_id", "tagger_type"], :name => "index_tagalong_tags_on_tagger_id_and_tagger_type"
+
+  create_table "contacts", :force => true do |t|
+    t.string "name"
+    t.string "phone"
+    t.datetime "created_at"
+    t.datetime "udpated_at"
+  end
+
+  create_table "users", :force => true do |t|
+    t.string "email"
+    t.string "name"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,53 @@
+require 'logger'
+
+require 'rubygems'
+require 'bundler/setup'
+
+require File.expand_path('../../lib/tagalong', __FILE__)
+
+db_name = ENV['DB'] || 'sqlite3'
+database_yml = File.expand_path('../database.yml', __FILE__)
+
+if File.exists?(database_yml)
+  active_record_configuration = YAML.load_file(database_yml)
+  
+  ActiveRecord::Base.configurations = active_record_configuration
+  config = ActiveRecord::Base.configurations[db_name]
+  
+  begin
+    ActiveRecord::Base.establish_connection(db_name)
+    ActiveRecord::Base.connection
+  rescue
+    case db_name
+    when /mysql/      
+      ActiveRecord::Base.establish_connection(config.merge('database' => nil))
+      ActiveRecord::Base.connection.create_database(config['database'],  {:charset => 'utf8', :collation => 'utf8_unicode_ci'})
+    when 'postgresql'
+      ActiveRecord::Base.establish_connection(config.merge('database' => 'postgres', 'schema_search_path' => 'public'))
+      ActiveRecord::Base.connection.create_database(config['database'], config.merge('encoding' => 'utf8'))
+    end
+    
+    ActiveRecord::Base.establish_connection(config)
+  end
+    
+  ActiveRecord::Base.logger = Logger.new(File.join(File.dirname(__FILE__), "debug.log"))
+  ActiveRecord::Base.default_timezone = :utc
+  
+  ActiveRecord::Base.silence do
+    ActiveRecord::Migration.verbose = false
+    
+    load(File.dirname(__FILE__) + '/schema.rb')
+    load(File.dirname(__FILE__) + '/models.rb')
+  end
+else
+  raise "Please create #{database_yml} first to configure your database. Take a look at: #{database_yml}.sample"
+end
+
+def clean_database!
+  models = [Tagalong::TagalongTag, Tagalong::TagalongTagging]
+  models.each do |model|
+    ActiveRecord::Base.connection.execute "DELETE FROM #{model.table_name}"
+  end
+end
+
+clean_database!

data/tagalong.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/tagalong/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Andrew De Ponte"]
+  gem.email         = ["cyphactor@gmail.com"]
+  gem.description   = %q{A Rails tagging plugin that makes sense.}
+  gem.summary       = %q{A Rails tagging plugin that makes sense.}
+  gem.homepage      = "http://github.com/cyphactor/tagalong"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "tagalong"
+  gem.require_paths = ["lib"]
+  gem.version       = Tagalong::VERSION
+
+  gem.add_dependency "activerecord"
+  gem.add_development_dependency "sqlite3"
+  gem.add_development_dependency "rspec"
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: tagalong
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Andrew De Ponte
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &70241519058460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70241519058460
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &70241519058000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70241519058000
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70241519057520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70241519057520
+description: A Rails tagging plugin that makes sense.
+email:
+- cyphactor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/generators/tagalong/migration/migration_generator.rb
+- lib/generators/tagalong/migration/templates/active_record/migration.rb
+- lib/tagalong.rb
+- lib/tagalong/exceptions.rb
+- lib/tagalong/tag_manager.rb
+- lib/tagalong/tagalong_tag.rb
+- lib/tagalong/tagalong_tagging.rb
+- lib/tagalong/taggable.rb
+- lib/tagalong/tagger.rb
+- lib/tagalong/version.rb
+- spec/database.yml
+- spec/integration/tag_manager_integration_spec.rb
+- spec/lib/tagalong/tag_manager_spec.rb
+- spec/lib/tagalong/taggable_spec.rb
+- spec/lib/tagalong/tagger_spec.rb
+- spec/models.rb
+- spec/schema.rb
+- spec/spec_helper.rb
+- tagalong.gemspec
+homepage: http://github.com/cyphactor/tagalong
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.16
+signing_key: 
+specification_version: 3
+summary: A Rails tagging plugin that makes sense.
+test_files:
+- spec/database.yml
+- spec/integration/tag_manager_integration_spec.rb
+- spec/lib/tagalong/tag_manager_spec.rb
+- spec/lib/tagalong/taggable_spec.rb
+- spec/lib/tagalong/tagger_spec.rb
+- spec/models.rb
+- spec/schema.rb
+- spec/spec_helper.rb