simple_hashtag 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e8124940426b09197f994c911e96bc38f9e9e5c6
+  data.tar.gz: caea8d6daeab342ad2f59293811dfd31d4f83a28
+SHA512:
+  metadata.gz: 437c0a695584060eb1d62d244f8dab530eb08275ee578ef098140e4d472df5ee8aa258139453755a46afa8965ba1064277c4074548b439154180b32bdcc35529
+  data.tar.gz: 911e3593a7869ff82bb6198f1b06a78bea959e5f2691b5b22544665f679734503fe082b28a8fadc0164d02c98a59f6a770d5843fc022d63c950aa0e8eaa7f4c8

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
+_Notes.txt
+*.sqlite3

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,6 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+notifications:
+  recipients:
+    - ralovely@gmail.com

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Raphael Campardou
+
+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,174 @@
+# SimpleHashtag
+
+Ruby gem for Rails that parses, stores, retreives and formats hashtags in your model.
+
+_Simple Hashtag_ is a mix between–well–hashtags, as we know them, and categories.  
+It will scan your Active Record attribute for a hashtag, store it in an index, and display a page with each object containing the tag.
+
+It's simple, and like all things simple, it can create a nice effect, quickly.
+
+## Installation
+
+Add this line to your application's Gemfile:
+```ruby
+gem 'simple_hashtag'
+```
+
+And execute:
+```shell
+$ bundle
+```
+
+Then you have to generate the migration files:
+```shell
+$ rails g simple_hashtag:migration
+```
+
+This will create two migration files, one for the `hashtags` table and one for the `hashtagging` table.  
+You will need to run `rake db:migrate` to actually create the tables.
+
+__Optionnally__, you can create views,  
+if only to guide you through your own implementation:
+```shell
+$ rails g simple_hashtag:views
+```
+
+This will create a __basic controller__, a __short index view__ and a __small helper__.  
+It assume your views follow the convention of having a directory named after your model's plural, and a partial named after your model's name.
+```
+app
+|-- views
+|    |-- posts 
+|    |    |-- _post.html.erb
+```
+
+
+## Usage
+
+Just add `include SimpleHashtag::Hashtaggable` in your model.
+
+_Simple Hasthag_ will parse the `body` attribute by default:  
+
+```ruby
+class Post < ActiveRecord::Base
+  include SimpleHashtag::Hashtaggable
+end
+```
+
+
+If you need to parse another attribute instead,  
+add `hashtaggable_attribute` followed by the name of your attribute, i.e.:
+```ruby
+class Picture < ActiveRecord::Base
+  include SimpleHashtag::Hashtaggable
+  hashtaggable_attribute :caption
+end
+```
+
+From here on, if your text contains a hashtag, say _#RubyRocks_,  
+_Simple Hasthag_ will find it, store it in a table and retreive it and its associated object if asked.  
+Helpers are also available to create a link when displaying the text.
+
+### Controller and Views
+If you don't want to bother looking at the genrerated controller and views, here is a quick peek.  
+In a Controller, search for a Hashtag, and its associated records:
+```ruby
+class HashtagsController < ApplicationController
+  def index
+    @hashtag = SimpleHashtag::Hashtag.find_by_name(params[:hashtag])
+    @hashtagged = @hashtag.hashtaggables if @hashtag
+  end
+end
+```
+
+
+The index view could resemble something like this:
+```erb
+<h1><%= params[:hashtag] %></h1>
+<% if @hashtagged %>
+  <% @hashtagged.each do |hashtagged| %>
+    <% view    = hashtagged.class.to_s.underscore.pluralize %>
+    <% partial = hashtagged.class.to_s.underscore %>
+    <%= render "#{view}/#{partial}", {partial.to_sym => hashtagged} %>
+  <% end -%>
+<% else -%>
+  <p>There is no match for the <em><%= params[:hashtag] %></em> hashtag.</p>
+<% end -%>
+```
+In the gem it is actually extracted in a helper.
+
+
+### Routes
+
+If you use the provided controller and views, add this line to your `config/routes.rb` file:
+```ruby
+get 'hashtags/:hashtag',  to: 'hashtags#index',     as: :hashtag
+```
+
+The helper generating the link relies on it.
+
+
+
+### Spring Cleaning
+There is a class method `SimpleHashtag::Hashtag#clean_orphans` to remove unused hashtags from the DB.  
+It is currently not hooked, for two reasons:  
+- It is not optimised at all, DB-wise.  
+- Destructive method should be called explicitly.  
+
+Knowing all this, you can hook it after each change, or automate it with a Cron job, or even spring-clean manually once in a while.  
+
+Improvements for this method are listed in the Todo section below.
+
+
+## Gotchas
+### Association Query
+The association between a Hashtag and your models is a polymorphic many-to-many.  
+When querying the polymorphic association from the other side (tag.hashtaggables),  
+we perform a DB query for each hashtaggable, resulting in an n+1 query.
+
+The object returned by the query is an array, not an Arel query, so you can't chain (i.e.: to specify the order), and should do it by hand:
+
+```ruby
+hashtag = SimpleHashtag.find_by_name("RubyRocks")
+posts_and_picts = hashtag.hattaggables
+posts_and_picts.sort_by! { |p| p.created_at }
+```
+
+### find_by
+
+To preserve coherence, Hashtags are stored downcased.  
+To ensure coherence, they are also searched downcased.  
+Internally, the model overrides `find_by_name` to perform the downcase query.  
+Should you search Hashtags manually you should use the `SimpleHashtag::Hashtag#find_by_name` method, instead of `SimpleHashtag::Hashtag.find_by(name: 'RubyRocks')`
+
+
+## ToDo
+
+_Simple Hashtag_ is in its very early stage and would need a lot of love to reach 1.0.0.
+Among the many improvement areas:
+
+- Make the Regex that parses the text for the hashtag much more robust.  
+  This is how Twitter does it:  
+  [https://github.com/twitter/twitter-text-rb/blob/master/lib/twitter-text/regex.rb](https://github.com/twitter/twitter-text-rb/blob/master/lib/twitter-text/regex.rb)  
+  (Yes, that's 362 lines of regex. Neat.)
+- Allow for multiple hashtagable attributes on the same model
+- Allow a change in the name of the classes and tables to avoid conflicts
+- Make it ORM agnostic
+- Add an option so the helper displays the `#` or not, global or per model
+- Add an option to clean orphans after each edit or not
+- Improve the `SimpleHashtag::Hashtag#clean_orphans` method to do only one SQL query
+
+## Contributing
+
+All contributions are welcome.  
+I might not develop new features (unless a project does require it),  
+but I will definitely merge any interesting feature or bug fix quickly.
+
+You know the drill:
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Add passing tests
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/Rakefile

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

data/lib/generators/simple_hashtag/migration_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators/active_record'
+
+module SimpleHashtag
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      def self.next_migration_number(path)
+        ActiveRecord::Generators::Base.next_migration_number(path)
+      end
+
+      def generate_migration
+          migration_template "migrations/create_hashtags_migration.rb", "db/migrate/create_simple_hashtag_hashtags.rb"
+          migration_template "migrations/create_hashtaggings_migration.rb", "db/migrate/create_simple_hashtag_hashtaggings.rb"
+      end
+    end
+  end
+end

data/lib/generators/simple_hashtag/templates/migrations/create_hashtaggings_migration.rb

@@ -0,0 +1,11 @@
+# This migration comes from simple_hashtag
+class CreateSimpleHashtagHashtaggings < ActiveRecord::Migration
+  def change
+    create_table :simple_hashtag_hashtaggings do |t|
+      t.references :hashtag,      :index => true
+      t.references :hashtaggable, :polymorphic => true
+    end
+    add_index :simple_hashtag_hashtaggings, ["hashtaggable_id", "hashtaggable_type"],
+              :name => 'index_hashtaggings_hashtaggable_id_hashtaggable_type'
+  end
+end

data/lib/generators/simple_hashtag/templates/migrations/create_hashtags_migration.rb

@@ -0,0 +1,10 @@
+# This migration comes from simple_hashtag
+class CreateSimpleHashtagHashtags < ActiveRecord::Migration
+  def change
+    create_table :simple_hashtag_hashtags do |t|
+      t.string :name,             :index => true
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/simple_hashtag/templates/views/hashtags_controller.rb

@@ -0,0 +1,8 @@
+class HashtagsController < ApplicationController
+
+  def index
+    @hashtag = SimpleHashtag::Hashtag.find_by_name(params[:hashtag])
+    @hashtagged = @hashtag.hashtaggables if @hashtag
+  end
+
+end

data/lib/generators/simple_hashtag/templates/views/hashtags_helper.rb

@@ -0,0 +1,16 @@
+module HashtagsHelper
+  def linkify_hashtags(hashtaggable_content)
+    regex = SimpleHashtag::Hashtag::HASHTAG_REGEX
+    hashtagged_content = hashtaggable_content.to_s.gsub(regex) do
+      link_to($1, hashtag_path($2), {class: :hashtag})
+    end
+    hashtagged_content.html_safe
+  end
+
+  def render_hashtaggable(hashtaggable)
+    klass        = hashtaggable.class.to_s.underscore
+    view_dirname = klass.pluralize
+    partial      = klass
+    render "#{view_dirname}/#{partial}", {klass.to_sym => hashtaggable}
+  end
+end

data/lib/generators/simple_hashtag/templates/views/hashtags_index.html.erb

@@ -0,0 +1,8 @@
+<h1><%= params[:hashtag] %></h1>
+<% if @hashtagged %>
+  <% @hashtagged.each do |hashtagged| %>
+    <%= render_hashtaggable hashtagged %>
+  <% end -%>
+<% else -%>
+  <p>There is no match for the <em><%= params[:hashtag] %></em> hashtag.</p>
+<% end -%>

data/lib/generators/simple_hashtag/views_generator.rb

@@ -0,0 +1,14 @@
+module SimpleHashtag
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      def generate_views
+        copy_file "views/hashtags_controller.rb", "app/controllers/hashtags_controller.rb"
+        copy_file "views/hashtags_helper.rb", "app/helpers/hashtags_helper.rb"
+        copy_file "views/hashtags_index.html.erb", "app/views/hashtags/index.html.erb"
+      end
+    end
+  end
+end

data/lib/simple_hashtag/hashtag.rb

@@ -0,0 +1,39 @@
+module SimpleHashtag
+  class Hashtag < ActiveRecord::Base
+    self.table_name = "simple_hashtag_hashtags"
+
+    has_many :hashtaggings
+
+    # TODO Beef up the regex (ie.:what if content is HTML)
+    # this is how Twitter does it:
+    # https://github.com/twitter/twitter-text-rb/blob/master/lib/twitter-text/regex.rb
+    HASHTAG_REGEX = /\s(#([a-z0-9\-_]+))/i
+
+    def self.find_by_name(name)
+      Hashtag.where("lower(name) =?", name.downcase).first
+    end
+
+    def name=(val)
+      write_attribute(:name, val.downcase)
+    end
+
+    def name
+      read_attribute(:name).downcase
+    end
+
+    def hashtaggables
+      self.hashtaggings.collect { |h| h.hashtaggable }
+    end
+
+    def to_s
+      name
+    end
+
+    def self.clean_orphans # From DB
+      # TODO Make this method call a single SQL query
+      orphans = self.all.select { |h| h.hashtaggables.size == 0 }
+      orphans.map(&:destroy)
+    end
+
+  end
+end

data/lib/simple_hashtag/hashtaggable.rb

@@ -0,0 +1,45 @@
+module SimpleHashtag
+  module Hashtaggable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :hashtaggings, as: :hashtaggable,  class_name: "SimpleHashtag::Hashtagging"
+      has_many :hashtags, through: :hashtaggings, class_name: "SimpleHashtag::Hashtag"
+
+      before_save :update_hashtags
+
+      def hashtaggable_content
+        self.class.hashtaggable_attribute # to ensure it has been called at least once
+        content = self.send(self.class.hashtaggable_attribute_name)
+        content.to_s
+      end
+
+      def update_hashtags
+        self.hashtags = parsed_hashtags
+      end
+
+      def parsed_hashtags
+        parsed_hashtags = []
+        array_of_hashtags_as_string = scan_for_hashtags(hashtaggable_content)
+        array_of_hashtags_as_string.each do |s|
+          parsed_hashtags << Hashtag.find_or_create_by(name: s[1])
+        end
+        parsed_hashtags
+      end
+
+      def scan_for_hashtags(content)
+        match = content.scan(Hashtag::HASHTAG_REGEX)
+        match.uniq!
+        match
+      end
+    end
+
+    module ClassMethods
+      attr_accessor :hashtaggable_attribute_name
+
+      def hashtaggable_attribute(name=nil)
+        self.hashtaggable_attribute_name ||= name || :body
+      end
+    end
+  end
+end

data/lib/simple_hashtag/hashtagging.rb

@@ -0,0 +1,8 @@
+module SimpleHashtag
+  class Hashtagging < ActiveRecord::Base
+    self.table_name = "simple_hashtag_hashtaggings"
+
+    belongs_to :hashtag
+    belongs_to :hashtaggable, polymorphic: true
+  end
+end

data/lib/simple_hashtag/version.rb

@@ -0,0 +1,3 @@
+module SimpleHashtag
+  VERSION = "0.1.0"
+end

data/lib/simple_hashtag.rb

@@ -0,0 +1,6 @@
+require "simple_hashtag/hashtag"
+require "simple_hashtag/hashtagging"
+require "simple_hashtag/hashtaggable"
+
+module SimpleHashtag
+end

data/simple_hashtag.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'simple_hashtag/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "simple_hashtag"
+  spec.version       = SimpleHashtag::VERSION
+  spec.authors       = ["Raphael Campardou"]
+  spec.email         = ["ralovely@gmail.com"]
+  spec.description   = %q{Parse, store retreive and format hashtags in your text.}
+  spec.summary       = %q{Simple Hashtag is a mix between–well–hashtags as we know them and categories. It will scan your Active Record attribute for a tag and store it in an index.}
+  spec.homepage      = "https://github.com/ralovely/simple_hashtag"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 1.9.3"
+  spec.add_dependency "rails", "> 3.2.0"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "sqlite3"
+end