easy_tags 0.1.0.pre.alpha

data/lib/easy_tags/options/collection.rb

@@ -0,0 +1,28 @@
+module EasyTags
+  module Options
+    # Represents collection of options
+    class Collection
+      def initialize(options)
+        @options = options.uniq
+      end
+
+      # @return [Boolean]
+      def valid?
+        filtered_options.all?(&:valid?)
+      end
+
+      # @return [String]
+      def items
+        filtered_options
+      end
+
+      private
+
+        def filtered_options
+          @filtered_options ||= @options.to_a.flatten.compact.map do |raw_option|
+            Item.new(raw_option)
+          end
+        end
+    end
+  end
+end

data/lib/easy_tags/options/item.rb

@@ -0,0 +1,41 @@
+module EasyTags
+  module Options
+    # Represents a single option item
+    class Item
+      def initialize(option)
+        @option = option
+      end
+
+      # @return [Boolean]
+      def valid?
+        /[@$"]/ !~ name.inspect
+      end
+
+      # @return [Symbol]
+      def name
+        @name ||= key.to_sym
+      end
+
+      # @return [Array<Callback>]
+      def callbacks
+        return [] unless callbacks?
+
+        @option.values.first.map do |type, callback|
+          Callback.new(callback: callback, type: type)
+        end
+      end
+
+      private
+
+        def key
+          return @option.keys.first if callbacks?
+
+          @option
+        end
+
+        def callbacks?
+          @option.is_a?(Hash)
+        end
+    end
+  end
+end

data/lib/easy_tags/parsers/default.rb

@@ -0,0 +1,22 @@
+module EasyTags
+  module Parsers
+    # Default parser for [String] -> [Array] conversion
+    class Default
+      class << self
+        # Returns a new TagList using the given tag string.
+        #
+        # @param [String] tag_list_string
+        # @return [Array<String>]
+        #
+        # Example:
+        #   EasyTags::Parsers::Default.parse('One , Two,  Three')
+        #   ['One', 'Two', 'Three']
+        def parse(tag_list_string)
+          return [] if tag_list_string.to_s.empty?
+
+          tag_list_string.to_s.split(/,/).map(&:strip)
+        end
+      end
+    end
+  end
+end

data/lib/easy_tags/tag.rb

@@ -0,0 +1,36 @@
+module EasyTags
+  # Tag model
+  class Tag < ::ActiveRecord::Base
+    self.table_name = EasyTags.tags_table
+
+    has_many :taggings, dependent: :destroy, class_name: '::EasyTags::Tagging', inverse_of: :tag
+
+    validates_presence_of :name
+    validates_uniqueness_of :name
+    validates_length_of :name, maximum: 255
+
+    after_commit :notify_add, on: :create
+    after_commit :notify_remove, on: :destroy
+
+    # cast object to string
+    def to_s
+      name
+    end
+
+    private
+
+      def notify_add
+        ActiveSupport::Notifications.instrument(
+          'easy_tag.tag_added',
+          tag: self
+        )
+      end
+
+      def notify_remove
+        ActiveSupport::Notifications.instrument(
+          'easy_tag.tag_removed',
+          tag: self
+        )
+      end
+  end
+end

data/lib/easy_tags/tag_list.rb

@@ -0,0 +1,47 @@
+module EasyTags
+  # Represents a tag list
+  class TagList < SimpleDelegator
+    def initialize(
+      *args,
+      generator: EasyTags.generator,
+      parser: EasyTags.parser
+    )
+      self.generator = generator
+      self.parser = parser
+      super([])
+
+      add(*args)
+    end
+
+    # Add tags to the tag_list. Duplicate or blank tags will be ignored.
+    #
+    # Example:
+    #   tag_list.add('Fun', 'Happy')
+    def add(*names)
+      filter(names).each { |filtered_name| push(filtered_name) unless include?(filtered_name) }
+    end
+
+    # Transform the tag_list into a tag string
+    def to_s
+      generator.generate(self)
+    end
+
+    # Remove item from list
+    #
+    # Example:
+    #   tag_list.remove('Issues')
+    def remove(value)
+      __getobj__.delete(value)
+    end
+
+    private
+
+      attr_accessor :generator, :parser
+
+      def filter(names)
+        names.to_a.flatten.compact.map do |name|
+          parser.parse(name)
+        end.flatten.compact.uniq
+      end
+  end
+end

data/lib/easy_tags/taggable.rb

@@ -0,0 +1,52 @@
+# rubocop:disable Style/Documentation
+module EasyTags
+  module Taggable
+    module ClassMethods
+      # rubocop:enable Style/Documentation
+      #
+      # Examples
+      #
+      #   easy_tags_on :highlights
+      #
+      # with multiple contexts:
+      #
+      #   easy_tags_on :highlights, :tags
+      #
+      # with callbacks:
+      #
+      #   easy_tags_on(
+      #     highlights: {
+      #       after_add: :add_tag_callback, after_remove: ->(tagging) { puts "removed #{tagging.tag.name}" }
+      #     }
+      #   )
+      #
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def easy_tags_on(*tagging_contexts_params)
+        cattr_accessor :tagging_contexts
+        cattr_accessor :tagging_callbacks
+
+        options = Options::Collection.new(tagging_contexts_params.to_a)
+        raise 'invalid options' unless options.valid?
+
+        self.tagging_contexts ||= []
+        self.tagging_callbacks ||= {}
+
+        options.items.each do |option|
+          tagging_contexts.push(option.name) unless tagging_contexts.include?(option.name)
+          tagging_callbacks[option.name] = option.callbacks
+
+          EasyTags::TaggableContextMethods.inject(
+            class_instance: self,
+            context: option.name
+          )
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      EasyTags::TaggableMethods.inject(class_instance: base)
+    end
+  end
+end

data/lib/easy_tags/taggable_context.rb

@@ -0,0 +1,56 @@
+module EasyTags
+  # Handles tag context manipulation
+  class TaggableContext
+    # @param [String, Symbol] context
+    # @param [Proc] refresh_persisted_tags
+    # @param [Proc] on_change
+    def initialize(context:, refresh_persisted_tags:, on_change:)
+      self.context = context
+      self.refresh_persisted_tags = refresh_persisted_tags
+      self.on_change = on_change
+    end
+
+    # @return [true, false]
+    def changed?
+      tags.sort != persisted_tags.sort
+    end
+
+    # @return [TagList]
+    def tags
+      @tags ||= TagList.new(persisted_tags)
+    end
+
+    # @return [TagList]
+    def persisted_tags
+      @persisted_tags ||= TagList.new(refresh_persisted_tags.call)
+    end
+
+    # @param [String, Symbol] value
+    # @return [TagList]
+    def update(value)
+      @tags = TagList.new(value)
+
+      on_change.call(self) if changed?
+    end
+
+    # @return [TagList]
+    def new_tags
+      tags - persisted_tags
+    end
+
+    # @return [TagList]
+    def removed_tags
+      persisted_tags - tags
+    end
+
+    # clear memoized info and force a refresh
+    def refresh
+      @tags = nil
+      @persisted_tags = nil
+    end
+
+    private
+
+      attr_accessor :context, :refresh_persisted_tags, :on_change
+  end
+end

data/lib/easy_tags/taggable_context_methods.rb

@@ -0,0 +1,56 @@
+module EasyTags
+  # Handles injecting of the dynamic context related methods
+  # Example:
+  #   easy_tags_on :bees
+  #
+  #   # will create:
+  #
+  #   has_many :bees_taggings
+  #   has_many :bees_tags
+  #
+  #   def bees
+  #   def bees=
+  #   def bees_list
+  #   def bees_list=
+  class TaggableContextMethods
+    class << self
+      def inject(class_instance:, context:)
+        class_instance.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          has_many(
+            :#{context}_taggings, -> { includes(:tag).where(context: :#{context}) },
+            as: :taggable,
+            class_name: 'EasyTags::Tagging',
+            dependent: :destroy
+          )
+
+          has_many(
+            :#{context}_tags,
+            class_name: 'EasyTags::Tag',
+            through: :#{context}_taggings,
+            source: :tag
+          )
+
+          attribute :#{context}_list, ActiveModel::Type::Value.new
+
+          def #{context}
+            _taggable_context(:#{context}).tags
+          end
+
+          def #{context}=(value)
+            _taggable_context(:#{context}).update(value)
+            #{context}
+          end
+
+          def #{context}_list
+            _taggable_context(:#{context}).tags.to_s
+          end
+
+          def #{context}_list=(value)
+            _taggable_context(:#{context}).update(value)
+            #{context}_list
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/easy_tags/taggable_methods.rb

@@ -0,0 +1,109 @@
+module EasyTags
+  # Taggable instance methods
+  module TaggableMethods
+    class << self
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def inject(class_instance:)
+        # rubocop:disable Metrics/BlockLength
+        class_instance.class_eval do
+          has_many(
+            :taggings,
+            as: :taggable,
+            dependent: :destroy,
+            class_name: '::EasyTags::Tagging',
+            inverse_of: :taggable
+          )
+
+          has_many(
+            :base_tags,
+            through: :taggings,
+            source: :tag,
+            class_name: '::EasyTags::Tag',
+            inverse_of: :tag
+          )
+
+          after_save :_update_taggings, :_refresh_tagging
+          after_find :_refresh_tagging
+
+          # override ActiveRecord::Persistence#reload
+          # to refresh tags each time the model instance gets reloaded
+          def reload
+            _refresh_tagging
+            super
+          end
+
+          private
+
+            attr_accessor :_taggable_contexts
+
+            def _taggable_contexts
+              @_taggable_contexts ||= {}
+            end
+
+            def _update_taggings
+              tagging_contexts.each do |context|
+                context_tags = _taggable_context(context)
+
+                next unless context_tags.changed?
+
+                context_tags.new_tags.each do |tag_name|
+                  tag = Tag.find_or_create_by!(name: tag_name)
+                  taggings.create!(context: context, tag: tag)
+                end
+
+                taggings
+                  .joins(:tag)
+                  .where(context: context)
+                  .where(Tag.table_name => { name: context_tags.removed_tags })
+                  .destroy_all
+              end
+            end
+
+            def _refresh_tagging
+              tagging_contexts.each do |context|
+                _taggable_context(context).refresh
+              end
+            end
+
+            def _mark_dirty(context:, taggable_context:)
+              write_attribute("#{context}_list", taggable_context.tags.to_s)
+              set_attribute_was("#{context}_list", taggable_context.persisted_tags.to_s)
+              attribute_will_change!("#{context}_list")
+            end
+
+            def _taggable_context(context)
+              _taggable_contexts[context] ||= TaggableContext.new(
+                context: context,
+                refresh_persisted_tags: lambda {
+                  taggings.joins(:tag).where(context: context).pluck(:name)
+                },
+                on_change: lambda { |tag_context|
+                  _mark_dirty(context: context, taggable_context: tag_context)
+                }
+              )
+            end
+
+            def _notify_tag_change(type:, tagging:)
+              callbacks_for_type = tagging_callbacks[tagging.context.to_sym].select do |callback|
+                callback.type == type
+              end
+
+              callbacks_for_type.each do |callback|
+                callback.run(taggable: self, tagging: tagging)
+              end
+            end
+
+            def _notify_tag_add(tagging)
+              _notify_tag_change(type: :after_add, tagging: tagging)
+            end
+
+            def _notify_tag_remove(tagging)
+              _notify_tag_change(type: :after_remove, tagging: tagging)
+            end
+        end
+        # rubocop:enable Metrics/BlockLength
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/easy_tags/tagging.rb

@@ -0,0 +1,34 @@
+module EasyTags
+  # Tagging model
+  class Tagging < ::ActiveRecord::Base
+    self.table_name = EasyTags.taggings_table
+
+    belongs_to :tag, class_name: '::EasyTags::Tag', optional: false, inverse_of: :taggings
+    belongs_to :taggable, polymorphic: true, optional: false, inverse_of: :taggings
+
+    validates_uniqueness_of :tag_id, scope: %i[taggable_type taggable_id context]
+
+    after_commit :notify_add, on: :create
+    after_commit :notify_remove, on: :destroy
+
+    private
+
+      def notify_add
+        ActiveSupport::Notifications.instrument(
+          "easy_tag.tagging_added.#{taggable_type.to_s.tableize}.#{context}",
+          tagging: self
+        )
+
+        taggable.send(:_notify_tag_add, self)
+      end
+
+      def notify_remove
+        ActiveSupport::Notifications.instrument(
+          "easy_tag.tagging_removed.#{taggable_type.to_s.tableize}.#{context}",
+          tagging: self
+        )
+
+        taggable.send(:_notify_tag_remove, self)
+      end
+  end
+end

data/lib/easy_tags/version.rb

@@ -0,0 +1,3 @@
+module EasyTags
+  VERSION = '0.1.0-alpha'.freeze
+end

data/lib/easy_tags.rb

@@ -0,0 +1,74 @@
+require 'active_support/dependencies/autoload'
+require 'active_record'
+
+# rubocop:disable Style/Documentation
+module EasyTags
+  extend ActiveSupport::Autoload
+
+  autoload :Tag, 'easy_tags/tag'
+  autoload :TaggableMethods, 'easy_tags/taggable_methods'
+  autoload :TaggableContextMethods, 'easy_tags/taggable_context_methods'
+  autoload :TaggableContext, 'easy_tags/taggable_context'
+  autoload :Taggable, 'easy_tags/taggable'
+  autoload :Tagging, 'easy_tags/tagging'
+  autoload :TagList, 'easy_tags/tag_list'
+  autoload :VERSION, 'easy_tags/version'
+
+  module Parsers
+    autoload :Default, 'easy_tags/parsers/default'
+  end
+
+  module Generators
+    autoload :Default, 'easy_tags/generators/default'
+  end
+
+  module Options
+    autoload :Callback, 'easy_tags/options/callback'
+    autoload :Item, 'easy_tags/options/item'
+    autoload :Collection, 'easy_tags/options/collection'
+  end
+  # rubocop:enable Style/Documentation
+
+  # handle lib configuration options
+  #
+  # Example
+  #
+  #  EasyTags.setup do |config|
+  #    config.tags_table = :tags
+  #    config.taggings_table = :taggings
+  #    config.parser = EasyTags::Parsers::Default
+  #    config.generator = EasyTags::Generators::Default
+  #  end
+  #
+  class Configuration
+    OPTIONS = %i[
+      tags_table
+      taggings_table
+      parser
+      generator
+    ].freeze
+
+    attr_accessor(
+      *OPTIONS
+    )
+
+    def initialize
+      self.tags_table = :tags
+      self.taggings_table = :taggings
+      self.parser = Parsers::Default
+      self.generator = Generators::Default
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def setup
+      yield(configuration)
+    end
+
+    delegate(*Configuration::OPTIONS, to: :configuration)
+  end
+end

data/lib/generators/easy_tags/migration_generator.rb

@@ -0,0 +1,30 @@
+require 'rails/generators/active_record'
+
+module EasyTags
+  module Generators
+    # generates database migration
+    #
+    # Usage
+    #   rails g easy_tags:migration
+    #
+    class MigrationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_migrations
+        migration_template(
+          'create_tables_migration.rb.erb',
+          "#{db_migrate_path}/easy_tags_create_tables.rb",
+          migration_version: migration_version
+        )
+      end
+
+      private
+
+        def migration_version
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+    end
+  end
+end

data/lib/generators/easy_tags/templates/create_tables_migration.rb.erb

@@ -0,0 +1,17 @@
+class EasyTagsCreateTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table <%= ":#{EasyTags.tags_table}" %> do |t|
+      t.string :name, index: true
+
+      t.timestamps null: false
+    end
+
+    create_table <%= ":#{EasyTags.taggings_table}" %> do |t|
+      t.references :tag, foreign_key: { to_table: <%= ":#{EasyTags.tags_table}" %> }, null: false, index: true
+      t.references :taggable, polymorphic: true, index: true, null: false
+      t.string :context, null: false, index: true
+
+      t.datetime :created_at, null: false
+    end
+  end
+end