easy_tags 0.1.0.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 946ce5a345e151980fa49a96c8595025e20398f0
+  data.tar.gz: 53b9c21505e59edaee95dd3937b8164b8b4f7f97
+SHA512:
+  metadata.gz: 37abe520d5e1fafb8974be26a1ab02175a2f19f26eab84eee1673b848d72abbaa10bfbdb87024454aac16ab3cbed9a55e5022fc6b9304664c392dee6234b0da3
+  data.tar.gz: aa63f981b6220bb317dbad45b349a417da549d7c63f8c8c40586452d49b9a38132cd91e1ba5dae0ccd07572b7e0d81bddc5bc4ff14ecd5d8c41bcb39a8611ef0

data/.codeclimate.yml

@@ -0,0 +1,3 @@
+plugins:
+  rubocop:
+    enabled: true

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.idea
+*.lock
+*.gem
+gemfiles/.bundle/
+.DS_Store

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,15 @@
+Metrics/LineLength:
+  Max: 120
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/SymbolArray:
+  Enabled: true
+
+Layout/IndentationConsistency:
+  EnforcedStyle: rails
+
+AllCops:
+  Exclude:
+    - 'spec/**/*'

data/.travis.yml

@@ -0,0 +1,33 @@
+sudo: false
+language: ruby
+cache: bundler
+before_script: bundle update
+before_install:
+  - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true
+  - gem install bundler -v '< 2'
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
+rvm:
+  - 2.3.8
+  - 2.4.5
+  - 2.5.3
+  - 2.6.0
+  - ruby-head
+gemfile:
+  - Gemfile
+  - gemfiles/activerecord_5.0.gemfile
+  - gemfiles/activerecord_5.1.gemfile
+  - gemfiles/activerecord_5.2.gemfile
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+  fast_finish: true
+env:
+  global:
+    - CC_TEST_REPORTER_ID=c7f705db7f3e2658ca529a196cd65b724f6b674a7ed6ac2e01928135babdac35

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/Appraisals

@@ -0,0 +1,14 @@
+appraise 'activerecord-5.0' do
+  gem 'activerecord', '~> 5.0.0'
+  gem 'activesupport', '~> 5.0.0'
+end
+
+appraise 'activerecord-5.1' do
+  gem 'activerecord', '~> 5.1.0'
+  gem 'activesupport', '~> 5.1.0'
+end
+
+appraise 'activerecord-5.2' do
+  gem 'activerecord', '~> 5.2.0'
+  gem 'activesupport', '~> 5.2.0'
+end

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in easy_tags.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Iwo Dziechciarow
+
+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/MIGRATING_FROM_AATO.MD

@@ -0,0 +1,41 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Migrating from ActsAsTaggableOn to EasyTags](#migrating-from-actsastaggableon-to-easytags)
+  - [Database](#database)
+  - [Features](#features)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Migrating from ActsAsTaggableOn to EasyTags
+
+ ### Database
+ `EasyTags` uses the same table structure as `ActsAsTaggableOn` - you most probably do not have to do any migrations
+
+ ### Features
+ in comparison to `ActsAsTaggableOn` some features/behaviors were deliberately not included in `EasyTags`:
+ - singularization/pluralizion of context names (we use flat naming)
+ - `Tag Ownership`
+ - Query helpers (ie. `tagged_with`)
+ - statistic helpers (ie. `most_used`, `least_used`)
+ - `Dynamic Tag Contexts`
+
+ ### Configuration
+ `EasyTags` does not implement configuration options like:
+ `delimiter`, `force_lowercase`, `force_parameterize` etc.
+
+ you can use custom parser for that
+
+ ### Auto-generated context methods
+`EasyTags` uses consistent types and naming
+
+|                                    | `easy_tags`          | `acts_as_tagabble_on` |
+|------------------------------------|----------------------|-----------------------|
+| `has_many` to `Tag` relation       | context_tags         | context(pluralized)               |
+| `has_many` to `Taggings` relation  | context_taggings     | context(singularized)_taggings      |
+| set tags using string of tag names | context_list=(value) | context(singularized)_list=(value)  |
+| get string of tag names            | context_list         | -                     |
+| set tags with array of tag names   | context=(value)      | context(singularized)_list=(value)  |
+| get array of tag names             | context              | context(singularized)_list                    |
+

data/README.md

@@ -0,0 +1,344 @@
+[![Maintainability](https://api.codeclimate.com/v1/badges/5c35fe854f8cbd3f1209/maintainability)](https://codeclimate.com/github/iiwo/easy_tags/maintainability)
+[![Build Status](https://travis-ci.org/iiwo/easy_tags.svg?branch=master)](https://travis-ci.org/iiwo/easy_tags)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/5c35fe854f8cbd3f1209/test_coverage)](https://codeclimate.com/github/iiwo/easy_tags/test_coverage)
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [EasyTags](#easytags)
+  - [Migrating from ActsAsTaggableOn](#migrating-from-actsastaggableon)
+  - [Installation](#installation)
+    - [Post Installation](#post-installation)
+  - [Usage](#usage)
+    - [Setup](#setup)
+    - [Interface](#interface)
+    - [Examples](#examples)
+      - [Adding/Removing tags](#addingremoving-tags)
+      - [Querying](#querying)
+        - [Context relations](#context-relations)
+        - [Global relations](#global-relations)
+    - [Callbacks](#callbacks)
+      - [Instance scope callbacks](#instance-scope-callbacks)
+      - [Active Support Instrumentation custom notifications](#active-support-instrumentation-custom-notifications)
+        - [Tag notifications](#tag-notifications)
+        - [Tagging notifications](#tagging-notifications)
+    - [Dirty objects](#dirty-objects)
+  - [Configuration](#configuration)
+  - [Testing](#testing)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# EasyTags
+
+Easy contextual tagging for Rails
+
+## Migrating from ActsAsTaggableOn
+
+This gem was inspired by [ActsAsTaggableOn](https://github.com/mbleigh/acts-as-taggable-on).
+It was built on similar model, but rewritten from scratch and simplified with better maintainability in mind.
+Considerable amount of features has been removed and we've made some breaking changes.
+Please refer to [ActsAsTaggableOn migration notes](https://github.com/iiwo/easy_tags/blob/master/MIGRATING_FROM_AATO.MD) if you want to migrate
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'easy_tags'
+```
+
+And then execute:
+```shell
+$ bundle
+```
+
+### Post Installation
+
+generate migration with:
+```shell
+rails g easy_tags:migration
+```
+
+## Usage
+
+### Setup
+
+in your ActiveRecord model add:
+
+```ruby
+include EasyTags::Taggable
+
+easy_tags_on :highlights
+```
+
+with multiple tag contexts:
+```ruby
+include EasyTags::Taggable
+
+easy_tags_on :highlights, :tags, :notes
+```
+
+### Interface
+upon the `easy_tags_on` declaration:
+```ruby
+easy_tags_on :highlights
+```
+
+the following methods will be auto-generated and made available for your model instance (`highlights` being an example context name):
+
+| description                        | method                    |
+|------------------------------------|---------------------------|
+| set tags using string of tag names | `highlights_list=(value)` |
+| get string of tag names            | `highlights_list`         |
+| set tags with array of tag names   | `highlights=(value)`      |
+| get array of tag names             | `highlights`              |
+
+- the String accessor is helpful when working with client side tagging UI solutions such as ie. [select2](https://select2.org/tagging)
+- the Array accessor gives you convenient array item manipulation
+
+### Examples
+
+#### Adding/Removing tags
+
+Using Array accessor
+```ruby
+# assign/replace tags (comma separated using the default parser)
+model.highlights = ['My Tag', 'Second Tag', 'Some Other tag']
+# => [
+#      [0] "My Tag",
+#      [1] "Second Tag",
+#      [2] "Some Other tag"
+#  ]
+
+# add tags
+model.highlights.add('One More', 'And Another')
+model.highlights
+# => [
+#     [0] "My Tag",
+#     [1] "Second Tag",
+#     [2] "Some Other tag",
+#     [3] "One More",
+#     [4] "And Another"
+#  ]
+
+# remove a single tag
+model.highlights.remove('One More')
+model.highlights
+# => [
+#     [0] "My Tag",
+#     [1] "Second Tag",
+#     [2] "Some Other tag",
+#     [3] "And Another"
+#  ]
+
+# remember to persist changes
+model.save
+```
+
+Using String accessor
+```ruby
+# add multiple tags (comma separated using the default parser)
+model.highlights_list = 'My Tag, Second Tag, Some Other tag'
+# > "My Tag, Second Tag, Some Other tag"
+
+# remove a single tag
+model.highlights_list = 'My Tag, Second Tag'
+# > "My Tag, Second Tag"
+
+# remove all tags
+model.highlights_list = ''
+
+# remember to persist changes
+model.save
+```
+
+#### Querying
+`EasyTags` does not offer any query helper scopes, but it's fairly easy to query without them.
+
+##### Context relations
+Upon the `easy_tags_on` declaration:
+```ruby
+easy_tags_on :highlights
+```
+
+the following relations will be auto-generated and made available for your model instance (`highlights` being an example context name):
+
+| description                                  | relation                |
+|----------------------------------------------|-------------------------|
+| `has_many` to `EasyTags::Tag` relation       | highlights_tags         |
+| `has_many` to `EasyTags::Taggings` relation  | highlights_taggings     |
+
+- `EasyTags::Tag` model represents a single tag name
+- `EasyTags::Taggings` represents a join table between your model and the `EasyTags::Tag` model, it also holds the tag context value
+
+Find all model instances with a specific tag name:
+```ruby
+MyModel.joins(:highlights_tags).where(tags: { name: 'My Tag' })
+```
+
+Eager loading:
+```ruby
+MyModel.includes(:highlights_tags)
+```
+
+##### Global relations
+Upon the `EasyTags::Taggable` inclusion
+```ruby
+include EasyTags::Taggable
+```
+the fallowing context independent relations will be auto-generated and made available for your model instance:
+
+| description                                  | relation                                |
+|----------------------------------------------|-----------------------------------------|
+| `has_many` to `EasyTags::Taggings` relation  | has_many :taggings, as: :taggable       |
+| `has_many` to `EasyTags::Tag` relation       | has_many :base_tags, through: :taggings |
+
+You can use them for querying multiple contexts
+```ruby
+MyModel.joins(:base_tags).where(taggings: { context: %w[highlights billing_highlights] })
+```
+
+### Callbacks
+
+#### Instance scope callbacks
+
+```ruby
+include EasyTags::Taggable
+
+easy_tags_on(
+  highlights: { after_add: :add_tag_callback, after_remove: -> (tagging) { puts "removed #{tagging.tag.name}" } }
+)
+
+def add_tag_callback(tagging)
+  puts "added #{tagging.tag.name}"
+end
+```
+
+#### Active Support Instrumentation custom notifications
+
+##### Tag notifications
+
+```ruby
+ActiveSupport::Notifications.subscribe 'easy_tag.tag_added' do |tag|
+  puts "added #{tag.name}"
+end
+```
+
+```ruby
+ActiveSupport::Notifications.subscribe 'easy_tag.tag_removed' do |tag|
+  puts "removed #{tag.name}"
+end
+```
+
+##### Tagging notifications
+
+```ruby
+ActiveSupport::Notifications.subscribe 'easy_tag.tagging_added.YOUR_MODEL_TABLEIZED.CONTEXT_NAME' do |tagging|
+  puts "added #{tagging.tag.name}"
+end
+```
+
+```ruby
+ActiveSupport::Notifications.subscribe 'easy_tag.tagging_added.YOUR_MODEL_TABLEIZED.CONTEXT_NAME' do |tagging|
+  puts "removed #{tagging.tag.name}"
+end
+```
+
+### Dirty objects
+
+`EasyTags` implements `ActiveModel::Dirty` attribute changes tracking fot all the context String accessors (the `CONTEXT_NAME_list` attributes)
+
+```ruby
+model.highlights
+# []
+
+model.highlights = ['Tag One', 'Tag Two']
+# [
+#     [0] "Tag One",
+#     [1] "Tag Two"
+# ]
+
+model.changed?
+# true
+
+model.highlights_list_changed?
+# true
+
+model.highlights_list_was
+# ""
+
+model.highlights_list_change
+# [
+#     [0] "",
+#     [1] "Tag One,Tag Two"
+# ]
+
+model.save
+# true
+
+model.changed?
+# false
+
+model.highlights_list_changed?
+# false
+
+model.previous_changes
+# {
+#     "highlights_list" => [
+#         [0] nil,
+#         [1] "Tag One,Tag Two"
+#     ]
+# }
+
+model.highlights_list_previously_changed?
+# true
+
+model.highlights_list_previous_change
+# [
+#     [0] nil,
+#     [1] "Tag One,Tag Two"
+# ]
+```
+
+## Configuration
+
+```ruby
+# config/initializers/easy_tags.rb
+
+EasyTags.setup do |config|
+  config.tags_table = :tags
+  config.taggings_table = :taggings
+  config.parser = EasyTags::Parsers::Default
+  config.generator = EasyTags::Generators::Default
+end
+```
+
+You can customize db table names with `tags_table` and `taggings_table` options.
+
+You can customize the parser and the generator to use different separators, filtering or processing.
+The default parser uses comma as separator and is case sensitive.
+
+
+## Testing
+```
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/easy_tags. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'easy_tags'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/easy_tags.gemspec

@@ -0,0 +1,33 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'easy_tags/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'easy_tags'
+  spec.version = EasyTags::VERSION
+  spec.authors = ['Iwo Dziechciarow']
+  spec.email = ['iiwo@o2.pl']
+
+  spec.summary = 'EasyTags allows you to tag a single model on several contexts'
+  spec.description = 'Easy tagging for Rails'
+  spec.homepage = 'https://github.com/iiwo/easy_tags'
+  spec.license = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'activerecord', '~> 5.0'
+  spec.add_runtime_dependency 'activesupport', '~> 5.0'
+
+  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency 'database_cleaner'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov-console'
+  spec.add_development_dependency 'sqlite3', '~> 1.3.6'
+end

data/gemfiles/activerecord_5.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 5.0.0'
+gem 'activesupport', '~> 5.0.0'
+
+gemspec path: '../'

data/gemfiles/activerecord_5.1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 5.1.0'
+gem 'activesupport', '~> 5.1.0'
+
+gemspec path: '../'

data/gemfiles/activerecord_5.2.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 5.2.0'
+gem 'activesupport', '~> 5.2.0'
+
+gemspec path: '../'

data/lib/easy_tags/generators/default.rb

@@ -0,0 +1,24 @@
+module EasyTags
+  module Generators
+    # Default generator for [Array] -> [String] conversion
+    class Default
+      class << self
+        # Generates a new String using the given Array
+        #
+        # @param [Array] tag_list
+        # @return [String]
+        #
+        # Example:
+        #   EasyTags::Generators::Default.generate(['One', 'Two', 'Three'])
+        #   'One, Two, Three'
+        def generate(tag_list)
+          tag_list ||= []
+
+          return '' if tag_list.empty?
+
+          tag_list.join(',')
+        end
+      end
+    end
+  end
+end

data/lib/easy_tags/options/callback.rb

@@ -0,0 +1,34 @@
+module EasyTags
+  module Options
+    # Represents a single callback item
+    class Callback
+      attr_reader :context
+
+      TYPES = %i[after_add after_remove].freeze
+
+      # @param [Proc] callback
+      # @param [Symbol] type
+      def initialize(callback:, type:)
+        @callback = callback
+        @type = type
+
+        raise "unknown callback type - must be one of #{TYPES}" unless TYPES.include?(type)
+      end
+
+      # @return [String]
+      attr_reader :type
+
+      # invoke callback for a taggable object for a specific tagging
+      #
+      # @param [Object] taggable
+      # @param [Object] tagging
+      def run(taggable:, tagging:)
+        if @callback.is_a?(Symbol)
+          taggable.send(@callback, tagging)
+        elsif @callback.is_a?(Proc)
+          taggable.instance_exec tagging, &@callback
+        end
+      end
+    end
+  end
+end